vuln-checker 0.5.5
CLI tool to fetch CVEs using NVD Feeds
Requires Python: >=3.7
Keywords: cve, vulnerability, cli, security, nvd, cpe

# vuln-checker

[![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.11.0-blue)
[![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)
[![GitHub stars](https://img.shields.io/github/stars/skm248/vuln-checker?style=social)](https://github.com/skm248/vuln-checker/stargazers)

> ✨🔍 vuln-checker: Search CVEs by CPE product/version with Enhanced SBOM Support

---

## Features

- **Uses local NVD JSON feeds** to avoid external API dependency and speed up scanning.  
- **Auto-updates vulnerability feeds** automatically if older than 24 hours to ensure fresh data for detection.  
- **Parses CycloneDX-JSON SBOMs** generated by popular tools (e.g., Syft) to identify vulnerable components effectively.  
- **Fetches matching CPEs** (Common Platform Enumerations) using product names and version details for precise vulnerability mapping.  
- **Batch mode support** allowing scanning of multiple product-version pairs via CSV input for large scale assessments.  
- **Flexible export formats:** JSON, CSV, Excel (XLSX), and HTML reports with detailed vulnerability data.  
- **Fast scanning mode** using optimized algorithms to reduce analysis time while maintaining accuracy.  
- **Parallel processing** with configurable concurrency (`--max-workers`) to handle multiple scans efficiently.  
- **Command-line friendly** enabling seamless integration into CI/CD pipelines and automated workflows.  
- **Self-updating mechanism** via standard Python package management (`pip install --upgrade vuln-checker`) to stay current with latest vulnerability data and features.  
- **Detailed vulnerability reports** including CVE details, severity levels, and remediation recommendations to assist prioritization.  
- **Cross-platform support** compatible with major OSes (Linux, macOS, Windows) where Python and dependencies are supported.
- **Supports excluding false-positive CPEs** via an external excluded_cpes.txt file placed alongside the main script.

---

## Installation

**Install via pip:**

```bash
pip install vuln-checker
```

**Or from GitHub:**

```bash
git clone https://github.com/skm248/vuln-checker.git
cd vuln_checker
pip install -r requirements.txt
pip install .
```

## Usage
#### Command-Line Options

Run `vuln-checker --help` to see the full, current set of options. Selected and notable flags implemented in `vuln_checker/main.py`:

- `--input-csv` : Path to CSV file with product/version rows (mutually exclusive with `--products`, `--cpes-file`, `--sbom`).
- `--products` : Product/version mapping string (e.g. `jquery:1.11.3,1.11.5 lodash:3.5.0`).
- `--cpes-file` : File with one CPE per line to look up directly.
- `--sbom` : Path to a CycloneDX SBOM (JSON).
- `--fast` : Enable faster parallel processing using caching.
- `--max-workers` : Number of parallel workers (default: 5).
- `--max-components` : Limit number of components processed (useful for quick runs).
- `--skip-search` : Skip components without existing CPEs.
- `--update-feeds` : Force download of latest NVD JSON feeds (see `nvd_feeds/`).
- `--force-update` : When used with `--update-feeds`, forces re-download even if feeds are fresh.
- `--feed-dir` : Directory containing NVD feeds (default: `nvd_feeds`).
- `--cache-file` : Path to the CVE cache file (default: `cve_cache.json`).
- `--no-clear-cache` : Prevent clearing the CVE cache when running.
- `--migrate-cache` : Attempt to migrate/normalize an existing cache file.
- `--severity` : Comma-separated severity filter (e.g. `Critical,High`).
- `--format` : Output format (`json`, `csv`, `html`, `excel`). Default: `json`.
- `--output` : Output filename for reports.
- `--upgrade` : Check PyPI for a newer `vuln-checker` version and, if available, start an upgrade process.
- `--yes` : Auto-confirm interactive prompts (used by `--upgrade` to skip the confirmation prompt).
- `--version` : Print the tool version and exit.

**Notes** on `--upgrade` behavior:
- When `--upgrade` is used the tool checks PyPI for the latest release. If a newer version exists, it prints the version and prompts to upgrade (unless `--yes` is passed).
- Upgrade implementation spawns a detached background Python subprocess that runs `pip install --upgrade --force-reinstall --no-cache-dir --user vuln-checker` using the same Python executable; the tool exits after starting the background process. The upgrade will only proceed if the package is installed via pip (it will skip otherwise).

---

**Examples:**
1. Single Product via Command-Line:
   ```bash
      vuln-checker --products "jquery:1.11.3,1.11.5 lodash:3.5.0" --format html --output custom_report.html
   ```
      - Fetches CVEs for multiple products/versions provided as a comma-separated list.

2. Batch Processing with CSV: 
     - Create a products.csv file with the following format:

          products,versions\
          jquery,1.11.3,1.11.5\
          lodash,3.5.0
     - Run:
       ```bash
          vuln-checker --input-csv products.csv --format csv --output output.csv
       ```
     -  Processes all product/version pairs from the CSV.

3. Filter by Severity: 
   ```bash
      vuln-checker --products "jquery:1.11.3,1.11.5" --severity critical,high --format json --output output.json
   ```
    -   Filters CVEs with HIGH severity only.

4.	Specify Output File: 
    ```bash
       vuln-checker --input-csv products.csv --format html --output custom_report.html
    ```
    -   Saves the report to a custom file name.


## 📦 New Features
**--version**

You can now check the current installed version of the vuln-checker tool using:

   ```bash
      vuln-checker --version
   ```
   - This fetches the version directly from the pyproject.toml file, ensuring consistency with your package metadata.

**--upgrade**
Easily upgrade to the latest version of vuln-checker from PyPI using:

  ```bash
      vuln-checker --upgrade
  ```

This command will:
1. Check the latest available version on PyPI.
2. Compare it with your currently installed version.
3. Only upgrade if a newer version is available.

To auto-confirm the upgrade (without a prompt), use the --yes flag:

  ```bash
      vuln-checker --upgrade --yes
  ```
⚠️ If you already have the latest version installed, the tool will skip the upgrade.

## Excluded CPEs Configuration

This tool supports **excluding specific CPE entries** from vulnerability scans to help reduce false positives.

Excluded CPEs must be listed (one per line) in a plain text file named **`excluded_cpes.txt`**, located in the **same directory** as `main.py`.

At startup, the tool automatically loads this file and ignores any CVEs linked to the listed CPEs.

---

**Example:**

```text
# Exclude old Netty CPEs due to false positives
cpe:2.3:a:netty:netty:1.2.10:*:*:*:*:*:*:*
```
## File Format

- Each line in `excluded_cpes.txt` should contain **one full CPE string**.
- Lines starting with `#` are treated as **comments** and ignored.
- Blank lines are also ignored.
- The file must be saved in **plain text format**.

## 📦 vuln-checker Data Storage and Logging Overview

The **vuln-checker** tool automatically manages its own data files, NVD feed cache, and logs.  
All files are created and stored in **the directory where the tool is executed**, allowing you to run it from any location without changing your setup.

---

### 🚀 Running the Tool

You can run **vuln-checker** from **any folder**.  
All generated data (cache, NVD feeds, and logs) will be stored in that same folder.

### Example

```bash
cd /home/user/<User_Workspace>
vuln-checker
```

After running, you’ll see several new files and directories created in /home/user/\<User_Workspace>.

### 🗂️ Generated Files and Directories
-----------------------------------

### **1\. cve\_cache.json**

*   **Location:** cve\_cache.json    
*   **Purpose:** Stores locally cached CVE data for faster lookups during future runs.    
*   **Behavior:**    
    *   Created automatically on the first run.        
    *   Updated or reused between runs to improve performance.        
    *   Can be deleted anytime to rebuild a fresh cache.        

### **2\. nvd\_feed/**

*   **Location:** ./nvd\_feeds/    
*   **Purpose:** Contains downloaded **National Vulnerability Database (NVD)** JSON feeds used for vulnerability lookups.

    ```bash 
    nvdcve-1.1-2002.json.gz
    nvdcve-1.1-2003.json.gz
    ...
    nvdcve-1.1-2025.json.gz
    ```    
*   **Behavior:**    
    *   The tool downloads these feeds automatically if missing.        
    *   Feeds are kept locally to avoid re-downloading each time.        
    *   Updated periodically to reflect the latest vulnerability data.        

### **3\. logs/vuln-checker.log**

*   **Location:** vuln-checker.log    
*   **Purpose:** Stores detailed runtime logs for every execution, including loaded feeds, processing steps, and warnings.    
*   **Behavior:**
    
    *   Automatically created if not found.        
    *   Each run appends new entries.        
    *   Helpful for troubleshooting, monitoring updates, and verifying scan operations.        

#### Example Log Output:

    [2025-10-17 14:23:11] INFO: NVD feeds loaded (2002–2025)
    [2025-10-17 14:23:14] INFO: Cache file cve_cache.json loaded successfully
    [2025-10-17 14:23:20] INFO: Scan completed — 0 vulnerabilities found   `

To view logs:
`  cat logs/vuln-checker.log   `

or open the file directly in your preferred text editor.

### 🧠 Tips
-------

*   You can **run vuln-checker from any location** — all output stays in the same folder.
*   Check **vuln-checker.log** for clear details on what happened during a scan.
*   Automatically **cve_cache.json** will get updated untill you use --no-clear-cache to not delete.
*   Auto-updates feeds in the **nvd_feeds** folder if older than 24 hours.


#### Final Arguments
    --input-csv INPUT_CSV               CSV file of products and versions
    --products PRODUCTS                 Products and versions string
    --cpes-file CPES_FILE               Path to file of CPEs
    --sbom SBOM                         Path to CycloneDX SBOM file (JSON)
    --fast                              Fast mode: parallel processing with caching
    --max-workers MAX_WORKERS           Number of parallel workers
    --max-components MAX_COMPONENTS     Limit number of components to process
    --skip-search                       Skip components without existing CPEs
    --update-feeds                      Download the latest NVD JSON feeds
    --force-update                      Force re-download all feeds even if fresh
    --feed-dir FEED_DIR                 Directory for NVD feeds (default: nvd_feeds)
    --cache-file CACHE_FILE             CVE cache file location
    --no-clear-cache                    Prevent clearing the CVE cache
    --migrate-cache                     Migrate and normalize existing CVE cache
    --severity SEVERITY                 Severity filter (comma separated)
    --format                            json,csv,html,excel
    --output OUTPUT                     Report output filename
    --upgrade                           Upgrade vuln-checker
    --yes                               Auto-confirm prompts
    --version                           show program's version number and exit

### Notes
1. Exactly one of --input-csv or --products or --cpes-file or --sbom must be provided.
2. Hyperlinks in CSV are formatted as Excel =HYPERLINK formulas, and in JSON as a dictionary with url and value fields.
____

### MIT License

Copyright (c) 2025 skm248

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.