Metadata-Version: 2.4
Name: vuln-checker
Version: 0.5.6a1
Summary: High-performance CLI CVE vulnerability scanner for servers and SBOMs
Author: skm248
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Security
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.32.4
Requires-Dist: packaging>=23.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: toml>=0.10.2
Requires-Dist: tomli>=2.0.1
Requires-Dist: tqdm>=4.65.0
Requires-Dist: urllib3>=2.6.0
Dynamic: license-file

```text
██╗   ██╗██╗   ██╗██╗     ███╗   ██╗         ██████╗██╗  ██╗███████╗ ██████╗██╗  ██╗███████╗██████╗ 
██║   ██║██║   ██║██║     ████╗  ██║        ██╔════╝██║  ██║██╔════╝██╔════╝██║ ██╔╝██╔════╝██╔══██╗
██║   ██║██║   ██║██║     ██╔██╗ ██║ ██████╗██║     ███████║█████╗  ██║     █████╔╝ █████╗  ██████╔╝
╚██╗ ██╔╝██║   ██║██║     ██║╚██╗██║ ╚═════╝██║     ██╔══██║██╔══╝  ██║     ██╔═██╗ ██╔══╝  ██╔══██╗
 ╚████╔╝ ╚██████╔╝███████╗██║ ╚████║        ╚██████╗██║  ██║███████╗╚██████╗██║  ██╗███████╗██║  ██║
  ╚═══╝   ╚═════╝ ╚══════╝╚═╝  ╚═══╝         ╚══════╝╚═╝  ╚═╝╚══════╝ ╚══════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝
                           [ LOCAL & OFFLINE VULNERABILITY SCANNER ]
```

[![PyPI version](https://img.shields.io/pypi/v/vuln-checker?color=brightgreen)](https://pypi.org/project/vuln-checker/)
![Python](https://img.shields.io/badge/python-3.9+-blue?logo=python&logoColor=white)
[![CodeQL](https://github.com/skm248/vuln-checker/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/skm248/vuln-checker/actions/workflows/github-code-scanning/codeql)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**vuln-checker** is an enterprise-grade, high-performance CLI vulnerability scanner that maps software components to CVEs using local NVD feeds. It offers native offline scanning capabilities for packages, CycloneDX SBOMs, and server environments without requiring persistent internet connections or hitting API rate limits.

---

## 🌟 Key Features

*   **Offline NVD Mirroring**: Seamlessly downloads and mirrors NVD data feeds locally for lightning-fast, rate-limit-free offline scans.
*   **Multi-Mode Scan Capabilities**:
    *   **Server Scan (`--scan-server`)**: Discovers installed system packages (dpkg, rpm) and library ecosystems (pip, npm, maven) across your system.
    *   **Directory Scan (`--scan-dir SCAN_DIR`)**: Recursively audits a target directory, codebase, or offline installation folder for packages, lockfiles, and archives.
    *   **CycloneDX SBOM Parser (`--sbom`)**: Evaluates software components in CycloneDX-JSON formats with robust package URL (`purl`) matching.
    *   **Ad-Hoc Products (`--products`)**: Quick check for specific packages and versions directly via CLI.
    *   **Batch CSV Processing (`--input-csv`)**: Scans custom server inventories in bulk.
*   **Advanced Categorized Reporting (New)**:
    - **Multi-Tab HTML Dashboards**: Rich, responsive interface containing severity counts (Chart.js), real-time search, and interactive markdown descriptions.
    - **Multi-Sheet Excel Reports**: High-fidelity workbooks with auto-filters, bold headers, auto-wrap text, and clickable hyperlink references.
    - **Strict Deduplication**: Consolidates findings to list each issue exactly once with all detected paths merged.
    - **Conditional Layout Suppression**: Tabs and Excel sheets are created conditionally **only if** they contain relevant findings, keeping outputs pristine.
*   **False Positive Mitigation**: Suppress benign or non-applicable advisories using standard VEX (Vulnerability Exploitability eXchange) mappings or simple exclusion files (`excluded_cpes.txt`).

---

## 📂 Report Categorization Engine

All vulnerability findings are parsed and organized into five dedicated, mutually exclusive categories:

1.  **📦 Jars / War / Zip**: Java ecosystem archives, nested packages, and archive dependencies.
2.  **🟢 Npm Audit**: Node.js ecosystem packages (`node_modules`).
3.  **🔴 RetireJS**: Frontend JavaScript libraries and client-side assets.
4.  **🐍 Pip-Audit**: Python packages and virtual environment dependencies.
5.  **🐧 OS & System Packages**: Operating system level packages (Debian/RPM).

> [!NOTE]
> **Conditional Tab Suppression**: If a category has zero findings, it is automatically omitted from both HTML dashboards and Excel workbooks to avoid clutter.

---

## 🚀 Quick Start

### 1. Installation

Install the stable release via pip:
```bash
pip install vuln-checker
```

### 2. Mirror NVD Feeds (Required on first execution)
Download and mirror NVD data feeds locally (covers 2002 to present):
```bash
vuln-checker --update-feeds
```

### 3. Usage Examples

**Scan a Target Directory (e.g. Codebase or Installation Folder):**
```bash
vuln-checker --scan-dir /var/www/my_app --format html,excel --output reports/scan_report
```
*Recursively gathers nested libraries, manifests, and archives in `/var/www/my_app` and audits them against local feeds.*

**Full System Scan with Real-time Network Threat Mapping:**
```bash
vuln-checker --scan-server --fast-agent --format html --output reports/full_audit
```
*Scans all system packages and maps discovered vulnerabilities to active listening ports via Linux procfs.*

**Zero-Dependency Offline Scan (Bypass Syft):**
```bash
vuln-checker --scan-dir /opt/my_service --native-only --format html --output reports/native_scan
```
*Performs directory auditing using built-in, lightweight Python package collectors, ignoring external tools.*

**Scan a CycloneDX SBOM Document:**
```bash
vuln-checker --sbom sbom.json --fast --format html --output report.html
```

**Evaluate specific packages from CLI:**
```bash
vuln-checker --products "jquery:1.11.3 lodash:3.5.0" --severity High,Critical
```

---

## 🔧 CLI Options Reference

The scanner supports the following command-line flags, grouped by function:

### 🖥️ Scan Modes (Mutually Exclusive - choose one)
| Flag | Arguments | Description |
| :--- | :--- | :--- |
| `--scan-dir` | `<dir_path(s)>` | Recursively scans specific directories or mount points for packages, JARs, and manifests. |
| `--scan-server` | None | Scans the host system (Debian/RPM, python site-packages, npm, maven, etc.). |
| `--sbom` | `<file_path>` | Scans a CycloneDX SBOM JSON document. |
| `--products` | `"<name>:<ver> ..."` | Audits space-separated product name and version pairs directly from command line. |
| `--input-csv` | `<file_path>` | Scans a bulk list of products and versions from a CSV spreadsheet. |
| `--cpes-file` | `<file_path>` | Audits a list of raw CPE identifiers from a flat text file. |

### ⚙️ Performance & Advanced Controls
| Flag | Arguments | Description |
| :--- | :--- | :--- |
| `--native-only` | None | Bypasses all external analysis tools (like Syft/Retire.js) and runs native Python package collectors. |
| `--fast-agent` | None | Maps vulnerabilities to active listening ports and PIDs on the host system in real-time. |
| `--fast` | None | Enables fast mode using concurrent workers and cached results. |
| `--max-workers`| `<number>` | Number of concurrent workers to process findings. |
| `--baseline` | `<file_path>` | Compares current findings with a previous JSON report to generate a **Delta Report**. |
| `--vex-file` | `<file_path>` | Filters out false-positive CVEs by importing standard Vulnerability Exploitability eXchange (VEX) files. |

### 📂 Output & Customization
| Flag | Arguments | Description |
| :--- | :--- | :--- |
| `--format` | `json,csv,html,excel` | Comma-separated list of formats to generate (default: `json`). |
| `--output` | `<file_path>` | Prefix or output filename for the report. |
| `--severity` | `Low,Medium,High,Critical` | Filters findings by severity levels. |
| `--config` | `<file_path>` | Loads configuration values from a custom TOML config file. |
| `--log-level` | `DEBUG,INFO,WARNING,ERROR` | Controls terminal logging verbosity (default: `INFO`). |

### 🔄 Feed & Cache Management
| Flag | Arguments | Description |
| :--- | :--- | :--- |
| `--update-feeds` | None | Downloads and mirrors NVD JSON vulnerability feeds locally. |
| `--force-update` | None | Forces re-download of all feeds even if they are fresh. |
| `--feed-dir` | `<dir_path>` | Custom directory for local NVD feed files. |
| `--start-year` | `<year>` | Overrides default start year (2002) for NVD vulnerability feeds. |

---

## ⚙️ Configuration (`config.toml`)

Customize scan options, cache duration, worker threads, and paths using a local `config.toml` file:

```toml
[feeds]
feed_dir = "nvd_feeds"
start_year = 2002
max_age_hours = 24

[cache]
cache_file = "cve_cache.json"
enabled = true

[server_scan]
max_workers = 8

[output]
output_dir = "reports"
formats = ["json", "csv", "html", "excel"]
```

Run scans utilizing your custom config:
```bash
vuln-checker --config config.toml --scan-server
```

### Suppressing False Positives
You can suppress benign, non-applicable, or mis-mapped advisories using two local text files (looking first in the current working directory, then in the package's `data/` folder):

#### 1. Global CPE Exclusions (`excluded_cpes.txt`)
Populate it with target CPEs to suppress them entirely from reports. Supports prefix wildcard matching (`*`):
```text
# Ignore all vulnerabilities in a specific product
cpe:2.3:a:apache:commons-lang:*

# Ignore a specific library version
cpe:2.3:a:junit:junit:4.12
```

#### 2. Core Application Isolation (`core_apps.txt`)
To prevent client-side libraries (like `example-connector-java` or `my-client-library`) from matching core server/database CPEs (like `example_db:example_db` or `my-server:my-server`), add the server product name to this file. 
The package includes built-in defaults (`example_db`, `my-server`, etc.), but you can override or append additional apps:
```text
# Add one product name per line
custom-db
another-server
```

#### 3. Vulnerability Exploitability eXchange (VEX)
For complex suppression rules, use standard VEX files via the \--vex-file\ flag. You can use the provided templates as a reference:
*   [examples/vex_sample.json](examples/vex_sample.json) (Standard VEX format)
*   [examples/vex_simple_sample.json](examples/vex_simple_sample.json) (Simplified format)

---

## 📊 Report Formats

| Format | Features & Highlights |
| :--- | :--- |
| **HTML** | Dynamic HTML5 interactive dashboard, Chart.js pie charts, global/local DataTables filters, markdown parsing, and tabbed categories. |
| **Excel** | Multi-sheet auto-filtered workbook, formatted text-wrap, hyperlinked CVEs, and automatic descending severity sorting. |
| **CSV** | Streamlined flat CSV output utilizing standard `=HYPERLINK` formulas for NVD reference links. |
| **JSON** | Full structured JSON telemetry suited for CI/CD pipeline automation and ingestion. |

---

## 📋 Requirements
- Python **3.9** or newer
- Dependencies: `requests`, `packaging`, `jinja2`, `openpyxl`, `toml`, `tomli`, `tqdm`.

---

## ⚖️ License
Distributed under the MIT License. See `LICENSE` for details.

