Metadata-Version: 2.4
Name: vkrscan
Version: 1.0.0
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 Python cybersecurity analysis framework and CLI tool for identifying hidden data, exposed secrets, common web-security weaknesses, and cryptographic/encoding artifacts with evidence-based reporting.

---

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

---

## Key Features

* **Steganography & Hidden Data Analysis**:
  * 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).

* **Secrets & Credential Discovery**:
  * High-fidelity pattern engine for AWS, GitHub, GitLab, Google Cloud, Slack, Stripe, Private Keys, Database connection URLs, AI keys (OpenAI, Anthropic), and JWTs.
  * Shannon entropy thresholding to reduce false positives on random strings.
  * Safe-by-default redaction engine preserving prefix/suffix (`AKIA************7XYZ`).
  * Custom rules support via YAML.

* **Authorized Web Security Assessment**:
  * Safe checks strictly bounded by mandatory authorization warning banners.
  * Security headers audit (`CSP`, `HSTS`, `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, `Permissions-Policy`).
  * Cookie security audit (`HttpOnly`, `Secure`, `SameSite`).
  * TLS/SSL certificate validation, expiration alert, and protocol deprecation checks.
  * Information disclosure identification and conservative sensitive file exposure probes (`.env`, `.git/config`, `docker-compose.yml`, `web.config`, etc.).
  * Harmless reflected input probe for contextual Cross-Site Scripting (XSS) assessment.
  * Non-destructive SQL injection indicator and database syntax error detection.

* **Cryptographic & Encoding Utilities**:
  * Multi-format encoding and decoding (`Base64`, `Base64URL`, `Hex`, `URL`, `Unicode`, `Binary`).
  * Heuristic auto-detection of unknown encoded strings.
  * Cryptographic one-way hashing (`MD5`, `SHA-1`, `SHA-256`, `SHA-512`, `SHA-3`).
  * File hashing with multi-digest streaming.
  * Safe JSON Web Token (JWT) inspection, claims auditing, and `alg: none` detection.

* **Unified Evidence Collection & Reporting**:
  * Standardized `Finding` and `Evidence` data models across all scanners.
  * Transparent 0–100 risk scoring with contributor breakdown.
  * Rich terminal user interface with styled tables, progress gauges, and badges.
  * Machine-readable structured JSON export.
  * Standalone, responsive HTML report dashboard.

---

## Ethical & Safe Design

VKRScan is designed for:
* Defensive security analysis
* CTF / lab training environments
* Local system testing
* Systems owned by the user or where explicit testing authorization has been granted

VKRScan does **NOT** implement credential theft, malware deployment, persistence, destructive exploitation, authentication bypass, or arbitrary third-party automated attacks.

---

## Installation

```bash
pip install vkrscan
```

### From Source
```bash
git clone https://github.com/vkrscan/vkrscan.git
cd vkrscan
pip install -e .
```

---

## Quick Start CLI Examples

### 1. Interactive Cyberpunk Shell
Run VKRScan without arguments or with `shell` to launch the interactive prompt:
```bash
vkrscan
# or
vkrscan shell
```
Inside the interactive shell:
```text
vkrscan> help
vkrscan> show
vkrscan> set target https://authorized.example
vkrscan> set modules web
vkrscan> run
vkrscan> steg image.png
vkrscan> secrets ./src
vkrscan> jwt <token>
vkrscan> exit
```

### 2. Unified Scanner (CLI Mode)
```bash
# Auto-detect target and run appropriate modules
vkrscan scan https://authorized.example
vkrscan scan ./my-project-repo
vkrscan scan image.png

# Target specific modules
vkrscan scan ./my-project-repo --modules secrets --format html --output report.html
```

### 2. Steganography Analysis
```bash
vkrscan steg sample.png
vkrscan steg audio.wav
```

### 3. Secrets Scanner
```bash
vkrscan secrets ./src
vkrscan secrets ./src --rules examples/custom-rules.yaml
```

### 4. Web Security Assessment
```bash
vkrscan web https://authorized.example
```

### 5. Encoding & Auto-Detection
```bash
vkrscan encode base64 "Confidential"
vkrscan decode base64 "Q29uZmlkZW50aWFs"
vkrscan analyze "aGVsbG8gd29ybGQ="
```

### 6. Cryptographic Hashing
```bash
vkrscan hash "admin"
vkrscan hash-file firmware.bin
```

### 7. JWT Inspection
```bash
vkrscan jwt eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
```

---

## Architecture

```text
Target (URL, Directory, Media, JWT, File)
   ↓
Target Classifier (vkrscan.utils.validators)
   ↓
Scan Engine Coordinator (vkrscan.core.engine)
   ↓
Plugins (BaseScanner)
 ├── Steganography Analyzer
 ├── Secrets Scanner
 ├── Web Security Analyzer
 └── Cryptography Utilities
   ↓
Normalized Finding & Evidence Models
   ↓
Transparent Risk Scoring (0 - 100)
   ↓
Reporters (Terminal UI, JSON, HTML)
```

---

## Running Tests

Run the test suite with pytest:
```bash
pytest -v
```

With coverage:
```bash
pytest --cov=vkrscan --cov-report=term-missing
```

---

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
