vkrscan 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- vkrscan-1.0.0/LICENSE +21 -0
- vkrscan-1.0.0/PKG-INFO +237 -0
- vkrscan-1.0.0/README.md +198 -0
- vkrscan-1.0.0/pyproject.toml +72 -0
- vkrscan-1.0.0/setup.cfg +4 -0
- vkrscan-1.0.0/tests/test_cli.py +58 -0
- vkrscan-1.0.0/tests/test_shell.py +38 -0
- vkrscan-1.0.0/vkrscan/__init__.py +13 -0
- vkrscan-1.0.0/vkrscan/cli.py +323 -0
- vkrscan-1.0.0/vkrscan/config.py +111 -0
- vkrscan-1.0.0/vkrscan/core/__init__.py +18 -0
- vkrscan-1.0.0/vkrscan/core/engine.py +113 -0
- vkrscan-1.0.0/vkrscan/core/evidence.py +31 -0
- vkrscan-1.0.0/vkrscan/core/logger.py +60 -0
- vkrscan-1.0.0/vkrscan/core/models.py +83 -0
- vkrscan-1.0.0/vkrscan/core/plugin.py +67 -0
- vkrscan-1.0.0/vkrscan/core/severity.py +134 -0
- vkrscan-1.0.0/vkrscan/crypto/__init__.py +15 -0
- vkrscan-1.0.0/vkrscan/crypto/encoding.py +206 -0
- vkrscan-1.0.0/vkrscan/crypto/hashing.py +81 -0
- vkrscan-1.0.0/vkrscan/crypto/jwt.py +187 -0
- vkrscan-1.0.0/vkrscan/exceptions.py +25 -0
- vkrscan-1.0.0/vkrscan/reports/__init__.py +11 -0
- vkrscan-1.0.0/vkrscan/reports/html.py +247 -0
- vkrscan-1.0.0/vkrscan/reports/json.py +21 -0
- vkrscan-1.0.0/vkrscan/reports/terminal.py +94 -0
- vkrscan-1.0.0/vkrscan/secrets/__init__.py +5 -0
- vkrscan-1.0.0/vkrscan/secrets/entropy.py +33 -0
- vkrscan-1.0.0/vkrscan/secrets/patterns.py +218 -0
- vkrscan-1.0.0/vkrscan/secrets/redaction.py +29 -0
- vkrscan-1.0.0/vkrscan/secrets/scanner.py +168 -0
- vkrscan-1.0.0/vkrscan/shell.py +322 -0
- vkrscan-1.0.0/vkrscan/steg/__init__.py +5 -0
- vkrscan-1.0.0/vkrscan/steg/analyzer.py +323 -0
- vkrscan-1.0.0/vkrscan/steg/entropy.py +94 -0
- vkrscan-1.0.0/vkrscan/steg/lsb.py +200 -0
- vkrscan-1.0.0/vkrscan/steg/metadata.py +133 -0
- vkrscan-1.0.0/vkrscan/steg/signatures.py +157 -0
- vkrscan-1.0.0/vkrscan/steg/strings.py +147 -0
- vkrscan-1.0.0/vkrscan/utils/__init__.py +13 -0
- vkrscan-1.0.0/vkrscan/utils/files.py +104 -0
- vkrscan-1.0.0/vkrscan/utils/network.py +28 -0
- vkrscan-1.0.0/vkrscan/utils/validators.py +106 -0
- vkrscan-1.0.0/vkrscan/web/__init__.py +5 -0
- vkrscan-1.0.0/vkrscan/web/analyzer.py +93 -0
- vkrscan-1.0.0/vkrscan/web/crawler.py +54 -0
- vkrscan-1.0.0/vkrscan/web/exposure.py +111 -0
- vkrscan-1.0.0/vkrscan/web/headers.py +204 -0
- vkrscan-1.0.0/vkrscan/web/sqli.py +175 -0
- vkrscan-1.0.0/vkrscan/web/tls.py +136 -0
- vkrscan-1.0.0/vkrscan/web/xss.py +122 -0
- vkrscan-1.0.0/vkrscan.egg-info/PKG-INFO +237 -0
- vkrscan-1.0.0/vkrscan.egg-info/SOURCES.txt +55 -0
- vkrscan-1.0.0/vkrscan.egg-info/dependency_links.txt +1 -0
- vkrscan-1.0.0/vkrscan.egg-info/entry_points.txt +2 -0
- vkrscan-1.0.0/vkrscan.egg-info/requires.txt +18 -0
- vkrscan-1.0.0/vkrscan.egg-info/top_level.txt +1 -0
vkrscan-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 chvkrsubhash (VKRScan Authors & Contributors)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
vkrscan-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: vkrscan
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Modular Python cybersecurity analysis framework and CLI tool
|
|
5
|
+
Author: VKRScan Security Team
|
|
6
|
+
License: MIT
|
|
7
|
+
Keywords: cybersecurity,security-scanner,steganography,secrets-detection,web-security,jwt,cli
|
|
8
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
9
|
+
Classifier: Environment :: Console
|
|
10
|
+
Classifier: Intended Audience :: Information Technology
|
|
11
|
+
Classifier: Intended Audience :: System Administrators
|
|
12
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Topic :: Security
|
|
18
|
+
Requires-Python: >=3.11
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
License-File: LICENSE
|
|
21
|
+
Requires-Dist: typer>=0.12.0
|
|
22
|
+
Requires-Dist: rich>=13.7.0
|
|
23
|
+
Requires-Dist: pydantic>=2.7.0
|
|
24
|
+
Requires-Dist: httpx>=0.27.0
|
|
25
|
+
Requires-Dist: beautifulsoup4>=4.12.0
|
|
26
|
+
Requires-Dist: lxml>=5.2.0
|
|
27
|
+
Requires-Dist: pillow>=10.3.0
|
|
28
|
+
Requires-Dist: numpy>=1.26.0
|
|
29
|
+
Requires-Dist: cryptography>=42.0.0
|
|
30
|
+
Requires-Dist: pyjwt>=2.8.0
|
|
31
|
+
Requires-Dist: pyyaml>=6.0.1
|
|
32
|
+
Requires-Dist: dnspython>=2.6.0
|
|
33
|
+
Provides-Extra: dev
|
|
34
|
+
Requires-Dist: pytest>=8.0.0; extra == "dev"
|
|
35
|
+
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
|
|
36
|
+
Requires-Dist: ruff>=0.4.0; extra == "dev"
|
|
37
|
+
Requires-Dist: mypy>=1.10.0; extra == "dev"
|
|
38
|
+
Dynamic: license-file
|
|
39
|
+
|
|
40
|
+
# VKRScan
|
|
41
|
+
|
|
42
|
+
[](https://python.org)
|
|
43
|
+
[](https://opensource.org/licenses/MIT)
|
|
44
|
+
[](https://github.com/astral-sh/ruff)
|
|
45
|
+
|
|
46
|
+
> **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.
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
```text
|
|
51
|
+
╔══════════════════════════════════════════════════════════════╗
|
|
52
|
+
║ VKRScan ║
|
|
53
|
+
║ Cybersecurity Analysis Framework ║
|
|
54
|
+
╚══════════════════════════════════════════════════════════════╝
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Key Features
|
|
60
|
+
|
|
61
|
+
* **Steganography & Hidden Data Analysis**:
|
|
62
|
+
* MIME & magic byte verification, format integrity, and extension mismatch detection.
|
|
63
|
+
* Detection of trailing data appended beyond format EOF markers (PNG, JPEG, BMP, WAV).
|
|
64
|
+
* Metadata extraction (EXIF, GPS identification, PNG chunks, WAV audio parameters).
|
|
65
|
+
* Global and sliding-window Shannon entropy analysis for encrypted/compressed cluster detection.
|
|
66
|
+
* Channel-specific Least Significant Bit (LSB) statistical distribution and anomaly scoring.
|
|
67
|
+
* Printable ASCII/UTF-8 string carving with token recognition (URLs, emails, Base64, CTF flags).
|
|
68
|
+
|
|
69
|
+
* **Secrets & Credential Discovery**:
|
|
70
|
+
* High-fidelity pattern engine for AWS, GitHub, GitLab, Google Cloud, Slack, Stripe, Private Keys, Database connection URLs, AI keys (OpenAI, Anthropic), and JWTs.
|
|
71
|
+
* Shannon entropy thresholding to reduce false positives on random strings.
|
|
72
|
+
* Safe-by-default redaction engine preserving prefix/suffix (`AKIA************7XYZ`).
|
|
73
|
+
* Custom rules support via YAML.
|
|
74
|
+
|
|
75
|
+
* **Authorized Web Security Assessment**:
|
|
76
|
+
* Safe checks strictly bounded by mandatory authorization warning banners.
|
|
77
|
+
* Security headers audit (`CSP`, `HSTS`, `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, `Permissions-Policy`).
|
|
78
|
+
* Cookie security audit (`HttpOnly`, `Secure`, `SameSite`).
|
|
79
|
+
* TLS/SSL certificate validation, expiration alert, and protocol deprecation checks.
|
|
80
|
+
* Information disclosure identification and conservative sensitive file exposure probes (`.env`, `.git/config`, `docker-compose.yml`, `web.config`, etc.).
|
|
81
|
+
* Harmless reflected input probe for contextual Cross-Site Scripting (XSS) assessment.
|
|
82
|
+
* Non-destructive SQL injection indicator and database syntax error detection.
|
|
83
|
+
|
|
84
|
+
* **Cryptographic & Encoding Utilities**:
|
|
85
|
+
* Multi-format encoding and decoding (`Base64`, `Base64URL`, `Hex`, `URL`, `Unicode`, `Binary`).
|
|
86
|
+
* Heuristic auto-detection of unknown encoded strings.
|
|
87
|
+
* Cryptographic one-way hashing (`MD5`, `SHA-1`, `SHA-256`, `SHA-512`, `SHA-3`).
|
|
88
|
+
* File hashing with multi-digest streaming.
|
|
89
|
+
* Safe JSON Web Token (JWT) inspection, claims auditing, and `alg: none` detection.
|
|
90
|
+
|
|
91
|
+
* **Unified Evidence Collection & Reporting**:
|
|
92
|
+
* Standardized `Finding` and `Evidence` data models across all scanners.
|
|
93
|
+
* Transparent 0–100 risk scoring with contributor breakdown.
|
|
94
|
+
* Rich terminal user interface with styled tables, progress gauges, and badges.
|
|
95
|
+
* Machine-readable structured JSON export.
|
|
96
|
+
* Standalone, responsive HTML report dashboard.
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## Ethical & Safe Design
|
|
101
|
+
|
|
102
|
+
VKRScan is designed for:
|
|
103
|
+
* Defensive security analysis
|
|
104
|
+
* CTF / lab training environments
|
|
105
|
+
* Local system testing
|
|
106
|
+
* Systems owned by the user or where explicit testing authorization has been granted
|
|
107
|
+
|
|
108
|
+
VKRScan does **NOT** implement credential theft, malware deployment, persistence, destructive exploitation, authentication bypass, or arbitrary third-party automated attacks.
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## Installation
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
pip install vkrscan
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### From Source
|
|
119
|
+
```bash
|
|
120
|
+
git clone https://github.com/vkrscan/vkrscan.git
|
|
121
|
+
cd vkrscan
|
|
122
|
+
pip install -e .
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
## Quick Start CLI Examples
|
|
128
|
+
|
|
129
|
+
### 1. Interactive Cyberpunk Shell
|
|
130
|
+
Run VKRScan without arguments or with `shell` to launch the interactive prompt:
|
|
131
|
+
```bash
|
|
132
|
+
vkrscan
|
|
133
|
+
# or
|
|
134
|
+
vkrscan shell
|
|
135
|
+
```
|
|
136
|
+
Inside the interactive shell:
|
|
137
|
+
```text
|
|
138
|
+
vkrscan> help
|
|
139
|
+
vkrscan> show
|
|
140
|
+
vkrscan> set target https://authorized.example
|
|
141
|
+
vkrscan> set modules web
|
|
142
|
+
vkrscan> run
|
|
143
|
+
vkrscan> steg image.png
|
|
144
|
+
vkrscan> secrets ./src
|
|
145
|
+
vkrscan> jwt <token>
|
|
146
|
+
vkrscan> exit
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### 2. Unified Scanner (CLI Mode)
|
|
150
|
+
```bash
|
|
151
|
+
# Auto-detect target and run appropriate modules
|
|
152
|
+
vkrscan scan https://authorized.example
|
|
153
|
+
vkrscan scan ./my-project-repo
|
|
154
|
+
vkrscan scan image.png
|
|
155
|
+
|
|
156
|
+
# Target specific modules
|
|
157
|
+
vkrscan scan ./my-project-repo --modules secrets --format html --output report.html
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
### 2. Steganography Analysis
|
|
161
|
+
```bash
|
|
162
|
+
vkrscan steg sample.png
|
|
163
|
+
vkrscan steg audio.wav
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
### 3. Secrets Scanner
|
|
167
|
+
```bash
|
|
168
|
+
vkrscan secrets ./src
|
|
169
|
+
vkrscan secrets ./src --rules examples/custom-rules.yaml
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
### 4. Web Security Assessment
|
|
173
|
+
```bash
|
|
174
|
+
vkrscan web https://authorized.example
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
### 5. Encoding & Auto-Detection
|
|
178
|
+
```bash
|
|
179
|
+
vkrscan encode base64 "Confidential"
|
|
180
|
+
vkrscan decode base64 "Q29uZmlkZW50aWFs"
|
|
181
|
+
vkrscan analyze "aGVsbG8gd29ybGQ="
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
### 6. Cryptographic Hashing
|
|
185
|
+
```bash
|
|
186
|
+
vkrscan hash "admin"
|
|
187
|
+
vkrscan hash-file firmware.bin
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### 7. JWT Inspection
|
|
191
|
+
```bash
|
|
192
|
+
vkrscan jwt eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## Architecture
|
|
198
|
+
|
|
199
|
+
```text
|
|
200
|
+
Target (URL, Directory, Media, JWT, File)
|
|
201
|
+
↓
|
|
202
|
+
Target Classifier (vkrscan.utils.validators)
|
|
203
|
+
↓
|
|
204
|
+
Scan Engine Coordinator (vkrscan.core.engine)
|
|
205
|
+
↓
|
|
206
|
+
Plugins (BaseScanner)
|
|
207
|
+
├── Steganography Analyzer
|
|
208
|
+
├── Secrets Scanner
|
|
209
|
+
├── Web Security Analyzer
|
|
210
|
+
└── Cryptography Utilities
|
|
211
|
+
↓
|
|
212
|
+
Normalized Finding & Evidence Models
|
|
213
|
+
↓
|
|
214
|
+
Transparent Risk Scoring (0 - 100)
|
|
215
|
+
↓
|
|
216
|
+
Reporters (Terminal UI, JSON, HTML)
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## Running Tests
|
|
222
|
+
|
|
223
|
+
Run the test suite with pytest:
|
|
224
|
+
```bash
|
|
225
|
+
pytest -v
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
With coverage:
|
|
229
|
+
```bash
|
|
230
|
+
pytest --cov=vkrscan --cov-report=term-missing
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
---
|
|
234
|
+
|
|
235
|
+
## License
|
|
236
|
+
|
|
237
|
+
This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
|
vkrscan-1.0.0/README.md
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
# VKRScan
|
|
2
|
+
|
|
3
|
+
[](https://python.org)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
[](https://github.com/astral-sh/ruff)
|
|
6
|
+
|
|
7
|
+
> **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.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
╔══════════════════════════════════════════════════════════════╗
|
|
13
|
+
║ VKRScan ║
|
|
14
|
+
║ Cybersecurity Analysis Framework ║
|
|
15
|
+
╚══════════════════════════════════════════════════════════════╝
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Key Features
|
|
21
|
+
|
|
22
|
+
* **Steganography & Hidden Data Analysis**:
|
|
23
|
+
* MIME & magic byte verification, format integrity, and extension mismatch detection.
|
|
24
|
+
* Detection of trailing data appended beyond format EOF markers (PNG, JPEG, BMP, WAV).
|
|
25
|
+
* Metadata extraction (EXIF, GPS identification, PNG chunks, WAV audio parameters).
|
|
26
|
+
* Global and sliding-window Shannon entropy analysis for encrypted/compressed cluster detection.
|
|
27
|
+
* Channel-specific Least Significant Bit (LSB) statistical distribution and anomaly scoring.
|
|
28
|
+
* Printable ASCII/UTF-8 string carving with token recognition (URLs, emails, Base64, CTF flags).
|
|
29
|
+
|
|
30
|
+
* **Secrets & Credential Discovery**:
|
|
31
|
+
* High-fidelity pattern engine for AWS, GitHub, GitLab, Google Cloud, Slack, Stripe, Private Keys, Database connection URLs, AI keys (OpenAI, Anthropic), and JWTs.
|
|
32
|
+
* Shannon entropy thresholding to reduce false positives on random strings.
|
|
33
|
+
* Safe-by-default redaction engine preserving prefix/suffix (`AKIA************7XYZ`).
|
|
34
|
+
* Custom rules support via YAML.
|
|
35
|
+
|
|
36
|
+
* **Authorized Web Security Assessment**:
|
|
37
|
+
* Safe checks strictly bounded by mandatory authorization warning banners.
|
|
38
|
+
* Security headers audit (`CSP`, `HSTS`, `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, `Permissions-Policy`).
|
|
39
|
+
* Cookie security audit (`HttpOnly`, `Secure`, `SameSite`).
|
|
40
|
+
* TLS/SSL certificate validation, expiration alert, and protocol deprecation checks.
|
|
41
|
+
* Information disclosure identification and conservative sensitive file exposure probes (`.env`, `.git/config`, `docker-compose.yml`, `web.config`, etc.).
|
|
42
|
+
* Harmless reflected input probe for contextual Cross-Site Scripting (XSS) assessment.
|
|
43
|
+
* Non-destructive SQL injection indicator and database syntax error detection.
|
|
44
|
+
|
|
45
|
+
* **Cryptographic & Encoding Utilities**:
|
|
46
|
+
* Multi-format encoding and decoding (`Base64`, `Base64URL`, `Hex`, `URL`, `Unicode`, `Binary`).
|
|
47
|
+
* Heuristic auto-detection of unknown encoded strings.
|
|
48
|
+
* Cryptographic one-way hashing (`MD5`, `SHA-1`, `SHA-256`, `SHA-512`, `SHA-3`).
|
|
49
|
+
* File hashing with multi-digest streaming.
|
|
50
|
+
* Safe JSON Web Token (JWT) inspection, claims auditing, and `alg: none` detection.
|
|
51
|
+
|
|
52
|
+
* **Unified Evidence Collection & Reporting**:
|
|
53
|
+
* Standardized `Finding` and `Evidence` data models across all scanners.
|
|
54
|
+
* Transparent 0–100 risk scoring with contributor breakdown.
|
|
55
|
+
* Rich terminal user interface with styled tables, progress gauges, and badges.
|
|
56
|
+
* Machine-readable structured JSON export.
|
|
57
|
+
* Standalone, responsive HTML report dashboard.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## Ethical & Safe Design
|
|
62
|
+
|
|
63
|
+
VKRScan is designed for:
|
|
64
|
+
* Defensive security analysis
|
|
65
|
+
* CTF / lab training environments
|
|
66
|
+
* Local system testing
|
|
67
|
+
* Systems owned by the user or where explicit testing authorization has been granted
|
|
68
|
+
|
|
69
|
+
VKRScan does **NOT** implement credential theft, malware deployment, persistence, destructive exploitation, authentication bypass, or arbitrary third-party automated attacks.
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## Installation
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
pip install vkrscan
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### From Source
|
|
80
|
+
```bash
|
|
81
|
+
git clone https://github.com/vkrscan/vkrscan.git
|
|
82
|
+
cd vkrscan
|
|
83
|
+
pip install -e .
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## Quick Start CLI Examples
|
|
89
|
+
|
|
90
|
+
### 1. Interactive Cyberpunk Shell
|
|
91
|
+
Run VKRScan without arguments or with `shell` to launch the interactive prompt:
|
|
92
|
+
```bash
|
|
93
|
+
vkrscan
|
|
94
|
+
# or
|
|
95
|
+
vkrscan shell
|
|
96
|
+
```
|
|
97
|
+
Inside the interactive shell:
|
|
98
|
+
```text
|
|
99
|
+
vkrscan> help
|
|
100
|
+
vkrscan> show
|
|
101
|
+
vkrscan> set target https://authorized.example
|
|
102
|
+
vkrscan> set modules web
|
|
103
|
+
vkrscan> run
|
|
104
|
+
vkrscan> steg image.png
|
|
105
|
+
vkrscan> secrets ./src
|
|
106
|
+
vkrscan> jwt <token>
|
|
107
|
+
vkrscan> exit
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### 2. Unified Scanner (CLI Mode)
|
|
111
|
+
```bash
|
|
112
|
+
# Auto-detect target and run appropriate modules
|
|
113
|
+
vkrscan scan https://authorized.example
|
|
114
|
+
vkrscan scan ./my-project-repo
|
|
115
|
+
vkrscan scan image.png
|
|
116
|
+
|
|
117
|
+
# Target specific modules
|
|
118
|
+
vkrscan scan ./my-project-repo --modules secrets --format html --output report.html
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### 2. Steganography Analysis
|
|
122
|
+
```bash
|
|
123
|
+
vkrscan steg sample.png
|
|
124
|
+
vkrscan steg audio.wav
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### 3. Secrets Scanner
|
|
128
|
+
```bash
|
|
129
|
+
vkrscan secrets ./src
|
|
130
|
+
vkrscan secrets ./src --rules examples/custom-rules.yaml
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### 4. Web Security Assessment
|
|
134
|
+
```bash
|
|
135
|
+
vkrscan web https://authorized.example
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### 5. Encoding & Auto-Detection
|
|
139
|
+
```bash
|
|
140
|
+
vkrscan encode base64 "Confidential"
|
|
141
|
+
vkrscan decode base64 "Q29uZmlkZW50aWFs"
|
|
142
|
+
vkrscan analyze "aGVsbG8gd29ybGQ="
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### 6. Cryptographic Hashing
|
|
146
|
+
```bash
|
|
147
|
+
vkrscan hash "admin"
|
|
148
|
+
vkrscan hash-file firmware.bin
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### 7. JWT Inspection
|
|
152
|
+
```bash
|
|
153
|
+
vkrscan jwt eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## Architecture
|
|
159
|
+
|
|
160
|
+
```text
|
|
161
|
+
Target (URL, Directory, Media, JWT, File)
|
|
162
|
+
↓
|
|
163
|
+
Target Classifier (vkrscan.utils.validators)
|
|
164
|
+
↓
|
|
165
|
+
Scan Engine Coordinator (vkrscan.core.engine)
|
|
166
|
+
↓
|
|
167
|
+
Plugins (BaseScanner)
|
|
168
|
+
├── Steganography Analyzer
|
|
169
|
+
├── Secrets Scanner
|
|
170
|
+
├── Web Security Analyzer
|
|
171
|
+
└── Cryptography Utilities
|
|
172
|
+
↓
|
|
173
|
+
Normalized Finding & Evidence Models
|
|
174
|
+
↓
|
|
175
|
+
Transparent Risk Scoring (0 - 100)
|
|
176
|
+
↓
|
|
177
|
+
Reporters (Terminal UI, JSON, HTML)
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## Running Tests
|
|
183
|
+
|
|
184
|
+
Run the test suite with pytest:
|
|
185
|
+
```bash
|
|
186
|
+
pytest -v
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
With coverage:
|
|
190
|
+
```bash
|
|
191
|
+
pytest --cov=vkrscan --cov-report=term-missing
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## License
|
|
197
|
+
|
|
198
|
+
This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0.0", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "vkrscan"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "Modular Python cybersecurity analysis framework and CLI tool"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
authors = [{ name = "VKRScan Security Team" }]
|
|
11
|
+
license = { text = "MIT" }
|
|
12
|
+
requires-python = ">=3.11"
|
|
13
|
+
keywords = ["cybersecurity", "security-scanner", "steganography", "secrets-detection", "web-security", "jwt", "cli"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 5 - Production/Stable",
|
|
16
|
+
"Environment :: Console",
|
|
17
|
+
"Intended Audience :: Information Technology",
|
|
18
|
+
"Intended Audience :: System Administrators",
|
|
19
|
+
"License :: OSI Approved :: MIT License",
|
|
20
|
+
"Operating System :: OS Independent",
|
|
21
|
+
"Programming Language :: Python :: 3",
|
|
22
|
+
"Programming Language :: Python :: 3.11",
|
|
23
|
+
"Programming Language :: Python :: 3.12",
|
|
24
|
+
"Topic :: Security",
|
|
25
|
+
]
|
|
26
|
+
dependencies = [
|
|
27
|
+
"typer>=0.12.0",
|
|
28
|
+
"rich>=13.7.0",
|
|
29
|
+
"pydantic>=2.7.0",
|
|
30
|
+
"httpx>=0.27.0",
|
|
31
|
+
"beautifulsoup4>=4.12.0",
|
|
32
|
+
"lxml>=5.2.0",
|
|
33
|
+
"pillow>=10.3.0",
|
|
34
|
+
"numpy>=1.26.0",
|
|
35
|
+
"cryptography>=42.0.0",
|
|
36
|
+
"pyjwt>=2.8.0",
|
|
37
|
+
"pyyaml>=6.0.1",
|
|
38
|
+
"dnspython>=2.6.0",
|
|
39
|
+
]
|
|
40
|
+
|
|
41
|
+
[project.optional-dependencies]
|
|
42
|
+
dev = [
|
|
43
|
+
"pytest>=8.0.0",
|
|
44
|
+
"pytest-cov>=5.0.0",
|
|
45
|
+
"ruff>=0.4.0",
|
|
46
|
+
"mypy>=1.10.0",
|
|
47
|
+
]
|
|
48
|
+
|
|
49
|
+
[project.scripts]
|
|
50
|
+
vkrscan = "vkrscan.cli:app"
|
|
51
|
+
|
|
52
|
+
[tool.setuptools.packages.find]
|
|
53
|
+
where = ["."]
|
|
54
|
+
include = ["vkrscan*"]
|
|
55
|
+
|
|
56
|
+
[tool.pytest.ini_options]
|
|
57
|
+
testpaths = ["tests"]
|
|
58
|
+
python_files = ["test_*.py"]
|
|
59
|
+
python_classes = ["Test*"]
|
|
60
|
+
python_functions = ["test_*"]
|
|
61
|
+
addopts = "-v --tb=short"
|
|
62
|
+
|
|
63
|
+
[tool.ruff]
|
|
64
|
+
line-length = 100
|
|
65
|
+
target-version = "py311"
|
|
66
|
+
|
|
67
|
+
[tool.mypy]
|
|
68
|
+
python_version = "3.11"
|
|
69
|
+
warn_return_any = true
|
|
70
|
+
warn_unused_configs = true
|
|
71
|
+
disallow_untyped_defs = false
|
|
72
|
+
ignore_missing_imports = true
|
vkrscan-1.0.0/setup.cfg
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
"""Tests for VKRScan CLI commands."""
|
|
2
|
+
|
|
3
|
+
from pathlib import Path
|
|
4
|
+
from typer.testing import CliRunner
|
|
5
|
+
from vkrscan.cli import app
|
|
6
|
+
|
|
7
|
+
runner = CliRunner()
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def test_cli_version() -> None:
|
|
11
|
+
result = runner.invoke(app, ["--version"])
|
|
12
|
+
assert result.exit_code == 0
|
|
13
|
+
assert "VKRScan" in result.stdout
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def test_cli_encode_decode() -> None:
|
|
17
|
+
enc_result = runner.invoke(app, ["encode", "base64", "CyberDefense2026"])
|
|
18
|
+
assert enc_result.exit_code == 0
|
|
19
|
+
assert "Q3liZXJEZWZlbnNlMjAyNg==" in enc_result.stdout
|
|
20
|
+
|
|
21
|
+
dec_result = runner.invoke(app, ["decode", "base64", "Q3liZXJEZWZlbnNlMjAyNg=="])
|
|
22
|
+
assert dec_result.exit_code == 0
|
|
23
|
+
assert "CyberDefense2026" in dec_result.stdout
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def test_cli_analyze_encoding() -> None:
|
|
27
|
+
result = runner.invoke(app, ["analyze", "Q3liZXJEZWZlbnNlMjAyNg=="])
|
|
28
|
+
assert result.exit_code == 0
|
|
29
|
+
assert "Base64" in result.stdout
|
|
30
|
+
assert "CyberDefense2026" in result.stdout
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def test_cli_hash() -> None:
|
|
34
|
+
result = runner.invoke(app, ["hash", "admin", "--alg", "sha256"])
|
|
35
|
+
assert result.exit_code == 0
|
|
36
|
+
assert "SHA-256" in result.stdout
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def test_cli_secrets_scan(fake_secrets_repo: Path, tmp_path: Path) -> None:
|
|
40
|
+
out_json = tmp_path / "cli_report.json"
|
|
41
|
+
result = runner.invoke(app, ["secrets", str(fake_secrets_repo), "--format", "json", "--output", str(out_json)])
|
|
42
|
+
assert result.exit_code == 0
|
|
43
|
+
assert out_json.exists()
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def test_cli_steg_scan(clean_png_file: Path, tmp_path: Path) -> None:
|
|
47
|
+
out_html = tmp_path / "steg_report.html"
|
|
48
|
+
result = runner.invoke(app, ["steg", str(clean_png_file), "--format", "html", "--output", str(out_html)])
|
|
49
|
+
assert result.exit_code == 0
|
|
50
|
+
assert out_html.exists()
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def test_cli_jwt() -> None:
|
|
54
|
+
token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
|
|
55
|
+
result = runner.invoke(app, ["jwt", token])
|
|
56
|
+
assert result.exit_code == 0
|
|
57
|
+
assert "HS256" in result.stdout
|
|
58
|
+
assert "John Doe" in result.stdout
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
"""Tests for VKRScan Interactive Cyberpunk Shell."""
|
|
2
|
+
|
|
3
|
+
from vkrscan.shell import VKRScanShell
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
def test_shell_initialization() -> None:
|
|
7
|
+
shell = VKRScanShell()
|
|
8
|
+
assert shell.settings["target"] == "(not set)"
|
|
9
|
+
assert shell.settings["modules"] == "all"
|
|
10
|
+
assert shell.settings["format"] == "terminal"
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def test_shell_set_and_show() -> None:
|
|
14
|
+
shell = VKRScanShell()
|
|
15
|
+
shell.handle_command("set target https://authorized.example")
|
|
16
|
+
assert shell.settings["target"] == "https://authorized.example"
|
|
17
|
+
|
|
18
|
+
shell.handle_command("set format json")
|
|
19
|
+
assert shell.settings["format"] == "json"
|
|
20
|
+
|
|
21
|
+
shell.handle_command("set timeout 25")
|
|
22
|
+
assert shell.settings["timeout"] == "25"
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def test_shell_help_and_exit() -> None:
|
|
26
|
+
shell = VKRScanShell()
|
|
27
|
+
assert shell.handle_command("help") is True
|
|
28
|
+
assert shell.handle_command("show") is True
|
|
29
|
+
assert shell.handle_command("exit") is False
|
|
30
|
+
assert shell.handle_command("quit") is False
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def test_shell_crypto_commands() -> None:
|
|
34
|
+
shell = VKRScanShell()
|
|
35
|
+
assert shell.handle_command("encode base64 HelloCyber") is True
|
|
36
|
+
assert shell.handle_command("decode base64 SGVsbG9DeWJlcg==") is True
|
|
37
|
+
assert shell.handle_command("analyze SGVsbG9DeWJlcg==") is True
|
|
38
|
+
assert shell.handle_command("hash admin") is True
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
"""VKRScan - Modular Python Cybersecurity Analysis Framework.
|
|
2
|
+
|
|
3
|
+
VKRScan provides modular security analysis capabilities for:
|
|
4
|
+
- Steganography & hidden-data analysis
|
|
5
|
+
- Secrets & credential discovery
|
|
6
|
+
- Authorized web security assessment
|
|
7
|
+
- Cryptographic, encoding, and JWT analysis
|
|
8
|
+
- Unified evidence collection and reporting
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
__version__ = "1.0.0"
|
|
12
|
+
__author__ = "VKRScan Security Team"
|
|
13
|
+
__all__ = ["__version__", "__author__"]
|