Skip to content
Generated from cxg --help. Report problems against cert-x-gen, not this page.

cxg pentest

The AI-driven whitebox pentest pipeline, its auth subcommands, and every flag.

Whitebox pentests for web/Electron; Tauri source maps and optional in-process proof

Web/Electron: reads whitebox/findings.sarif produced by guardlink, ranks threats against an operator goal, and asks your local AI CLI (claude / codex / gemini) to write JavaScript probe templates that read the target’s source to craft code-aware payloads. Those templates execute in N parallel authenticated Chromium contexts, emitting confirmed/refuted/ambiguous findings to a JSON report plus a JSONL audit log of every HTTP request.

Tauri instead maps IPC commands and capability grants against the threat model; --tauri-prove opts into command proof in a headless harness, without a live webview.

Web/Electron capabilities:

  • Interactive auth capture for SSO/MFA flows (no need to script logins)
  • Chained-auth probes (IDOR cross-user) via --auth-numbers 2+
  • Pre-flight identity inspection — landing-test based, no /me-path required
  • Goal-driven LLM ranking of guardlink hypotheses
  • Validator-guarded code-generation with hard 240s timeout per AI call
  • Retry-with-mutation on AMBIGUOUS triage (max N retries, env-bound skip)
  • Scope enforcement (URL/method allowlist, per-endpoint budget, 5xx hard-kill)
  • Cookie-jar primitives in templates (HttpOnly-aware via Playwright)
  • Out-of-band callbacks in two modes: inject a canary cxg cannot read (--oast), or register one cxg owns and polls (--oast-interactsh) — only the second yields an in-band blind-vuln confirmation
  • Per-profile custom headers (WAF bypass, internal-test headers)
  • Split report: confirmed_findings vs mitigation_verifications vs ambiguous
cxg pentest [OPTIONS] <COMMAND>
Subcommand Summary
install Safely install the pipeline; check (but never install) Python dependencies. Explicit development installs retain source discovery, including CXG_SOURCE
update Refresh from this binary’s embedded bundle, offline; preserve previous files
status Inspect pipeline content without Python, filesystem writes, or recovery
capabilities Print installed orchestrator capabilities as JSON (no target contact)
auth Capture — or, via a subcommand, import/verify — an authenticated session profile
auth-list List saved auth profiles under ~/.cert-x-gen/auth/
scope-init Write an example scope.yaml the operator can edit
run Run the full end-to-end pentest pipeline against a target

The global options apply here too.

Full trailing help from cxg pentest --help
TARGETS:
web: live browser probes; --codebase and --target required, --auth optional.
electron: live desktop probes; also requires --app-cmd or --app-binary.
tauri: source map of IPC commands and capability grants correlated with GuardLink.
Requires --codebase with whitebox/findings.sarif; no --target, --auth or launch command needed.
Default report: tauri_surface_mapped, caveat enumerated_not_live_probed.
An empty findings list does not establish safety: no commands were invoked.
--tauri-prove builds an app copy for headless in-process command proof, without a live webview.
Local CLI binaries use cxg scan --scope cli://<binary>, not pentest run.
EXAMPLES:
cxg pentest install
guardlink sarif ./app-repo -p my-app -o ./app-repo/whitebox/findings.sarif
cxg pentest run --target-type tauri --codebase ./app-repo
cxg pentest run --target-type tauri --codebase ./app-repo --tauri-prove --tauri-prove-timeout 1200

Safely install the pipeline; check (but never install) Python dependencies. Explicit development installs retain source discovery, including CXG_SOURCE

cxg pentest install [OPTIONS]
Option Description
--force Refresh even when current, preserving the previous tree as a backup

The global options apply here too.

Refresh from this binary’s embedded bundle, offline; preserve previous files

cxg pentest update [OPTIONS]
Option Description
--json Print only a machine-readable result on stdout
--from-embedded Explicitly replace a source-derived installation with the embedded bundle

The global options apply here too.

Inspect pipeline content without Python, filesystem writes, or recovery

cxg pentest status [OPTIONS]
Option Description
--json Print binary version, digests, origin, freshness and interrupted state

The global options apply here too.

Print installed orchestrator capabilities as JSON (no target contact).

Reports protocol features such as exact-threat-id, not target-type support or evidence that a target was tested. See cxg pentest run --help for web, Electron and Tauri targets; local CLI binaries use cxg scan --scope cli://<binary>. Requires cxg pentest install first. Example: cxg pentest capabilities

cxg pentest capabilities [OPTIONS]

The global options apply here too.

Capture — or, via a subcommand, import/verify — an authenticated session profile

Capture supports web and Electron only. Tauri source maps and in-process proofs need no captured profile; use cxg pentest run --target-type tauri --codebase ./app-repo. Local CLI scans need no browser auth profile either.

With no subcommand this captures interactively: it spawns a real headed Chromium window. You log in by ANY means — username/password, SSO redirect, MFA prompt, hardware key, magic link, OAuth popup. When the app dashboard is showing, press ENTER in the terminal (or close the browser) and cxg snapshots cookies + localStorage + sessionStorage from every origin the browser touched. The profile is saved at ~/.cert-x-gen/auth/<profile>.json plus metadata at <profile>.meta.json.

A post-capture landing-test verifies the session works: it re-opens a fresh browser context with the saved state, navigates to --target, and checks whether the final URL/page looks like a login or the app dashboard.

Use --auth-numbers N for chained-auth scenarios (e.g. IDOR testing needs two different identities). cxg prompts for a human-readable label for each capture.

For CI, where no human can drive a browser, use the subcommands instead: cxg pentest auth import replays a session captured once and exported as a Playwright storage_state, with no browser; cxg pentest auth verify checks a saved session is still alive (exit 0 alive / non-zero dead) before a run spends any AI budget.

Examples: # Single interactive capture (no subcommand) cxg pentest auth --target https://app.example.com --profile admin
# Two identities for chained-auth (e.g. IDOR victim + attacker) cxg pentest auth --target https://app.example.com --profile pentest --auth-numbers 2
# Scripted login (no browser pop-up) cxg pentest auth --target https://app.example.com --profile bot \ --creds 'user@example.com:hunter2' --login-path /api/auth/login
# Capture a profile that sends a WAF-bypass header on every request cxg pentest auth --target https://app.example.com --profile pentest \ --header "x-test-automation:abc123xyz"
# CI: import a session captured once, then verify it before a run cxg pentest auth import --profile pentest --target https://staging.app \ --storage-state ./pentest.storage.json cxg pentest auth verify --profile pentest
cxg pentest auth [OPTIONS]
Subcommand Summary
import Import a saved Playwright storage_state as a profile (no browser)
verify Check a saved web session is still alive (exit 0 alive / non-zero dead)
Option Description
--target <TARGET> Target URL where login happens (e.g. https://app.example.com). After capture, the landing-test verifier opens this URL with the saved cookies; if it doesn’t bounce to a login page, the session is alive. Required for interactive capture (no subcommand). The import/verify subcommands take their own --target instead.
--profile <PROFILE> Profile name. If --auth-numbers > 1, this is the PREFIX and final profiles are named <profile>-1, <profile>-2, etc. Use a stable name so subsequent cxg pentest run --auth <profile> invocations can reload it. Required for interactive capture (no subcommand).
--auth-numbers <AUTH_NUMBERS> Number of profiles to capture in sequence. Each capture opens its own Chromium window and prompts for a label (e.g. “victim”, “attacker”, “admin”). Required ≥2 for chained-auth probes like IDOR cross-user tests Default: 1.
--creds <CREDS> Inline credentials email:password for scripted login (skips browser pop-up). Only works for password-based auth — SSO/MFA flows MUST use interactive capture
--creds-file <CREDS_FILE> File with profile:email:password[:label] per line for scripted batch capture. Useful for re-auth between scans of password-only test apps
--login-path <LOGIN_PATH> Endpoint path for scripted login POST. Only used with --creds or --creds-file. The captured browser will POST {email, password} as JSON to <target><login-path> Default: /api/auth/login.
--label <LABEL> Human-readable label for the profile (e.g. “admin”, “low-priv-user”). Shown in scan output to make findings readable. Does not affect behavior
--verify-url <VERIFY_URL> Authenticated API liveness endpoint checked after capture and saved with the profile for later verification. Defaults to /api/me
--header <NAME:VALUE> Custom HTTP header NAME:VALUE sent on every outbound request from this profile’s browser context — including login, every scan probe, every health check. Repeatable for multiple headers. Saved with the profile so future cxg pentest run --auth <profile> invocations reuse them automatically. Use case: WAF-bypass tokens granted by infra (e.g. x-test-automation), internal-test headers, custom forwarding hints. SECURITY: header values are stored in plaintext under ~/.cert-x-gen/auth/<profile>.meta.json. Treat the file like a credential. chmod 600 if your machine has multiple users. Delete the profile when the engagement ends. Header values are sent to EVERY origin the browser touches, including IDPs — keep this in mind for SSO flows.
--tier <TIER> Explicit privilege rank for this identity: an integer 0-100 or an alias high/medium/low (= 90/50/10). Overrides the role-based heuristic and is fed to the AI ranker so it selects the right identity per probe (lowest tier for privesc, etc.). Omit to auto-derive from the app’s role. In multi-capture (--auth-numbers > 1) this pre-fills the per-identity prompt
--persona <PERSONA> Semantic role hint (e.g. “billing-analyst”) passed to the AI as extra context — useful when the app’s /me endpoint exposes no clear role field
--cohort <COHORT> Peer-group name (e.g. “analyst-team-a”). Give two SAME-permission, DIFFERENT-user sessions the same cohort so the AI treats them as peers and targets horizontal IDOR / cross-tenant access between them
--tag <NAME=VALUE> Free-form NAME=VALUE context attached to the profile and shown to the AI. Repeatable
--target-type <TARGET_TYPE> Target type to capture auth for. web (default): the existing authenticated-browser capture against an HTTP application. electron: launch the Electron desktop app and capture its session state instead of a browser’s. Auth capture does not support Tauri. Its source map and optional in-process proof need no captured profile; select tauri on cxg pentest run instead. Default: web.
--app-cmd <APP_CMD> Command that launches the desktop app, e.g. “npm run electron:dev”. Required with --target-type electron unless --app-binary is given. cxg appends --remote-debugging-port and a per-identity --user-data-dir.
--app-binary <APP_BINARY> Path to a built desktop app, e.g. /Applications/Foo.app. Alternative to --app-cmd; the two are mutually exclusive.
--auth-dir <AUTH_DIR> Auth profile directory (also honours CERT_X_GEN_HOME)

The global options apply here too.

Import a saved Playwright storage_state as a profile (no browser)

The CI-replay primitive: a human captures a session once locally (SSO, MFA and all), exports the Playwright storage_state, and every pipeline run injects it here without a display or a human. The written profile is byte-for-byte what an interactive capture produces, so a later cxg pentest run --auth <profile> cannot tell an imported profile from a captured one.

Examples: # From a file on disk cxg pentest auth import --profile pentest --target https://staging.app \ --storage-state ./pentest.storage.json
# From stdin (a CI secret piped straight in, never written to disk in the clear) cat "$SESSION_SECRET" | cxg pentest auth import --profile pentest \ --target https://staging.app --storage-state -
# From the base64 env var, into a restored bundle dir, CI-strict cxg pentest auth import --profile pentest --target https://staging.app \ --auth-dir ./ci-auth --ci
cxg pentest auth import [OPTIONS] --profile <PROFILE> --target <TARGET>
Option Description
--profile <PROFILE> Profile name. A subsequent cxg pentest run --auth <profile> loads it exactly like a captured one
--target <TARGET> Target URL this session authenticates against. Recorded in the profile. A run sends this identity’s traffic to its own --scope/--target; the saved origin is used instead only when --service is also given
--storage-state <PATH|-> Path to a Playwright storage_state JSON, or - to read it from stdin (a CI secret pipes straight in, never touching disk in plaintext beyond the profile dir). Omit to materialise it from the base64 env var CXG_AUTH_STATE_<NAME> instead (NAME is the profile name uppercased with non-alphanumerics folded to underscore — e.g. profile pentest-alice reads CXG_AUTH_STATE_PENTEST_ALICE)
--label <LABEL> Human-readable label (e.g. ‘admin’), shown in scan output
--tier <TIER> Explicit privilege rank: an integer 0-100 or an alias high/medium/low. Same meaning as on capture
--persona <PERSONA> Semantic role hint passed to the AI as extra context
--cohort <COHORT> Peer-group name for horizontal IDOR / cross-tenant tests
--tag <NAME=VALUE> Free-form NAME=VALUE context attached to the profile. Repeatable
--header <NAME:VALUE> Custom HTTP header NAME:VALUE sent on every request from this profile (e.g. a WAF-bypass token). Repeatable. Stored as a credential; values are never echoed
--liveness-path <LIVENESS_PATH> Authenticated API liveness path on this service (default /api/me)
--liveness-status <LIVENESS_STATUS> Expected HTTP status, repeatable (default any 2xx; 401/403 always fail)
--service <SERVICE> Service name included in readiness receipts. Opts this profile into multi-service: its saved --target origin, not the run’s target, receives its traffic and liveness check
--auth-dir <AUTH_DIR> Write into this auth directory instead of ~/.cert-x-gen/auth. A pipeline restores a bundle of profiles into one dir and points the run at it with the same flag
--ci Non-interactive CI mode: refuse a world-accessible --auth-dir rather than write a credential a fellow user could read. Also enabled by CXG_CI=1

The global options apply here too.

Check a saved web session is still alive (exit 0 alive / non-zero dead)

An API liveness gate for a saved session, shared with scan-time pre-flight. A pipeline runs this before spending a whole run, and re-captures (or re-imports) when it fails.

Example: cxg pentest auth verify --profile pentest || echo "session expired, re-import"
cxg pentest auth verify [OPTIONS] --profile <PROFILE>
Option Description
--profile <PROFILE> Profile name to verify
--target <TARGET> Override the profile’s saved target (a profile imported with --service keeps its own)
--me-path <ME_PATH> Authenticated API endpoint (default /api/me); per-profile liveness_check wins. When neither is configured and /api/me is absent, the landing test decides Default: /api/me.
--auth-dir <AUTH_DIR> Read the profile from this auth directory instead of ~/.cert-x-gen/auth

The global options apply here too.

List saved auth profiles under ~/.cert-x-gen/auth/

Shows profile name, label, target URL, and whether extra_headers are present. Useful before running cxg pentest run --auth <name> to confirm which profile you’ll be scanning as.

cxg pentest auth-list [OPTIONS]
Option Description
--auth-dir <AUTH_DIR> Read saved profiles from this directory

The global options apply here too.

Write an example scope.yaml the operator can edit

scope.yaml controls the safety rails for a scan: method allowlist (default GET/POST/HEAD/OPTIONS — DELETE/PUT/PATCH require --destructive-ok), URL allow/blocklist regexes, per-endpoint and total request budgets, 5xx-streak hard-kill threshold, and the authorization_attestation field that’s recorded in the audit log header.

Example: cxg pentest scope-init -o my-engagement-scope.yaml
cxg pentest scope-init [OPTIONS]
Option Description
-o, --output <OUTPUT> Output file path. Default: scope.yaml in the current directory Default: scope.yaml.

The global options apply here too.

Run the full end-to-end pentest pipeline against a target

Targets: web and Electron use live probes. Tauri maps IPC commands and JSON capability grants from source, correlated with the GuardLink threat model. Install with cxg pentest install and generate whitebox/findings.sarif with guardlink sarif . -p my-app -o whitebox/findings.sarif in the app repository. Tauri requires --codebase; no --target, --auth or app launch command is needed. Keep the default --template-lang js: the legacy py pipeline rejects Tauri.

A default Tauri report is tauri_surface_mapped with enumerated_not_live_probed: commands are not invoked, and empty findings do not establish safety. Opt in with --tauri-prove for headless in-process command proof; this needs a Rust toolchain and the app’s build prerequisites, and does not drive a live webview.

Web/Electron pipeline steps: [1] Load guardlink hypotheses from <codebase>/whitebox/findings.sarif [1b] Inspect captured auth profiles via landing-test (profile_inspect.inspect_profiles_async) [2] LLM-rank hypotheses against --goal + profile coverage; AI generates JS templates that read source via Claude/Codex/Gemini’s own Read/Grep tools [3] Load + statically validate templates (validator.py) [4] Open N parallel authenticated Chromium contexts; inject the cxg JS bridge [5] Run each template; triage findings (CONFIRMED / REFUTED / AMBIGUOUS); mutate-and-retry on payload-fixable AMBIGUOUS, skip environment-bound [6] Write report.json and audit.jsonl to --session-dir

The full set of probes available to templates is documented in pentest/docs/TEMPLATES.md. The runtime intelligence layer (validator, scope, session health, mutation, triage, audit) is in pentest/docs/ARCHITECTURE.md.

Examples: # Single-profile read-only scan with default settings cxg pentest run --codebase ./repo --target http://localhost:8000 \ --auth admin --ai --ai-provider claude
# Two identities for IDOR/chained-auth, AI off → built-in probes only cxg pentest run --codebase ./repo --target http://localhost:8000 \ --auth victim,attacker
# Verify mitigations only (skips unmitigated threats so you can confirm # declared defenses hold at runtime). Useful for well-annotated codebases. cxg pentest run --codebase ./repo --target https://staging.app \ --auth pentest --ai --ai-provider claude \ --mitigation-mode mitigated --max-templates 16
# SSRF testing against a canary cxg OWNS — it registers the interactsh # session and polls it, so a callback becomes a confirmed finding cxg pentest run --codebase ./repo --target https://staging.app \ --auth pentest --ai --ai-provider claude \ --oast-interactsh \ --goal "verify SSRF on /slack/proxy via OAST callback"
# Same probes, but against a canary cxg can only inject into (e.g. a Burp # Collaborator host). Templates build the URL; YOU read the hit in # Collaborator. Findings stay unconfirmed as far as cxg is concerned. cxg pentest run --codebase ./repo --target https://staging.app \ --auth pentest --ai --ai-provider claude \ --oast c4ca4238a0b92.oastify.com \ --goal "test SSRF on /slack/proxy; check Collaborator for callbacks"

Exit codes: 0 → no confirmed findings (clean scan) 1 → no templates available (guardlink output missing or empty, or every template in a replayed --template-dir was withheld for carrying no // @attach_scheme: path header); report.json is still written 2 → confirmed findings present 3 → scan was hard-killed (5xx streak, scope violation) OR, under --no-restart, a desktop target died mid-scan and was not relaunched 4 → mis-specified run, refused at pre-flight before any probing: a --scope-file cxg cannot read (missing, unreadable, invalid YAML, not a mapping, empty file, or PyYAML absent), --scope-file with --template-lang py, --target-type electron without --app-cmd/ --app-binary, --oast together with --oast-interactsh, or an auth profile whose kind does not match the target substrate 5 → a selected auth profile or service is dead, expired, or unverified by its configured liveness endpoint, with or without --ci; probes for ready services still run, and the report is complete: false, status: incomplete. A blocked or failed request does not change the exit code; it is listed in request_failures and also makes the report status: incomplete

cxg pentest run [OPTIONS] --codebase <CODEBASE>

Options

Option Description
--insecure-tls Ignore server TLS certificate errors for web browser and raw HTTP requests
--proxy <PROXY> Proxy server URL for web browser and raw HTTP requests
--client-cert <CLIENT_CERT> PEM client certificate for the target origin
--client-key <CLIENT_KEY> PEM private key for the client certificate

Authentication

Option Description
--auth <AUTH> Comma-separated auth profile names previously captured via cxg pentest auth. Probes that need multiple identities (IDOR cross-user, session-replay-against- victim) require ≥2 profiles. The lowest-privilege identity is auto-selected as the actor for privesc-class probes. Empty means a first-class anonymous (no-login) web/Electron run, not interactive capture. Tauri source maps and in-process proofs need no --auth profile. Default: ``.
--auth-profile <AUTH_PROFILE> Name prefix for --interactive-auth captures Default: pentest.
--interactive-auth <INTERACTIVE_AUTH> Open N headed browser windows for interactive login at scan start, then run the pipeline with the resulting fresh profiles. Each capture prompts you for a per-identity label. Use this when your captured profiles have expired or when you don’t want to manage profile lifecycle separately. Profiles are saved as <--auth-profile>-1, <--auth-profile>-2, etc. Default: 0.
--auth-numbers <AUTH_NUMBERS> Minimum auth contexts the scan requires
--creds-file <CREDS_FILE> File of profile:email:password[:label] lines used to AUTO RE-AUTH a dead session mid-scan (the session-health monitor detects death via the landing test). Without this, a probe that kills its own session — e.g. session_replay’s logout — leaves remaining probes unable to run. Recommended for any scan with --mutation-retries > 0 or scans with SessionReplay / Csrf class templates.
--me-path <ME_PATH> Authenticated API liveness endpoint (default /api/me; per-profile setting wins) Default: /api/me.
--skip-health-check Skip periodic health checks (startup API verification still runs; a dead profile still exits 5)
--auth-dir <AUTH_DIR> Read auth profiles from this directory instead of ~/.cert-x-gen/auth. A CI pipeline restores a bundle of profiles (imported via cxg pentest auth import --auth-dir <dir>) into its own directory and points the run at the same directory here, so pre-flight, the engine, and the health monitor all read the restored bundle rather than the operator’s home store.
--ci Non-interactive CI mode: refuse a world-accessible --auth-dir. When credentials are in use, a world-accessible --auth-dir is refused (exit 4) rather than trusted. A dead or expired auth session exits 5 with or without this flag, and --skip-health-check does not bypass that: startup API verification still runs and a profile it cannot prove alive still fails the run. Also enabled by the environment variable CXG_CI=1, for pipelines that cannot add the flag to the invocation.

Execution

Option Description
--scope-file <SCOPE_FILE> Path to scope.yaml. Default: safe permissive defaults (any URL, GET/POST/HEAD/ OPTIONS, 30 reqs/endpoint, 1500 reqs total, kill on 8-streak 5xx). Generate one with cxg pentest scope-init. If this flag is given and the file cannot be read — path does not exist, unreadable, invalid YAML, not a mapping, empty, or PyYAML not installed — the run is REFUSED with exit 4. It does not fall back to the defaults: a bound cxg cannot read is not the same as no bound. Omitting the flag entirely is the supported way to run on the defaults. An empty value never reaches that check and is not ignored either: --scope-file "$SCOPE" with SCOPE unset is rejected by the CLI parser as a usage error (exit 2, a value is required for '--scope-file <SCOPE_FILE>' but none was supplied) before the scan starts. Refused with exit 4 on --template-lang py as well: the legacy Python probe path enforces no scope at all, so a file accepted there would be discarded.
--destructive-ok Allow DELETE/PUT/PATCH methods AND paths matching destructive regexes (/wipe, /delete-all, /factory-reset, etc.) in scope.yaml. Default OFF. Required for templates that test destructive-action authz. USE WITH CARE on production targets. The engine emits a warning at startup and every blocked request is still recorded in the audit log.
--headed Show Chromium windows instead of running headless
--template-timeout <TEMPLATE_TIMEOUT> Per-template dispatch ceiling, seconds (backstop; default 900)
--stall-timeout <STALL_TIMEOUT> Idle-time stall timeout, seconds (electron only; default 90)
--no-restart Do NOT relaunch a desktop target that dies mid-scan. Default is to restart it (max 2 per instance, 3 per run), report the crash as a denial_of_service finding, re-probe the suspected IPC channel once and then quarantine it. With this flag a dead target ends the scan with a truncation caveat and exit 3 — the pre-recovery behaviour.
--attestation <ATTESTATION> Free-text written authorization statement recorded in the audit log header. Include engagement ID, operator name, change-management ticket, etc. Example: “Engagement PT-2026-003, operator J. Doe, ticket CHG-1234” Strongly recommended for any non-local scan. The audit log header is the dispute-ready record of “I had authorization to do this scan.”

Probe execution

Option Description
--auth-inputs <JSON> Operator-owned configuration for IMAP and needs-you questions
--attacker-origin Run cross-site probes (CSRF, CORS, clickjacking) from a loopback origin cxg controls, in the same browsing context as the identity under test. Without this, those classes are reported as NOT PROBED rather than tested from the target’s own origin. A same-origin probe of them is unsound: an app defended only by an Origin check accepts cxg’s own-origin request, so the probe confirms an attack a real cross-site attacker could never land.
--allow-raw-socket Permit cxg.socket: raw TCP/TLS bytes with no HTTP client in between. Required for request smuggling, desync and header-order attacks, which no HTTP client can express — both window.fetch and Playwright’s APIRequestContext normalise the framing that IS the payload for those classes. Can desync connections or wedge a server.
--allow-grpc Permit native gRPC (HTTP/2) probes against bare gRPC services
--grpc-descriptor-set <FILE> protoc FileDescriptorSet for typed gRPC messages
--no-grpc-reflection Do not use gRPC server reflection to learn message types
--enable-chaining Let a probe hand a fact it discovered to a later probe. Templates declare @provides: <name> / @requires_artifact: <name>; cxg orders providers before consumers and passes the value through a per-run store. Edges are also derived automatically from guardlink @flows.
--capture-http Save redacted per-template HARs and curl reproductions for web JS probes

Output

Option Description
-o, --output <OUTPUT> JSON report output path (default report.json in session dir)
--session-dir <SESSION_DIR> Session artifacts directory (audit.jsonl, report.json)

Target

Option Description
--codebase <CODEBASE> Source codebase root (contains whitebox/findings.sarif)
--target <TARGET> Running target app URL. Both http:// and https:// are supported. Every identity’s traffic and liveness check go to this target, unless a profile was imported with --service, which opts it into its own saved origin. Required for --target-type web and electron; omit it for --target-type tauri, which maps the IPC surface from source and navigates nowhere. A web/Electron run without --target is refused at preflight (exit 4).
--target-type <TARGET_TYPE> Target type to pentest. web (default): the existing authenticated-browser pipeline against an HTTP application. electron: launch N isolated instances of an Electron desktop app, drive their renderers over CDP, and additionally probe IPC channels, renderer configuration, and local data at rest. tauri: map a Tauri app’s IPC command and capability surface from source — the #[tauri::command] handlers, their generate_handler! registration, and the capabilities/*.json grants — and correlate it against the guardlink threat model. This is a source-surface MAP, not a live probe: a Tauri app exposes no CDP endpoint on macOS or Linux, so cxg cannot drive its webview the way it drives an Electron renderer. --target is not required for it, and the default report carries an enumerated_not_live_probed caveat. No command is confirmed or refuted unless --tauri-prove opts into the in-process harness. No --auth or app launch command is needed. Keep --template-lang js; py is rejected. EXAMPLES: cxg pentest run --target-type electron --app-cmd “npm run electron:dev” \ --codebase ./app-repo --target https://api.example.com --auth desk-1,desk-2 cxg pentest run --target-type tauri --codebase ./app-repo Default: web.
--app-cmd <APP_CMD> Command that launches the desktop app, e.g. “npm run electron:dev”. Required with --target-type electron unless --app-binary is given. cxg appends --remote-debugging-port and a per-identity --user-data-dir.
--app-binary <APP_BINARY> Path to a built desktop app, e.g. /Applications/Foo.app. Alternative to --app-cmd; the two are mutually exclusive.
--host-scan-path <HOST_SCAN_PATH> Additionally scan a real installation directory for data at rest. By default host probes read only the isolated user-data directories cxg created itself. Pass this to opt in to scanning an existing install.
--tauri-prove For --target-type tauri: after mapping the IPC surface, build an in-process proof harness against the app’s own crate (Tauri’s test feature) and drive ranked commands through get_ipc_response with hostile arguments, feeding confirmed / refuted / unevaluated into the findings. Needs a Rust toolchain; a command the harness cannot drive is skipped with a reason, never refuted. Copies the app to the session’s tauri-harness/ and runs cargo test using a headless MockRuntime. Probes cover sentinel-based path traversal and renderer-controlled authorization arguments. A confirmation proves observed harness behavior; a refutation covers only attempted arguments. It does not test live navigation, DOM behavior or clickjacking, nor reproduce the app’s full setup or capability configuration. Review caveats, ambiguous and tauri_skipped_commands; build failures do not establish safety.
--tauri-prove-timeout <TAURI_PROVE_TIMEOUT> Combined seconds budgeted for the --tauri-prove harness build and run. Used only for Tauri proof; default 1200. Example: --tauri-prove-timeout 1200 Default: 1200.

AI Generation

Option Description
--threat-id <THREAT_ID> Exactly select imported hypotheses carrying this GuardLink id before ranking. Unknown ids refuse before target contact. Requires JS generation on web/electron; disables unrelated discovery, boundary and host probes. Not authorization
--ai Enable AI-driven template generation
--ai-provider <AI_PROVIDER> AI provider. auto prefers the editor bridge when $BUGB_BRIDGE_URL is set, then the first available CLI tool (claude > codex > gemini), falling back to ANTHROPIC_API_KEY / OPENAI_API_KEY HTTP APIs. Otherwise specify explicitly. CLI providers don’t need API keys — they use your existing CLI auth. Options: auto | bridge | claude | codex | gemini | anthropic | openai bridge posts each prompt to $BUGB_BRIDGE_URL (with Authorization: Bearer $BUGB_BRIDGE_TOKEN when set) and reads the completion back — an editor/CI integration point rather than a local CLI. Default: claude.
--goal <GOAL> Natural-language pentest goal. Used as context for both LLM-based hypothesis ranking AND template generation. Be specific about which vuln classes, endpoints, or claims you want tested. Examples: “test for IDOR in records and transactions APIs” “verify each declared @mitigates actually holds at runtime” “find unguarded admin endpoints accessible to non-admin tokens”
--max-templates <MAX_TEMPLATES> Max templates the LLM ranker may select Default: 8.
--mutation-retries <MUTATION_RETRIES> Max AI mutation retries on AMBIGUOUS triage Default: 2.
--generation-timeout <GENERATION_TIMEOUT> Hard wall-clock timeout per AI generation call. The whole process tree is killed if exceeded. Default 240s. Claude CLI typically takes 60-170s per template; Codex 90-220s; Gemini 30-180s. Bump to 600+ for very large codebases the AI has to grep through. Default: 240.
--template-lang <TEMPLATE_LANG> Template language: js (default; required for Tauri/Electron) or py (legacy web) Default: js.
--template-dir <TEMPLATE_DIR> Reuse JS templates from a previously-generated session directory. Skips the AI generation step entirely. Useful for re-running the same templates against different targets, or after fixing engine bugs that affected template execution. Template directories are at ~/.cert-x-gen/templates/session-<timestamp>-<pid>/. JS probes are discovered recursively, using scan’s exclusions for build artifacts, dependencies, disabled templates and skeleton directories. Scanner templates are refused: convert them separately with guardlink translate --from <template> --contract probe using a GuardLink version that supports probe translation. cxg never converts on replay. A template carrying no // @attach_scheme: path header is WITHHELD — never executed — and named in a templates_withheld caveat in report.json, because it may have been generated under a same-named file’s intent context. See pentest/docs/ARCHITECTURE.md for the rule and the remedy for each case.
--mitigation-mode <MITIGATION_MODE> Hypothesis filter: any|unmitigated|mitigated Default: any.

OAST

Option Description
--oast <HOST> An external out-of-band callback host cxg can INJECT INTO but cannot read back (Burp Collaborator, a canary you host, an interactsh domain you generated yourself). Exposed to templates as cxg.oast.url(label, scheme?) so payloads carry a callback URL — but cxg never learns whether it fired, so nothing here confirms anything: blind probes (SSRF, blind SQLi, blind XXE, blind cmd-injection) still fall back to status-code heuristics and timing, and the AI prompt is instructed to mark them confirmed=false. Reading the callback is the operator’s job, in their own tooling. Want cxg to do the confirming? Use --oast-interactsh instead. Example: --oast c4ca4238a0b923820dcc.oastify.com If the host is an interactsh domain rather than a Collaborator one, run interactsh-client in another terminal first and paste the hostname it prints — that terminal is the only place these callbacks become visible. (With --oast-interactsh there is no second terminal: cxg is the client.)
--oast-interactsh [<SERVER_URL>] Register an interactsh session cxg OWNS and poll it — the mode that can actually confirm a blind vulnerability. Because cxg registered the session it holds the correlation id, so templates can call cxg.oast.poll(label), read the interactions back in-band, and a callback becomes a genuine confirmed=true finding with the interaction recorded as evidence. cxg is the interactsh client here; you do not run one alongside it. The optional value is the interactsh server to register against; omit it to use interactsh’s default public servers. Mutually exclusive with --oast. Two canaries would split payloads between a host cxg can poll and one it cannot, so “was this confirmed?” would have no single answer per finding. Examples: --oast-interactsh (default servers), or --oast-interactsh https://oast.example.internal (your own instance).
--oast-listener [<BIND>] Host a built-in OAST callback cxg OWNS and poll it, bound to an interface the TARGET can reach rather than to loopback — the mode that confirms a blind vulnerability (SSRF, XXE, command injection, SSTI, NoSQL, LDAP, deserialization) against a target with no internet egress, such as an env up sandbox or internal staging, where --oast-interactsh cannot (its public servers need egress) and --oast cannot be read back. cxg holds the listener, so templates call cxg.oast.poll(label) and a callback becomes a confirmed=true finding with the interaction as evidence. The label rides in the URL path (http://<host>/<label>), not a subdomain, because the bind address has no wildcard DNS under it. The optional value selects the bind: omit it or docker-bridge for the docker bridge gateway (reachable from a container on the default bridge), host-docker-internal for a Docker Desktop container, or an address/hostname (e.g. 10.0.0.5, or ip:10.0.0.5) for internal staging. Mutually exclusive with --oast and --oast-interactsh: one canary per run, or payloads split between callbacks nobody correlates per finding.
--oast-listener-dns Add a DNS leg to --oast-listener (needs udp/53)
--oast-redirect-location <URL> Default Location URL for redirects staged with cxg.oast.redirect(label)
--oast-redirect-status <OAST_REDIRECT_STATUS> Default HTTP redirect status (302 when omitted) [possible values: 302, 307]
--oast-dns-rebind-ip <IPV4> First A query per name returns the listener IPv4; later queries return this IPv4, all with TTL 0. The target resolver must reach this DNS server

Hypothesis filtering

Option Description
--discover-routes Discover routes from source instead of requiring guardlink annotations. guardlink only parses GAL annotations, so an un-annotated codebase yields zero hypotheses and the scan exits with “no templates available” having tested nothing. Measured on OWASP Juice Shop: guardlink 0, discovery 105.
--batch-size <BATCH_SIZE> Generate templates for N hypotheses per AI call instead of one each. Measured: 130-220s per AI template, so 105 routes cost ~4.5 hours. Default 1 is the existing per-hypothesis path, byte-for-byte. Default: 1.
--deterministic-templates Emit probes with no AI call at all for unambiguous shapes. Covers cross-identity IDOR reads and missing collection authorization — 47 of Juice Shop’s 105 discovered routes. These probes read no source, so they cannot cite a code-level cause; breadth, not depth.
--no-code-graph Do not read a code graph for this codebase. By default, when codegraph-mcp or bravos graph is installed and a graph has been built for the codebase, its route table leads --discover-routes and its reachable-sink ranking orders which hypotheses get templates. With no graph available the run is unchanged either way.
--only-routes <FILE> Test only the hypotheses whose route or enclosing function is listed in FILE. Entries are METHOD /path (ANY or * for every method; path templates and concrete paths match each other; a trailing * is a prefix), /path, file::Function or file:Function, one per line, or JSON — including a code graph’s route or attack-surface answer as written. Everything else is excluded before ranking and reported with its reason. An EMPTY list means nothing is in scope: the run exits 0 without contacting the target.
--only-route <ENTRY> One allowlist entry, e.g. ‘GET /api/users/{id}’ (repeatable)
--skills-file <FILE> Append the operator skills in FILE to AI generation and mutation prompts. Markdown written by a caller (bravos writes the skills its operator tagged for template authoring). Appended last, under an untrusted heading: it is advice on how to write a probe and never overrides the template rules.

Generation

Option Description
--no-author Guarantee zero model calls. Plain scan already replays selected scanner and JS probe templates without authoring. Explicit pentest runs require --template-dir and disable ranking, generation and mutation

The global options apply here too.

Full trailing help from cxg pentest run --help
SCAN FRONT DOOR:
cxg scan --pentest accepts every option listed above through the same pentest engine.
--scope URL aliases --target URL; --templates DIR aliases --template-dir DIR.
Supply one HTTP(S) URL; ports, CIDR, cli:// targets and scan-only filters are refused.
JS probes only; any-language probes are not yet supported. The legacy --template-lang py path remains available.
Convert scanner templates separately: guardlink translate --from <template> --contract probe
(requires a GuardLink version with probe translation; --no-author never converts).
--no-author --template-dir DIR guarantees zero model calls (ranking, generation and mutation disabled).
Pentest verdicts are engine-confirmed; ordinary scan findings remain template-reported.
TAURI EXAMPLES:
# Prepare the source threat model (after cxg pentest install)
guardlink sarif ./app-repo -p my-app -o ./app-repo/whitebox/findings.sarif
# Source map only; no commands invoked
cxg pentest run --target-type tauri --codebase ./app-repo
# Opt in to headless in-process command proof
cxg pentest run --target-type tauri --codebase ./app-repo --tauri-prove --tauri-prove-timeout 1200