Skip to content

Pentest a web application

cxg scan --pentest and cxg pentest run run the same whitebox pipeline: it reads guardlink’s threat hypotheses about a codebase, drives an authenticated browser against the running app, and writes confirmed, refuted, and ambiguous findings to a report. This guide sets up the two inputs it needs, a findings.sarif and a live session, and launches it against a target you host yourself.

flowchart TB
    GL["guardlink findings.sarif,<br/>inline annotations, endpoints"] --> HY["hypotheses"]
    CB["your source code"] --> SEL
    AP["captured auth profiles"] --> PF["pre-flight:<br/>which identity is this cookie?"]
    PF --> SEL["pick a probe per<br/>vulnerability class"]
    HY --> SEL
    SEL --> RUN["run probes in parallel<br/>authenticated browser contexts"]
    RUN --> TR["triage every result"]
    TR --> REP["report.json"]
    TR --> LOG["audit.jsonl"]

    class REP,LOG emphasis
  • cxg installed. See Installation.
  • The Python orchestrator installed: cxg pentest install. Run it once; it copies the pipeline into ~/.cert-x-gen/pentest/ and checks its Python deps.
  • For model-assisted authoring, an AI CLI on your PATH: claude, codex, or gemini. The pipeline asks it to write probe templates. Supplied-probe replay does not require a model.
  • A guardlink findings.sarif for the codebase. See feed guardlink findings into cxg. cxg reads it from <codebase>/whitebox/findings.sarif.

Any local app with a session works. The pipeline needs the app running (to probe) and its source on disk (for guardlink and for the AI to read). Point --target at the URL and --codebase at the source tree.

  1. Confirm the app has an authenticated API endpoint that refuses a request with no session.

    Terminal window
    curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8931/api/me
    401

    The session pre-flight calls this endpoint, /api/me by default. 401 or 403 means dead, a 2xx with the session’s cookies means alive. If your app has no /api/me, name the endpoint it does have; otherwise cxg falls back to a weaker landing-page test.

  2. Confirm the guardlink hypotheses are in place.

    Terminal window
    ls ./app/whitebox/findings.sarif

The pipeline acts as a logged-in user, so it needs a captured session. For CI and for a reproducible run, import a Playwright storage_state rather than capturing interactively. Keep it out of your home store by writing to a dedicated, 0700 directory.

  1. Import the session as a named profile.

    Terminal window
    mkdir -p ci-auth && chmod 700 ci-auth
    cxg pentest auth import --profile mechanic --target http://127.0.0.1:8931 \
    --storage-state ./mechanic.json --auth-dir ./ci-auth
    ✓ imported 1 cookies across 1 domains, 0 localStorage items, 0 sessionStorage items
    [auth] imported mechanic (storage_state, 1 cookies)

    The profile files are written 0600. A later run that loads this profile cannot tell an imported session from an interactively captured one.

  2. Verify the session is alive before spending a whole run on it.

    Terminal window
    cxg pentest auth verify --profile mechanic --auth-dir ./ci-auth
    ✓ session for 'mechanic' is ALIVE against http://127.0.0.1:8931
    · authenticates by cookie: no JWT-shaped value in localStorage or sessionStorage (0 entries searched); this identity is either cookie-authenticated or holds no credentials at all
    · API liveness returned 200

    Truncated after the liveness line; a one-line cookie summary follows. A session the app no longer accepts prints this and exits 1, which is your cue to re-capture:

    ✗ session for expired expired — re-capture and re-import
    · authenticates by cookie: no JWT-shaped value in localStorage or sessionStorage (0 entries searched); this identity is either cookie-authenticated or holds no credentials at all
    · dead session: API liveness returned 401

Against an app with no /api/me, and no path configured, 1.9.2 falls back to the landing-page test that 1.8.0 used, and auth verify exits 0:

✓ session for 'member' is ALIVE against http://127.0.0.1:8932
· landing test: landed at http://127.0.0.1:8932/ (no login redirect); API liveness http://127.0.0.1:8932/api/me answered 404 (liveness endpoint not found (404): configure --liveness-path with an authenticated API endpoint)

Truncated as above. The fallback applies when /api/me answers 404, HTML or a redirect. A /api/me that answers 401 or 403 still decides, so an expired cookie on the same app read as dead. The landing test proves less: it checks that the landing page did not redirect to a login, and the 1.9.2 changelog names the case it misses. 1.9.0 and 1.9.1 called the same session unverified and exited 1.

That fixture served its session check at /api/session. Save that path with the profile when you import it, so every later verify, pre-flight and health check uses it instead of the fallback:

Terminal window
cxg pentest auth import --profile member2 --target http://127.0.0.1:8932 \
--storage-state ./session.json --auth-dir ./ci-auth \
--service community --liveness-path /api/session
cxg pentest auth verify --profile member2 --auth-dir ./ci-auth
✓ session for 'member2' is ALIVE against http://127.0.0.1:8932
· API liveness returned 200

Truncated as above. The profile’s private metadata now carries "liveness_check": {"path": "/api/session"} and "service": "community". --liveness-status is repeatable and names the statuses that mean alive; the default is any 2xx, and 401 or 403 always mean dead. --me-path on auth verify or run sets the path for profiles that saved none; a saved liveness_check wins over it.

--service also opts the profile into its own service: its traffic and liveness check go to the --target saved at import rather than the run’s --scope. Without --service, every identity uses --scope. For profiles that belong to different services, the pentest README covers cross-service cxg.fetchAs and the scope it needs.

Point it at the running app and its source, and give it a goal.

Terminal window
cxg pentest run \
--codebase ./app \
--target http://127.0.0.1:8002 \
--auth live --auth-dir ./ci-auth \
--ai --ai-provider claude \
--goal "verify the IDOR exposure on the profile endpoint" \
--attestation "Local test against a self-hosted demo, 2026-08-13"

The pre-flight is deterministic and worth reading in full:

[1] guardlink: 1 SARIF hypotheses, 0 inline, 0 endpoints
[scope] audit log → ~/.cert-x-gen/sessions/pentest-20260813-141227/audit.jsonl
[1b] inspecting 1 captured auth profiles…
· live role=user tier=20 email=demo@example.com id=1
· landed at http://127.0.0.1:8002/ (no login redirect)
[2] generating JS templates via claude (reads codebase)…

This pre-flight was captured on an earlier release. Since 1.9.0 each identity’s lines end with the API liveness result instead of a landing page:

[1b] inspecting 2 captured auth profiles…
🍪 mechanic: cookie session (1 cookie(s)); no JWT-shaped value in localStorage or sessionStorage (0 entries searched); this identity is either cookie-authenticated or holds no credentials at all
🍪 customer: cookie session (1 cookie(s)); no JWT-shaped value in localStorage or sessionStorage (0 entries searched); this identity is either cookie-authenticated or holds no credentials at all
· mechanic role=mechanic tier=30 auth=cookie
· authenticates by cookie: no JWT-shaped value in localStorage or sessionStorage (0 entries searched); this identity is either cookie-authenticated or holds no credentials at all
· API liveness returned 200

Truncated after the first profile. On 1.5.0, a SARIF from guardlink’s pentest profile adds [1h] lines between [1] and [scope], covering flows, boundaries, and results cxg skipped. They are shown on feed guardlink findings into cxg.

Step [1] is guardlink ingestion, with one SARIF hypothesis loaded from app/whitebox/findings.sarif. Step [1b] is the session pre-flight: it resolved the identity behind the cookie before spending any AI budget. Step [2] hands the ranked hypotheses to your AI CLI, which reads the codebase and writes probe templates.

flowchart TB
    H["a hypothesis, such as<br/>idor on /api/profile"] --> Q{"built-in probe<br/>for this class?"}
    Q -->|yes| R["run against the app<br/>as a logged-in user"]
    Q -->|"no, with --ai"| AI["AI writes one from your source,<br/>then it must compile and validate"]
    Q -->|"no, without --ai"| SK["skipped"]
    AI -->|passes| R
    AI -->|fails| SK

    class R emphasis

guardlink only knows the routes someone annotated. --discover-routes adds the routes cxg finds in the source. When a code graph has been built for the codebase and bravos graph or codegraph-mcp is installed, cxg reads the graph’s route table first, which covers routers a source scan cannot see, and ranks hypotheses by which sinks their routes reach. The graph comes with Bravos with a paid plan or trial.

Build and inspect the graph using the current Bravos graph guide. Read the graph’s resolution verdict before using its routes or rankings. report.json records which graph input was used in code_graph; unknown reach is not public access or proof of safety. Without graph tooling, or with --no-code-graph, cxg uses its other inputs. The current Bravos MCP wiring preserves the graph store used by its launcher, so consumers must use the same store as the build.

To hold a run to the routes a change reached, see test only what a pull request changed.

--threat-id holds a run to one GuardLink threat. It matches the threatId that guardlink writes into each SARIF result, not cxg’s internal hypothesis id, and it selects every hypothesis carrying that id before any ranking or deduplication. Route discovery, boundary hypotheses and the other unrelated probes are switched off. It needs JS generation on a web or Electron target; Python probes, --template-dir replay and Tauri runs refuse it.

An id that is not in the SARIF refuses at pre-flight, exit 4, before any contact with the target:

Terminal window
$ cxg pentest run --codebase . --target http://127.0.0.1:9 --threat-id gl-000000000000
✗ --threat-id 'gl-000000000000' matched 0 of 2 known threat id(s) in ~/notes-app/whitebox/findings.sarif (sha256 4c0ef3189bf2, codebase HEAD 4710923f942de48a9c5ef87ebd1aa6405e9e2aaa); no target contact. An id from another repository or an older snapshot refuses here too; the excluded list in report.json names every id present.

Truncated to the refusal; the banner and run header come first. The report still lands, with status threat_id_not_found and a threat_selection block listing every hypothesis it excluded, each with the reason outside_requested_threat_id and its real threat_id, so a typo and an id from another snapshot are told apart. --threat-id is not authorization: the scope, budgets and attestation still govern the probes it selects.

Since 1.8.0, plain cxg scan recognizes supplied JavaScript probe contracts and runs them through the pentest engine automatically. Ordinary scanner scripts keep their language runners, so a directory can contain both. The probe target comes from --scope; --codebase defaults to the current directory. Supply captured profiles, scope and runtime inputs required by the selected probes.

For an explicitly probe-only run, use scan --pentest or pentest run with --no-author. In a local fixture, probes/ contained one reviewed JS probe for GET /private, and auth/ held an entitled test profile:

Terminal window
cxg --disable-update-check scan --pentest --codebase . \
--scope http://127.0.0.1:8918 --template-dir probes \
--auth entitled --auth-dir auth --session-dir explicit-session \
--no-author --no-code-graph
[CONFIRMED] [MEDIUM ] missing_authentication GET /private

Truncated to the finding line. The command exited 2: the engine independently replayed a declared protected read with a guest and entitled control. This is a local intentionally exposed fixture, not a claim about another application’s privacy policy. See proof outcomes.

--no-author requires supplied JS probes in explicit pentest mode. It disables ranking, generation and mutation, including deterministic generation. It does not convert scanner scripts. A supplied Python scanner in that directory was refused with exit 4 before contact; use GuardLink translation to author probe drafts separately.

Directories are searched recursively, excluding scan’s generated/dependency directories. Empty searches and attachment-withheld packs are reported separately. Missing // @attach_scheme: path headers withhold probes rather than guessing attachment context. Missing identities or capabilities are refusals/skips, not refutations of security claims.

The explicit --pentest front door accepts the pentest run inputs, with --scope as one HTTP(S) target and --templates DIR as a probe-directory alias. It refuses scanner filters, ports, CIDR and CLI scopes. Plain scan accepts non-authoring engine controls, including --ci, capture, timeouts, containment and chaining; authoring switches require explicit pentest mode. Scanner-only runs retain their own contract.

After upgrading an existing installation, including between 1.9.x releases, run this before your next pentest:

Terminal window
cxg pentest install --force

On a scratch installation that had the 1.9.1 pipeline, 1.9.2 printed:

Pentest pipeline updated 69cd7f1de270d3bae41eae37dec3f0d20a762753953f9b23a1482299d74b779c → 179e8f82abc2910055a4b59af8502bb99c790e4d1dd23722d116c4943e4e24f3 for CXG 1.9.2.

Truncated after the bundle update line; the backup path is omitted.

Then check what changed for an existing setup:

  • Liveness. Pre-flight calls an authenticated API endpoint, /api/me by default. On 1.9.0 and 1.9.1 an app without one read as unverified and the run exited 5; 1.9.2 falls back to the landing-page test instead. Save the real endpoint on each profile either way.
  • --skip-health-check skips only periodic health checks and re-authentication. The startup check still runs.
  • Request paths. 1.9.0 and 1.9.1 resolved cxg.fetch and cxg.url paths at the origin, dropping a --scope path such as /dashboard. 1.9.2 keeps the prefix; see paths keep the scope’s prefix. Recheck any template you changed for 1.9.0 to name its prefix in full.
  • Profiles with --service. Only a profile imported with --service sends its traffic to its own saved --target. Every other profile uses --scope.
  • Report consumers. report.json carries profile_liveness and services, and an unavailable profile makes the run complete: false. A complete run reads "status": "ok" on 1.9.2; 1.9.0 and 1.9.1 wrote "complete".

The digest identifies the embedded bundle. Replacing the binary alone does not replace an already materialized pipeline. The release also requires Python 3.10 or newer for its pinned h2 dependency.

Ordinary embedded installs also refresh on their first pentest action after an upgrade. Source-checkout installs and CXG_SOURCE overrides retain their selected source. To switch deliberately to the embedded bundle, use the update command with --from-embedded.

The whole previous tree is backed up under ~/.cert-x-gen/pentest-backups/. Auth profiles, sessions and template stores are separate. Refresh does not run pip or install browsers; install the new pipeline’s pinned dependencies, including h2 for HTTP/2 race transport. Without h2, races use the HTTP/1.1 fallback.

Terminal window
cxg pentest capabilities
{"capabilities": ["exact-threat-id", "mail", "totp", "ask"]}

This reports protocol capabilities, not target coverage. cxg pentest status --json is the read-only freshness check and works without Python.

In a pipeline the exit code is the machine-readable verdict:

Exit Meaning
0 No confirmed findings. Check proof and coverage outcomes before treating the run as clean.
1 No templates were available to run (guardlink output missing or empty, or the ranker selected none).
2 Confirmed findings present.
3 The scan was hard-killed by a 5xx streak or a scope violation.
4 The run was mis-specified and refused at pre-flight, before any probing. An unreadable --scope-file or --only-routes file is one cause, and a --threat-id the SARIF does not hold is another.
5 A selected profile or its service was dead or unverified. Probes that needed it were skipped; the report is incomplete.

Exit 5 is what makes this safe to automate. See run cxg in CI for the non-interactive setup that relies on it.

Artifacts land in the session directory named in the [scope] line: report.json (the split of confirmed / mitigation-verified / ambiguous) and audit.jsonl (every HTTP request the run made). The audit log is the dispute-ready record of what was sent, which is why --attestation is stamped into its header.

flowchart TB
    R["a probe runs"] --> T{"deterministic triage"}
    T -->|confirmed| OK["confirmed_findings"]
    T -->|refuted| MV["mitigation_verifications"]
    T -->|"ambiguous,<br/>environment-bound"| AMB["ambiguous"]
    T -->|"ambiguous,<br/>payload-bound"| M["AI rewrites the probe<br/>to address the failure"]
    M -->|"up to 3 times"| R

    class OK,MV,AMB emphasis

Read Proof and coverage outcomes before treating the result as clean. Since 1.7.0 each finding carries triage, triage_reason, reason_kind and proof_status. inconclusive_refusal does not verify a mitigation, and not_run records gaps. OAuth, OIDC and SAML findings still cannot be confirmed.

  • No login. Leave --auth out and the run probes the app anonymously on a clean browser surface, without asking for an interactive login. Checks that need a session are recorded as not run under auth_skipped instead of stopping the run, and report.json says which mode ran in auth_mode: anonymous, mixed or authenticated.

  • Two identities. Cross-user IDOR and session-replay probes need at least two profiles. Import a second and pass --auth victim,attacker.

  • Confirm blind vulnerabilities out of band. For SSRF and blind injection, add OAST, and read detect blind vulnerabilities with OAST first, because the OAST modes mean different things.