Scan an authorized URL, API specification, source tree, or supported combination and produce a policy-aware security report.
Stable in v3.7.0
Syntax
terminal
fendix scan [flags]Arguments and required inputs
At least one of --url, --spec, or --code is required. --import augments a scan and does not satisfy the target requirement.
Examples
Basic API scan
terminal
fendix scan --url https://staging.example.comSource scan
terminal
fendix scan --code . --format json --output results.jsonCoverage gate
terminal
fendix scan --code . --require-analyzers pip,npm,govulncheck --fail-on-coverage-gapSARIF output
terminal
fendix scan --code . --format sarif --output results.sarifTargets and scope
Scroll the table horizontally to inspect every column.
| Option | Type | Default | Requirement | Configuration | Environment | Description |
|---|---|---|---|---|---|---|
--url | string | — | Optional | — | — | Target API base URL (black-box scanning) |
--spec | string | — | Optional | — | — | Path or HTTP(S) URL to an OpenAPI/Swagger YAML or JSON spec |
--code | string | — | Optional | — | — | Path to source code directory (white-box scanning) |
Authentication
Scroll the table horizontally to inspect every column.
| Option | Type | Default | Requirement | Configuration | Environment | Description |
|---|---|---|---|---|---|---|
--auth | string | — | Optional | — | FENDIX_AUTH | Auth header value, e.g. "Bearer token123" |
--auth-type | string | — | Optional | — | FENDIX_AUTH_TYPE | Auth type: bearer, apikey, apikey-query, basic, cookie (default: auto-detect)bearer · apikey · apikey-query · basic · cookie |
--auth-header | string | Authorization | Optional | — | FENDIX_AUTH_HEADER | Custom auth header name; with apikey-query this names the query parameter (pass api_key for the conventional name) |
--auth-user2 | string | — | Optional | — | — | Second user auth for IDOR checks, e.g. "Bearer token-user2" |
--profile | string | — | Optional | auth.profile | — | Auth profile name from ~/.fendix/profiles/<name>.yaml |
Crawl and safety
Scroll the table horizontally to inspect every column.
| Option | Type | Default | Requirement | Configuration | Environment | Description |
|---|---|---|---|---|---|---|
--enable-active | bool | false | Optional | scan.enable_active | — | Enable active injection probes (default: false) |
--max-probes-per-endpoint | int | 20 | Optional | — | — | Max active probes per endpoint (only effective with --enable-active) |
-w, --workers | int | 10 | Optional | scan.workers | — | Concurrent HTTP workers |
--timeout | int | 10 | Optional | scan.timeout | — | HTTP timeout in seconds |
--delay | int | 100 | Optional | scan.delay_ms | — | Milliseconds between HTTP requests |
--wordlist | string | — | Optional | crawler.wordlist_path | — | Path to brute-force wordlist (one path per line); overrides built-in CommonPaths |
--crawl-depth | int | 1 | Optional | crawler.crawl_depth | — | Recursive HTML link crawl depth (0 disables; 1 = home-page links only) |
--max-endpoints | int | 500 | Optional | crawler.max_endpoints | — | Cap total discovered endpoints (0 = no cap) |
--max-requests | int64 | 0 | Optional | budgets.max_requests | — | Soft-cap on total HTTP requests across all checks (0 = no cap) |
--max-duration | duration | 0s | Optional | budgets.max_duration | — | Soft-cap on total scan wall-clock time, e.g. 5m (0 = no cap) |
--respect-robots | bool | false | Optional | crawler.respect_robots | — | Treat robots.txt Disallow as a hard restriction (default: queue as discovery hints) |
--allow-private-targets | bool | false | Optional | — | — | Allow the scanner to connect to private/loopback/link-local addresses and the cloud metadata IP (disables the SSRF egress guard). Auto-enabled when --url already resolves to a private/loopback host. |
Analyzers and imports
Scroll the table horizontally to inspect every column.
| Option | Type | Default | Requirement | Configuration | Environment | Description |
|---|---|---|---|---|---|---|
--checks | stringSlice | auth,injection,deps (runtime) | Optional · Repeatable | — | — | Override checks when the Python whitebox engine runs (default: auth,injection,deps). --code auto-enables that phase unless --python-engine=false is explicit; the native Go scanners run independently.auth · injection · deps |
--python-engine | bool | auto-enabled by --code unless explicitly false | Optional | — | — | Spawn the Python whitebox engine for auth/injection/deps checks (TASK-118). --code enables it automatically unless --python-engine=false is explicit. Standalone binaries do not bundle the engine; provide a local python/ tree or FENDIX_ENGINE (the official container supplies one). |
--fast | bool | false | Optional | — | — | Skip semgrep and the native dependency scanners. Known limitation: --fast does not disable the Python engine auto-enabled by --code; add --python-engine=false when a native-only pre-commit scan is required. |
--no-native-deps | bool | false | Optional | — | — | Disable the in-process Go dep-CVE scanner (TASK-119). Defer to the Python deps.py path instead. |
--use-pip-audit | bool | false | Optional | — | — | Shell out to the pip-audit binary for Python dep-CVE scanning instead of the native OSV.dev client. Falls back to OSV.dev with a warning if pip-audit is not on PATH. |
--offline | bool | false | Optional | — | — | Use the local offline-db snapshot for native pip/npm CVEs and skip native govulncheck (create the snapshot with 'fendix db update'). Known limitation: the Python deps check auto-enabled by --code does not receive this flag and may run networked tools; for a hermetic scan add --checks auth,injection or --python-engine=false. |
--offline-db | string | ~/.fendix/offline-db.json (runtime) | Optional | — | — | Path to the offline-db snapshot (default: ~/.fendix/offline-db.json). Only effective with --offline. |
--no-plugins | bool | false | Optional | — | — | Disable out-of-tree plugin discovery in .fendix/plugins/ + ~/.fendix/plugins/ |
--allow-repo-local-plugins | bool | false | Optional | — | — | Opt in to running repo-local plugins under <scan-dir>/.fendix/plugins/ (UNSAFE on untrusted PRs; ~/.fendix/plugins/ is always trusted) |
--import | stringSlice | — | Optional · Repeatable | — | — | Merge findings from another scanner's SARIF 2.1.0 file into this scan (repeatable). Imported findings go through the standard pipeline; a native fendix finding at the same weakness+location becomes strong cross-tool corroboration. See also the standalone 'fendix import' command. |
Decisions and coverage
Scroll the table horizontally to inspect every column.
| Option | Type | Default | Requirement | Configuration | Environment | Description |
|---|---|---|---|---|---|---|
--fail-on | string | — | Optional | fail_on | — | Exit 1 if a finding at this severity reaches BLOCK: CRITICAL, HIGH, MEDIUM, LOW (confidence gating applies — see --enforce-confidence)CRITICAL · HIGH · MEDIUM · LOW |
--enforce-confidence | bool | true | Optional | scan.enforce_confidence | — | Only BLOCK a finding at or above --fail-on when the confidence band supports it AND something corroborates the claim: LOW band warns; a finding with no corroborating signal at all warns; MEDIUM band blocks only with an INDEPENDENT signal (cross-engine agreement, confirmed route, reachable taint path, proven path, payload-validated probe, cross-tool corroboration, contradicted authentication requirement); self-evident signals (direct response read, deterministic detection in production source, imported high-precision rule) gate at HIGH. Evidence is never suppressed. Pass --enforce-confidence=false to restore the legacy severity-only gate — findings that block only because of that relaxation are marked policy_override in the report. |
--deescalate-tests | bool | true | Optional | scan.deescalate_tests | — | Report findings in test/fixture code as INFO instead of WARN (evidence is preserved, never suppressed). A finding at or above --fail-on can still block when independent corroboration supports it; an unsupported test-code match is held at WARN. Pass --deescalate-tests=false to treat test-code findings like production ones. |
--block-on-inapplicable | bool | false | Optional | — | — | Gate the build on a vulnerable dependency even when Fendix found no import of the advisory's affected component. Default false: such a finding is reported in full and held at WARN, because the vulnerable code path is not applicable to this project on the available evidence. Set this when policy is "no vulnerable version ships, applicable or not" — e.g. where the SBOM is what gets audited rather than the call graph. |
--fail-on-scanner-error | bool | false | Optional | — | — | Exit non-zero (2) if any recorded analyzer — any entry in metadata.scanner_status, which is the full registry (dast, spec, active-probes, secrets, textscan, semgrep, govulncheck, pip, npm, plugins, the python-engine and its checks) — ran and errored. CI-friendly: turns a silent coverage gap into a build failure. Skipped entries never count. |
--fail-on-coverage-gap | bool | false | Optional | — | — | Exit 2 when an analyzer this run was configured to execute was unavailable or failed (metadata.coverage.configured_complete=false). Disabled, not-applicable and unsupported analyzers never trip it. |
--require-analyzers | stringSlice | — | Optional · Repeatable | — | — | Comma-separated analyzer names that must be delivered (recorded ok or not_applicable) for exit 0; anything else exits 2. Stricter than --fail-on-coverage-gap: a required analyzer disabled by another flag is a contradiction and exits 2. Names: dast, spec, active-probes, secrets, textscan, semgrep, govulncheck, pip, npm, python-engine, python-engine/auth, python-engine/injection, python-engine/deps, pluginsdast · spec · active-probes · secrets · textscan · semgrep · govulncheck · pip · npm · python-engine · python-engine/auth · python-engine/injection · python-engine/deps · plugins |
Policy and history
Scroll the table horizontally to inspect every column.
| Option | Type | Default | Requirement | Configuration | Environment | Description |
|---|---|---|---|---|---|---|
--config | string | .fendix.yaml in cwd (auto-detect) | Optional | — | — | Path to .fendix.yaml policy file (default: auto-detect .fendix.yaml in cwd) |
--baseline | string | — | Optional | — | — | Path to a baseline (from --save-baseline) or JSON report; only occurrences not proven present in it are reported |
--save-baseline | string | — | Optional | — | — | Save current findings, with every occurrence identity, to this path (baseline format v2) |
--ignore | string | — | Optional | ignore_path | — | Path to .fendix-ignore file |
--diff | string | — | Optional | — | — | Diff-aware scan against a git ref (bare --diff = vs HEAD, --diff=origin/main = vs that ref). The native secrets, text and Semgrep scanners read only the changed files, whole files, so existing issues in them are reported; dependency-CVE scanners run only when a manifest changed and then report its full set; the Python engine, DAST and plugins always scan the full target. If git diff fails, or a changed file cannot be placed under --code (as when --code is a subdirectory of the repository), the scan falls back to a full scan. |
--staged | bool | false | Optional | — | — | Diff-aware scan over staged changes only (git diff --cached). Implies --diff. This is what the pre-commit hook runs. |
Output and diagnostics
Scroll the table horizontally to inspect every column.
| Option | Type | Default | Requirement | Configuration | Environment | Description |
|---|---|---|---|---|---|---|
-o, --output | string | — | Optional | — | — | Output file path (default: stdout) |
-f, --format | string | json | Optional | scan.format | — | Output format: json, html, sarif, pdfjson · html · sarif · pdf |
--lang | string | en | Optional | — | — | HTML report language: en (default), ar (Arabic, RTL). Other formats stay English.en · ar |
--debug-bundle | string | — | Optional | — | — | Write a redacted diagnostic tarball to this path at scan end (intended for bug reports) |
-v, --verbose | bool | false | Optional | — | — | Print all requests and raw findings |