VKRScan

VKRScan is a modular, production-ready cybersecurity analysis framework and CLI tool for offensive reconnaissance awareness, web application security auditing, Git repository inspection, exposed secret detection, steganography analysis, and cryptographic evaluation with unified, evidence-based reporting.

---

╔══════════════════════════════════════════════════════════════╗
║                           VKRScan                            ║
║              Cybersecurity Analysis Framework                ║
╚══════════════════════════════════════════════════════════════╝

---

Key Features

🌐 Advanced Web Security Analysis

• Scope-Controlled Polite Crawler:
  • Configurable breadth-first crawling bounded strictly by same-origin rules (--depth, --max-pages, --rate-limit).
  • Automatic discovery of hyperlinks, state-changing <form> elements, <script> bundles, and REST/JSON endpoints.
• Intelligent Parameter Extraction & Classification:
  • Parses parameters from query strings, form inputs, and JSON request bodies.
  • Semantically classifies parameters into categories: REDIRECT, URL_FETCH (SSRF candidates), AUTH, FILE, SQL_CANDIDATE, NUMERIC, GENERIC.
• Context-Aware Cross-Site Scripting (XSS) Reflection:
  • Injects benign, unique canary tokens (vkrxss_<token>) across discovered parameters.
  • Identifies reflection context: HTML body text, tag attributes, JavaScript blocks, and URL attributes with character break-out audits.
• Differential SQL Injection (SQLi) Analysis:
  • Tests GET parameters, POST forms, and JSON payloads with benign syntax-breaking boundary markers.
  • Detects database syntax error patterns across MySQL, PostgreSQL, Oracle, SQLite, and Microsoft SQL Server.
  • Performs response length and status differential analysis without attempting database dumps.
• Cross-Site Request Forgery (CSRF) Audit:
  • Audits all discovered state-changing forms (POST, PUT, DELETE) for missing or predictable anti-CSRF tokens.
  • Validates session cookie SameSite flags (Strict, Lax, None) and flags high-risk combinations.
• Safe Server-Side Request Forgery (SSRF) Candidate Auditing:
  • Identifies high-risk parameters (url, dest, callback, webhook, target, etc.).
  • Verifies SSRF vulnerabilities exclusively using controlled, external callback token tracking (SSRFCallbackManager) without scanning private or loopback networks.
• Safe Open Redirect Detection:
  • Tests redirect-susceptible parameters using benign domain payloads (https://example.com/vkrscan_redirect_test).
  • Detects both HTTP Location headers and HTML <meta http-equiv="refresh"> tags.
• CORS Misconfiguration Auditor:
  • Tests CORS headers with simulated arbitrary origins, null origins, and wildcard origins.
  • Flags critical misconfigurations where Access-Control-Allow-Origin dynamically reflects untrusted origins while enabling Access-Control-Allow-Credentials: true.
• Security Headers & Cookie Security:
  • Evaluates presence and strength of Content-Security-Policy, Strict-Transport-Security, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, and Permissions-Policy.
  • Verifies HttpOnly, Secure, and SameSite attributes on all session and application cookies.
• Information & Sensitive File Disclosure:
  • Checks for exposed development artifacts, environment files, stack traces, and internal server paths (.env, .git/config, docker-compose.yml, web.config, etc.).
• Safe Technology Fingerprinting:
  • Fingerprints web servers, application frameworks, CMS platforms, CDNs, and JavaScript libraries with confidence scoring (LOW, MEDIUM, HIGH).

---

🔍 Reconnaissance & Port Scanning

• Subdomain Discovery (vkrscan subdomains DOMAIN):
  • Passive certificate transparency log queries via crt.sh.
  • Active DNS resolution verification (IPv4 A and IPv6 AAAA records) with fallback dictionary bruteforcing.
  • Live HTTP and HTTPS status and responsiveness probing.
• Targeted TCP Port Scanner (vkrscan ports TARGET):
  • Focused strictly on 19 predefined well-known infrastructure and service ports:
    • 21 (FTP), 22 (SSH), 23 (Telnet), 25 (SMTP), 53 (DNS), 80 (HTTP), 110 (POP3), 111 (RPCbind), 135 (MSRPC), 139 (NetBIOS), 143 (IMAP), 443 (HTTPS), 445 (SMB), 993 (IMAPS), 995 (POP3S), 1433 (MSSQL), 3306 (MySQL), 3389 (RDP), 5432 (PostgreSQL), 8080 (HTTP-Proxy), 8443 (HTTPS-Alt).
  • Concurrency controlled via thread pooling with rate limiting.
  • Automatic warning alerts for cleartext and insecure protocols (Telnet, FTP, HTTP, SMB).

---

📁 Git Repository Security Scanner (vkrscan git PATH)

• Tracked Sensitive File Auditing:
  • Identifies high-risk tracked files in the working directory (.env, .pem, .key, id_rsa, credentials.json, wp-config.php, etc.).
• Historical Commit History Diff Scanning:
  • Traverses Git commit history (git log -p) to discover secrets committed and subsequently removed in later commits.
  • Zero raw credential exposure: all discovered keys and tokens are strictly masked with irreversible redaction (AKIA************7XYZ).
  • Suppresses test fixtures, placeholder tokens, and allowlisted comments (# vkrscan:allow-secret).

---

🔑 Secret & Credential Detection (vkrscan secrets PATH)

• Built-in signature rules for AWS, GitHub, GitLab, Google Cloud, Slack, Stripe, Private Keys, Database URIs, AI API keys (OpenAI, Anthropic), and JWTs.
• Shannon entropy analysis to filter low-entropy random strings.
• Extensible custom YAML detection rules.

---

🖼️ Steganography & Media Forensics (vkrscan steg FILE)

• MIME & magic byte verification, format integrity, and extension mismatch detection.
• Detection of trailing data appended beyond format EOF markers (PNG, JPEG, BMP, WAV).
• Metadata extraction (EXIF, GPS identification, PNG chunks, WAV audio parameters).
• Global and sliding-window Shannon entropy analysis for encrypted/compressed cluster detection.
• Channel-specific Least Significant Bit (LSB) statistical distribution and anomaly scoring.
• Printable ASCII/UTF-8 string carving with token recognition (URLs, emails, Base64, CTF flags).

---

🔐 Cryptographic & Encoding Utilities

• Multi-format encoding and decoding (Base64, Base64URL, Hex, URL, Unicode, Binary).
• Heuristic auto-detection of unknown encoded strings (vkrscan analyze).
• Cryptographic one-way hashing (MD5, SHA-1, SHA-256, SHA-512, SHA-3) and streaming file hashing.
• Safe JSON Web Token (JWT) inspection, claims auditing, and alg: none detection.

---

📊 Attack Surface Telemetry & Unified Reporting

• Standardized Finding and Evidence data models across all scanners.
• Consolidated AttackSurface telemetry (discovered endpoints, forms, parameters, open ports, subdomains, and identified technologies).
• Transparent 0–100 risk scoring with contributor breakdown and overall security score (100 - risk).
• Rich Terminal User Interface: Styled tables, severity gauges, and attack surface summaries.
• Standalone Responsive HTML Dashboard:
  • Dark-mode executive dashboard with zero external CDN/framework dependencies (fully offline-functional).
  • Interactive severity filters, attack surface matrix, and collapsible evidence inspectors.
• Machine-Readable JSON: Clean JSON export for CI/CD integration and automated pipeline validation.

---

Ethical & Safe Design

VKRScan is designed exclusively for:

• Defensive security auditing and posture assessment
• Educational CTF / laboratory environments
• Systems owned by the user or where explicit written testing authorization has been granted

VKRScan does NOT implement credential theft, database dumping, malware deployment, persistence, destructive exploitation, or unauthorized scanning of loopback/private ranges.

---

Installation

pip install vkrscan

From Source

git clone https://github.com/vkrscan/vkrscan.git
cd vkrscan
pip install -e .

---

CLI Usage & Commands

1. Unified Scanner (vkrscan scan)

Automatically classifies targets (URL, Domain, Git repository, local directory, image, or JWT) and runs all applicable scanners:

# Web application scan with HTML and JSON reports
vkrscan scan https://example.com --html report.html --json report.json

# Domain reconnaissance (subdomains + ports)
vkrscan scan example.com --html recon.html

# Local Git repository security audit
vkrscan scan ./my-project --html git_audit.html

# Deep web scan with crawler limits
vkrscan scan https://example.com --depth 3 --max-pages 50 --timeout 15.0

2. Web Security Analyzer (vkrscan web)

# Audit web application with crawler and parameter analysis
vkrscan web https://example.com --depth 2 --max-pages 30

# Export findings to standalone HTML dashboard
vkrscan web https://example.com --html web_report.html

3. Port Scanner (vkrscan ports)

# Scan predefined 19 well-known ports on a target
vkrscan ports example.com

# Scan specific ports with custom timeout
vkrscan ports 192.0.2.1 --ports "80,443,8080,8443" --timeout 1.5

4. Subdomain Discovery (vkrscan subdomains)

# Passive crt.sh + DNS resolution verification
vkrscan subdomains example.com

# Passive discovery only (no active DNS queries)
vkrscan subdomains example.com --passive-only

5. Git Repository Scanner (vkrscan git)

# Scan working tree and commit history
vkrscan git ./my-repo

# Limit history depth
vkrscan git ./my-repo --max-commits 100 --html git_findings.html

6. Secrets Detection (vkrscan secrets)

# Scan local codebase for exposed secrets
vkrscan secrets ./src

# Use custom YAML detection rules
vkrscan secrets ./src --rules ./custom-rules.yaml

7. Steganography Analysis (vkrscan steg)

vkrscan steg forensic_sample.png
vkrscan steg sound_record.wav

8. Cryptographic & Encoding Utilities

# Encode and decode data
vkrscan encode base64 "Confidential Data"
vkrscan decode hex "436f6e666964656e7469616c"

# Heuristic string auto-detection
vkrscan analyze "aGVsbG8gd29ybGQ="

# Cryptographic hashing
vkrscan hash "password123" --algo sha256
vkrscan hash-file setup.exe --algo sha256

# JWT claims and algorithm inspection
vkrscan jwt eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

9. Interactive Cyberpunk Shell (vkrscan shell)

vkrscan shell
# or simply
vkrscan

Inside the interactive shell:

vkrscan> set target https://authorized.example
vkrscan> set depth 2
vkrscan> set html web_audit.html
vkrscan> show
vkrscan> run
vkrscan> exit

---

Configuration (vkrscan.yaml)

VKRScan can be customized using a local vkrscan.yaml or ~/.vkrscan/config.yaml file:

general:
  output_dir: "./reports"
  default_format: "terminal"
  timeout: 10.0
  rate_limit: 5.0
  max_threads: 5
  user_agent: "VKRScan-Security-Auditor/2.0"

web:
  crawl_depth: 2
  max_pages: 50
  test_sqli: true
  test_xss: true
  test_cors: true
  test_csrf: true
  test_ssrf: true
  test_redirects: true
  test_exposure: true
  fingerprint: true

recon:
  subdomain_threads: 10
  dns_timeout: 2.0
  port_timeout: 1.5
  port_threads: 5

git:
  scan_history: true
  max_commits: 250
  scan_diffs: true

secrets:
  min_entropy: 3.5
  redact: true

steg:
  entropy_window_size: 1024
  min_string_length: 6

---

Architecture & Project Layout

vkrscan/
├── cli.py                  # Typer CLI entrypoint & commands
├── config.py               # YAML & environment configuration models
├── shell.py                # Interactive cmd2 Cyberpunk shell
├── core/
│   ├── engine.py           # Unified multi-target scan coordinator
│   ├── evidence.py         # Standardized evidence model & builders
│   ├── models.py           # Core Finding, TargetInfo, AttackSurface models
│   ├── plugin.py           # BaseScanner interface & PluginRegistry
│   └── severity.py         # RiskScore, Severity & Confidence formulas
├── recon/
│   ├── ports.py            # Predefined 19 TCP port scanner & service ID
│   └── subdomains.py       # crt.sh passive + DNS verification + HTTP probe
├── git/
│   └── scanner.py          # Git working tree & commit history patch auditor
├── web/
│   ├── analyzer.py         # Web Security orchestrator & plugin
│   ├── cors.py             # CORS reflection & credential auditor
│   ├── crawler.py          # Scope-controlled recursive crawler
│   ├── csrf.py             # CSRF token & SameSite cookie auditor
│   ├── exposure.py         # Sensitive files & debug/trace disclosure
│   ├── fingerprint.py      # Technology & framework fingerprinting
│   ├── headers.py          # HTTP security header auditing
│   ├── parameters.py       # Parameter extraction & semantic classification
│   ├── redirect.py         # Safe open redirect detection
│   ├── sqli.py             # Differential & error SQLi testing (GET/POST/JSON)
│   ├── ssrf.py             # Controlled callback SSRF auditor
│   └── xss.py              # Context-aware reflected XSS tester
├── secrets/
│   ├── rules.py            # Built-in patterns & custom YAML rules
│   └── scanner.py          # Codebase secret scanner with redaction
├── steg/
│   ├── analyzer.py         # Media format, EOF, entropy, LSB analyzer
│   └── carving.py          # Printable string carving
├── crypto/
│   ├── encoding.py         # Multi-format encoder, decoder & auto-detect
│   ├── hashing.py          # Cryptographic digest engine
│   └── jwt_analyzer.py     # JWT token claims & algorithm inspector
├── reports/
│   ├── html.py             # Self-contained responsive HTML report generator
│   ├── json_report.py      # Machine-readable JSON report generator
│   └── terminal.py         # Rich terminal UI report with attack surface
└── utils/
    ├── console.py          # Cyberpunk styled banner & console helpers
    ├── network.py          # Safe HTTP client factory & rate limiting
    └── validators.py       # Target classification & validation utilities

---

Running the Test Suite

# Run all tests
python -m pytest

# Run with test coverage
python -m pytest --cov=vkrscan --cov-report=term-missing

---

License

This project is licensed under the MIT License. See LICENSE for details.