cve-sentinel 0.1.2

CVE auto-detection and remediation proposal system for Claude Code

CVE Sentinel

Your AI-Powered Vulnerability Detector

Automatically detect vulnerabilities in your dependencies before they become threats.

---

Demo

https://github.com/user-attachments/assets/25634a88-8ed0-4da4-9b11-4e924ad87adf

---

Why CVE Sentinel?

Built for the AI Coding 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) to deliver broader coverage:

Source	Strength
NVD	Industry standard, detailed CVSS scores, comprehensive CVE data
Google OSV	Faster updates, ecosystem-specific advisories (npm, PyPI, Go, etc.)

By querying both sources, CVE Sentinel catches vulnerabilities that single-source tools miss.

Key Features

• Always-On Detection - Automatically scans when you start Claude Code sessions
• Multi-Source Intelligence - NVD + Google OSV for maximum coverage
• 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)

cve-sentinel init

This sets up a SessionStart Hook - CVE Sentinel will automatically scan your project every time you launch Claude Code.

---

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

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.

---

Claude Code Integration

CVE Sentinel is designed to work seamlessly with Claude Code. After running cve-sentinel init, it will:

1. Automatically scan your project when you start a Claude Code session
2. Report vulnerabilities directly in your conversation
3. Suggest fixes that Claude can help you implement

---

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.}