Skip to content
BranchesTags

Repository files navigation

🛡️ 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
  1. Create a Slack app using config/slack-manifest.yml
  2. Set environment variables: 
    export SLACK_SIGNING_SECRET=<signing-secret>
export SLACK_BOT_TOKEN=xoxb-<bot-token>
  3. Set slash command URL to https://<your-domain>/slack/commands
  4. Set events URL to https://<your-domain>/slack/events
  5. Use: /sentinel cve CVE-2024-3094 or @Sentinel cve CVE-2024-3094

Microsoft Teams Integration

sentinel setup teams   # Interactive setup guide
  1. Create an outgoing webhook in your Teams channel pointing to https://<your-domain>/teams/webhook
  2. Set environment variables: 
    export TEAMS_WEBHOOK_SECRET=<base64-hmac-secret>
  3. Mention the bot: @Sentinel cve CVE-2024-3094

Telegram Integration

sentinel setup telegram   # Interactive setup guide
  1. Create a bot via @BotFather
  2. Set environment variables: 
    export TELEGRAM_BOT_TOKEN=<bot-token>
  3. Set webhook: curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" -d '{"url":"https://<YOUR_DOMAIN>/telegram/webhook"}'
  4. Send commands: /cve CVE-2024-3094, /scan <repo> --cve CVE-XXXX

Docker Deployment

cd docker/
# Set env vars in .env file or export them
docker compose up -d

# With nginx reverse proxy:
docker compose --profile with-nginx up -d

Endpoints

Endpoint Method Description
/health GET Health check
/api/cve POST REST API — explain a CVE
/api/scan POST REST API — scan a repo
/slack/commands POST Slack slash commands
/slack/events POST Slack Events API
/teams/webhook POST Teams outgoing webhook
/telegram/webhook POST Telegram bot webhook

About

CLI tool that explains CVEs in plain English and scans repos for impact. Powered by Claude.

Resources

Readme
MIT license

Security policy

Security policy
Activity

Stars

20 stars

Watchers

1 watching

Forks

2 forks
Report repository

Releases

Packages

Contributors

Languages