CVE Sentinel

Your AI-Powered Vulnerability Detector

Automatically detect vulnerabilities in your dependencies before they are hacked.

Demo

📺 Watch full demo video

cveSentinel.mp4

Why CVE Sentinel?

Built for the AI-driven Era

Traditional vulnerability scanners run periodically in CI/CD pipelines — but AI-driven development moves faster. When you're building with Claude Code, new dependencies get added in real-time. CVE Sentinel provides always-on protection that activates the moment you start coding, catching vulnerabilities before they ever reach your repository.

Superior Coverage with Multi-Source Intelligence

Most scanners rely on a single vulnerability database. CVE Sentinel combines NVD (National Vulnerability Database) and Google OSV (Open Source Vulnerabilities) with intelligent filtering to deliver broader coverage without false positives:

Source	Strength
Google OSV	High precision, ecosystem-aware queries, faster updates
NVD	Broader coverage, detailed CVSS scores, comprehensive CVE data

Detection Comparison

Method	CVEs Detected	False Positives	Assessment
OSV Only	19	0	✓ High precision, limited coverage
NVD Only	115	98+	✗ Many false positives
CVE Sentinel (Combined)	38	0	✓ Best of both worlds

Tested on 5 popular packages: vite, express, lodash, axios, cypress

By combining both sources with CPE-based filtering and confidence scoring, CVE Sentinel achieves 2x detection coverage compared to OSV-only scanning while maintaining zero false positives.

Intelligent False Positive Filtering

Raw NVD keyword searches often return irrelevant results. CVE Sentinel filters them out automatically:

Package	False Match	Reason	Result
`cypress`	Cypress Semiconductor chips	Hardware vendor	❌ Filtered
`vite`	VITEC video encoders	Different product	❌ Filtered
`express`	ExpressVPN	Different product	❌ Filtered

How it works:

🔍 CPE Matching - Validates vendor/product names against known mappings
🏭 Hardware Exclusion - Blocks 20+ hardware vendors (Intel, Broadcom, etc.)
📊 Confidence Scoring - HIGH / MEDIUM / LOW ratings for each match
🔢 Version Validation - Checks if your version is actually affected

Key Features

Always-On Detection - Automatically scans when you start Claude Code sessions
Multi-Source Intelligence - NVD + Google OSV for maximum coverage
Smart Filtering - Eliminates false positives with CPE-based validation
7+ Languages - JavaScript, Python, Go, Java, Ruby, Rust, PHP and more
3 Analysis Levels - From quick manifest scans to deep source code analysis
Actionable Fixes - Get specific upgrade commands, not just vulnerability reports

Quick Start

Installation

# Install from PyPI
pip install cve-sentinel

# Or install from GitHub (latest development version)
pip install git+https://github.com/cawa102/cveSentinel.git

Scan Your Project

# Scan current directory
cve-sentinel scan

# Scan a specific directory
cve-sentinel scan /path/to/project

# Scan with options
cve-sentinel scan /path/to/project --level 2 --exclude node_modules --exclude .venv

No configuration file required - just run and scan!

Auto-scan with Claude Code (Optional)

Want CVE Sentinel to automatically scan every time you start Claude Code? See How to Work with Claude Code for setup instructions.

NVD API Key (Recommended)

For faster scanning, get a free API key from NVD:

export NVD_API_KEY=your-api-key-here

Without an API key, requests are rate-limited to 5 per 30 seconds.

How It Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Your Project   │────▶│  CVE Sentinel   │────▶│  Security Report│
│                 │     │                 │     │                 │
│ package.json    │     │ ┌─────────────┐ │     │ 3 Critical      │
│ requirements.txt│     │ │ NVD API 2.0 │ │     │ 5 High          │
│ go.mod          │     │ └─────────────┘ │     │ 2 Medium        │
│ Cargo.toml      │     │ ┌─────────────┐ │     │                 │
│ ...             │     │ │ Google OSV  │ │     │ + Fix Commands  │
│                 │     │ └─────────────┘ │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Supported Languages (Default)

Language	Package Managers	Files Analyzed
JavaScript	npm, yarn, pnpm	`package.json`, `package-lock.json`, `yarn.lock`
Python	pip, poetry, pipenv	`requirements.txt`, `pyproject.toml`, `Pipfile`
Go	go mod	`go.mod`, `go.sum`
Java	Maven, Gradle	`pom.xml`, `build.gradle`
Ruby	Bundler	`Gemfile`, `Gemfile.lock`
Rust	Cargo	`Cargo.toml`, `Cargo.lock`
PHP	Composer	`composer.json`, `composer.lock`

Analysis Levels

Choose the depth of analysis that fits your needs:

Level	What It Scans	Best For
1	Manifest files only	Quick CI checks
2	+ Lock files (transitive deps)	Regular development (default)
3	+ Source code imports	Pre-release audits

# Quick scan - manifest files only (Level 1)
cve-sentinel scan --level 1

# Standard scan - includes lock files (Level 2, default)
cve-sentinel scan

# Deep scan - includes source code analysis (Level 3)
cve-sentinel scan --level 3

# Scan specific directory with level
cve-sentinel scan /path/to/project --level 3

Usage

cve-sentinel scan [PATH] [OPTIONS]

Option	Description
`PATH`	Target directory to scan (default: current directory)
`--level`, `-l`	Analysis level: 1, 2, or 3 (default: 2)
`--exclude`, `-e`	Paths to exclude (can be specified multiple times)
`--verbose`, `-v`	Enable verbose output
`--fail-on`	Exit with error if vulnerabilities at or above this severity (default: HIGH)

Examples

# Basic scan
cve-sentinel scan

# Scan with exclusions
cve-sentinel scan --exclude node_modules --exclude dist

# CI/CD usage - fail on critical vulnerabilities only
cve-sentinel scan --fail-on CRITICAL

# Verbose deep scan
cve-sentinel scan /path/to/project --level 3 --verbose

Configuration (Optional)

For persistent settings, create .cve-sentinel.yaml in your project root:

# Scan settings
analysis_level: 2

# Exclude paths (e.g., test fixtures)
exclude:
  - node_modules/
  - vendor/
  - .venv/

# Cache settings
cache_ttl_hours: 24

# Auto-scan on Claude Code startup
auto_scan_on_startup: true

# Data sources configuration
datasources:
  osv_enabled: true       # High precision, ecosystem-aware
  nvd_enabled: true       # Broader coverage with filtering
  nvd_min_confidence: medium  # high, medium, or low
  prefer_osv: true        # Prefer OSV data when available from both

Confidence Levels

Level	Criteria	Included by Default
HIGH	Exact CPE match + ecosystem verified	✓ Yes
MEDIUM	CPE match or partial match + ecosystem	✓ Yes
LOW	Keyword match only	✗ No

CLI options override configuration file settings.

Custom File Patterns

Your unique projects sometimes use non-standard file names for their dependencies. CVE Sentinel lets you specify additional file patterns to scan:

# .cve-sentinel.yaml
custom_patterns:
  python:
    manifests:
      - "deps/*.txt"
      - "requirements-*.txt"
    locks:
      - "custom.lock"
  javascript:
    manifests:
      - "dependencies.json"

Supported Ecosystems

Config Key	Aliases	Default Files
`javascript`	`npm`	`package.json`, `package-lock.json`, `yarn.lock`
`python`	`pypi`	`requirements.txt`, `pyproject.toml`, `Pipfile`
`go`	-	`go.mod`, `go.sum`
`java`	`maven`, `gradle`	`pom.xml`, `build.gradle`
`ruby`	`rubygems`	`Gemfile`, `Gemfile.lock`
`rust`	`crates.io`	`Cargo.toml`, `Cargo.lock`
`php`	`packagist`	`composer.json`, `composer.lock`

Custom patterns extend the defaults - your standard files are always scanned.

How to Work with Claude Code

CVE Sentinel integrates with Claude Code as a SessionStart Hook. Once configured, it automatically scans your project for vulnerabilities every time you launch Claude Code.

Quick Setup (Recommended)

Run the install script to set up everything automatically:

# Clone the repository
git clone https://github.com/cawa102/cveSentinel.git
cd cveSentinel

# Run the installer
./scripts/install.sh

This script:

Installs the cve-sentinel package
Creates the hook script at ~/.claude/hooks/cve-sentinel-scan.sh
Configures Claude Code's ~/.claude/settings.json

Manual Setup

If you prefer manual configuration or already have cve-sentinel installed via pip:

Step 1: Create the hook script

Create ~/.claude/hooks/cve-sentinel-scan.sh:

#!/bin/bash
PROJECT_DIR="${1:-.}"

should_scan() {
    if [ -f "$PROJECT_DIR/.cve-sentinel.yaml" ]; then
        return 0
    fi
    for file in package.json requirements.txt pyproject.toml Gemfile Cargo.toml go.mod composer.json pom.xml build.gradle; do
        if [ -f "$PROJECT_DIR/$file" ]; then
            return 0
        fi
    done
    return 1
}

if should_scan; then
    nohup cve-sentinel scan --path "$PROJECT_DIR" > /dev/null 2>&1 &
fi

Make it executable:

chmod +x ~/.claude/hooks/cve-sentinel-scan.sh

Step 2: Configure Claude Code settings

Add the hook to ~/.claude/settings.json:

{
  "hooks": {
    "sessionStart": [
      {
        "name": "cve-sentinel",
        "command": "~/.claude/hooks/cve-sentinel-scan.sh",
        "args": ["${projectPath}"],
        "enabled": true
      }
    ]
  }
}

Project Configuration (Optional)

For project-specific settings, run in your project directory:

cve-sentinel init

This creates:

.cve-sentinel.yaml - Configuration file for custom settings
.cve-sentinel/ - Directory for scan results and cache

How It Works with Claude Code

Once configured:

Session Start - Hook triggers automatically when you launch Claude Code
Background Scan - CVE Sentinel scans dependencies without blocking your session
Results Available - Check .cve-sentinel/results.json for vulnerability details
Claude Assistance - Ask Claude to review results and help implement fixes

Sample Output

⚠ CVE Scan Complete: 73 vulnerabilities found

[CVE-2025-xxxxx] (Description)
Severity: 
Description: 
Affected Files: '/path/where/this/vuln/exists'
Fix:
...

Troubleshooting

API Rate Limiting

Error querying OSV for npm: OSV API bad request: {"code":3,"message":"Too many queries."}

Cause: Too many requests to OSV API in a short period.

Solution: The tool automatically retries with exponential backoff. For large projects, the scan may take longer. If errors persist, wait a few minutes and try again.

CVSS Score Parsing Error

could not convert string to float: 'CVSS:3.1/AV:N/AC:L/...'

Cause: Older version of CVE Sentinel. This was fixed in recent updates.

Solution: Update to the latest version:

pip install --upgrade cve-sentinel

Configuration Errors

Error	Cause	Solution
`analysis_level must be between 1 and 3`	Invalid analysis level	Use `--level 1`, `2`, or `3`
`target_path does not exist`	Invalid scan path	Check the path exists
`Failed to parse YAML config file`	Invalid YAML syntax	Check `.cve-sentinel.yaml` syntax

NVD API Errors

NVD API rate limit exceeded

Cause: NVD API has strict rate limits without an API key (5 requests per 30 seconds).

Solution: Get a free API key from NVD and set it:

export CVE_SENTINEL_NVD_API_KEY=your-api-key-here

Python Version Error

Package 'cve-sentinel' requires a different Python: 3.8.x not in '>=3.9'

Cause: Python version is too old.

Solution: Use Python 3.9 or later:

python3.9 -m pip install cve-sentinel

Development

# Clone and install
git clone https://github.com/cawa102/cveSentinel.git
cd cveSentinel
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check .

Contributing

Contributions are welcome! Whether it's:

Adding support for new languages
Improving vulnerability detection
Enhancing the user experience

Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

_{Built with security in mind. Powered by Claude Code.}

Name		Name	Last commit message	Last commit date
Latest commit History 58 Commits
.github		.github
assets		assets
cve_sentinel		cve_sentinel
docs		docs
scripts		scripts
templates		templates
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

CVE Sentinel

Demo

Why CVE Sentinel?

Built for the AI-driven Era

Superior Coverage with Multi-Source Intelligence

Detection Comparison

Intelligent False Positive Filtering

Key Features

Quick Start

Installation

Scan Your Project

Auto-scan with Claude Code (Optional)

NVD API Key (Recommended)

How It Works

Supported Languages (Default)

Analysis Levels

Usage

Examples

Configuration (Optional)

Confidence Levels

Custom File Patterns

Supported Ecosystems

How to Work with Claude Code

Quick Setup (Recommended)

Manual Setup

Step 1: Create the hook script

Step 2: Configure Claude Code settings

Project Configuration (Optional)

How It Works with Claude Code

Sample Output

Troubleshooting

API Rate Limiting

CVSS Score Parsing Error

Configuration Errors

NVD API Errors

Python Version Error

Development

Contributing

License

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages