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
Before you start
Section titled “Before you start”cxginstalled. 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, orgemini. The pipeline asks it to write probe templates. Supplied-probe replay does not require a model. - A guardlink
findings.sariffor the codebase. See feed guardlink findings into cxg. cxg reads it from<codebase>/whitebox/findings.sarif.
Stand up a target you control
Section titled “Stand up a target you control”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.
-
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/me401The session pre-flight calls this endpoint,
/api/meby default.401or403means dead, a2xxwith 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. -
Confirm the guardlink hypotheses are in place.
Terminal window ls ./app/whitebox/findings.sarif
Give the pipeline a session
Section titled “Give the pipeline a session”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.
-
Import the session as a named profile.
Terminal window mkdir -p ci-auth && chmod 700 ci-authcxg 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 laterrunthat loads this profile cannot tell an imported session from an interactively captured one. -
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 200Truncated 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
Tell cxg which endpoint proves a session
Section titled “Tell cxg which endpoint proves a session”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:
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/sessioncxg pentest auth verify --profile member2 --auth-dir ./ci-auth ✓ session for 'member2' is ALIVE against http://127.0.0.1:8932 · API liveness returned 200Truncated 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.
Launch the pipeline
Section titled “Launch the pipeline”Point it at the running app and its source, and give it a goal.
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 200Truncated 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
Let a code graph supply the routes
Section titled “Let a code graph supply the routes”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.
Test one threat
Section titled “Test one threat”--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:
$ 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.
Replay supplied probes without a model
Section titled “Replay supplied probes without a model”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:
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 /privateTruncated 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 you upgrade cxg
Section titled “After you upgrade cxg”After upgrading an existing installation, including between 1.9.x releases, run this before your next pentest:
cxg pentest install --forceOn 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/meby default. On 1.9.0 and 1.9.1 an app without one read as unverified and the run exited5; 1.9.2 falls back to the landing-page test instead. Save the real endpoint on each profile either way. --skip-health-checkskips only periodic health checks and re-authentication. The startup check still runs.- Request paths. 1.9.0 and 1.9.1 resolved
cxg.fetchandcxg.urlpaths at the origin, dropping a--scopepath 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--servicesends its traffic to its own saved--target. Every other profile uses--scope. - Report consumers.
report.jsoncarriesprofile_livenessandservices, and an unavailable profile makes the runcomplete: 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.
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.
Read the exit code
Section titled “Read the exit code”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.
Read the report
Section titled “Read the report”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.
What to change next
Section titled “What to change next”No login. Leave
--authout 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 underauth_skippedinstead of stopping the run, andreport.jsonsays which mode ran inauth_mode:anonymous,mixedorauthenticated.-
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.
Related
Section titled “Related”- Pentest an Electron desktop app runs the same pipeline against a desktop target.
- Test a Tauri app maps a Tauri app’s IPC surface and can prove commands in process.
- Feed guardlink findings into cxg
produces the
findings.sarifthis guide assumes. cxg pentestdocuments every flag.

