SKILL.md - cors-tester

# SKILL.md - cors-tester

## What this tool does

cors-tester sends an HTTP OPTIONS preflight request followed by an actual request from one or more specified origins to a target URL. It inspects the CORS response headers, checks for known misconfigurations, and reports each origin as ALLOWED, DENIED, or ALLOWED-WITH-WARNINGS.

## Install and build

```bash
pnpm install
pnpm run build        # outputs to dist/
pnpm link --global    # makes `cors-tester` available in PATH
```

## Basic usage

```bash
# Single origin
cors-tester --origin https://myapp.com https://api.example.com/data

# Multiple origins
cors-tester \
  --origin https://myapp.com \
  --origin http://localhost:3000 \
  https://api.example.com/data

# POST with custom headers
cors-tester \
  --origin https://myapp.com \
  --method POST \
  --headers "Authorization,Content-Type,X-Request-ID" \
  https://api.example.com/orders

# Test with credentials flag
cors-tester --origin https://myapp.com --credentials https://api.example.com/user/me

# JSON output for CI
cors-tester \
  --origin https://myapp.com \
  --format json \
  --output cors-report.json \
  https://api.example.com/data

# SARIF output for GitHub Security tab
cors-tester \
  --origin https://myapp.com \
  --format sarif \
  --output cors.sarif \
  https://api.example.com/data

# Start web UI
cors-tester --ui
cors-tester --ui --port 8080
```

## Flags

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--origin <url>` | `-o` | (required) | Origin to test. Repeatable. |
| `--method <M>` | `-m` | GET | HTTP method for actual request |
| `--headers <h>` | `-H` | (none) | Comma-separated request headers for preflight |
| `--credentials` | `-c` | false | Include credentials flag in check |
| `--timeout <ms>` | `-t` | 5000 | Request timeout in milliseconds |
| `--format <fmt>` | `-f` | table | Output format: table, json, sarif |
| `--output <path>` | `-O` | stdout | Write output to file |
| `--ui` | | false | Start web UI on port 4444 |
| `--port <n>` | | 4444 | Web UI port |
| `--no-color` | | false | Disable ANSI color |
| `--quiet` | | false | Print summary line only |
| `--version` | `-v` | | Print version |
| `--help` | `-h` | | Print help |

## Exit codes

| Code | Meaning |
|------|---------|
| 0 | All tested origins allowed, no errors or warnings |
| 1 | One or more origins denied or have errors |
| 2 | One or more origins allowed but have warnings only |
| 3 | Fatal error (bad arguments, DNS failure, invalid URL) |

## Result statuses

| Status | Meaning |
|--------|---------|
| `allowed` | Origin passes all CORS checks |
| `denied` | Server does not allow the origin (no CORS headers) |
| `misconfigured` | Server returns headers that browsers will reject (e.g. wildcard + credentials) |
| `error` | Request failed (timeout, DNS failure, TLS error) |

## Error codes

| Code | Severity | Description |
|------|----------|-------------|
| `NO_CORS_HEADERS` | error | No `Access-Control-Allow-Origin` header in response |
| `WILDCARD_WITH_CREDENTIALS` | error | `Access-Control-Allow-Origin: *` combined with `Access-Control-Allow-Credentials: true` - browsers block this |
| `REQUEST_TIMEOUT` | error | Request timed out before response received |
| `DNS_LOOKUP_FAILED` | error | Could not resolve the target hostname |
| `TLS_CERTIFICATE_ERROR` | error | SSL/TLS handshake failed |
| `WILDCARD_ORIGIN` | warning | `Access-Control-Allow-Origin: *` - any origin can read the response |
| `MISSING_VARY_ORIGIN` | warning | Server reflects specific origin but `Vary` does not include `Origin` |
| `LONG_MAX_AGE` | warning | `Access-Control-Max-Age` exceeds browser cache limits (7200s Firefox, 600s Chrome) |
| `MISSING_CREDENTIALS_HEADER` | warning | `--credentials` flag was set but server did not return `Access-Control-Allow-Credentials: true` |

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `CORS_TESTER_NO_COLOR` | 0 | Set to 1 to disable ANSI color output |
| `CORS_TESTER_QUIET` | 0 | Set to 1 to suppress per-origin output |
| `CORS_TESTER_TIMEOUT` | 5000 | Default request timeout in ms |

## JSON output schema

```json
{
  "url": "https://api.example.com/data",
  "method": "GET",
  "testedAt": "2026-03-20T14:22:31.004Z",
  "durationMs": 280,
  "results": [
    {
      "origin": "https://myapp.com",
      "status": "allowed",
      "preflightStatus": 204,
      "actualStatus": 200,
      "durationMs": 142,
      "corsHeaders": {
        "access-control-allow-origin": "https://myapp.com",
        "access-control-allow-methods": "GET, POST, OPTIONS",
        "vary": "Origin, Accept-Encoding"
      },
      "warnings": [],
      "errors": []
    }
  ],
  "summary": {
    "allowed": 1,
    "denied": 0,
    "warnings": 0,
    "errors": 0,
    "total": 1
  }
}
```

## Web UI API

When started with `--ui`, the server exposes:

```
POST /api/test
Content-Type: application/json

{
  "url": "https://api.example.com/data",
  "origins": ["https://myapp.com", "https://evil.com"],
  "method": "GET",
  "headers": ["Authorization"],
  "credentials": false,
  "timeout": 5000
}
```

Response: the same JSON schema as `--format json` output.

```
GET /        serves the built React UI (ui/dist/index.html)
GET /assets/* serves static assets
```

## GitHub Actions example

```yaml
- name: Test CORS
  run: |
    cors-tester \
      --origin "${{ vars.ALLOWED_ORIGIN }}" \
      --format sarif \
      --output cors.sarif \
      "${{ vars.API_URL }}/health"

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: cors.sarif
```

## Behavior notes

- The tool sends a real HTTP OPTIONS request followed by a real actual request. It does not simulate browser behavior; it calls the endpoint from the test runner's network.
- For `--credentials`, the tool checks that `Access-Control-Allow-Credentials: true` is present and that `Access-Control-Allow-Origin` is not `*`.
- All header name comparisons are case-insensitive.
- The `Vary` header check splits on commas and trims whitespace before comparing to `Origin`.
- If the preflight fails (4xx, 5xx, timeout), the actual request is skipped and the result status is `error`.
- The web UI (port 4444) calls `testCors()` server-side; it is not affected by browser CORS restrictions itself.

## Troubleshooting

**Error: No --origin specified**
Add at least one `--origin` flag before the URL argument.

**Error: REQUEST_TIMEOUT**
Check that the target host is reachable from where the tool runs. Increase `--timeout` if the server is slow to respond to OPTIONS.

**Warning: MISSING_VARY_ORIGIN**
The server reflects specific origins but does not include `Origin` in `Vary`. This is a CDN/proxy cache correctness issue. Fix by adding `Origin` to the `Vary` header on CORS responses.

**Error: WILDCARD_WITH_CREDENTIALS**
Remove `Access-Control-Allow-Credentials: true` from the response, or replace the wildcard `*` with the specific requesting origin using a server-side allowlist lookup.