WebScope.js

Educational Defensive Web Recon Tool - Visibility enables defense and learning.

WebScope.js is a powerful defensive security scanner that analyzes publicly exposed web application surfaces and highlights potential security risks. It helps developers, students, and security professionals understand their web exposure and improve security posture through safe, ethical reconnaissance.

Features

11 Security Plugins

Module	Description	Risk Assessment
headers	HTTP security header analysis	Missing CSP, HSTS, X-Frame-Options
tls	SSL/TLS certificate inspection	Expired certs, weak protocols
dns	DNS record enumeration	Missing records, misconfigurations
robots	robots.txt & sitemap.xml	Exposed paths
fingerprint	Technology detection	Server, framework identification
cors	CORS configuration	Wildcard origins
http-methods	HTTP method testing	Dangerous methods enabled
ports	Common port scanning	Open high-risk ports
security-txt	security.txt policy validation	Missing contact/expiry
exposure	Exposed files/endpoint checks	.env/.git/config/backup leaks
os	Passive OS fingerprint guessing	Environment confidence hints

Output Formats

CLI - Colored terminal output
JSON - Structured data for automation
HTML - Beautiful styled report
CSV - Spreadsheet-compatible
TXT - Plain text format

Filter System

Filter by severity (CRITICAL, HIGH, MEDIUM, LOW)
Filter by module highest risk
Filter by module include/exclude and prefix
Filter by score range (min/max) and minimum issue count
Filter by issue type
Filter by modules with findings only
Includes 10 built-in filters in src/filters/

Nano AI Assistant

Local Nano AI summarizes results and suggests prioritized remediation steps
Included in CLI/TXT/HTML outputs and JSON result payload

Educational Mode

--learn explains what each scanned module is checking and how to validate it manually
webscope.js learn <topic> provides module-by-module learning topics
Prompt mode supports set learn true and learn <topic>

Installation

# Clone or download the project
cd WebScope.js

# Install dependencies
npm install

# Optional: build Rust sidecar engine for fast port checks
npm run build:rust-engine

# Link for global CLI usage
npm link

# Or run directly
node bin/webscope.js

By default, scans print results in terminal only. Use -o <format> with -f <file> when you want to export a report file.

Rust Engine (Optional)

WebScope.js can use a Rust sidecar binary for the ports module:

# Build engine
npm run build:rust-engine

# Run scan with Rust engine
webscope.js scan example.com --modules ports --engine rust

# Choose Rust execution mode (threaded|parallel|async|sync)
webscope.js scan example.com --modules ports --engine rust --rust-mode async

If the Rust binary is not available, WebScope.js automatically falls back to the Node.js ports scanner.

Project metadata (author, contact, version, engine notes) is stored in metadata.json.

Refactored structure:

src/help-menu.js - shared help/explain menu system
src/metadata.js - metadata loader
src/nano-ai.js - Nano AI local assistant
src/scanner.js - scanner orchestration
src/plugins/ - 11 plugins
src/filters/ - 10 filters
src/engines/scanners/ - async/sync/rust-threaded scan engines
src/engines/rust.js - Rust sidecar bridge

Quick Start

Command Line

# Quick scan (basic modules)
webscope.js quick example.com

# Full scan (all modules)
webscope.js full example.com

# Custom scan with selected modules
webscope.js scan example.com --modules headers,tls,dns

# Enable passive OS fingerprint guessing
webscope.js scan example.com --os

# Educational walkthrough after a scan
webscope.js scan example.com --learn

# Read a focused learning topic
webscope.js learn headers

# Generate HTML report
webscope.js scan example.com -o html -f report.html

# Filter results by severity
webscope.js scan example.com --severity CRITICAL,HIGH

# Filter by highest module risk + findings only
webscope.js scan example.com --risk CRITICAL,HIGH --has-issues

# Export CSV explicitly
webscope.js scan example.com -o csv -f report.csv

# Explain available flags/keywords
webscope.js --explain
webscope.js --explain keywords

# Use Rust engine for ports module (falls back to Node if binary is missing)
webscope.js scan example.com --modules ports --engine rust
webscope.js scan example.com --modules ports --engine rust --rust-mode threaded

Interactive Console

# Launch prompt mode directly (recommended)
webscope.js --prompt-mode
# or
webscope.js --prompt-mode

# Start prompt mode with preloaded settings
webscope.js scan example.com --modules headers,tls --prompt-mode

# In prompt mode:
webscope.js(console) > set target example.com
webscope.js(console) > set modules headers,tls,dns
webscope.js(console) > execute
webscope.js(console) > output json
webscope.js(console) > save report.html

Command-Line Usage

Flag System

WebScope.js supports a flexible flag system for quick scanning:

webscope.js [target] [options]
webscope.js scan [target] [options]
webscope.js [command] [target] [options]

Global Flags

Flag	Short	Description	Example
`--target`	`-t`	Target URL or domain	`-t example.com`
`--output`	`-o`	Output format	`-o json`
`--file`	`-f`	Save to file	`-f report.html`
`--modules`	`-m`	Modules to run	`-m headers,tls`
`--quick`	`-q`	Quick scan mode	`-q`
`--verbose`	`-v`	Verbose output	`-v`
`--severity`	-	Filter by severity	`--severity CRITICAL`
`--risk`	-	Filter by highest module risk	`--risk CRITICAL,HIGH`
`--min-score`	-	Minimum score	`--min-score 50`
`--max-score`	-	Maximum score	`--max-score 80`
`--has-issues`	-	Only keep modules with findings	`--has-issues`
`--include-modules`	-	Filter output to selected modules	`--include-modules headers,tls`
`--module-prefix`	-	Filter output by module prefix	`--module-prefix sec`
`--issue-type`	-	Filter output by issue type	`--issue-type missing,warning`
`--min-issues`	-	Minimum issue count per module	`--min-issues 1`
`--exclude`	-	Exclude modules	`--exclude ports,exposure`
`--engine`	-	Execution engine (`node`,`rust`,`rust-threaded`,`rust-async`,`rust-sync`)	`--engine rust-async`
`--rust-mode`	-	Rust ports mode (`threaded`,`parallel`,`async`,`sync`)	`--rust-mode async`
`--scan-engine`	-	Scheduler engine (`async`,`sync`,`rust-threaded`)	`--scan-engine rust-threaded`
`--learn`	-	Print educational explanations after scan	`--learn`
`--explain`	-	Explain flags and prompt keywords	`--explain keywords`
`--prompt-mode`	-	Start console-style prompt mode	`--prompt-mode`
`--no-color`	-	Disable colors	`--no-color`

Examples

# Basic usage with just a target
webscope.js example.com

# Specify target with flag
webscope.js scan -t example.com

# JSON output to file
webscope.js scan example.com -o json -f results.json

# HTML report
webscope.js scan example.com -o html -f report.html

# Quick scan
webscope.js quick example.com

# Full scan with all modules
webscope.js full example.com

# Custom modules
webscope.js scan example.com -m headers,tls,dns,security-txt

# All modules
webscope.js scan example.com -m all

# With filters
webscope.js scan example.com --severity CRITICAL,HIGH
webscope.js scan example.com --risk HIGH,MEDIUM
webscope.js scan example.com --min-score 70
webscope.js scan example.com --max-score 90
webscope.js scan example.com --has-issues
webscope.js scan example.com --include-modules headers,tls
webscope.js scan example.com --module-prefix sec
webscope.js scan example.com --issue-type missing
webscope.js scan example.com --min-issues 1
webscope.js scan example.com --exclude ports,exposure

# Combine flags
webscope.js scan example.com -o html -f report.html -m headers,tls --severity HIGH

# Use Rust engine
webscope.js scan example.com -m ports --engine rust
webscope.js scan example.com -m ports --engine rust --rust-mode async
webscope.js scan example.com -m ports --engine rust-threaded
webscope.js scan example.com -m ports --engine rust-async

# Use scheduler engine
webscope.js scan example.com --scan-engine rust-threaded

# Launch prompt mode
webscope.js --prompt-mode
webscope.js scan example.com --prompt-mode

# Educational explanations after scan
webscope.js scan example.com --learn

# Learn a specific module
webscope.js learn tls

# Explain docs in terminal
webscope.js --explain
webscope.js --explain flags

Commands

Command	Alias	Description
`scan [target]`	default	Run security scan
`quick [target]`	`q`	Quick scan (basic modules)
`full [target]`	`f`	Full scan (all modules)
`modules`	`mod`	List available modules
`formats`	`fmt`	List output formats
`filters`	`fl`	List filter options
`explain [topic]`	`exp`	Explain flags/keywords (`flags`, `keywords`, `all`)
`learn [topic]`	`lesson`	Educational topics (`overview`, `principles`, `modules`, `<module>`)
`serve`	`s`	Start API server
`console`	`shell`, `interactive`	Start interactive prompt mode

Interactive Console

WebScope.js includes an interactive console mode for beginners:

webscope.js --prompt-mode
# or:
webscope.js console

Console Commands

set target <url>          Set target to scan
set modules <list|all>    Set modules (comma-separated or "all")
set learn <true|false>    Enable educational explanation mode
set engine <value>        Set engine (node|rust|rust-threaded|rust-async|rust-sync)
set rust-mode <mode>      Set Rust ports mode (threaded|parallel|async|sync)
set scan-engine <name>    Set scheduler engine (async|sync|rust-threaded)
set severity <levels>     Set severity filter (CRITICAL,HIGH,MEDIUM,LOW,INFO)
set risk <levels>         Set highest module risk filter
set min-score <0-100>     Set minimum score filter
set max-score <0-100>     Set maximum score filter
set has-issues <bool>     Keep only modules with findings (true/false)
set include-modules <list> Filter output to selected modules
set module-prefix <list>   Filter output by module prefix
set issue-type <list>      Filter output by issue type
set min-issues <count>     Filter output by minimum issue count
set exclude <list>        Exclude modules
set output <format>       Set output format (cli,json,html,csv,txt)
set file <path>           Set default save file
set verbose <true|false>  Toggle verbose mode
unset <option>            Clear filters/settings
use <module|all>          Use a single module (console-style) or all modules
show modules              List available modules/plugins
show filters              Show active filters
show formats              Show output formats
config                    Show current prompt configuration quickly
explain [topic]           Explain flags/keywords (flags|keywords|all)
show options              Show current prompt configuration
show keywords             Show flag keywords supported in prompt mode
show learn                Show educational guide for latest results
show ai                   Show Nano AI summary from latest run
show results              Show latest scan results
execute [quick|full]      Run scan
learn [topic]             Show learning topic (overview|principles|modules|<module>)
output <format>           Shortcut for set output
save [format] <file>      Save latest results (supports csv/json/html/txt)
banner                    Clear screen and print banner
clear                     Clear screen
help                      Show this help
exit / quit / back        Exit prompt mode

Flag Keyword Mapping In Prompt Mode

CLI Flag	Prompt Mode Equivalent
`--target`	`set target <url>`
`--modules`	`set modules <list
`--learn`	`set learn true`
`--engine`	`set engine <value>`
`--rust-mode`	`set rust-mode <mode>`
`--severity`	`set severity <levels>`
`--risk`	`set risk <levels>`
`--min-score`	`set min-score <0-100>`
`--max-score`	`set max-score <0-100>`
`--has-issues`	`set has-issues true`
`--include-modules`	`set include-modules <list>`
`--module-prefix`	`set module-prefix <list>`
`--issue-type`	`set issue-type <list>`
`--min-issues`	`set min-issues <count>`
`--exclude`	`set exclude <list>`
`--output`	`set output <format>`
`--scan-engine`	`set scan-engine <name>`
`--file`	`set file <path>`
`--verbose`	`set verbose true
`--quick`	`execute quick`
`--explain`	`explain [topic]`
`--help`	`help`

Console Examples

webscope.js(console) > set target example.com
webscope.js(console) > set modules headers,tls,dns
webscope.js(console) > set learn true
webscope.js(console) > set severity CRITICAL,HIGH
webscope.js(console) > set risk HIGH,MEDIUM
webscope.js(console) > set scan-engine rust-threaded
webscope.js(console) > set rust-mode async
webscope.js(console) > set include-modules headers,tls
webscope.js(console) > set issue-type missing
webscope.js(console) > set engine rust
webscope.js(console) > config
webscope.js(console) > explain keywords
webscope.js(console) > execute
webscope.js(console) > show ai
webscope.js(console) > learn headers
webscope.js(console) > output json
webscope.js(console) > save report.json
webscope.js(console) > execute quick
webscope.js(console) > exit

API Server

Start the API server for programmatic access:

webscope.js serve
webscope.js serve -p 3000
webscope.js serve --host 0.0.0.0 -p 8080

API Endpoints

GET  /                   - API info page
POST /api/scan           - Run security scan
GET  /api/modules        - List available modules
GET  /api/filters        - List filter options
GET  /api/formats        - List output formats
GET  /api/health         - Health check

API Examples

# Run scan via API
curl -X POST http://localhost:3000/api/scan \
  -H "Content-Type: application/json" \
  -d '{"target": "example.com", "modules": {"headers": true, "tls": true}, "engine": "node"}'

# Run ports with Rust async mode via API
curl -X POST http://localhost:3000/api/scan \
  -H "Content-Type: application/json" \
  -d '{"target": "example.com", "modules": {"ports": true}, "engine": "rust", "rustMode": "async"}'

# Include educational explanation in JSON response
curl -X POST http://localhost:3000/api/scan \
  -H "Content-Type: application/json" \
  -d '{"target":"example.com","learn":true}'

# Get modules
curl http://localhost:3000/api/modules

# Get filters
curl http://localhost:3000/api/filters

Modules

Core Plugins (Enabled by Default)

headers - Analyze HTTP security headers (CSP, HSTS, X-Frame-Options, etc.)
tls - Check SSL/TLS certificate validity and configuration
dns - Enumerate DNS records (A, AAAA, MX, NS, TXT, CNAME)
robots - Check robots.txt and sitemap.xml
fingerprint - Detect server technologies and frameworks

Extended Plugins (Disabled by Default)

cors - Check CORS configuration
http-methods - Test allowed HTTP methods
ports - Scan common ports
security-txt - Validate /.well-known/security.txt
exposure - Check exposed files/endpoints (.env, .git/config, backups, metrics)

Using Modules

# Enable specific modules
webscope.js scan example.com -m headers,tls,dns

# Enable all modules
webscope.js scan example.com -m all

# In console
webscope.js(console) > set modules headers,tls,dns,cors
webscope.js(console) > execute

Output Formats

Scans print directly in terminal by default. To export a file, pass both -o <format> and -f <file>.

CLI (Default)

webscope.js scan example.com
webscope.js scan example.com -o cli

JSON

webscope.js scan example.com -o json
webscope.js scan example.com -o json -f results.json

HTML

webscope.js scan example.com -o html
webscope.js scan example.com -o html -f report.html

CSV

webscope.js scan example.com -o csv
webscope.js scan example.com -o csv -f data.csv

TXT

webscope.js scan example.com -o txt
webscope.js scan example.com -o txt -f report.txt

Filters

Filter Options

Filter	Description	Values
`--severity`	Filter by finding severity	CRITICAL, HIGH, MEDIUM, LOW, INFO
`--risk`	Filter by module highest risk	CRITICAL, HIGH, MEDIUM, LOW, INFO
`--min-score`	Minimum score threshold	0-100
`--max-score`	Maximum score threshold	0-100
`--has-issues`	Keep only modules with findings	boolean flag
`--include-modules`	Include only specific modules	Comma-separated list
`--exclude`	Exclude specific modules	Comma-separated list
`--module-prefix`	Include module names matching prefix	Comma-separated list
`--issue-type`	Include findings by issue type	Comma-separated list
`--min-issues`	Minimum issue count per module	integer >= 0
`--modules`	Select which plugins execute	Comma-separated list or `all`

Filter Examples

# Show only critical issues
webscope.js scan example.com --severity CRITICAL

# Show critical and high
webscope.js scan example.com --severity CRITICAL,HIGH

# Filter by highest module risk
webscope.js scan example.com --risk HIGH,MEDIUM

# Minimum score of 70
webscope.js scan example.com --min-score 70

# Maximum score of 85
webscope.js scan example.com --max-score 85

# Keep only modules with findings
webscope.js scan example.com --has-issues

# Specific modules only
webscope.js scan example.com --include-modules headers,tls,dns

# Exclude certain modules
webscope.js scan example.com --exclude ports,exposure

# Prefix-based module filter
webscope.js scan example.com --module-prefix sec

# Type-based finding filter
webscope.js scan example.com --issue-type missing

# Minimum issue count
webscope.js scan example.com --min-issues 1

# Combine filters
webscope.js scan example.com --severity CRITICAL,HIGH --risk HIGH --min-score 50 --has-issues --min-issues 1

Security Considerations

Blocks localhost/private IP addresses - Prevents scanning internal networks
Passive checks only - No exploitation or aggressive scanning
Request timeout limits - Prevents hanging connections
Clear user-agent identification - Identifies scanner in requests
Rate limiting - Respects target servers

License

MIT License - See LICENSE file for details.

Credits

Created for defensive security research and educational purposes. Use responsibly and only on systems you have permission to scan.

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
.vscode		.vscode
bin		bin
building-scripts		building-scripts
engines/rust-scanner		engines/rust-scanner
node_modules		node_modules
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
metadata.json		metadata.json
package-lock.json		package-lock.json
package.json		package.json

License

voltsparx/WebScope.js

Folders and files

Latest commit

History

Repository files navigation

WebScope.js

Table of Contents

Features

11 Security Plugins

Output Formats

Filter System

Nano AI Assistant

Educational Mode

Installation

Rust Engine (Optional)

Quick Start

Command Line

Interactive Console

Command-Line Usage

Flag System

Global Flags

Examples

Commands

Interactive Console

Console Commands

Flag Keyword Mapping In Prompt Mode

Console Examples

API Server

API Endpoints

API Examples

Modules

Core Plugins (Enabled by Default)

Extended Plugins (Disabled by Default)

Using Modules

Output Formats

CLI (Default)

JSON

HTML

CSV

TXT

Filters

Filter Options

Filter Examples

Security Considerations

License

Credits

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages