🛡️ 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:

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

`devops` — DevOps / SRE

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

Mobile SDK Scanning

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

# 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

Create a Slack app using config/slack-manifest.yml

Set environment variables:

export SLACK_SIGNING_SECRET=<signing-secret>
export SLACK_BOT_TOKEN=xoxb-<bot-token>

Set slash command URL to https://<your-domain>/slack/commands
Set events URL to https://<your-domain>/slack/events
Use: /sentinel cve CVE-2024-3094 or @Sentinel cve CVE-2024-3094

Microsoft Teams Integration

sentinel setup teams   # Interactive setup guide

Create an outgoing webhook in your Teams channel pointing to https://<your-domain>/teams/webhook