Getting Started
Initialize your environment and execute your first verification-driven security analysis scan in under five minutes.
Mental Model
VScanX is engineered under a **verification-first** philosophy. Unlike traditional scanners that output hundreds of speculative warnings based on basic version headers or regex matches, VScanX models your system's dynamic posture and automatically deploys safe, isolated payloads to prove whether a vulnerability is actually reproducible.
Running a scan involves three simple phases:
- Probing: A lightweight module analyzes target surface interfaces (HTTP parameters, EVM contract addresses, RPC nodes, or LLM agent endpoints).
- Eventing: Detected anomalies are emitted as typed event contracts to a central event bus.
- Validation: The orchestrator spawns an isolated sandbox to run dynamic verification payloads, confirming the finding with absolute confidence.
Prerequisites & Requirements
Ensure your host system meets the following engineering baselines before installing:
- Runtime: Python 3.11 or higher.
- Network Libs: Raw socket capture capabilities (requires standard administrative permissions or root access to mount Scapy engines).
- Containerization: Docker or gVisor socket accessibility (strictly required if orchestrating containerized sandbox validation checks).
[!] Administrative / Root Permissions
Because VScanX's network modules utilize standard Scapy interfaces to perform packet injection and passive TLS handshakes, raw socket privileges are required. Run the orchestrator with sudo privileges on Linux, or ensure administrative command terminals are active on Windows.
Installation Walkthrough
Clone the core framework source repository and prepare your Python virtual environment:
git clone https://github.com/hnikhil-dev/VScanX.git cd VScanX
Create and activate an isolated virtual environment to prevent package namespace collisions:
# On Unix / macOS python -m venv venv source venv/bin/activate # On Windows python -m venv venv venv\Scripts\activate
Install all core framework dependencies via the requirements index:
pip install -r requirements.txt
Executing Your First Scan
VScanX supports specialized scanning domains out of the box. Execute a verified Web scan using the CLI entrypoint:
python vscanx.py -t target-url.com --verify
💡 Pro-Tip: Decoupled Replay Cache
Every scan cycle automatically saves a serialized run snapshot under ~/.vscanx/runs/. You can perform rapid delta regression tests on target code mutations later without running a full re-scan by calling: python vscanx.py --replay <run_id>.
Core Scanning Profiles
VScanX organizes modules into four primary scan profiles:
| Profile Flag | Target Schema | Verification Sandbox | Sample Command |
|---|---|---|---|
| --profile web | HTTP APIs & Web Apps | Isolated Docker container | python vscanx.py -t target.io --profile web --verify |
| --profile network | Ports & TLS Layers | Raw socket assertion checks | python vscanx.py -t 192.168.1.1 --profile network --verify |
| --profile web3 | Ethereum Contracts | Local Anvil RPC fork node | python vscanx.py -t 0xde0B... --profile web3 --verify |
| --profile agentic | AI Agent Prompt APIs | gVisor runtime shell pod | python vscanx.py -t api.agent.io --profile agentic --verify |
Onboarding Troubleshooting
Issue: Scapy Raw Socket Bind Error
Resolution: On Linux, prepending sudo is required to bind socket listeners. On Windows, make sure the Npcap/WinPcap driver is active. Alternatively, specify a safe passive network interface manually: python vscanx.py -t target.io --interface eth0.
Issue: Docker Socket Validation Timeout
Resolution: Ensure the Docker daemon is active and your current shell user is added to the docker security group. If running in a local CI sandbox without container access, use the passive mode fallback flags: --verify-mode local-only.