A CLI-native web vulnerability scanner. Detection, AI-assisted analysis, and reporting from a single binary; no server, no UI, no daemon.
$ webcross scan -u https://example.com --watch
[+] Scanning https://example.com
[+] Done in 12.4s - 7 findings across 1 target(s)
[+] Wrote html: ./webcross-out/20260719-134022/webcross-20260719-134022.html
v3.x shipped a Flask web UI alongside the CLI. v4.0 drops the UI: every
feature is reachable as a subcommand, every output is a flag, every
long-running thing can be piped or watched. If you need a daemon, wrap
webcross with systemd or a cron job. See docs/adr/0001-drop-server.md
for the rationale.
# Recommended: pipx (isolated, CLI-first)
pipx install web-cross
# Or: pip
pip install web-cross
# Optional extras:
pip install 'web-cross[ai]' # Anthropic + Groq SDKs
pip install 'web-cross[pdf]' # WeasyPrint for PDF reports
pip install 'web-cross[all]' # everything# A quick scan
webcross scan -u https://example.com
# Full scan, save report and persist scan
webcross scan -u https://example.com --format all --out report/
# Run a subset of modules
webcross scan -u https://example.com --modules sqli,xss,csrf
# Read targets from a file (one per line, # comments allowed)
webcross scan --file targets.txt
# Read targets from stdin
cat targets.txt | webcross scan --stdin
# TUI progress overlay (planned for Phase 1)
webcross scan -u https://example.com --watch
# Cancel after 60 seconds (planned for Phase 1)
webcross scan -u https://example.com --cancel-after 60webcross
├── scan Run a vulnerability scan
├── list List stored scans
├── show SCAN_ID Show one scan's findings
├── report SCAN_ID Render a scan to a file
├── diff SCAN_A SCAN_B Compare two scans finding-by-finding
├── delete SCAN_ID Delete a stored scan
├── payload Manage the payload corpus
├── cve Local CVE cache
├── config Inspect the resolved configuration
├── tui SCAN_ID Open the textual dashboard for a stored scan
└── shell-completion Emit a shell completion script
webcross scan and webcross report both support:
html(default) — single-file report with risk gauge, finding cards, and remediationjson— machine-readable; ideal for piping intojqor other toolstext— terminal-friendlypdf— printable executive reportsarif— SARIF 2.1.0, ready forgh code-scanning upload(Phase 2)all— emit everything
Pipe the JSON output into other tools:
# Show only critical findings as TSV
webcross show <scan-id> --severity critical --format tsv
# Generate a GitHub-PR-comment-style diff
webcross diff <scan-a> <scan-b> --format markdown > /tmp/diff.md--ai enables an LLM-driven second-pass over the findings. Supported
providers: Anthropic (Claude), Groq (Llama 3.3 / Mixtral), Ollama (local).
webcross scan -u https://example.com --ai --ai-provider anthropic --ai-key sk-ant-...
webcross scan -u https://example.com --ai --ai-provider ollamaIf no provider is configured, --ai is a no-op and the scan continues
with the deterministic scanner output.
Layered: CLI flags > WEBCROSS_* env vars > ~/.config/webcross/config.toml > ./webcross.toml > defaults.
webcross config show # print the resolved config
webcross config path # show which TOML files are read# Unit + integration tests
pytest tests/ -v
# Just the CLI smoke tests (no network needed)
pytest tests/test_cli.py -v
# End-to-end scan against the in-process fixture app
pytest tests/test_cli_integration.py -v# Build
docker build -t webcross:0.0.4 .
# Scan
docker run --rm -v "$PWD/out:/home/webcross/.local/share/webcross/out" \
webcross:0.0.4 scan -u https://example.com --out-dir out/
# Shell into the image with the [dev] extra preinstalled
docker run --rm -it -v "$PWD:/app" webcross:0.0.4 bashThe container ships the CLI only. There is no exposed port and no
HEALTHCHECK — docker run is fire-and-forget per scan.
webcross/ # new top-level package
cli.py # click group, --version, --color, --debug
errors.py # WebcrossError hierarchy
console.py # rich console singleton, color/unicode detection
config.py # layered config: TOML < env < explicit
commands/
scan.py # delegates to scanner.py via _shim
list_cmd.py # `webcross list`
show.py # `webcross show`
report.py # `webcross report`
diff.py # `webcross diff`
delete.py # `webcross delete`
payload.py # `webcross payload`
cve.py # `webcross cve` (Phase 3)
config_cmd.py # `webcross config`
tui.py # `webcross tui` (Phase 4)
completion.py # `webcross shell-completion`
_shim.py # back-compat bridge to scanner.py
core/ # existing infra, mostly unchanged
http_client.py # AsyncHTTPClient (httpx-based)
store.py # renamed from scan_store.py
...
modules/ # existing scanners, unchanged in Phase 0
reporting/ # existing generators, unchanged
database/ # existing SQLAlchemy layer, unchanged
tests/
test_cli.py # click CliRunner smoke tests
test_cli_integration.py# fixture-app end-to-end tests
fixtures/
vuln_app.py # stdlib http.server fixture
scanner.py # legacy argparse shim, will be removed in 4.0.0 final
This is 0.0.4 — the first release of the CLI-native redesign. See
docs/adr/0001-drop-server.md for the rationale and the roadmap through a
stable 1.0.
Phase 0 is complete:
-
server.pydeleted; Flask deps dropped -
core/scan_store.py->core/store.py -
pyproject.tomlwithextras_requireandwebcrossentry point -
webcrosspackage with full subcommand tree -
scanner.pyshim preserves back-compat forpython scanner.py -u URL -
tests/fixtures/vuln_app.pystdlib fixture -
tests/test_cli.pysmoke tests -
tests/test_cli_integration.pyend-to-end tests - Dockerfile switched to
python:3.12-slimandENTRYPOINT ["webcross"] - docker-compose profiles (
cli,dev) -
ruff.tomlandpytest.iniremoved; consolidated intopyproject.toml - CI matrix bumped to py3.12 + py3.13 with a CLI smoke job
Phase 1+ work is tracked in the plan file.
Web-Cross is intended for authorized security testing only. Always obtain proper authorization before scanning any system. The authors are not responsible for any misuse.
MIT — see LICENSE.