webscan - Automated CLI security auditor for web configurati

项目说明

<di="center">

<img src="assets/header.svg" alt="WebScan — automated web security auditor" width="820" />

WebScan

Discover. . Report.

An asynchronous web security auditor that findings against response
content before it reports them — so the list you hand a de is short,
specific, and worth their time.

![CI]()
![PyPI]()
![Python]()

<img src="assets/demo.svg" alt="WebScan terminal scan summary" width="760" />

</div>

> [!WARNING]
> Scan only what you are authorized to scan. Use WebScan solely on systems you
> own or ha written permission to test. You are responsible for
> authorization, scope, rate limits, and the impact of every request it sends.

---

Contents

<table>
<tr>
<td ="top" width="50%">

Getting started

</td>
<td ="top" width="50%">

How it works

</td>
</tr>
<tr>
<td ="top" width="50%">

Reference

</td>
<td ="top" width="50%">

Project

</td>
</tr>
</table>

---

Why WebScan

Most scanners fail in one of two directions: they report e and bury the
real issue, or they stay quiet and miss it. WebScan is built around the first
problem — every heuristic finding is checked against what the ser
returned before it reaches the report.

| Principle | What it means in practice |
|---|---|
| Signal o | Findings carry a firm / tentative / informational confidence tag. Soft-404 calibration, response-similarity checks, and site-wide deduplication run before anything is reported. |
| Safe by default | The default profile skips checks that mutate state or call external services. --safe-mode lowers concurrency, caps the request rate, respects robots.txt, and sends an honest User-Agent. |
| Built for review | Terminal output a human can read, --explain in plain language, e attached to findings, and --suggest-fixes for copy-paste remediation. |
| Automation ready | Six report formats, risk gates, report diffing, SARIF for Code Scanning, and webhooks — all with meaningful exit codes. |
| Small surface | Two runtime dependencies: aiohttp and PyYAML. E heavier is an opt-in extra. |

---

Install

The PyPI badge abo the pip install will actually give you.
GitHub releases can run ahead of PyPI; to track the newest code, install from
the repository instead:

<details>
<summary><b>Optional extras</b></summary>

<br>

| Extra | Pulls in | Needed for |
|---|---|---|
| ai | anthropic | --ai-triage, --ai-summary (also needs ANTHROPIC_API_KEY) |
| serve | fastapi, u | webscan serve and the local history dashboard |
| dev | pytest, ruff, mypy, … | Running the test suite and the linters |

</details>

<details>
<summary><b>From source, Docker, and pipx</b></summary>

<br>

Full details, including offline installs, are in
docs/installation.md.

</details>

Requirements: Python 3.11 or newer. Linux, macOS, and Windows.

---

Quick start

1. Run a polite first audit. --safe-mode keeps the request rate low;
--explain adds a plain-language paragraph under each finding.

2. Sa you can share.

This writes reports/example.json, .html, and .md. The HTML report is
self-contained — it opens in a browser on a machine that has ne of
WebScan.

3. Keep only what is worth acting on.

---

Presets

A preset bundles the plugin selection, crawl behaviour, and confidence threshold
into one flag, so a useful scan does not require writing a config file first.

| Preset | What it does | Reach for it when |
|---|---|---|
| quick | Default plugins, firm findings only | You want a fast, high-confidence look |
| safe | Polite crawl, soft-404 handling, firm findings only | The target is production and you are a guest on it |
| full | Safe crawl plus DNS, technology, and robots/sitemap recon | You are profiling a target, not just checking it |
| active | Defaults plus the heavier acti | You ha for intrusi |

A preset sets defaults, so explicit flags still win: --preset safe --depth 4
gives you the safe preset with a deeper crawl. Presets cannot be combined with
--config / --profile — pick one source of configuration, and WebScan will
say so plainly if you pick both.

---

Choose your workflow

| You need to… | Start here | You get |
|---|---|---|
| Baseline a site you own | webscan -t --safe-mode | Terminal summary |
| Find routes before auditing | webscan -t --crawl --depth 3 | Crawl plus a scan of e discovered |
| See only actionable signal | --min-se high --min-confidence firm | High-impact, directly findings |
| Scan behind a login | --cookie, --header, --basic-auth, --login-url | Session-aware checks |
| Compare two deployments | webscan diff baseline.json current.json --fail-on-new | New, fixed, and changed findings |
| Gate a pull request | --format sarif -o report --fail-on-risk 70 | SARIF artifact and a non-zero exit code |
| Share results outside the team | --format html md --anonymize | Redacted, offline-readable reports |
| Revisit past scans | webscan serve | Local dashboard at |

---

The scan pipeline

Concurrency is bounded twice — by the connection pool and by a semaphore — so a
scan cannot accidentally flood a target. --stealth drops both to a single
in-flight request.

---

Plugin catalog

WebScan ships 41 plugins: 33 run by default, 8 are opt-in. Run
webscan --list-plugins for the registry as installed; the annotated catalogue
is in docs/plugins.md.

Passi

These read what the ser sent — responses, certificates, HTML,
Ja, cookies, headers — and never send an exploit payload.

headers · secrets · cors · cookies · ssl_tls · security_txt ·
jwt_audit · csrf · clickjacking · ·
prototype_pollution · csp_analyzer · waf_detect · websocket_security

Acti

These send probes and then the response before reporting anything.

| Plugin | Co |
|---|---|
| config_files | Exposed .env, .git, backups, keys, dumps, common config files |
| directories | Admin panels, debug paths, open listings, sensiti |
| sql_injection | Error-based, boolean-blind, and time-blind |
| xss | Reflected parameters, classified by injection context |
| path_tra · lfi_rfi | Unix/Windows tra and PHP wrapper probes, content |
| open_redirect | Redirect payload with Location host |
| ssrf | Cloud metadata and localhost response signatures |
| http_methods | Dangerous PUT, DELETE, TRACE, CONNECT, PATCH |
| subdomains | Certificate Transparency, with optional DNS brute force |
| graphql_depth | Depth abuse and field-suggestion disclosure |
| xxe | XML entity probes with per-scan markers |
| idor | Object-ID with similarity and auth-error suppression |
| cache_poisoning · host_header_injection | Host and forwarding header reflection |
| ssti | Jinja2, Twig, FreeMarker, ERB, and Smarty syntax |
| backup_files | Source- .bak, .old, .orig, ~, .save |
| file_upload | Harmless upload with predicted-URL accessibility check |
| web_cache_deception | Dynamic URLs with static extensions on sensiti |

Opt-in checks

Eight plugins stay out of the default run, for three distinct reasons.

| Plugin | Co | Why it is opt-in |
|---|---|---|
| mass_assignment | API role and property injection | 🔧 May mutate target state |
| race_condition | Concurrent request comparison | 🔧 May mutate target state |
| request_smuggling | CL.TE and TE.CL timing probes | 🔧 May mutate target state |
| c | Detected software mapped to known CVEs | 🌐 Queries an external database |
| dns_security | DNSSEC, CAA, SPF, DMARC, DKIM | 🌐 Queries public DNS resolvers |
| graphql | Endpoints with introspection enabled | 🔍 Reconnaissance, not a |
| tech_fingerprint | Server, framework, CMS identification | 🔍 Reconnaissance, not a |
| robots_sitemap | robots.txt / sitemap.xml leaks and hygiene | 🔍 Reconnaissance, not a |

> [!IMPORTANT]
> --plugins replaces the default set — it does not add to it. When you want
> the defaults plus something extra, use a preset or list every plugin you want.

---

Confidence and se

Every finding carries both. Se says how bad it would be; confidence says
how sure WebScan is that it is real.

| Confidence | Meaning | Typical use |
|---|---|---|
| firm | Directly observed, or proven by a content check | Hand straight to a de |
| tentative | Strong heuristic that needs a human to confirm | Triage queue |
| informational | Best-practice note or manual-review signal | Hardening backlog |

--min-confidence drops findings from all output, reports included.
--min-se filters the console summary only.

---

Reports

| Format | Flag | Best for |
|---|---|---|
| JSON | --format json | APIs, archives, custom tooling |
| JSONL | --format jsonl | jq, streaming, line-oriented pipelines |
| Markdown | --format md | Pull requests and human review |
| HTML | --format html | Self-contained stakeholder reports |
| SARIF | --format sarif | GitHub Code Scanning, IDE integrations |
| CSV | --format csv | Excel, Jira, data imports |

Full details — every field, the anonymiser's guarantees, and the HTML
report's structure — are in docs/reports.md.

---

Risk, compliance, and diffing

webscan diff reads two JSON reports and prints what is new, what was
fixed, and what changed. With --fail-on-new it exits 1 as soon as a
new CRITICAL or HIGH finding appears — which is the check you want in CI.

---

Local dashboard

Open to launch scans, revisit previous ones, and filter
findings by se, confidence, plugin, or free-text search.

History lives in ~/.webscan/history.db and is ne. Point it
somewhere else with --history-db /path/to/history.db or WEBSCAN_HISTORY_DB.

> [!CAUTION]
> serve binds to 127.0.0.1 on purpose. It is a local helper, not a hardened
> public service — put your own authentication and rate limiting in front of it
> before exposing it to any network you do not control.

---

CLI reference

<details open>
<summary><b>Targets, discovery, and authentication</b></summary>

</details>

<details>
<summary><b>Network, safety, and e</b></summary>

> TLS is off by default so the scanner can audit hosts with
> self-signed or expired certificates. Turn it on with --strict-ssl when a
> valid certificate is itself part of what you are checking.

</details>

<details>
<summary><b>Plugins, output, and performance</b></summary>

</details>

Subcommands: webscan serve (local backend) and webscan diff (compare two
reports). webscan --help always prints the reference for your installed
; webscan -V prints that .

---

Configuration profiles

Keep reusable settings in YAML and commit them. Explicit CLI flags o
whatever the profile says.

Every supported key is documented in
docs/configuration.md.

---

CI/CD

Exit codes

| Code | When |
|---|---|
| 0 | The scan completed and no gate was tripped |
| 1 | A finding at or above --fail-on (default: CRITICAL/HIGH), a risk score below --fail-on-risk, a new regression under diff --fail-on-new, or a fatal error |

GitHub Actions

Docker

GitLab CI, Jenkins, and gating strategies are covered in
docs/ci-cd.md.

---

Python API

The same ScanReport renders through Reporter(report) with .to_json(),
.to_jsonl(), .to_markdown(), .to_html(), .to_sarif(), and .to_csv().
See docs/python-api.md.

---

Architecture

Runtime dependencies are deliberately small — aiohttp and PyYAML. The module
map and design constraints are in docs/architecture.md.

---

Benchmark

A cold, single-target Safe Mode run against other general-purpose scanners.
Treat it as a reference point, not a promise for every network or target.

| Scanner | Time | Findings | False positives | Co |
|---|---:|---:|---:|---:|
| WebScan 2.8 | 7.1s | 16 | 0 | 41 plugins |
| Nuclei 3.8 | 34.2s | 21 | not measured | template-based |
| Nikto 2.6 | 42.6s | 30 | 5+ observed | legacy checks |

Target httpbin.org, 41 plugins, Safe Mode, one cold run. Reproduce it with
python benchmarks/run_benchmark.py --help.

---

Documentation

Full reference documentation lives in docs/.

| Guide | Covers |
|---|---|
| Installation | pip, extras, Docker, pipx, offline installs |
| Quickstart | First scan to first report |
| Plugin reference | All 41 checks, opt-in rationale, the confidence model |
| Configuration | YAML profiles, every key, en |
| Reports | Six formats, anonymising, diffing, risk scoring, dashboard |
| CI/CD integration | Exit codes, gating, GitHub Actions, GitLab, Jenkins |
| Python API | scan(), report dataclasses, rendering |
| Plugin de | The BasePlugin contract, helpers, testing, publishing |
| Architecture | Module map, pipeline, concurrency, design constraints |
| Troubleshooting | Install problems, noisy results, missing checks, CI issues |

---

De

Install the git hooks to run the same checks CI does:

To add a check: subclass BasePlugin, implement run(), and register it under
the webscan.plugins entry-point group. Reuse the acti for retry,
soft-404 calibration, and response similarity so your plugin inherits the same
false-positi as the built-ins. The contract is in
docs/plugin-de.md; the contribution
process is in CONTRIBUTING.md.

---

Security

Found a in WebScan itself? Please do not open a public issue —
report it pri through
GitHub Security Ad.
Response targets, supported , and the security model of running a scan
are in SECURITY.md.

Legal

WebScan is for authorized security testing only. Use it solely on systems you
own or ha written permission to test. Unauthorized scanning may be
illegal in your jurisdiction. You are solely responsible for how you use it.

<di="center">
<br>

Made for responsible testing and fewer false positives.

Documentation ·
Report a bug ·
Security policy ·
Contribute ·
Changelog

</div>

项目信息

开发语言：Python

Star 数：25

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Automated CLI security auditor for web configuration vulnerabilities.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。