vuln-checker

vuln-checker

✨🔍 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:

pip install vuln-checker

Or from GitHub:

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:

• Single Product via Command-Line:

     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.

• 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:

       vuln-checker --input-csv products.csv --format csv --output output.csv
    

  • Processes all product/version pairs from the CSV.

• Filter by Severity:

     vuln-checker --products "jquery:1.11.3,1.11.5" --severity critical,high --format json --output output.json
  

  • Filters CVEs with HIGH severity only.

• Specify Output File:

     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:

   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:

    vuln-checker --upgrade

This command will:

• Check the latest available version on PyPI.
• Compare it with your currently installed version.
• Only upgrade if a newer version is available.

To auto-confirm the upgrade (without a prompt), use the --yes flag:

    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:

# 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

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.

  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

• Exactly one of --input-csv or --products or --cpes-file or --sbom must be provided.
• 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.