api-security-probe

Lightweight API security probe that runs in seconds. No ZAP, no browser, no heavy setup. Point it at any REST API and it checks for common authentication and infrastructure weaknesses.

What it checks

| Check | What it does | |---|---| | Auth Rate Limit | Fires 20 rapid bad login attempts, expects a 429 response | | API Rate Limit | Fires 10 rapid requests per configured endpoint, expects a 429 response | | JWT: Tampered signature | Corrupts the token signature, expects 401 | | JWT: Expired token | Sends a known expired token, expects 401 | | JWT: Token after logout | Logs out then reuses the old token, expects 401 | | JWT: Algorithm none attack | Strips the signature and sets alg: none, expects 401 | | JWT: RS256 to HS256 confusion | Signs a token using the server's public key as an HMAC secret, expects 401 | | BOLA (cross-role) | Uses a regular user token against admin-only endpoints, expects 401/403 | | IDOR (cross-user) | Uses user2's token against user's resource IDs, expects 401/403/404 | | Security Headers | Checks for HSTS, X-Content-Type-Options, X-Frame-Options, CSP, Referrer-Policy | | TLS Certificate | Warns if the certificate expires within 30 days | | Open Ports | Scans for unexpected open ports (databases, SSH, debug ports) |

Install

npm install -g api-security-probe

Or as a project dev dependency:

npm install --save-dev api-security-probe

Quick Start

Step 1: Create a config file (copy from sample/probe.config.yml):

target: https://api.example.com

auth:
  type: oauth2-password
  url: https://auth.example.com/realms/myrealm/protocol/openid-connect/token
  client_id: myclient
  client_secret: ${AUTH_CLIENT_SECRET}

roles:
  admin:
    username: ${ADMIN_USERNAME}
    password: ${ADMIN_PASSWORD}
  user:
    username: ${USER_USERNAME}
    password: ${USER_PASSWORD}

session:
  probe_endpoint: /accounts

bola:
  admin_endpoints:
    - GET /admin/users

Step 2: Set your credentials as environment variables:

export AUTH_CLIENT_SECRET=...
export ADMIN_USERNAME=...
export ADMIN_PASSWORD=...
export USER_USERNAME=...
export USER_PASSWORD=...

Step 3: Run:

api-security-probe --config probe.config.yml

CLI Options

api-security-probe --config <file> [options]

Options:
  --config, -c <file>   Path to probe config file (YAML or JSON)
  --tests  <list>       Comma-separated tests to run (default: all)
                        rate-limit, api-rate-limit, session, bola, idor,
                        headers, tls, ports
  --output <file>       Write results to a JSON file
  --help,  -h           Show this help

Config Reference

target

Base URL of the API under test.

auth

| Field | Required | Description | |---|---|---| | type | Yes | Auth type. Currently supports oauth2-password | | url | Yes | Token endpoint URL | | client_id | Yes | OAuth2 client ID | | client_secret | No | OAuth2 client secret (omit for public clients) | | logout_url | No | Logout endpoint. Required for the token-after-logout check | | jwks_url | No | JWKS endpoint. Required for the RS256-to-HS256 check |

roles

| Role | Used by | |---|---| | admin | Session checks, BOLA, API rate limit, security headers | | user | BOLA check (should be blocked from admin endpoints) | | user2 | IDOR check (should not access user's resources) |

Each role takes username and password. Roles not needed for the selected tests are not authenticated.

tests

List of tests to run. If omitted, all tests run. Can also be overridden via --tests on the CLI.

session

| Field | Description | |---|---| | probe_endpoint | An authenticated endpoint used as the target for all JWT attack checks |

bola

| Field | Description | |---|---| | admin_endpoints | List of admin-only endpoints. Format: METHOD /path or just /path (defaults to GET) |

idor

| Field | Description | |---|---| | endpoints | List of endpoints with path parameters. Format: METHOD /path/{paramName} | | example_ids | Map of parameter names to user's resource IDs |

rate_limit

| Field | Description | |---|---| | api_endpoints | Endpoints to probe for rate limiting. Format: METHOD /path or just /path |

headers

| Field | Description | |---|---| | probe_endpoint | Endpoint to probe for security headers. Falls back to session.probe_endpoint if not set |

ports

| Field | Description | |---|---| | check | List of ports to scan. Defaults to [22, 23, 3306, 5432, 6379, 27017, 8080, 8443, 9200] |

Environment Variables

Config values support ${VARIABLE_NAME} syntax and are resolved from environment variables at runtime. This keeps credentials out of config files.

client_secret: ${AUTH_CLIENT_SECRET}

If a referenced variable is not set, the tool exits with an error before running any checks.

CI Integration

# GitHub Actions example
- name: Run API security probe
  env:
    AUTH_CLIENT_SECRET: ${{ secrets.AUTH_CLIENT_SECRET }}
    ADMIN_USERNAME: ${{ secrets.ADMIN_USERNAME }}
    ADMIN_PASSWORD: ${{ secrets.ADMIN_PASSWORD }}
    USER_USERNAME: ${{ secrets.USER_USERNAME }}
    USER_PASSWORD: ${{ secrets.USER_PASSWORD }}
  run: npx api-security-probe --config probe.config.yml --output results.json

The process exits with code 1 if any check fails, making it suitable as a CI gate.

Output

Terminal output is color-coded and grouped:

• FAILED section first: each failing check with per-item detail and the reason it failed
• PASSED section: checks that passed, with sub-item counts
• SKIPPED section: checks that were skipped (e.g. TLS on an HTTP target)
• Summary table: per-check PASS / FAIL / SKIP counts with totals
• Start time, finish time, total duration, and final verdict on every run

Timestamps use UTC and are shown as 09 May 2026 07:27:52 +00:00.

Pass --output results.json to also write a machine-readable JSON file:

{
  "target": "https://api.example.com",
  "started_at": "2026-05-09T07:27:52.000Z",
  "finished_at": "2026-05-09T07:27:53.000Z",
  "duration_ms": 1045,
  "verdict": "FAILED",
  "summary": { "passed": 10, "failed": 5, "skipped": 1, "total": 8 },
  "checks": [...]
}

License

MIT