中文

wscan

A web security scanner for authorized security testing. Use the WebUI for the fastest start, or use the CLI for repeatable scans and automation.

⚠️ Authorization required: Only scan systems you own or are explicitly authorized to test. Passive mode also captures traffic sent through the configured proxy. Define a target scope before starting, and never route unrelated traffic through a passive task. See the License before use.

What you can do

• Manage targets, scan tasks, vulnerabilities, pages, and technology findings in the WebUI.
• Run active scans with a static crawler, a headless-browser crawler, a single URL, a URL file, or a raw request.
• Run a scoped MITM passive scan and inspect traffic generated by an authorized browser or client.
• Export results and keep scan history across WebUI restarts.
• Run selected plugins or POC templates when your engagement requires them.
• Use the built-in reverse platform for blind-vulnerability callbacks.
• Start an AI Pentest project from the WebUI when you need guided, multi-step testing.

Vulnerabilities and security issues covered

wscan focuses on common Web application vulnerabilities and security misconfigurations. Available coverage depends on the selected plugins, request data, authentication state, target behavior, and scan mode. The main categories include:

• Injection: SQL injection, command injection, expression/template injection, CRLF/header injection, and related parameter injection checks.
• Cross-site vulnerabilities: reflected/stored XSS checks and JSONP or cross-origin data exposure.
• File and path issues: path traversal, sensitive file/directory discovery, backup/configuration exposure, and file upload checks.
• Server-side request and parser issues: SSRF, XXE, unsafe deserialization, Fastjson, Shiro, XStream, ThinkPHP, and Struts-related checks.
• Authentication and session issues: HTTP Basic/Digest weaknesses, simple form weak-password checks, cookie/security-flag checks, and authentication-related exposure.
• Configuration and information exposure: missing or unsafe HTTP security headers, TLS/SSL configuration issues, debug/error information, sensitive comments, credentials/API keys, emails, phone numbers, and other secrets in responses or JavaScript.
• Web technology and API discovery: component fingerprinting, JavaScript endpoint discovery, Swagger/OpenAPI discovery, redirects, and other exposed web resources.
• Custom and external checks: YAML-based custom FUZZ rules plus optional Nuclei/Xray/Goby-compatible POC templates.

A finding is a lead for review, not automatically proof of impact. Confirm important findings manually within the authorized scope, especially checks involving active probes, authentication, file uploads, SSRF, or blind callbacks.

Quick start: WebUI

1. Start the WebUI

Download a release from Releases, or build the binary from this repository. Then run:

./wscan webui --webui-host=127.0.0.1 --webui-port=7002

Open http://127.0.0.1:7002 in your browser. Use 0.0.0.0 only when the WebUI must be reachable from another machine, and protect the host with your network controls.

2. Create an active scan

1. Open New Scan.
2. Keep Active scan selected.
3. Enter an authorized target URL, such as https://example.com/.
4. Select a saved target or configure the crawler and scope.
5. Choose Crawl + Scan, Crawl only, or Scan only.
6. Open the task to watch progress, pages, technologies, and vulnerabilities.

Use Dynamic for JavaScript-heavy applications. Use Static for a faster HTML crawl.

3. Create a passive scan

Passive mode listens on a local MITM proxy and does not crawl the target itself.

1. Open New Scan and select Passive listener.
2. Enter the Scan target URL. This target defines the allowed host/path scope.
3. Keep the default proxy address, 127.0.0.1:7100, or choose another available address.
4. Select the plugins and scope you want to use.
5. Click Start listener.
6. Configure the authorized browser or client to use the displayed proxy address.
7. Install the generated project CA certificate (ca.crt) in that browser or client.
8. Browse the authorized target through the proxy.
9. Review traffic and findings in the task, then click Stop when finished.

The passive task requires a scan target so traffic to unrelated hosts is rejected. Do not use a passive proxy as a general-purpose browser proxy.

Generate the CA when needed:

./wscan genca

The CA private key (ca.key) is sensitive. Do not upload it or share it.

Viewing and exporting results

• Scans shows task status, progress, target, traffic/page count, and vulnerability count.
• Open a task to view collected pages/requests, technologies, vulnerabilities, and the saved request configuration.
• Use the vulnerability filters to narrow findings by severity or type.
• Use the task export actions to download collected URLs as TXT, JSON, or XML.
• Scan and vulnerability history is stored under the configured data directory and is restored after restart.

CLI quick reference

The CLI is useful for scripts, CI jobs, and reproducible scans. The command is ws or webscan.

Active scans

# Static crawl + scan
./wscan ws --basic-crawler \
  --url https://example.com/ \
  --json-output=result.json --html-output=result.html

# Headless-browser crawl for JavaScript applications
./wscan ws --browser-crawler \
  --url https://example.com/ \
  --html-output=result.html

# Scan URLs from a file, one URL per line
./wscan ws --basic-crawler --url-file=urls.txt --json-output=result.json

# Scan one endpoint with a request body
./wscan ws --url https://example.com/login \
  --data 'username=test&password=test' \
  --json-output=result.json

# Crawl without running vulnerability checks
./wscan ws --browser-crawler --url https://example.com/ \
  --no-scan --json-crawler-output=crawl.json

# Run only selected plugins
./wscan ws --basic-crawler --url https://example.com/ \
  --plug=sqldet,xss --json-output=result.json

CLI passive scan

# Generate the project CA first if needed
./wscan genca

# Listen on the default-style local address
./wscan ws --listen=127.0.0.1:7100 --json-output=result.json

# Restrict the plugin set
./wscan ws --listen=127.0.0.1:7100 \
  --plug=sqldet,xss --json-output=result.json

Configure the browser/client proxy and CA as described in the WebUI passive-scan section. Use the configured mitm.restriction in config.yaml to enforce hostname, path, port, and parameter restrictions for CLI passive scans.

Targets, scope, authentication, and proxy

For repeatable WebUI use, save targets with their include/exclude patterns and authentication settings before launching a task.

• Target: the base URL you are authorized to test.
• Include / exclude: limit paths and request patterns; keep logout and destructive endpoints excluded unless explicitly required.
• Authentication: configure the supported authentication type in the task form or saved target. Treat credentials and cookies as secrets.
• Proxy: use the global proxy from Config → Proxy, or override it for one active task. This is the upstream proxy used by wscan; it is different from the local MITM listener used by passive mode.

Example upstream proxy configuration:

http:
  proxy: "socks5://127.0.0.1:1080"

POC templates and custom plugins

POC templates are not bundled. If your authorized engagement requires them, point the POC option at a local Nuclei/Xray/Goby-compatible template directory:

./wscan ws --url https://example.com/ \
  --poc=/path/to/pocs/* --html-output=poc-result.html

Advanced authoring references:

• Web fingerprint plugin guide
• Web vulnerability plugin guide
• Custom FUZZ plugin guide

AI automated pentest

From the WebUI, create an AI Pentest project, enter an authorized target origin and a concrete goal, choose a worker, and start the project. The UI streams the agent's progress, tool calls, discovered facts, and findings.

Use a narrowly defined target and goal. Review every generated action and finding before treating it as a confirmed result. The local Claude Code worker requires the claude command to be available and authenticated; the rule-based worker can run without an LLM.

Reverse platform for blind callbacks

Start the reverse platform when an authorized test needs an external callback to confirm a blind vulnerability:

./wscan reverse

See Best Practices for deployment and callback configuration.

MCP server

Expose task and scan operations to an authorized MCP client:

./wscan mcp --mcp-host=127.0.0.1 --mcp-port=7001

Do not expose the MCP or WebUI ports publicly without authentication and network access controls.

Configuration and troubleshooting

• config.yaml contains crawler, HTTP, MITM, plugin, and reverse-platform settings.
• Run ./wscan ws --help and ./wscan webui --help to see the flags available in your build.
• If a passive task cannot start, check whether the listen port is already in use and whether ca.crt / ca.key are readable.
• If HTTPS traffic fails through MITM, install the generated CA in the client and ensure the client trusts it.
• If a scan finds nothing, verify the target scope, authentication state, selected plugins, and whether the client actually sent traffic through the configured proxy.

Best practices

• Start with a small, explicit scope and a low-impact plugin/profile selection.
• Exclude logout, delete, payment, password-reset, and other state-changing endpoints unless the engagement explicitly covers them.
• Use a dedicated browser profile for passive scans so unrelated traffic is not captured.
• Store result files, cookies, tokens, CA keys, and configuration backups securely.
• Stop the WebUI, MCP server, reverse platform, and passive listener when they are no longer needed.

License

See LICENSE.md.