Skip to content
MacTashPublic

About

A comprehensive and growing web vulnerability scanner that aims to provide a professional report at the end of scanning

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Web-Cross Vulnerability Scanner v0.0.4

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

Why a CLI

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.

Install

# 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

Quick start

# 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 60

Subcommands

webcross
├── 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

Output formats

webcross scan and webcross report both support:

  • html (default) — single-file report with risk gauge, finding cards, and remediation
  • json — machine-readable; ideal for piping into jq or other tools
  • text — terminal-friendly
  • pdf — printable executive report
  • sarif — SARIF 2.1.0, ready for gh 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 analysis

--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 ollama

If no provider is configured, --ai is a no-op and the scan continues with the deterministic scanner output.

Configuration

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

Testing

# 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

Docker

# 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 bash

The container ships the CLI only. There is no exposed port and no HEALTHCHECK — docker run is fire-and-forget per scan.

Architecture (Phase 0)

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

Status

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.py deleted; Flask deps dropped
  • core/scan_store.py -> core/store.py
  • pyproject.toml with extras_require and webcross entry point
  • webcross package with full subcommand tree
  • scanner.py shim preserves back-compat for python scanner.py -u URL
  • tests/fixtures/vuln_app.py stdlib fixture
  • tests/test_cli.py smoke tests
  • tests/test_cli_integration.py end-to-end tests
  • Dockerfile switched to python:3.12-slim and ENTRYPOINT ["webcross"]
  • docker-compose profiles (cli, dev)
  • ruff.toml and pytest.ini removed; consolidated into pyproject.toml
  • CI matrix bumped to py3.12 + py3.13 with a CLI smoke job

Phase 1+ work is tracked in the plan file.

Legal

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.

License

MIT — see LICENSE.

About

A comprehensive and growing web vulnerability scanner that aims to provide a professional report at the end of scanning

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages