🛡️ Sentinel — CVE Explainer CLI

"Does this CVE even affect me?" — answered in seconds, not hours.

Sentinel takes a CVE ID, fetches data from NVD, OSV.dev, and MITRE, then uses Claude to produce a clear, actionable 5-section vulnerability briefing.

Install

cd sentinel/
pip install -e .

Configure

# Required: Anthropic API key
sentinel config set api-key sk-ant-...

# Optional: NVD API key (higher rate limits)
sentinel config set nvd-key xxxxxxxx-xxxx-...

# Or use environment variables
export ANTHROPIC_API_KEY=sk-ant-...
export NVD_API_KEY=xxxxxxxx-xxxx-...

Usage

# Explain a CVE (5-section report with colored terminal output)
sentinel cve CVE-2024-3094

# Choose output persona (see Personas below)
sentinel cve CVE-2024-3094 --format exec       # Executive / CISO summary
sentinel cve CVE-2024-3094 -f engineer          # Deep technical advisory
sentinel cve CVE-2024-3094 -f devops            # Infrastructure-focused
sentinel cve CVE-2024-3094 -f security          # Default 5-section report

# Also works with scan
sentinel scan . --cve CVE-2024-3094 --format exec

# JSON output
sentinel cve CVE-2024-3094 --json

# Markdown output
sentinel cve CVE-2024-3094 --markdown

# Brief one-paragraph summary
sentinel cve CVE-2024-3094 --brief

# Skip cache, fetch fresh data
sentinel cve CVE-2024-3094 --no-cache

# Verbose mode (show timing and source details)
sentinel cve CVE-2024-3094 -v

Output Personas (--format / -f)

security (default) — Security Analyst

The classic 5-section vulnerability briefing:

Section	What it answers
🔍 What it is	Plain-English explanation
💥 How to exploit	Attack vector, PoC summary, difficulty
🚨 Who should panic	Affected software, versions, ecosystems
🛡️ How to patch safely	Remediation steps, patch links
✅ What to test	Verification steps after patching

exec — Executive / CISO

A 10-second read for busy executives. Traffic light severity, business impact, one action item. No jargon.

🔴 CRITICAL — CVE-2024-3094 (XZ Backdoor)

A backdoor was planted in a core Linux compression library used across most servers.
Attackers can intercept and modify data on any system running xz 5.6.0-5.6.1.
Immediate downgrade required — estimated 15-30 min per server, no downtime expected.

Risk: Supply chain compromise — high severity, active exploitation
Impact: All Linux infrastructure running affected versions
Action needed: Downgrade xz to 5.4.6. Verify with `xz --version`.

engineer — Software Engineer

Deep technical dive with exact versions, upgrade commands, grep patterns, and test steps:

Section	Focus
📦 Affected Libraries & Versions	Exact version ranges, dependency chains
🔧 Code-Level Remediation	Specific upgrade commands, config changes
🔍 What to Grep For	Patterns to search your codebase
🧪 How to Test the Fix	Verification commands, regression tests
⚠️ Breaking Changes	Deprecations, behavioral differences

devops — DevOps / SRE

Infrastructure-focused with containers, K8s, CI/CD, and monitoring:

Section	Focus
🏗️ Affected Infrastructure	Base images, containers, cloud services
🚀 Deployment Impact	Rolling update strategy, downtime assessment
🔄 Rollback Plan	How to revert if the patch causes issues
📊 Monitoring & Detection	Logs, alerts, exploitation detection
🚨 Incident Response Steps	Step-by-step if actively exploited

Mobile SDK Scanning

Sentinel detects dependencies in mobile app build configs that standard scanners miss:

Ecosystem	Files Parsed	Lock File (preferred)
Android (Gradle)	build.gradle, build.gradle.kts, gradle/libs.versions.toml	—
iOS (CocoaPods)	Podfile	Podfile.lock
iOS (Swift PM)	Package.swift	Package.resolved
Flutter (Dart)	pubspec.yaml	pubspec.lock

# Scan an Android project
sentinel scan ./my-android-app --cve CVE-2024-XXXX

# Scan an iOS project
sentinel scan ./my-ios-app --cve CVE-2024-XXXX

# Scan a Flutter project
sentinel scan ./my-flutter-app

Features:

• Resolves Gradle variable references ($firebaseBomVersion) from gradle.properties and ext {} blocks
• Parses Gradle version catalogs (libs.versions.toml)
• Handles CocoaPods subspecs (Firebase/Analytics)
• Prefers lock files over manifests for accurate resolved versions
• Supports both Groovy and Kotlin DSL Gradle files

K8s Runtime BOM Scanner

Scan your Kubernetes cluster for vulnerable container images:

# Scan all namespaces
sentinel scan --k8s

# Scan specific namespace
sentinel scan --k8s --namespace production

# Check specific CVE across cluster
sentinel scan --k8s --cve CVE-2024-3094

# Generate SBOM for all running images
sentinel scan --k8s --sbom

# Scan a specific image (no cluster connection needed)
sentinel scan --k8s --image nginx:1.25

K8s RBAC Setup

Sentinel needs read-only access. Apply the minimal RBAC manifest:

kubectl apply -f config/k8s-rbac.yaml

This creates a sentinel-readonly ServiceAccount with only get and list on pods, namespaces, deployments, replicasets, daemonsets, and statefulsets. No write access.

Execution Path Analysis

Determine if a CVE actually affects your code by tracing whether vulnerable functions are reachable from entry points:

# Full analysis with Claude interpretation
sentinel scan . --cve CVE-2024-22195 --execution-path

# Local-only (no data sent externally)
sentinel scan . --cve CVE-2024-22195 --execution-path --local-only

Verdicts:

• 🔴 REACHABLE — entry point → ... → vulnerable function call found
• ✅ NOT_REACHABLE — vulnerable package imported but vulnerable function never called
• 🟡 IMPORTED_ONLY — package is a dependency but never directly imported in source
• 🟠 INCONCLUSIVE — dynamic dispatch, reflection, or complex patterns detected

Security: What data leaves your environment?

Mode	Data sent externally
--local-only	Nothing — pure local AST analysis
Default	Only sanitized metadata: function names, import names, call graph edges (node/edge list), CVE description. Never source code.

All data sent to Claude is logged to ~/.sentinel/audit.log for review.

Cache Management

sentinel cache clear    # Clear all cached data

Config

Config stored at ~/.sentinel/config.json. Cache at ~/.sentinel/cache.db.

sentinel config set api-key <key>
sentinel config set nvd-key <key>
sentinel config set model <model-name>
sentinel config get api-key

🌐 Webhook Server & Integrations

Sentinel includes a FastAPI server that accepts commands from Slack, Microsoft Teams, Telegram, and a generic REST API.

Start the Server

sentinel server start                    # Default port 8080
sentinel server start --port 9090        # Custom port
sentinel server start --workers 4        # Multiple workers
sentinel server status                   # Check if running

REST API

# Explain a CVE
curl -X POST http://localhost:8080/api/cve \
  -H "Content-Type: application/json" \
  -d '{"cve_id": "CVE-2024-3094"}'

# Scan a repo
curl -X POST http://localhost:8080/api/scan \
  -H "Content-Type: application/json" \
  -d '{"repo_url": "https://github.com/user/repo", "cve_id": "CVE-2024-3094"}'

# Health check
curl http://localhost:8080/health

Slack Integration

sentinel setup slack   # Interactive setup guide