vulnreach 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.
- vulnreach-1.0.0/LICENSE +21 -0
- vulnreach-1.0.0/MANIFEST.in +10 -0
- vulnreach-1.0.0/PKG-INFO +607 -0
- vulnreach-1.0.0/README.md +561 -0
- vulnreach-1.0.0/pyproject.toml +118 -0
- vulnreach-1.0.0/requirements.txt +22 -0
- vulnreach-1.0.0/setup.cfg +4 -0
- vulnreach-1.0.0/src/vulnreach/__init__.py +28 -0
- vulnreach-1.0.0/src/vulnreach/cli.py +29 -0
- vulnreach-1.0.0/src/vulnreach/core.py +37 -0
- vulnreach-1.0.0/src/vulnreach/tracer_.py +1002 -0
- vulnreach-1.0.0/src/vulnreach/utils/__init__.py +14 -0
- vulnreach-1.0.0/src/vulnreach/utils/exploitability_analyzer.py +353 -0
- vulnreach-1.0.0/src/vulnreach/utils/get_metadata.py +50 -0
- vulnreach-1.0.0/src/vulnreach/utils/java_reachability_analyzer.py +347 -0
- vulnreach-1.0.0/src/vulnreach/utils/multi_language_analyzer.py +123 -0
- vulnreach-1.0.0/src/vulnreach/utils/vuln_reachability_analyzer.py +727 -0
- vulnreach-1.0.0/src/vulnreach.egg-info/PKG-INFO +607 -0
- vulnreach-1.0.0/src/vulnreach.egg-info/SOURCES.txt +22 -0
- vulnreach-1.0.0/src/vulnreach.egg-info/dependency_links.txt +1 -0
- vulnreach-1.0.0/src/vulnreach.egg-info/entry_points.txt +3 -0
- vulnreach-1.0.0/src/vulnreach.egg-info/requires.txt +18 -0
- vulnreach-1.0.0/src/vulnreach.egg-info/top_level.txt +1 -0
- vulnreach-1.0.0/tests/test_exploitability_analysis.py +160 -0
vulnreach-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 procrastinator
|
|
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.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
include README.md
|
|
2
|
+
include LICENSE
|
|
3
|
+
include requirements.txt
|
|
4
|
+
include pyproject.toml
|
|
5
|
+
recursive-include src/vulnreach *.py
|
|
6
|
+
global-exclude *.pyc
|
|
7
|
+
global-exclude __pycache__
|
|
8
|
+
global-exclude .git*
|
|
9
|
+
global-exclude security_findings*
|
|
10
|
+
global-exclude *.egg-info*
|
vulnreach-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,607 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: vulnreach
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Smart Vulnerability Reachability Analyzer - Beyond version checking
|
|
5
|
+
Author-email: Hrishikesh Nate <ihrishikeshnate@gmail.com>
|
|
6
|
+
Maintainer-email: Hrishikesh Nate <ihrishikeshnate@gmail.com>
|
|
7
|
+
License: MIT
|
|
8
|
+
Project-URL: Homepage, https://github.com/ihrishikesh0896/vulnreach
|
|
9
|
+
Project-URL: Documentation, https://github.com/ihrishikesh0896/vulnreach#readme
|
|
10
|
+
Project-URL: Repository, https://github.com/ihrishikesh0896/vulnreach.git
|
|
11
|
+
Project-URL: Bug Tracker, https://github.com/ihrishikesh0896/vulnreach/issues
|
|
12
|
+
Keywords: security,vulnerability,sca,sbom,reachability
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Intended Audience :: System Administrators
|
|
16
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
24
|
+
Classifier: Topic :: Security
|
|
25
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
26
|
+
Classifier: Topic :: System :: Systems Administration
|
|
27
|
+
Requires-Python: >=3.8
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
License-File: LICENSE
|
|
30
|
+
Requires-Dist: requests>=2.25.0
|
|
31
|
+
Requires-Dist: Flask
|
|
32
|
+
Requires-Dist: jinja2>=3.0.0
|
|
33
|
+
Requires-Dist: pandas>=1.3.0
|
|
34
|
+
Provides-Extra: dev
|
|
35
|
+
Requires-Dist: pytest>=6.0; extra == "dev"
|
|
36
|
+
Requires-Dist: pytest-cov>=2.0; extra == "dev"
|
|
37
|
+
Requires-Dist: black>=22.0; extra == "dev"
|
|
38
|
+
Requires-Dist: flake8>=4.0; extra == "dev"
|
|
39
|
+
Requires-Dist: mypy>=0.900; extra == "dev"
|
|
40
|
+
Provides-Extra: web
|
|
41
|
+
Requires-Dist: flask>=2.0.0; extra == "web"
|
|
42
|
+
Requires-Dist: gunicorn>=20.0.0; extra == "web"
|
|
43
|
+
Provides-Extra: export
|
|
44
|
+
Requires-Dist: jinja2>=3.0.0; extra == "export"
|
|
45
|
+
Dynamic: license-file
|
|
46
|
+
|
|
47
|
+
# ๐ก๏ธ VulnReach - Smart Vulnerability Reachability Analyzer
|
|
48
|
+
|
|
49
|
+
[]()
|
|
50
|
+
[]()
|
|
51
|
+
[]()
|
|
52
|
+
[]()
|
|
53
|
+
|
|
54
|
+
> **Beyond version checking**: Discover which vulnerabilities in your dependencies actually matter by analyzing real code usage patterns and exploitability.
|
|
55
|
+
|
|
56
|
+
VulnReach is an intelligent vulnerability analysis tool that goes beyond traditional dependency scanning. While most tools simply check versions, VulnReach analyzes your actual codebase to determine which vulnerable packages are **truly reachable** and pose real risk to your application. Now with **git repository support** and **exploitability analysis**.
|
|
57
|
+
|
|
58
|
+
## ๐ฏ Why VulnReach?
|
|
59
|
+
|
|
60
|
+
Traditional vulnerability scanners overwhelm you with alerts, but VulnReach answers the critical question:
|
|
61
|
+
|
|
62
|
+
> **"Is this vulnerability actually exploitable in MY codebase?"**
|
|
63
|
+
|
|
64
|
+
### The Problem
|
|
65
|
+
- ๐ **Traditional scanners**: "You have 147 vulnerabilities!"
|
|
66
|
+
- ๐ฐ **You**: "Which ones should I fix first? Are they even used?"
|
|
67
|
+
- โฐ **Result**: Analysis paralysis and wasted time on unused dependencies
|
|
68
|
+
|
|
69
|
+
### The VulnReach Solution
|
|
70
|
+
- ๐ฏ **VulnReach**: "You have 8 CRITICAL vulnerabilities that are actively used in your code"
|
|
71
|
+
- โ
**You**: Clear priorities, actionable insights, efficient remediation
|
|
72
|
+
- ๐ **Result**: Focus on what matters, fix real risks first
|
|
73
|
+
|
|
74
|
+
## ๐ Features
|
|
75
|
+
|
|
76
|
+
### ๐ **Smart Vulnerability Discovery**
|
|
77
|
+
- **SBOM Generation**: Uses [Syft](https://github.com/anchore/syft) to create comprehensive Software Bill of Materials
|
|
78
|
+
- **Vulnerability Scanning**: Leverages [Trivy](https://aquasecurity.github.io/trivy/) for industry-leading vulnerability detection
|
|
79
|
+
- **Multi-format Support**: SPDX, CycloneDX, and Syft native formats
|
|
80
|
+
- **Performance Tracking**: Detailed scan duration timing and metrics
|
|
81
|
+
|
|
82
|
+
### ๐ **Git Repository Support** *(NEW)*
|
|
83
|
+
- **Remote Repository Analysis**: Scan repositories directly from URLs without manual cloning
|
|
84
|
+
- **Multi-Platform Support**: GitHub, GitLab, Bitbucket, and custom git servers
|
|
85
|
+
- **SSH & HTTPS**: Supports both authentication methods
|
|
86
|
+
- **Automatic Cleanup**: Temporary clones are automatically cleaned up after analysis
|
|
87
|
+
- **Smart Naming**: Automatically extracts repository names for organized reporting
|
|
88
|
+
|
|
89
|
+
### ๐ง **Intelligent Reachability Analysis**
|
|
90
|
+
- **Multi-Language Support**: Python and Java projects with automatic language detection
|
|
91
|
+
- **Static Code Analysis**: Parses your entire codebase using AST analysis (Python) or regex patterns (Java)
|
|
92
|
+
- **Usage Pattern Detection**: Identifies imports, function calls, method calls, and instantiations
|
|
93
|
+
- **Dynamic Package Mapping**: Handles complex import-to-package mappings (e.g., `import yaml` โ `PyYAML`, `org.apache.commons` โ `commons-lang3`)
|
|
94
|
+
|
|
95
|
+
### ๐ฅ **Exploitability Analysis** *(NEW)*
|
|
96
|
+
- **Public Exploit Detection**: Checks for publicly available exploits using SearchSploit
|
|
97
|
+
- **CVE Intelligence**: Enhanced vulnerability context and exploit availability
|
|
98
|
+
- **Risk Amplification**: Identifies vulnerabilities with known exploits in the wild
|
|
99
|
+
- **Prioritization Support**: Helps focus on vulnerabilities with active exploitation
|
|
100
|
+
|
|
101
|
+
### ๐ **Risk Prioritization**
|
|
102
|
+
- **CRITICAL**: Actively used across multiple files with direct function calls
|
|
103
|
+
- **HIGH**: Used with direct function calls
|
|
104
|
+
- **MEDIUM**: Imported across multiple files
|
|
105
|
+
- **LOW**: Limited usage detected
|
|
106
|
+
- **NOT_REACHABLE**: Not used in codebase (safe to ignore)
|
|
107
|
+
|
|
108
|
+
### ๐ **Comprehensive Reporting**
|
|
109
|
+
- **Executive Summary**: High-level risk overview with timing metrics
|
|
110
|
+
- **Detailed Analysis**: File-by-file usage contexts
|
|
111
|
+
- **Exploitability Reports**: Public exploit availability and context
|
|
112
|
+
- **Remediation Guidance**: Version upgrade recommendations
|
|
113
|
+
- **JSON Output**: Machine-readable for CI/CD integration
|
|
114
|
+
- **Organized Output**: Structured reporting in `security_findings/project_name/` directories
|
|
115
|
+
|
|
116
|
+
## ๐ Prerequisites
|
|
117
|
+
|
|
118
|
+
Install the required security tools:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
# Install Syft (SBOM generation)
|
|
122
|
+
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin
|
|
123
|
+
|
|
124
|
+
# Install Trivy (vulnerability scanning)
|
|
125
|
+
# macOS
|
|
126
|
+
brew install trivy
|
|
127
|
+
|
|
128
|
+
# Linux
|
|
129
|
+
curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin
|
|
130
|
+
|
|
131
|
+
# Or see: https://aquasecurity.github.io/trivy/latest/getting-started/installation/
|
|
132
|
+
|
|
133
|
+
# Git (for repository cloning - usually pre-installed)
|
|
134
|
+
# macOS: Xcode Command Line Tools
|
|
135
|
+
xcode-select --install
|
|
136
|
+
|
|
137
|
+
# Linux (Ubuntu/Debian)
|
|
138
|
+
sudo apt update && sudo apt install git
|
|
139
|
+
|
|
140
|
+
# Optional: SearchSploit for exploitability analysis
|
|
141
|
+
sudo apt update && sudo apt install exploitdb
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Install Python dependencies:
|
|
145
|
+
```bash
|
|
146
|
+
pip install requests
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
## ๐ ๏ธ Installation
|
|
150
|
+
|
|
151
|
+
### Option 1: Install from PyPI (Recommended)
|
|
152
|
+
```bash
|
|
153
|
+
pip install vulnreach
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### Option 2: Install from Source
|
|
157
|
+
```bash
|
|
158
|
+
git clone https://github.com/ihrishikesh0896/vulnreach.git
|
|
159
|
+
cd vulnreach
|
|
160
|
+
pip install -e .
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
### Option 3: Development Setup
|
|
164
|
+
```bash
|
|
165
|
+
git clone https://github.com/ihrishikesh0896/vulnreach.git
|
|
166
|
+
cd vulnreach
|
|
167
|
+
pip install -e ".[dev]"
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
## ๐ Quick Start
|
|
171
|
+
|
|
172
|
+
### Basic Vulnerability Scan
|
|
173
|
+
```bash
|
|
174
|
+
# Scan your local project directory
|
|
175
|
+
vulnreach /path/to/your/project
|
|
176
|
+
|
|
177
|
+
# Scan remote git repository
|
|
178
|
+
vulnreach https://github.com/user/repo.git
|
|
179
|
+
|
|
180
|
+
# Scan GitHub repository (auto-detects .git)
|
|
181
|
+
vulnreach https://github.com/user/vulnerable-app
|
|
182
|
+
|
|
183
|
+
# Generate comprehensive report
|
|
184
|
+
vulnreach /path/to/your/project --output-report security_report.json
|
|
185
|
+
|
|
186
|
+
# Alternative command (for local installs)
|
|
187
|
+
vulnreach-scan /path/to/your/project
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### With Reachability Analysis (Recommended)
|
|
191
|
+
```bash
|
|
192
|
+
# Full analysis with multi-language reachability insights
|
|
193
|
+
vulnreach /path/to/your/project --run-reachability
|
|
194
|
+
|
|
195
|
+
# Analyze remote repository with reachability
|
|
196
|
+
vulnreach https://github.com/user/repo.git --run-reachability
|
|
197
|
+
|
|
198
|
+
# Supports Python and Java projects automatically
|
|
199
|
+
# Python: Analyzes .py files using AST parsing
|
|
200
|
+
# Java: Analyzes .java files using regex patterns
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
### With Exploitability Analysis *(NEW)*
|
|
204
|
+
```bash
|
|
205
|
+
# Check for public exploits using SearchSploit
|
|
206
|
+
vulnreach /path/to/your/project --run-exploitability
|
|
207
|
+
|
|
208
|
+
# Full security analysis (recommended)
|
|
209
|
+
vulnreach https://github.com/user/repo.git --run-reachability --run-exploitability
|
|
210
|
+
|
|
211
|
+
# Complete analysis with all features
|
|
212
|
+
vulnreach /path/to/project --run-reachability --run-exploitability --output-report full_report.json
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
### Advanced Usage
|
|
216
|
+
```bash
|
|
217
|
+
# Use existing SBOM
|
|
218
|
+
vulnreach --sbom existing_sbom.json --run-reachability
|
|
219
|
+
|
|
220
|
+
# Save SBOM for reuse
|
|
221
|
+
vulnreach /path/to/project --output-sbom project_sbom.json --run-reachability
|
|
222
|
+
|
|
223
|
+
# Direct scan (skip SBOM generation)
|
|
224
|
+
vulnreach /path/to/project --direct-scan --run-reachability
|
|
225
|
+
|
|
226
|
+
# SSH git repository with custom analysis
|
|
227
|
+
vulnreach git@github.com:user/private-repo.git --run-reachability --run-exploitability
|
|
228
|
+
|
|
229
|
+
# Specify different SBOM formats
|
|
230
|
+
vulnreach /path/to/project --sbom-format cyclonedx-json --run-reachability
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
## ๐ Sample Output
|
|
234
|
+
|
|
235
|
+
### Basic Scan Output
|
|
236
|
+
```
|
|
237
|
+
๐ Starting Security Analysis with Syft and Trivy...
|
|
238
|
+
๐ฅ Cloning repository: https://github.com/user/vulnerable-app.git
|
|
239
|
+
โ
Repository cloned to: /tmp/vulnreach_clone_abc123
|
|
240
|
+
๐ Security findings will be saved to: security_findings/vulnerable-app
|
|
241
|
+
|
|
242
|
+
๐ก๏ธ SECURITY SCAN RESULTS
|
|
243
|
+
================================================================================
|
|
244
|
+
๐ Scan completed at: 2024-08-14T10:30:45
|
|
245
|
+
โฑ๏ธ Scan duration: 23.45 seconds
|
|
246
|
+
๐ง SBOM Generator: Syft
|
|
247
|
+
๐ Vulnerability Scanner: Trivy
|
|
248
|
+
|
|
249
|
+
๐ฆ Total Components: 127
|
|
250
|
+
โ ๏ธ Vulnerable Components: 8
|
|
251
|
+
๐จ Total Vulnerabilities: 23
|
|
252
|
+
|
|
253
|
+
๐ Severity Breakdown:
|
|
254
|
+
๐ด CRITICAL: 3
|
|
255
|
+
๐ HIGH: 5
|
|
256
|
+
๐ก MEDIUM: 12
|
|
257
|
+
๐ข LOW: 3
|
|
258
|
+
|
|
259
|
+
๐จ TOP CRITICAL/HIGH VULNERABILITIES:
|
|
260
|
+
------------------------------------------------------------
|
|
261
|
+
๐ด CVE-2024-1234 - requests@2.25.1
|
|
262
|
+
Severity: CRITICAL (CVSS: 9.8)
|
|
263
|
+
Title: Remote Code Execution in HTTP parsing
|
|
264
|
+
๐ง Fixed in: 2.32.0
|
|
265
|
+
|
|
266
|
+
๐งน Cleaning up temporary clone directory: /tmp/vulnreach_clone_abc123
|
|
267
|
+
โฑ๏ธ Total scan duration: 23.45 seconds
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
### With Reachability Analysis
|
|
271
|
+
```
|
|
272
|
+
=== Vulnerability Reachability Analysis ===
|
|
273
|
+
Total vulnerabilities analyzed: 23
|
|
274
|
+
Critical (actively used): 2
|
|
275
|
+
High (used with calls): 1
|
|
276
|
+
Medium (imported): 3
|
|
277
|
+
Low (limited usage): 5
|
|
278
|
+
Not reachable: 12
|
|
279
|
+
|
|
280
|
+
๐จ CRITICAL: requests v2.25.1
|
|
281
|
+
Reason: Package requests is actively used across 8 files with direct function calls
|
|
282
|
+
Upgrade to: 2.32.0
|
|
283
|
+
๐ src/api/client.py:15 - import requests
|
|
284
|
+
๐ src/utils/http.py:23 - response = requests.get(url)
|
|
285
|
+
๐ src/auth/oauth.py:45 - requests.post(token_url, data=payload)
|
|
286
|
+
... and 12 more usages
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
### With Exploitability Analysis *(NEW)*
|
|
290
|
+
```
|
|
291
|
+
๐ฅ Running exploitability analysis using SearchSploit...
|
|
292
|
+
|
|
293
|
+
=== Exploitability Analysis Results ===
|
|
294
|
+
Total vulnerabilities analyzed: 23
|
|
295
|
+
Vulnerabilities with public exploits: 5
|
|
296
|
+
High-risk exploitable vulnerabilities: 2
|
|
297
|
+
|
|
298
|
+
๐ฅ HIGH EXPLOITABILITY: CVE-2024-1234 - requests@2.25.1
|
|
299
|
+
๐ CVSS Score: 9.8 (CRITICAL)
|
|
300
|
+
๐ฏ Public Exploits Found: 3
|
|
301
|
+
๐ SearchSploit Results:
|
|
302
|
+
- Python Requests 2.25.1 - Remote Code Execution
|
|
303
|
+
- HTTP Parser Buffer Overflow Exploit
|
|
304
|
+
- Multiple PoC exploits available
|
|
305
|
+
|
|
306
|
+
๐ฅ Exploitability report saved to: security_findings/vulnerable-app/exploitability_report.json
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
## ๐๏ธ Project Structure
|
|
310
|
+
|
|
311
|
+
```
|
|
312
|
+
vulnreach/
|
|
313
|
+
โโโ src/
|
|
314
|
+
โ โโโ vulnreach/
|
|
315
|
+
โ โโโ cli.py # CLI entry point
|
|
316
|
+
โ โโโ core.py # Core components export
|
|
317
|
+
โ โโโ tracer_.py # Main analysis engine
|
|
318
|
+
โ โโโ utils/
|
|
319
|
+
โ โโโ __init__.py
|
|
320
|
+
โ โโโ vuln_reachability_analyzer.py # Core reachability analysis
|
|
321
|
+
โ โโโ java_reachability_analyzer.py # Java-specific analysis
|
|
322
|
+
โ โโโ multi_language_analyzer.py # Multi-language support
|
|
323
|
+
โ โโโ exploitability_analyzer.py # Exploitability analysis
|
|
324
|
+
โ โโโ get_metadata.py # Dynamic package mapping
|
|
325
|
+
โโโ security_findings/ # Generated reports (auto-created)
|
|
326
|
+
โ โโโ project_name/ # Organized by project/repo name
|
|
327
|
+
โ โโโ security_report.json # Main vulnerability report
|
|
328
|
+
โ โโโ consolidated.json # Upgrade recommendations
|
|
329
|
+
โ โโโ vulnerability_reachability_report.json # Reachability analysis
|
|
330
|
+
โ โโโ exploitability_report.json # Exploit analysis (NEW)
|
|
331
|
+
โ โโโ project.sbom.json # Generated SBOM (optional)
|
|
332
|
+
โโโ tests/ # Test suite
|
|
333
|
+
โโโ pyproject.toml # Modern Python packaging
|
|
334
|
+
โโโ README.md
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
### Report Organization *(NEW)*
|
|
338
|
+
Reports are now automatically organized by project name:
|
|
339
|
+
- **Local projects**: Uses directory name (e.g., `my-app` โ `security_findings/my-app/`)
|
|
340
|
+
- **Git repositories**: Uses repo name (e.g., `vulnerable-app.git` โ `security_findings/vulnerable-app/`)
|
|
341
|
+
- **Clean separation**: Each project gets its own directory for easy management
|
|
342
|
+
|
|
343
|
+
## ๐ Report Structure
|
|
344
|
+
|
|
345
|
+
### Security Report (`security_report.json`) *(ENHANCED)*
|
|
346
|
+
```json
|
|
347
|
+
{
|
|
348
|
+
"scan_timestamp": "2024-08-14T10:30:45.123456",
|
|
349
|
+
"scan_duration": 23.45,
|
|
350
|
+
"tools": {
|
|
351
|
+
"sbom_generator": "Syft",
|
|
352
|
+
"vulnerability_scanner": "Trivy"
|
|
353
|
+
},
|
|
354
|
+
"summary": {
|
|
355
|
+
"total_components": 127,
|
|
356
|
+
"vulnerable_components": 8,
|
|
357
|
+
"total_vulnerabilities": 23,
|
|
358
|
+
"severity_breakdown": {
|
|
359
|
+
"CRITICAL": 3,
|
|
360
|
+
"HIGH": 5,
|
|
361
|
+
"MEDIUM": 12,
|
|
362
|
+
"LOW": 3
|
|
363
|
+
}
|
|
364
|
+
},
|
|
365
|
+
"vulnerabilities": [...],
|
|
366
|
+
"components": [...]
|
|
367
|
+
}
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
### Consolidated Recommendations (`consolidated.json`)
|
|
371
|
+
```json
|
|
372
|
+
[
|
|
373
|
+
{
|
|
374
|
+
"package_name": "requests",
|
|
375
|
+
"installed_version": "2.25.1",
|
|
376
|
+
"recommended_fixed_version": "2.32.0",
|
|
377
|
+
"upgrade_needed": true
|
|
378
|
+
}
|
|
379
|
+
]
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
### Reachability Analysis (`vulnerability_reachability_report.json`)
|
|
383
|
+
```json
|
|
384
|
+
{
|
|
385
|
+
"summary": {
|
|
386
|
+
"critical_reachable": 2,
|
|
387
|
+
"not_reachable": 12
|
|
388
|
+
},
|
|
389
|
+
"vulnerabilities": [
|
|
390
|
+
{
|
|
391
|
+
"package_name": "requests",
|
|
392
|
+
"criticality": "CRITICAL",
|
|
393
|
+
"risk_reason": "Package requests is actively used across 8 files",
|
|
394
|
+
"usage_details": {
|
|
395
|
+
"files_affected": 8,
|
|
396
|
+
"usage_contexts": [...]
|
|
397
|
+
}
|
|
398
|
+
}
|
|
399
|
+
]
|
|
400
|
+
}
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
### Exploitability Analysis (`exploitability_report.json`) *(NEW)*
|
|
404
|
+
```json
|
|
405
|
+
{
|
|
406
|
+
"scan_timestamp": "2024-08-14T10:30:45.123456",
|
|
407
|
+
"analysis_summary": {
|
|
408
|
+
"total_vulnerabilities_analyzed": 23,
|
|
409
|
+
"vulnerabilities_with_exploits": 5,
|
|
410
|
+
"high_risk_exploitable": 2,
|
|
411
|
+
"searchsploit_available": true
|
|
412
|
+
},
|
|
413
|
+
"exploitable_vulnerabilities": [
|
|
414
|
+
{
|
|
415
|
+
"vulnerability_id": "CVE-2024-1234",
|
|
416
|
+
"package_name": "requests",
|
|
417
|
+
"package_version": "2.25.1",
|
|
418
|
+
"severity": "CRITICAL",
|
|
419
|
+
"cvss_score": 9.8,
|
|
420
|
+
"exploit_analysis": {
|
|
421
|
+
"exploits_found": 3,
|
|
422
|
+
"exploit_risk": "HIGH",
|
|
423
|
+
"searchsploit_results": [
|
|
424
|
+
"Python Requests 2.25.1 - Remote Code Execution",
|
|
425
|
+
"HTTP Parser Buffer Overflow Exploit"
|
|
426
|
+
]
|
|
427
|
+
}
|
|
428
|
+
}
|
|
429
|
+
]
|
|
430
|
+
}
|
|
431
|
+
```
|
|
432
|
+
|
|
433
|
+
## ๐ง Configuration
|
|
434
|
+
|
|
435
|
+
### Supported SBOM Formats
|
|
436
|
+
- `spdx-json` (default)
|
|
437
|
+
- `cyclonedx-json`
|
|
438
|
+
- `syft-json`
|
|
439
|
+
|
|
440
|
+
### Command Line Options *(UPDATED)*
|
|
441
|
+
```bash
|
|
442
|
+
# Target specification
|
|
443
|
+
target # Directory path OR git repository URL
|
|
444
|
+
|
|
445
|
+
# Core functionality
|
|
446
|
+
--sbom SBOM_FILE # Use existing SBOM file
|
|
447
|
+
--output-sbom SBOM_FILE # Save generated SBOM
|
|
448
|
+
--sbom-format FORMAT # SBOM format (spdx-json, cyclonedx-json, syft-json)
|
|
449
|
+
|
|
450
|
+
# Analysis options
|
|
451
|
+
--direct-scan # Skip SBOM, scan directly with Trivy
|
|
452
|
+
--run-reachability # Enable multi-language reachability analysis
|
|
453
|
+
--run-exploitability # Enable exploitability analysis (NEW)
|
|
454
|
+
|
|
455
|
+
# Output control
|
|
456
|
+
--output-report REPORT_FILE # Security report path (includes scan timing)
|
|
457
|
+
--output-consolidated CONS_FILE # Consolidated recommendations path
|
|
458
|
+
--trivy-output TRIVY_FILE # Save raw Trivy output
|
|
459
|
+
|
|
460
|
+
# Git repository support (automatic detection)
|
|
461
|
+
# Supports: https://github.com/user/repo.git
|
|
462
|
+
# https://github.com/user/repo
|
|
463
|
+
# git@github.com:user/repo.git
|
|
464
|
+
# ssh://git@server.com/user/repo.git
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
### Supported Git Platforms *(NEW)*
|
|
468
|
+
- **GitHub**: `https://github.com/user/repo.git` or `https://github.com/user/repo`
|
|
469
|
+
- **GitLab**: `https://gitlab.com/user/repo.git` or `https://gitlab.com/user/repo`
|
|
470
|
+
- **Bitbucket**: `https://bitbucket.org/user/repo.git`
|
|
471
|
+
- **Custom Git servers**: Any valid git URL
|
|
472
|
+
- **SSH access**: `git@server.com:user/repo.git`
|
|
473
|
+
- **Private repositories**: Supported if git credentials are configured
|
|
474
|
+
|
|
475
|
+
## ๐๏ธ CI/CD Integration
|
|
476
|
+
|
|
477
|
+
### GitHub Actions Example *(ENHANCED)*
|
|
478
|
+
```yaml
|
|
479
|
+
name: Security Analysis
|
|
480
|
+
on: [push, pull_request]
|
|
481
|
+
|
|
482
|
+
jobs:
|
|
483
|
+
security:
|
|
484
|
+
runs-on: ubuntu-latest
|
|
485
|
+
steps:
|
|
486
|
+
- uses: actions/checkout@v3
|
|
487
|
+
|
|
488
|
+
- name: Install tools
|
|
489
|
+
run: |
|
|
490
|
+
# Core security tools
|
|
491
|
+
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin
|
|
492
|
+
curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin
|
|
493
|
+
|
|
494
|
+
# Optional: Install SearchSploit for exploitability analysis
|
|
495
|
+
sudo apt update && sudo apt install exploitdb
|
|
496
|
+
|
|
497
|
+
- name: Run Complete VulnReach Analysis
|
|
498
|
+
run: |
|
|
499
|
+
# Full analysis with all features
|
|
500
|
+
vulnreach . --run-reachability --run-exploitability
|
|
501
|
+
|
|
502
|
+
- name: Upload Security Reports
|
|
503
|
+
uses: actions/upload-artifact@v3
|
|
504
|
+
if: always()
|
|
505
|
+
with:
|
|
506
|
+
name: security-reports
|
|
507
|
+
path: security_findings/
|
|
508
|
+
|
|
509
|
+
- name: Comment PR with Results
|
|
510
|
+
if: github.event_name == 'pull_request'
|
|
511
|
+
run: |
|
|
512
|
+
# Example: Post summary to PR (customize as needed)
|
|
513
|
+
echo "Security scan completed. Check artifacts for detailed reports."
|
|
514
|
+
|
|
515
|
+
# Alternative: Scan external repository
|
|
516
|
+
external-scan:
|
|
517
|
+
runs-on: ubuntu-latest
|
|
518
|
+
steps:
|
|
519
|
+
- name: Install tools
|
|
520
|
+
run: |
|
|
521
|
+
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin
|
|
522
|
+
curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin
|
|
523
|
+
|
|
524
|
+
- name: Scan External Repository
|
|
525
|
+
run: |
|
|
526
|
+
# Scan any public repository directly
|
|
527
|
+
vulnreach https://github.com/user/target-repo.git --run-reachability --run-exploitability
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
### Exit Codes
|
|
531
|
+
- `0`: No vulnerabilities or only LOW/MEDIUM severity
|
|
532
|
+
- `1`: CRITICAL or HIGH severity vulnerabilities found
|
|
533
|
+
- `130`: Interrupted by user
|
|
534
|
+
- Other: Unexpected errors
|
|
535
|
+
|
|
536
|
+
## ๐ค Contributing
|
|
537
|
+
|
|
538
|
+
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
|
|
539
|
+
|
|
540
|
+
### Development Setup
|
|
541
|
+
```bash
|
|
542
|
+
git clone https://github.com/ihrishikesh0896/vulnreach.git
|
|
543
|
+
cd vulnreach
|
|
544
|
+
pip install -e .
|
|
545
|
+
```
|
|
546
|
+
|
|
547
|
+
### Running Tests
|
|
548
|
+
```bash
|
|
549
|
+
python -m pytest tests/
|
|
550
|
+
```
|
|
551
|
+
|
|
552
|
+
## ๐ License
|
|
553
|
+
|
|
554
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
555
|
+
|
|
556
|
+
## ๐ Related Projects
|
|
557
|
+
|
|
558
|
+
- [Syft](https://github.com/anchore/syft) - SBOM generation
|
|
559
|
+
- [Trivy](https://github.com/aquasecurity/trivy) - Vulnerability scanning
|
|
560
|
+
- [Grype](https://github.com/anchore/grype) - Alternative vulnerability scanner
|
|
561
|
+
- [OSV](https://osv.dev/) - Open Source Vulnerability database
|
|
562
|
+
|
|
563
|
+
## ๐ What's New
|
|
564
|
+
|
|
565
|
+
### Version 2.0 Features *(NEW)*
|
|
566
|
+
- ๐ **Git Repository Support**: Scan remote repositories directly from URLs
|
|
567
|
+
- ๐ฅ **Exploitability Analysis**: Check for public exploits using SearchSploit
|
|
568
|
+
- โฑ๏ธ **Performance Tracking**: Detailed scan duration metrics and timing
|
|
569
|
+
- ๐ **Smart Organization**: Auto-organized reports by project/repository name
|
|
570
|
+
- ๐งน **Automatic Cleanup**: Temporary git clones are cleaned up automatically
|
|
571
|
+
- ๐ **Enhanced Security Reports**: Include scan timing and exploitability data
|
|
572
|
+
|
|
573
|
+
### Supported Workflows
|
|
574
|
+
- **Local Development**: Scan your development projects
|
|
575
|
+
- **Remote Analysis**: Analyze any public git repository
|
|
576
|
+
- **CI/CD Integration**: Automated security scanning in pipelines
|
|
577
|
+
- **Security Research**: Bulk analysis of multiple repositories
|
|
578
|
+
- **Compliance Checking**: Generate comprehensive security reports
|
|
579
|
+
|
|
580
|
+
## ๐ Support & Community
|
|
581
|
+
|
|
582
|
+
- ๐ **Bug Reports**: [GitHub Issues](https://github.com/ihrishikesh0896/vulnreach/issues)
|
|
583
|
+
- ๐ก **Feature Requests**: [GitHub Discussions](https://github.com/ihrishikesh0896/vulnreach/discussions)
|
|
584
|
+
- ๐ **Documentation**: [Official Docs](https://github.com/ihrishikesh0896/vulnreach/wiki)
|
|
585
|
+
- ๐ค **Contributing**: [Contributing Guide](CONTRIBUTING.md)
|
|
586
|
+
|
|
587
|
+
### Quick Help
|
|
588
|
+
```bash
|
|
589
|
+
# Get help with command options
|
|
590
|
+
vulnreach --help
|
|
591
|
+
|
|
592
|
+
# Examples with different targets
|
|
593
|
+
vulnreach https://github.com/user/repo.git --help
|
|
594
|
+
vulnreach /path/to/project --help
|
|
595
|
+
```
|
|
596
|
+
|
|
597
|
+
---
|
|
598
|
+
|
|
599
|
+
<div align="center">
|
|
600
|
+
|
|
601
|
+
**๐ก๏ธ Built with โค๏ธ for security-conscious developers**
|
|
602
|
+
|
|
603
|
+
*Now with Git repository support and exploitability analysis*
|
|
604
|
+
|
|
605
|
+
[โญ Star us on GitHub](https://github.com/ihrishikesh0896/vulnreach) | [๐ฌ Join the Discussion](https://github.com/ihrishikesh0896/vulnreach/discussions) | [๐ Read the Docs](https://github.com/ihrishikesh0896/vulnreach/wiki)
|
|
606
|
+
|
|
607
|
+
</div>
|