FSV — website security scanner

Web security scanner for the problems nobody is watching — dangling DNS & subdomain takeover, orphaned cloud buckets, compromised script CDNs, SPF includes that expired, debug mode left on, secrets in your JavaScript, end-of-life software, and the attack paths that turn small findings into a real compromise.
Runs as a CLI, a dashboard, an MCP server for AI agents, and a CI step.

MCP in 30 s · See it work · What it finds · Attack paths · Install · Usage · CI · FSV & ZAP · Limits · Docs · Contact

⚠ Authorized use only

FSV is a security assessment tool. Use it only against systems you own or are explicitly authorized in writing to test. Scanning systems without permission is illegal in most jurisdictions. Every entry point (web, CLI, MCP, CI) requires you to confirm authorization, and a shared deployment can additionally require proof of control of the target before any payload is sent (docs/DEPLOYMENT.md).

Connect your AI assistant in 30 seconds

Point Claude, Cursor or VS Code at FSV and ask it to review your site. The assistant asks you to confirm authorization, runs a passive check, then a full scan, leads with attack paths and hands you paste-ready fixes.

pip install fsv
fsv mcp-config --client claude-code     # prints:  claude mcp add fsv -- /path/to/fsv-mcp
fsv mcp-config --client claude-desktop  # or cursor · vscode — prints the JSON to paste

No install at all: with uv, point any MCP client at uvx fsv mcp ({ "command": "uvx", "args": ["fsv", "mcp"] }). FSV is listed in the official MCP Registry as io.github.twayst0/fsv.

Then, in the assistant: “Use the security_review prompt on https://my-shop.example — I own it.”

See it work

That output is real — a scan of the deliberately vulnerable demo site that ships in this repo. Reproduce it in a minute:

python examples/demo_site.py &                 # http://127.0.0.1:8961 — loopback only, fake secrets
fsv scan http://127.0.0.1:8961 --authorize
fsv web                                        # open the same scan in the dashboard

_{The cloud_storage check asks Amazon S3 whether the demo's bucket exists — that one request goes to AWS (read-only). Skip it with --no-external.}

What it finds that checklists miss

Plenty of tools tell you a header is missing. The incidents that actually hurt organisations — including very well-run ones — are quieter, and they live where nobody is looking.

Details, and every false-positive guard: docs/DETECTIONS.md.

Attack paths

Real compromises are rarely one bug — they're two or three "medium" problems that line up. Scanners rate each in isolation, so the combination stays invisible until someone writes the incident report. FSV reads its own findings (sending nothing more) and, where a chain is actually present, adds a finding that names the links, tells the story step by step, and states the cheapest single fix that breaks it. If a link is triaged away, the chain steps aside automatically.

Dashboard

Liquid-glass UI with live progress (survives a page reload), the attack-path panel, OWASP breakdown, per-host risk trend, inline triage, module picker, scan comparison, and one-click export — reports or paste-ready fixes.

Features

• Finds the pages first — besides links: robots.txt, sitemaps, routes leaked by debug pages, and API paths quoted in your JavaScript; action-like paths are never requested. --seed for anything else.
• A badge for your README — fsv badge <scan_id> writes a dated grade badge (FSV security | A · 2026-10-25); regenerate it from CI.
• Fix packs — turn findings into nginx / Apache / Caddy / Express / DNS configuration (fsv fixes <scan> nginx). Only what was actually found; CSP is emitted report-only.
• CI-ready — fsv.toml, baselines (gate only on new findings), --fail-on, SARIF for GitHub code scanning, and a ready-made GitHub Action.
• Triage that sticks — false positive / accepted risk / fixed / confirmed, stored per host by stable fingerprint, re-applied to later scans, excluded from the score. Diff any two scans; per-host trend.
• Evidence over guesses — exposure checks validate content (a .git/HEAD must look like one; an SPA that answers 200 to everything produces nothing). Every finding has a confidence, a CWE, an OWASP Top 10 (2021) category, impact and remediation.
• Honest failure — a crashing module is counted, explained and logged; a target that never answered is flagged, not graded "clean".
• Safe by construction — secrets masked at the source; cloud-metadata/link-local never reachable, loopback/RFC 1918 optionally blocked, on every lookup and redirect hop; dashboard CSRF/DNS-rebinding guard and token auth.
• Extensible — a module is one class; drop a file in ~/.fsv/plugins or ship an entry-point package (docs/WRITING_MODULES.md). Bring your own JS-library advisories and EOL dates.
• Fast & polite, hard to stall — async engine, shared HTTP client with cache, request coalescing, token-bucket rate limit, retries, size cap, time limit with partial results. A hanging endpoint costs one timeout per scan, not one per module; every response regex is linear-time. Tested against hostile local servers (redirect loops, 20 MB bodies, hangs, catch-all SPAs).
• Five report formats — Markdown (OWASP-grouped), JSON, self-contained HTML, SARIF 2.1, CSV.
• Local-first — results in a local SQLite file; the only optional third-party calls are listed in DEPLOYMENT.md.

Install

pip install fsv          # Python 3.11+  ·  pipx install fsv  keeps it isolated
fsv doctor               # checks Python, dependencies, DNS, database, plugins

From source: git clone https://github.com/twayst0/fsv && cd fsv && ./install.sh (or pip install -e .).

Requires Python 3.11+. Docker: see docs/DEPLOYMENT.md (docker compose up).

Usage

fsv scan example.com --authorize                       # full scan of a site you own
fsv scan example.com --authorize --profile passive     # read-only: no payloads sent
fsv web                                                # dashboard → http://127.0.0.1:7474

# scope & tuning
fsv scan example.com --authorize --exclude "/admin/*,/logout" --max-urls 100 --max-time 900 --tag prod
fsv scan example.com --authorize --header "Authorization: Bearer X" --cookie "session=abc"    # authenticated
fsv scan example.com --authorize --ct-logs        # also ask Certificate Transparency (crt.sh) for subdomains*
fsv scan example.com --authorize --no-external    # skip modules that contact hosts other than the target
fsv scan example.com --authorize --proxy env      # behind a corporate proxy (HTTPS_PROXY); or --proxy http://host:3128

# reports & fixes
fsv scan example.com --authorize -o report.html   # .md .json .html .sarif .csv
fsv report <scan_id> --format fix-nginx           # or fix-apache fix-caddy fix-express fix-dns
fsv fixes  <scan_id> nginx -o nginx-fixes.md

# triage, history, diff
fsv findings <scan_id>
fsv triage <scan_id> <finding_id> false_positive --note "test endpoint"
fsv list --target example.com   ·   fsv diff <before_id> <after_id>   ·   fsv prune --keep 50

# ownership proof (for shared deployments)           # * sends the domain name to crt.sh
fsv verify example.com   ·   fsv verify example.com --check

fsv modules   ·   fsv doctor

In CI

# fsv.toml  (commit it; ${VAR} is read from the environment — never commit secrets)
[scan]
profile  = "balanced"
max_urls = 100
exclude  = ["/admin/*"]
max_time = 900
fail_on  = "high"
baseline = ".fsv-baseline.json"
[scan.headers]
Authorization = "Bearer ${FSV_API_TOKEN}"

fsv scan staging.example.com --authorize --write-baseline .fsv-baseline.json    # once: accept today's state
fsv scan staging.example.com --authorize                                         # every build: fails only on NEW high+ findings

# .github/workflows/security.yml
- uses: twayst0/[email protected]          # pin a release tag (or a commit SHA)
  with:
    target: https://staging.example.com
    authorized: "true"          # you confirm you may test this target
    profile: balanced
    fail-on: high
    baseline: .fsv-baseline.json

SARIF is uploaded to GitHub code scanning; the HTML report and log are attached as an artifact.

FSV and OWASP ZAP

ZAP is the right tool for deep testing of an application's inputs — use it. FSV looks at what surrounds the application, where typical DAST scans don't go, and the two work well side by side:

Modules (32)

FSV ships 32 modules — 26 passive, 6 active. Run fsv modules for the live list.

How it works

One engine, four front doors. Address policy and proof of control live in the engine, so every front door gets them; request guard and token auth belong to the web server. See docs/ARCHITECTURE.md.

Limits — what FSV is not

• It reads HTML; it does not execute JavaScript, so content that only exists after client-side rendering isn't discovered.
• Active checks cover common reflected classes with benign markers. It is not a replacement for a penetration test, SAST or an SCA pipeline.
• The JS-advisory and end-of-life tables are curated snapshots — cross-check with OSV / endoflife.date for anything important, and extend them with the files above.
• DNS checks are only as good as the resolver (fsv doctor tests it). A resolver that can't answer produces no DNS findings, not bad ones.
• Findings carry a confidence; tentative ones are hints. Triage them, and tell us about false positives — they're the most useful bug reports.

Documentation

Detections · Architecture · Writing modules · Deploying safely · Security policy · Contributing · Changelog

_{The animated SVGs and screenshots above are generated from a real scan: scripts/build_readme_assets.sh --screenshots.}

Contact

twayst0 (tways) — author and maintainer

• Email: [email protected]
• Discord: .tways
• Security issues: please report privately (see SECURITY.md), not in a public issue.

Questions, collaboration and licensing enquiries are welcome by email or Discord.

License

MIT — free to use, modify and share, for anyone, including commercially. Keep the copyright and licence notice. Copyright © 2026 twayst0. See LICENSE.

Disclaimer

This software is provided "as is", for lawful, authorized security testing only. The authors accept no liability for misuse or damage. Always obtain written permission before testing any system you do not own.