Scan a target
A scan is three decisions: what to point at, which templates to run, and what to
write out. This guide works through each against a target on your own machine,
and calls out the flags whose behaviour does not match their --help text.
flowchart TB
TP["templates on disk:<br/>local, user, system"] --> FI["filter by id, tag, severity,<br/>or language, then exclude"]
SC["--scope: URL, host,<br/>domain, CIDR, @file"] --> TG["the targets to hit"]
FI --> RUN["every selected template runs<br/>against every target"]
TG --> RUN
RUN --> OUT["scan-results.json<br/>and any other format"]
RUN --> EC["an exit code"]
class OUT,EC emphasis
Before you start
Section titled “Before you start”cxginstalled. See Installation. You have also read your first scan.- Python 3, for the demo targets.
Set up two targets
Section titled “Set up two targets”Two servers, so scope selection has something to select between.
-
Serve two directories, each with an exposed listing.
Terminal window mkdir -p cxg-scan/a/data cxg-scan/b/datacd cxg-scanecho x > a/data/export.csvecho y > b/data/export.csv(cd a && python3 -m http.server 8899 --bind 127.0.0.1 &)(cd b && python3 -m http.server 8900 --bind 127.0.0.1 &) -
Confirm both answer.
Terminal window curl -s -o /dev/null -w '8899 %{http_code}\n' http://127.0.0.1:8899/curl -s -o /dev/null -w '8900 %{http_code}\n' http://127.0.0.1:8900/8899 2008900 200
Choose a scope
Section titled “Choose a scope”--scope is one flag that reads several shapes. A single URL is the simplest:
cxg scan --scope http://127.0.0.1:8899 --templates directory-listing-common-pathsA comma-separated list scans each entry:
cxg scan --scope http://127.0.0.1:8899,http://127.0.0.1:8900 \ --templates directory-listing-common-paths Targets Scanned: 2... MEDIUM: 2
TOTAL: 2For more than a couple of targets, put one per line in a file and pass it with
@:
printf 'http://127.0.0.1:8899\nhttp://127.0.0.1:8900\n' > targets.txtcxg scan --scope @targets.txt --templates directory-listing-common-paths Targets Scanned: 2--scope also accepts bare hosts, domains, and CIDR blocks like
192.168.1.0/24. For those, cxg scans each template’s own default ports.
Narrow the templates
Section titled “Narrow the templates”Running one template by ID is the tightest scope, and what the examples above use. To run a set, filter instead.
By tag:
cxg scan --scope http://127.0.0.1:8899 --tags exposureBy severity, one value or the flag repeated:
cxg scan --scope http://127.0.0.1:8899 --severity highcxg scan --scope http://127.0.0.1:8899 --severity high --severity critical--severity selects which templates run. It does not change the severity each
finding reports. See reading a scan.
Exclude by exact ID
Section titled “Exclude by exact ID”To drop a specific template from a filtered run, name it in full:
cxg scan --scope http://127.0.0.1:8899 --tags exposure \ --exclude-templates directory-listing-common-paths TOTAL: 0Write the output your pipeline needs
Section titled “Write the output your pipeline needs”--output sets the basename; --output-format sets one or more formats.
cxg scan --scope http://127.0.0.1:8899 --templates directory-listing-common-paths \ --output scan --output-format json,sarif,html,markdown,csvThat writes scan.json, scan.sarif, scan.html, scan.markdown, and
scan.csv from one run. Pick by consumer:
| Format | For |
|---|---|
json |
Automation. The full finding, evidence included. The default. |
sarif |
CI code-scanning: GitHub Advanced Security, VS Code. |
csv |
A spreadsheet: one row per finding, no evidence body. |
html |
A human reading a report. |
markdown |
Dropping into a doc or a ticket. |
The extension you type is replaced by the format’s own, so
--output report.txt --output-format json writes report.json.
Check what the exit code tells you
Section titled “Check what the exit code tells you”For scanner-only runs, completed findings and execution errors still exit 0
by default. Opt into status gates with --fail-on; a matching execution exits
2 after writing the reports. Supported statuses are confirmed, refuted,
skipped, errored and timed-out. Command/configuration failures exit 1;
if every candidate fails to load, the default is also 1, with a report.
Plain scan now runs supplied JS probes through the pentest engine, including
mixed directories. Engine-confirmed findings exit 2, refused probes or missing
engine inputs exit 4, and an interrupted engine run retains exit 3.
These engine exits apply even without an opt-in scanner gate. The pentest
CI guide covers session-health exit 5.
Keep coverage and verdict sources
Section titled “Keep coverage and verdict sources”Discovery failures are retained as execution outcomes. Inspect executions[]
and the declared/inferred status counts as well as findings. A declared scanner
result and an engine proof are different evidence:
| JSON value | Meaning |
|---|---|
verdict_source: "template-reported" |
a scanner’s declared finding |
verdict_source: "engine-adjudicated" |
a probe result evaluated by cxg’s proof rules |
probe_results |
full engine reports, including refusals, ambiguity and artifact locations |
network_requests_measured |
observed audited HTTP attempts, including engine setup/identity traffic |
network_requests: null |
total traffic is unknown; measured attempts are not the total |
Probe JSON is written alongside requested output formats. Supplied probes make
zero model calls; an explicit engine run can also enforce this with --no-author.
See replay supplied probes.
Select repository scanner templates by file path. --templates <id> does not
resolve ids from a supplied --template-dir. To run the whole reviewed directory,
use --template-dir alone. Create the output’s parent directory before scanning.
Clean up
Section titled “Clean up”kill %1 %2 2>/dev/nullcd ..rm -rf cxg-scanWhat to change next
Section titled “What to change next”- Tune the load.
--rate-limit,--parallel-targets, and--parallel-templatescontrol how hard a scan hits a target.--safedrops the checks that can disrupt a production system. - Pass context to a template.
--context '{"param_name":"id"}'feeds JSON to templates that need parameters. Many auth-class templates report anINFOline telling you exactly which context keys they want.
Related
Section titled “Related”- Read your first scan covers the summary and the results file.
cxg scanlists every flag, including the ones marked[NOT IMPLEMENTED].

