Scan from scripts
and CI.
The website, your editor and your pipeline all run the same scanner. This page covers the REST API, the command-line tool, the GitHub Action and OAuth sign-in for MCP clients, including what is and is not published yet.
Get a token
In Settings, under AI editors and API, create a token with the API
scope. It starts with ssk_. Store it as a secret, never in a file
in your repository. A token has one scope: an API token cannot call the MCP
endpoint and an MCP token cannot call the REST API. Neither can sign in,
change your password, buy anything or delete your account, and you can
revoke one from Settings at any time.
REST API
Base URL https://secscan.us/api/v1, with the header Authorization: Bearer ssk_....
| Endpoint | What it does |
|---|---|
GET /me | Who the token belongs to. |
POST /scans | Start a scan of {"url": "..."}. Uses one of your free scans or any credits you hold, exactly as the website does; free on the unlimited plan. Returns 202 with a scan id. |
GET /scans | Your recent scans, newest first (limit 1 to 50). |
GET /scans/{id} | Status and a short summary: grade, risk score, finding counts and coverage. Add ?wait=60 to hold until the scan finishes. |
GET /scans/{id}/report | The full report: findings with evidence and fixes, what the scan tested and skipped, and compliance mapping. 409 until the scan finishes. |
GET /scans/{id}/sarif | The findings as SARIF 2.1.0 for GitHub code scanning. |
GET /openapi.json | The OpenAPI 3.1 description of all of the above. No token needed. |
curl -X POST https://secscan.us/api/v1/scans \
-H "Authorization: Bearer $SECSCAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"https://staging.example.com"}'
Errors are JSON: {"error":{"code":"...","message":"..."}}. The limit is
120 requests a minute per account. A scan through the API is a scan like any
other: same allowance, same rate limits, same refusal of private and internal addresses.
What a pass means
A clean result means the tests that ran found nothing. Active tests (injection, access control, SSRF) run only on domains you have verified, so a scan of an unverified preview URL is passive only. Every response says how many tests ran and how many were skipped, so a pass never hides that.
Command line and GitHub Action
A single-file tool that starts a scan, waits for it and sets an exit code, so a build can fail on findings or on a grade below a threshold.
export SECSCAN_TOKEN=ssk_...
node secscan.mjs scan https://staging.example.com --fail-on high --min-grade C --sarif secscan.sarif
Options: --fail-on critical|high|medium|low|info|none (default high),
--min-grade A..F, --sarif file, --json file,
--timeout seconds (default 300).
| Exit code | Meaning |
|---|---|
0 | The scan finished and the build passes. |
1 | The scan finished and the policy failed. |
2 | Bad usage, or the scan failed or timed out. |
3 | The token was refused, or the API could not be reached. |
Not published yet. The tool and the GitHub Action exist and are tested, but the Action's repository and an npm package have not been published, so there is nothing to install from a registry today. Until then, use the REST API directly.
SARIF results have no file or line, because SecScan scans a running site, not source. Each result is located at the URL it was found at, and GitHub shows them as repository alerts rather than inline in a diff.
OAuth for MCP clients
MCP clients that support OAuth 2.1 can connect with a consent screen and no
token to copy. The server publishes standard metadata at
/.well-known/oauth-authorization-server and
/.well-known/oauth-protected-resource, supports dynamic client
registration and PKCE (S256 only), and issues one-hour access tokens with
rotating 30-day refresh tokens. OAuth grants are limited to the MCP scope;
they cannot use the REST API. Connected apps are listed in Settings, where you
can revoke them.
See AI editors (MCP) for the editor side.