A cross-platform vulnerability scanner, penetration tester, zero-day detector, and OS hardener with optional LLM-powered analysis. Built in Python with only two runtime dependencies.
VulnTester runs a five-phase security pipeline — scanning, penetration testing, zero-day detection, hardening, and AI analysis — producing a standalone HTML report with severity-rated findings, attack paths, anomaly scores, and remediation guidance.
- Features
- Supported Platforms
- Installation
- Quick Start
- Usage
- CLI Reference
- Architecture
- Reports
- Design Documentation
- Security Considerations
- Requirements
- License
Vulnerability Scanning — 14 scanners aligned to CIS benchmarks covering firewall configuration, SSH hardening, kernel parameters, filesystem permissions, password policies, cryptographic settings, network configuration, running services, installed software, patch status, antivirus presence, audit logging, Windows registry policies, and user account security.
Penetration Testing — 5 offensive security modules that enumerate attack surface: port scanning with banner grabbing, credential and secret exposure detection, network exposure analysis, privilege escalation vector identification (SUID binaries, sudo misconfigs, Docker socket access), and known service vulnerability checks.
Zero-Day Detection — 6 anomaly detectors with a heuristic correlation engine. Detects process name mimicry, deleted binaries, RWX memory regions, orphan processes, unusual network listeners, suspicious binary characteristics, file integrity violations, and behavioral deviations from saved baselines. The heuristic engine cross-correlates signals by PID and boosts confidence when multiple detectors flag the same process.
Automated Hardening — 12 hardening modules that remediate scanner findings with a backup-first approach. Every change is backed up to a timestamped directory with a JSON manifest before modification. Full rollback from any manifest with a single command.
LLM-Powered Analysis — Optional AI integration with Claude (Anthropic), Grok (xAI), or Gemini (Google). Sends aggregated findings for executive summaries, prioritized action items, systemic issue identification, and remediation code suggestions. Uses stdlib HTTP only — no vendor SDKs required.
Standalone HTML Reports — Single-file reports with embedded CSS/JS, dark/light mode, interactive severity filtering, sortable tables, and executive risk scoring. Works offline, in airgapped environments, and can be emailed or attached to compliance tickets.
| Platform | Scanning | Pen Testing | Zero-Day Detection | Hardening |
|---|---|---|---|---|
| Linux (Debian, Ubuntu, RHEL, CentOS, Fedora, Arch) | Full | Full | Full | Full |
| Windows 10/11, Server 2016+ | Full | Full | Full | Full |
| macOS 12+ | Full | Full | Full | Full |
Platform-specific logic is handled transparently — each module dispatches to the correct implementation based on detected OS.
git clone https://github.com/ssevera1/Vulnerability-Scanner.git
cd Vulnerability-Scanner
pip install .pip install -e .| Package | Version | Purpose |
|---|---|---|
psutil |
>= 5.9.0 | Cross-platform process and system introspection |
jinja2 |
>= 3.1.0 | HTML report templating |
Python 3.10 or later is required.
# Safe read-only scan (no system modifications)
vulntester --scan-only
# Full scan with interactive hardening prompts
vulntester
# Full scan with automatic hardening (no prompts)
vulntester --auto-harden
# Scan specific modules only
vulntester --scan-only --modules firewall ssh kernel
# Full pipeline with AI analysis
vulntester --llm-assist --llm-provider claude --llm-api-key sk-ant-...Note: Run with administrator/root privileges for complete scan coverage. Without elevated privileges, some checks (kernel parameters, service enumeration, registry inspection) will be skipped.
VulnTester operates in three mutually exclusive modes:
| Mode | Flag | Behavior |
|---|---|---|
| Interactive (default) | --interactive |
Scans the system, then prompts before each hardening module |
| Scan-only | --scan-only |
Read-only scan with no system modifications |
| Auto-harden | --auto-harden |
Scans and applies all recommended fixes without prompts |
# Interactive mode (default) — prompts for each hardener
vulntester
# Read-only audit
vulntester --scan-only
# Automated remediation for CI/CD or golden image builds
vulntester --auto-hardenRun only specific scanner/hardener modules by name:
# Scan only firewall, SSH, and kernel modules
vulntester --scan-only --modules firewall ssh kernel
# Harden only network and password settings
vulntester --modules network passwordsAvailable module names: antivirus, audit_logging, crypto, filesystem, firewall, kernel, network, passwords, patches, registry, services, software, ssh, users
Pen testing runs by default after the vulnerability scan. It identifies exploitable attack surface including open ports, exposed credentials, privilege escalation vectors, and known service vulnerabilities.
# Skip penetration testing
vulntester --scan-only --skip-pentest
# Run pen tests alongside scanning
vulntester --scan-onlyZero-day detection uses behavioral heuristics and anomaly scoring (0-100) to identify potentially unknown threats. The heuristic correlation engine runs after individual detectors and boosts confidence when multiple independent detectors flag the same process.
# Skip zero-day detection
vulntester --scan-only --skip-zeroday
# Full pipeline including zero-day detection
vulntester --scan-onlyWhen not in --scan-only mode, VulnTester offers to remediate detected vulnerabilities. Every change is backed up before application.
Interactive mode presents each hardener module with its findings and asks for confirmation:
--- Hardener: firewall (3 findings) ---
[CRITICAL] Firewall is disabled
[HIGH] Default incoming policy is ACCEPT
[MEDIUM] Firewall logging is disabled
Apply firewall fixes? [y/N/q]
Responding y applies fixes, N skips the module, and q aborts all remaining hardening.
Auto-harden mode applies all fixes without prompts:
vulntester --auto-hardenEvery hardening action creates a timestamped backup in ~/.vulntester/backups/. To undo all changes from a hardening session:
# Rollback from a specific backup manifest
vulntester --rollback ~/.vulntester/backups/20250115_143022/manifest.jsonThe manifest is a human-readable JSON file listing every file and registry value that was backed up. You can inspect it before rolling back:
cat ~/.vulntester/backups/20250115_143022/manifest.jsonSave the current system state as a baseline and compare against it in future scans to detect drift:
# Save current state as baseline
vulntester --scan-only --save-baseline baseline.json
# Compare against a saved baseline (detects new processes, ports, users, files)
vulntester --scan-only --baseline baseline.jsonThe behavioral baseline detector uses saved baselines for temporal reasoning — identifying what changed since the baseline was captured.
Enable optional AI-powered analysis by specifying a provider and API key. The LLM receives the complete scan report and returns an executive summary, prioritized actions, systemic issue identification, and per-finding remediation guidance.
# Using Claude (Anthropic)
vulntester --scan-only --llm-assist --llm-provider claude --llm-api-key sk-ant-...
# Using Grok (xAI)
vulntester --scan-only --llm-assist --llm-provider grok --llm-api-key xai-...
# Using Gemini (Google)
vulntester --scan-only --llm-assist --llm-provider gemini --llm-api-key AIza...API keys can also be set via environment variables:
| Provider | Environment Variable |
|---|---|
| Claude | ANTHROPIC_API_KEY |
| Grok | XAI_API_KEY |
| Gemini | GEMINI_API_KEY |
export ANTHROPIC_API_KEY="sk-ant-..."
vulntester --scan-only --llm-assist --llm-provider claudeUse --llm-model to override the default model:
vulntester --llm-assist --llm-provider claude --llm-model claude-opus-4-6Default models: Claude Sonnet 4.5, Grok 3, Gemini 2.0 Flash
vulntester [OPTIONS]
Scan Modes (mutually exclusive):
--scan-only Scan only, no hardening (safe mode)
--auto-harden Apply all fixes without prompts
--interactive Prompt before each fix (default)
Module Selection:
--modules MOD [MOD ...] Run only named modules
--skip-pentest Skip penetration testing
--skip-zeroday Skip zero-day detection
Baseline:
--baseline PATH Compare against saved baseline JSON
--save-baseline PATH Save current state as baseline
Output:
--report PATH HTML report output path (default: vulntester_report.html)
--verbose, -v Enable debug logging
Backup & Rollback:
--backup-dir PATH Custom backup directory
--rollback PATH Rollback from backup manifest.json
LLM Analysis (optional):
--llm-assist Enable AI-powered analysis
--llm-provider PROVIDER claude, grok, or gemini
--llm-api-key KEY API key (or use env vars)
--llm-model MODEL Override default model
Phase 1 Phase 2 Phase 3 Phase 4 Phase 5
Scanning --> Pen Testing --> Zero-Day --> Hardening --> LLM Analysis
(14 modules) (5 modules) Detection (12 modules) (optional)
(6 detectors)
|
Heuristic Engine
(cross-correlation)
|
v
Report Generation
(standalone HTML file)
vulntester/
├── __init__.py # Package metadata (v1.0.0)
├── __main__.py # Orchestrator — five-phase pipeline
├── cli.py # Argument parsing → ScanConfig
├── config.py # ScanConfig dataclass, Severity/Platform enums
├── platform_info.py # OS, distro, architecture detection
├── privilege.py # Admin/root privilege check
├── utils.py # Safe subprocess wrapper with timeouts, logging setup
├── backup.py # BackupManager — timestamped file + registry backup with JSON manifests
│
├── scanners/ # 14 CIS-aligned vulnerability scanners
│ ├── __init__.py # @register_scanner decorator registry
│ ├── base.py # AbstractScanner with platform dispatch
│ ├── antivirus.py # AV presence and status
│ ├── audit_logging.py # Audit log configuration
│ ├── crypto.py # TLS settings, weak ciphers
│ ├── filesystem.py # Permissions, sticky bits, mount options
│ ├── firewall.py # ufw / iptables / Windows Firewall / macOS ALF
│ ├── kernel.py # sysctl parameters (ASLR, SYN cookies, IP forwarding)
│ ├── network.py # Network configuration security
│ ├── passwords.py # PAM, complexity, expiration policies
│ ├── patches.py # apt / yum / dnf / Windows Update status
│ ├── registry.py # Windows registry security policies
│ ├── services.py # Running services, risky service detection
│ ├── software.py # Installed software inventory
│ ├── ssh.py # CIS 5.2 — PermitRootLogin, crypto algorithms
│ └── users.py # Account security, locked accounts, sudo
│
├── hardeners/ # 12 backup-first remediation modules
│ ├── __init__.py # @register_hardener decorator registry
│ ├── base.py # AbstractHardener with backup integration
│ ├── audit_logging.py # Enable/configure audit logging
│ ├── crypto.py # Enforce TLS 1.2+, remove weak ciphers
│ ├── filesystem.py # Fix permissions, mount options
│ ├── firewall.py # Enable firewall, set default deny
│ ├── kernel.py # Apply sysctl hardening
│ ├── network.py # Disable forwarding, block redirects
│ ├── passwords.py # Enforce password complexity
│ ├── registry.py # Fix Windows registry security values
│ ├── services.py # Disable unnecessary services
│ ├── software.py # Install pending security updates
│ ├── ssh.py # Apply CIS SSH recommendations
│ └── users.py # Lock dormant accounts, fix sudo
│
├── pentest/ # 5 offensive security modules
│ ├── __init__.py # @register_pentest decorator registry
│ ├── base.py # AbstractPenTest with platform dispatch
│ ├── credential_exposure.py # Scan for exposed secrets, API keys, SSH keys
│ ├── network_exposure.py # Public service exposure analysis
│ ├── port_scan.py # Port enumeration, banner grabbing, risk rating
│ ├── privilege_escalation.py # SUID, sudo misconfig, Docker socket, writable PATH
│ └── service_exploit.py # Known service vulnerability detection
│
├── zeroday/ # 6 anomaly detectors + heuristic engine
│ ├── __init__.py # @register_detector decorator registry
│ ├── base.py # AbstractZeroDayDetector with scoring (0-100)
│ ├── behavioral_baseline.py # Deviation from saved baseline
│ ├── binary_analysis.py # Suspicious binary characteristics
│ ├── file_integrity.py # SUID/SGID changes, modified system binaries
│ ├── heuristic_engine.py # Cross-module PID correlation, score boosting
│ ├── network_anomaly.py # Unusual listeners, suspicious connections
│ └── process_anomaly.py # Name mimicry, deleted binaries, RWX memory
│
├── llm/ # Optional multi-provider AI analysis
│ ├── __init__.py
│ ├── client.py # Unified HTTP client (Claude, Grok, Gemini) — stdlib only
│ └── analyzer.py # Prompt engineering, report analysis, remediation suggestions
│
└── report/ # Standalone HTML report generator
├── __init__.py
├── models.py # Finding, PenTestFinding, ZeroDayAnomaly, ScanReport dataclasses
└── generator.py # Jinja2 template → single-file HTML with dark/light mode
| Module | Description | CIS Reference |
|---|---|---|
antivirus |
Detects AV presence and operational status | CIS 8.1 |
audit_logging |
Verifies audit log configuration and retention | CIS 4.1 |
crypto |
Checks TLS settings, certificate validation, weak ciphers | CIS 1.1 |
filesystem |
File permissions, sticky bits, world-writable directories, mount options | CIS 1.1, 6.1 |
firewall |
Firewall status, default policies, rule analysis (ufw/iptables/netsh/ALF) | CIS 3.5 |
kernel |
Kernel parameters — ASLR, SYN cookies, IP forwarding, core dumps | CIS 3.1-3.3 |
network |
IP forwarding, ICMP redirects, source routing, network configuration | CIS 3.1-3.3 |
passwords |
Password complexity, expiration, PAM configuration, history | CIS 5.3-5.4 |
patches |
Pending security updates via apt/yum/dnf/Windows Update | CIS 1.9 |
registry |
Windows security registry policies (UAC, audit, network) | CIS (Windows) |
services |
Running service inventory, risky service detection | CIS 2.1-2.2 |
software |
Installed software inventory, known vulnerability detection | CIS 2.1 |
ssh |
SSH configuration — PermitRootLogin, crypto algorithms, protocol version | CIS 5.2 |
users |
Account security, dormant accounts, sudo/admin group membership | CIS 5.4-5.6 |
| Module | Description |
|---|---|
port_scan |
Enumerates listening services, performs banner grabbing, rates port risk |
credential_exposure |
Scans for exposed passwords, API keys, SSH private keys, and secrets in common locations |
network_exposure |
Identifies services exposed to external networks and evaluates attack surface |
privilege_escalation |
Detects SUID/SGID binaries, writable PATH directories, sudo misconfigurations, Docker socket access |
service_exploit |
Checks running services against known vulnerability signatures |
| Module | Score Range | Description |
|---|---|---|
process_anomaly |
0-100 | Name mimicry (e.g., "svchoost" vs "svchost"), deleted binaries, RWX memory regions, orphan processes |
network_anomaly |
0-100 | Unusual network listeners, suspicious outbound connections, DNS over non-standard ports |
file_integrity |
0-100 | SUID/SGID changes, recently modified system binaries, suspicious temp files |
binary_analysis |
0-100 | Stripped binaries in unusual locations, packed executables, static linking anomalies |
behavioral_baseline |
0-100 | Deviation from saved baseline — new processes, ports, files, users |
heuristic_engine |
N/A | Cross-module correlation — groups anomalies by PID, boosts score +20 when 2+ detectors agree |
Each hardener maps 1:1 to a scanner and remediates its findings. Modules: audit_logging, crypto, filesystem, firewall, kernel, network, passwords, registry, services, software, ssh, users.
All hardeners follow the backup-first pattern:
- Backup the original file or registry value
- Apply the fix (platform-specific)
- Record the action (success/failure) with backup location
- Save the manifest for potential rollback
VulnTester generates a standalone HTML report (vulntester_report.html by default) containing:
- Executive Summary — Total findings, severity distribution, overall risk score (0-100)
- Vulnerability Findings — Filterable, sortable table with severity, description, remediation, and CIS references
- Penetration Test Results — Attack paths, evidence, and mitigation guidance by category
- Zero-Day Anomalies — Anomaly scores, indicators, correlation notes, and investigation steps
- Hardening Actions — Log of applied fixes with success/failure status and backup locations
- LLM Analysis — AI-generated executive summary and prioritized recommendations (when enabled)
The report is a single .html file with embedded CSS and JavaScript. No external dependencies, CDN links, or server required. Opens in any web browser. Supports dark/light mode toggle.
# Custom report path
vulntester --scan-only --report /path/to/audit-report.htmlDetailed architecture documentation is available in the design/ directory:
- C4 Model Diagrams (Mermaid.js) — Context, Container, Component, and Code level views
- Architecture Decision Records — 10 ADRs documenting key design choices and trade-offs
See design/README.md for the full index.
- Read-only by default — Scanners and detectors never modify system state. Hardening requires explicit opt-in (
--interactiveor--auto-harden). - Backup everything — Every hardening action is backed up before execution with full rollback support.
- Minimal dependencies — Only 2 runtime packages (
psutil,jinja2) to minimize supply chain attack surface. - No shell injection — System introspection uses
psutilAPIs, not shell command parsing. Subprocess calls use list-form arguments, never shell interpolation. - Timeout protection — All subprocess calls have a configurable timeout (default 30s) to prevent hangs.
- Privilege awareness — Detects admin/root status and warns when running unprivileged. Never escalates privileges.
- LLM data handling — When
--llm-assistis used, scan findings are sent to the specified provider's API. No data is sent without explicit opt-in. API keys are never logged or included in reports.
- Python >= 3.10
- OS: Linux, Windows 10+, or macOS 12+
- Privileges: Administrator/root recommended for full coverage (runs with reduced capability otherwise)
- Network: Not required for scanning/hardening. Required only for
--llm-assistand--patches(update checks).
This project is provided as-is for security assessment and system hardening purposes. Use responsibly and only on systems you are authorized to scan.