API Security Scanner
Table of Contents
Purpose
The API Security Scanner performs static API discovery and security analysis on a source-code project. It walks the project tree and any OpenAPI / Swagger descriptors, builds an inventory of services, modules, endpoints, parameters, and data objects, and then runs the OWASP API Security Top 10 (2023) detectors against the inventory to produce a list of flaws.
The scanner is invoked through the standard Xygeni CLI as the apisecurity subcommand. It produces the same metadata, evidence, and severity model as the other Xygeni scans, so its findings integrate uniformly into dashboards, gates, and compliance reports.
Installation
The API Security scanner ships as part of the Xygeni Scanner — there is no separate binary or container. Install the Xygeni Scanner following the Xygeni CLI Installation guide, then verify the apisecurity subcommand is available:
Quick Start
Scan a local checkout and write a JSON report:
Inventory-only mode (no flaw detection):
Scan and upload to the Xygeni backend:
Scan Modes
Two modes selected by a single flag:
Full scan
(default)
Discovery + flaw detection. The inventory plus all enabled OWASP API risk detectors run end to end.
Inventory-only
--discovery-only
Discovery only. No flaw detection. Useful for feeding the inventory to SAST / DAST correlators, generating an API catalog, or comparing the implemented API against a documented spec without producing flaw findings. Sensitivity classification (PII / PCI / PHI / credential tags) still runs in this mode.
Inputs — Directory, Repository, Staged Files
Three input modes:
--dir <path> (default)
Scan a local checkout.
-r, --repo <url> --branch …
Clone the remote repository to a temporary directory, scan it, and remove the clone after the scan completes.
--staged-files
Scan only files staged in the local git index — useful as a pre-commit gate. Requires --dir to point at a git working tree.
--include and --exclude accept comma-separated glob patterns to narrow the file set further (for example, --exclude '**/test/**,**/build/**').
Hybrid Scanning — Specs & Live Probing
Beyond the source-code scan, two optional inputs let you enrich and confirm the analysis:
--spec <path-or-url>
Ingest one or more OpenAPI / Swagger specs — local files or http(s) URLs — in addition to anything auto-discovered under --dir. Repeatable or comma-separated. Endpoints from the spec are merged into the same inventory, which also powers the zombie_endpoint / orphan_spec drift detector.
--base-url <url>
Deployed-app base URL that enables opt-in live probing (off unless provided). For detectors that support it, the scanner issues a request per candidate endpoint and reads the gateway's response to confirm or refute the static verdict.
Live probing is non-destructive: it never removes findings, it annotates each probed flaw with a liveProbe property —
confirmed-<status>— the endpoint answered without credentials (the static finding is corroborated),refuted-401/refuted-403— the deployed gateway enforces authentication the source did not show,unreachable— the endpoint could not be contacted (connection refused, timeout, TLS error).
Probes run concurrently with a bounded pool and a per-request timeout, and any network error is isolated — probing never aborts a scan. It is opt-in precisely because it makes outbound requests to the target you name; do not point --base-url at production without authorization.
Output Formats
-f (repeatable) selects one or more output formats; -o selects the target file. When more than one format is requested, the file name is decorated with the format extension.
text (default)
Human-readable summary on stdout. Best for ad-hoc scans and developer feedback.
json
Full report shape — services, modules, endpoints, data objects, flaws, statistics, scanner metadata. The canonical machine-readable shape.
xygeni-json
Xygeni backend wire format — internally used by --upload but also emittable for offline upload pipelines.
csv
Flat, one-row-per-finding tabular export for spreadsheets and quick triage.
markdown
Markdown summary, convenient for PR comments and CI job summaries.
sarif
SARIF 2.1.0 — for ingestion by GitHub Code Scanning, Azure DevOps, and other tools that consume SARIF.
The JSON shape mirrors the other Xygeni scans (metadata, statistics, top-level finding arrays, scanner properties, SCM information from the git working tree) so existing JSON consumers extend uniformly.
Backend Upload
--upload uses the standard Xygeni backend ingest endpoint, the same one used by the SCA / SAST / Secrets / IaC scanners. The project is resolved by name (defaulting to the directory name; override with -n <name>), and the report is pushed under the same project's API Security scan history.
A scan that does not set --upload produces local output only — useful for CI gates and pre-commit hooks where backend persistence is not desired.
Framework Selection
By default, framework autodiscovery is on: a lightweight pre-pass inspects the project's dependency manifests and loads only the detectors that match detected frameworks. This keeps scan time low and avoids cross-framework false positives.
Two flags override autodiscovery:
--frameworks <list>
Pin the framework allowlist. Autodiscovery is skipped when this flag is set — user selection wins.
--skip-frameworks <list>
Add a framework denylist. Honored after autodiscovery, so the autodiscovered list is filtered against the denylist.
Framework IDs follow the per-language naming used in xygeni.apisecurity.yml — for example, spring-mvc, jax-rs, aspnet-core, fastapi, flask, django, express, nestjs, koa, fastify, hono, gin, laravel, openapi.
CI / CD Integration
The scanner is intended to be invoked from CI alongside the other Xygeni scans, typically against the project's main branch on each push and against the PR head on pull requests. Two common patterns:
--fail-on <severity> and --never-fail parallel the other Xygeni scans for gate behaviour. Most teams gate on HIGH for the first few weeks of adoption, then progressively tighten to MEDIUM as the noise floor settles.
Command Reference
--dir <path>
Local project directory to scan.
-r, --repo <url>
Clone a remote repository, scan it, and clean up after.
--branch <name>
Branch to check out from the repository (used with -r) or to record on the report (used with --dir).
--staged-files
Scan only files in the git staging area.
-n, --name <name>
Project name (defaults to inferred from --dir).
--discovery-only
Inventory-only mode — skip flaw detection.
--frameworks <list>
Comma-separated framework allowlist (skips autodiscovery).
--skip-frameworks <list>
Comma-separated framework denylist (applied after autodiscovery).
--include <patterns>
Comma-separated include globs.
--exclude <patterns>
Comma-separated exclude globs.
--spec <path-or-url>
OpenAPI / Swagger spec file(s) or URL(s) to ingest alongside the source scan (repeatable / comma-separated).
--base-url <url>
Deployed-app base URL; enables opt-in live probing for detectors that support it (off unless set).
-c, --conf <file>
Override the bundled xygeni.apisecurity.yml.
-f <fmt> (repeatable)
Output format(s) — text, json, xygeni-json, csv, markdown, sarif.
-o, --output <path>
Output file (extension added when multiple formats are requested).
-u, --upload
Upload the report to the Xygeni backend.
--fail-on <severity>
Exit non-zero on findings of the given severity or above.
--never-fail
Always exit 0, regardless of findings.
Exit Codes
These match the shared Xygeni exit-code convention used by the other scanners:
0
Success — no findings, all findings below the --fail-on threshold, or --never-fail set.
1
Invalid arguments.
2
Scan setup / run error (e.g., directory not found, repository clone failed).
128
At least one finding matched --fail-on — used when --fail-on is a severity threshold (or is given with no value, meaning "any finding").
129
At least one finding matched a --fail-on detector / expression selector.
Last updated