NoSQL Injection CLI Scanner

Command-line scanner for detecting potential NoSQL injection weaknesses in web form and endpoint workflows.

Features

1. URL validation and target reachability checks.
2. Same-origin crawling with configurable depth.
3. HTML form discovery and field extraction.
4. Payload injection in both application/x-www-form-urlencoded and application/json formats.
5. Heuristic response analysis with severity/confidence scoring.
6. JSON report generation and Rich console summaries.
7. Manual endpoint mode for JavaScript-driven forms.

Setup

Run from cli/.

1. Create a virtual environment

Windows PowerShell:

py -3.13 -m venv .venv
\.venv\Scripts\Activate.ps1

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate

2. Install dependencies

Windows PowerShell:

py -3.13 -m pip install -r requirements.txt

macOS / Linux:

python3 -m pip install -r requirements.txt

Usage

Help

py -3.13 scanner.py --help

Interactive mode (no flags)

py -3.13 scanner.py

The interactive menu offers:

1. Basic crawl scan (defaults)
2. Verbose crawl scan
3. Manual endpoint scan
4. Category-filtered crawl
5. Content-type filtered crawl
6. Advanced/custom scan
7. Exit

Basic scan

py -3.13 scanner.py --url http://localhost:3000 --output report.json

Verbose scan

py -3.13 scanner.py --url http://localhost:3000 --verbose --output verbose_report.json

Manual endpoint mode (skip crawling)

py -3.13 scanner.py --url http://localhost:3000 --endpoints "POST:/api/vuln/login:username,password" "POST:/api/vuln/search:query"

Filter payload categories

py -3.13 scanner.py --url http://localhost:3000 --categories operator_injection regex_extraction

Content type filter

py -3.13 scanner.py --url http://localhost:3000 --content-type json

CLI Options

• --url (required unless using no-flag interactive mode): target base URL.
• --max-depth (default 2): crawl depth limit.
• --timeout (default 5.0): request timeout in seconds.
• --delay (default 0.1): delay between injection requests.
• --output (default report.json): report output path.
• --verbose, -v: verbose request/response logging.
• --content-type (both|urlencoded|json): payload submission content type.
• --endpoints: manual endpoint specifications, format METHOD:/path:field1,field2.
• --categories: payload category allow-list.
• --confirm-external: required when scanning non-localhost targets.
• --version: print scanner version.

Argument validation notes:

• --max-depth must be at least 1.
• --timeout must be greater than 0.
• --delay must be greater than or equal to 0.
• --categories must match names defined in payloads.json.

Report Output Contract

The scanner writes a JSON report with this structure:

{
	"target": "http://localhost:3000/",
	"scan_time": "2026-04-26T10:15:00Z",
	"scan_duration_seconds": 42,
	"summary": {
		"pages_crawled": 3,
		"forms_tested": 2,
		"payloads_tested": 48,
		"potential_findings": 4,
		"by_severity": {
			"critical": 1,
			"high": 2,
			"medium": 1,
			"low": 0,
			"info": 0
		}
	},
	"findings": [
		{
			"severity": "critical",
			"confidence": "confirmed",
			"endpoint": "/api/vuln/login",
			"form_page": "http://localhost:3000/login.html",
			"method": "POST",
			"content_type": "json",
			"payload": {
				"username": {
					"$gt": ""
				},
				"password": {
					"$gt": ""
				}
			},
			"payload_category": "auth_bypass_combo",
			"evidence": "Auth bypass detected",
			"baseline_status": 401,
			"actual_status": 200,
			"response_snippet": "{\"ok\": true, ...}",
			"response_time_ms": 37.5
		}
	]
}

See a concrete sample in example_report.json.

Troubleshooting

Target unreachable

1. Ensure the target app is running.
2. Verify URL includes scheme (http:// or https://).
3. Confirm firewall/network policy allows local connections.

No forms discovered

1. Target may submit via JavaScript instead of HTML form actions.
2. Use manual endpoint mode via --endpoints.

Missing Python modules

Run:

py -3.13 -m pip install -r requirements.txt

Non-localhost target blocked

Add --confirm-external only when you are explicitly authorized to scan that target.

Invalid payload category

Run py -3.13 scanner.py --help to verify the flag syntax, then check category names in payloads.json.

Interrupted scan

If the scan receives Ctrl+C or SIGTERM, the scanner attempts to write a partial report to the configured --output path before exiting.

Exit Codes

• 0: scan completed successfully, or interactive mode exited without starting a scan.
• 1: runtime failure such as network, configuration, or report-writing errors.
• 2: invalid command usage or validation failure.
• 130: interrupted by SIGINT / Ctrl+C.
• 143: interrupted by SIGTERM.

Uninstall

The CLI is not packaged as a system-wide installer. To remove it:

• delete the cli/.venv directory
• remove any generated report files such as report.json
• optionally uninstall dependencies from the active environment with python -m pip uninstall -r requirements.txt -y

Legal and Ethical Use

Use this scanner only on systems you own or where you have explicit written authorization.

Unauthorized scanning or exploitation is prohibited.