Utility Tools

Diagnostic, testing, and development helpers for validating a deployment, exercising the portal API, generating test data, and checking dependencies. These are the tools you reach for when standing up a new agent, debugging an integration, or building demo environments.

Platform Validation

scripts/pi_validate.sh checks that a host is ready to run scans and uploads. It is especially useful on a fresh Raspberry Pi or other Linux target.

pi_validate.sh [options]

Options:
  --fix       Attempt to install missing dependencies automatically
  --json      Output results in JSON format
  --dry-run   Show what would be checked without executing fixes
  -h, --help  Show help

It runs eight checks: platform detection, bash version, core dependencies (nmap), optional dependencies, cross-platform MD5 hashing, cron availability, disk space, and network connectivity. --fix installs missing dependencies using the package manager for the detected platform (brew on macOS, apt-get on Debian and Linux).

./scripts/pi_validate.sh              # Report readiness
./scripts/pi_validate.sh --fix        # Report and repair missing deps
./scripts/pi_validate.sh --json       # Machine-readable output

See Raspberry Pi for the full deployment walk-through.

Dependency Check

scripts/dependency_check.sh provides the tiered dependency validation that the scan CLIs source at startup. It separates required tools (nmap) from core and optional tools, and reports which pipeline capabilities are available given what is installed. If nmap is missing it offers a platform-aware install prompt in interactive shells, and fails cleanly under CI, cron, or piped input. Run it directly to audit the recon dependencies on a host:

./scripts/dependency_check.sh

Missing optional tools (dig, whois, openssl, smbclient, snmpwalk, and so on) are reported as skipped capabilities rather than hard errors.

E2E Smoke Test

scripts/e2e_smoke_test.sh runs an end-to-end sequence against the configured consultation portal to verify connectivity and functionality.

e2e_smoke_test.sh -c <config> [options]

Required:
  -c <file>           Config file (CONSULTATION_API_URL, API key)

Options:
  --no-cleanup        Do not show cleanup instructions
  --dry-run           Show what would be tested without sending requests
  --timeout <sec>     Curl timeout in seconds (default: 30)
  -h, --help          Show help

The checks cover health, health JSON, benchmark auth, benchmark with key, sessions auth, upload method, upload round-trip, share-token lookup, upload auth, and delete auth.

./scripts/e2e_smoke_test.sh -c ~/netvuln-tool/configs/client.conf
./scripts/e2e_smoke_test.sh -c ~/netvuln-tool/configs/client.conf --dry-run

API Debug Tool

scripts/api_debug.sh wraps every portal endpoint in a subcommand CLI with verbose request and response logging. It is the tool for troubleshooting an integration or reproducing a failing request.

api_debug.sh [global flags] <subcommand> [subcommand flags]

Global flags

Flag	Purpose
-c <file>	Config file (sources CONSULTATION_API_URL and the API key)
-u <url>	API base URL override
-k <key>	API key override
-j <jwt>	JWT token for protected endpoints
--quiet	Minimal output (status code and body only)
--show-curl	Print the exact curl command, then execute it
--show-curl-only	Print the curl command without executing
--timeout <sec>	Override the default 30-second timeout
-h, --help	Show help

Subcommands

Subcommand	Method and path	Key flags
health	GET /api/health	--agents (requires JWT)
upload	POST /api/upload	-s <json> [-l <log>] [-r <report>] [-e <exec>]
download	GET /api/download	-s <session_id> [-f <filename>] [-o <output>]
share	GET /api/share	-t <token>
refresh	PUT /api/refresh	-s <session_id> -f <filename> -i <input_file>
benchmark	GET /api/benchmark	-s <session_id>
heartbeat	POST /api/health	--agent-id <id> --status <status> or --json <payload>
command-status	PATCH /api/agent-commands	--command-id <id> --agent-id <id> --status <s> or --json <payload>
sessions	GET /api/sessions	requires JWT via -j

# Check portal health
./scripts/api_debug.sh -c ~/netvuln-tool/configs/client.conf health

# Print the curl command for an upload without executing it
./scripts/api_debug.sh -c ~/netvuln-tool/configs/client.conf --show-curl-only upload -s session_results.json

# Quiet mode for scripting
./scripts/api_debug.sh -c ~/netvuln-tool/configs/client.conf --quiet health

# List sessions (protected endpoint, needs a JWT)
./scripts/api_debug.sh -c ~/netvuln-tool/configs/client.conf -j <jwt> sessions

The --show-curl and --show-curl-only flags print the exact curl command so you can reproduce a request by hand or attach it to a bug report. The endpoints themselves are documented in the API Contract.

Synthetic Collection Generator

scripts/synthetic_collection.sh generates realistic synthetic session data for testing portal features, trend analysis, and demo environments. It produces full session directories with configurable severity distributions and multi-session trends.

synthetic_collection.sh --target <target> [options]

Required:
  --target <string>        Target identifier, for example "10.0.0.0/24"

Options:
  --sessions <N>           Number of sessions to generate (default: 1)
  --findings <N>           Findings per session (default: 15)
  --mix <spec>             Severity distribution (default: "critical:10,high:20,medium:40,low:20,info:10")
  --interval <duration>    Time between sessions, for example 7d or 24h (default: 7d)
  --trend <direction>      improving, worsening, or stable (default: stable)
  --with-exceptions <N>    Mark N findings with exception metadata (default: 0)
  --seed <N>               Deterministic seed for reproducible output
  --client-id <string>     Client ID for portal multi-tenancy
  --json                   Output the created session paths as a JSON array
  -h, --help               Show help

# Five sessions showing an improving trend
./scripts/synthetic_collection.sh --target "10.0.0.0/24" --sessions 5 --trend improving

# Reproducible output with exception entries
./scripts/synthetic_collection.sh --target "192.168.1.0/24" --sessions 3 \
    --with-exceptions 2 --seed 42

# Custom severity mix scoped to a client, JSON output
./scripts/synthetic_collection.sh --target "172.16.0.0/16" --sessions 10 \
    --mix "critical:5,high:20,medium:45,low:25,info:5" \
    --client-id "acme-corp" --json