Metadata-Version: 2.4
Name: vkrscan
Version: 1.1.1
Summary: Modular Python cybersecurity analysis framework and CLI tool
Author: VKRScan Security Team
License: MIT
Keywords: cybersecurity,security-scanner,steganography,secrets-detection,web-security,jwt,cli
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: lxml>=5.2.0
Requires-Dist: pillow>=10.3.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: pyjwt>=2.8.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: dnspython>=2.6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Dynamic: license-file

# VKRScan

[![Python Version](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

> **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.

---

```text
╔══════════════════════════════════════════════════════════════╗
║                           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

```bash
pip install vkrscan
```

### From Source
```bash
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:
```bash
# 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`)
```bash
# 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`)
```bash
# 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`)
```bash
# 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`)
```bash
# 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`)
```bash
# 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`)
```bash
vkrscan steg forensic_sample.png
vkrscan steg sound_record.wav
```

### 8. Cryptographic & Encoding Utilities
```bash
# 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`)
```bash
vkrscan shell
# or simply
vkrscan
```
Inside the interactive shell:
```text
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:

```yaml
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

```text
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

```bash
# 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](LICENSE) for details.
