sentinelpulse 0.1.0

🛰️ A CVE drops at 2 AM. By 2:15 your agent has mapped the planet, found your exposure, alerted your team and drafted the patch.

SentinelPulse is an open-source, terminal-first CVE first-responder. It has its own local memory of vulnerabilities (a RAG "brain"), watches for new disclosures, checks them against your servers and tech stack, and writes the remediation files before you've finished your coffee.

Why • Features • Install • Quick start • Configuration • Guide • Commands • Privacy • FAQ

_{The world map watching global exposure to a CVE drain away hour by hour as the world patches (simulated demo data, see docs/make_demo_gif.py).}

pip install sentinelpulse

💡 Why this exists

A new CVE disclosure is a global race condition. The moment it's published, the internet turns into a leaderboard: attackers mass-scan for vulnerable systems, defenders scramble to patch, and whoever moves first wins. Humans usually find out the next morning. Bots find out in seconds.

SentinelPulse puts you on the fast side of that race:

1. 🧠 It remembers every CVE it has seen, enriched with real exploitation signals (CISA KEV, EPSS).
2. 👁️ It watches NVD around the clock and spots new disclosures within one poll interval.
3. 🎯 It checks your world first: your saved hosts and the tech stack they actually run.
4. 🌐 It maps the global blast radius: how many systems worldwide are exposed, and where.
5. 📣 It alerts you on Slack, Discord or email the moment something hits your stack.
6. 🔧 It drafts the fix: Dockerfile, Ansible playbook, WAF virtual patch and Kubernetes guardrail.

It's not a scanner. It's a CVE first-responder that lives in your terminal.

✨ Features at a glance

📸 See it in action

All screenshots below are real output from the CLI, regenerated with docs/make_screenshots.py.

🛰️ Radar: one CVE, from intel to world map to patch files

The exposure map here is simulated because no Shodan/Censys/FOFA keys were configured. The CLI labels this clearly. With keys, the counts are live.

🎯 Your hosts: passive banner analysis, matched to the CVE

scanme.nmap.org is the host the Nmap project provides for scan testing.

🔍 Stack auto-discovery + asset inventory

🧠 The RAG brain: ingest, stats and top risks

🏗️ How it works

flowchart LR
    NEW([🚨 New CVE on NVD]) --> WATCH{{👁️ watch mode}}
    USER([👩‍💻 you]) --> RADAR{{🛰️ radar}}
    WATCH --> RADAR

    subgraph INTEL [Free public intel feeds]
      NVD[NVD 2.0 API] & KEV[CISA KEV catalog] & EPSS[FIRST EPSS]
    end
    INTEL --> BRAIN[(🧠 RAG brain<br/>SQLite + FTS5<br/>~/.sentinelpulse/brain.db)]

    subgraph ASSETS [Your inventory]
      HOSTS[saved hosts] & STACK[tech stack]
    end
    HOSTS -- 🔍 auto-discovery --> STACK

    RADAR --> BRAIN
    RADAR --> WW[🌐 Worldwide exposure<br/>Shodan · Censys · FOFA]
    RADAR --> TGT[🎯 Passive banner analysis]
    ASSETS --> TGT
    ASSETS --> MATCH{hits your stack?}
    BRAIN --> MATCH

    BRAIN & WW & TGT --> LLM[🤖 AI briefing<br/>BYOK / claude-code]
    LLM --> PATCH[🔧 Patch artifacts<br/>Docker · Ansible · WAF · K8s]
    MATCH -- yes --> ALERT[📣 Slack · Discord · Email]

The pipeline for every CVE:

recall from brain (or fetch live) ─▶ match your stack ─▶ world exposure map ─▶ scan your hosts
                                  ─▶ AI briefing (optional) ─▶ patch files (optional) ─▶ alerts (watch)

Data sources

📋 Requirements

🚀 Installation

Option A: from PyPI (one command)

pip install sentinelpulse            # or: pipx install sentinelpulse

Tip: use a virtual environment (python3 -m venv .venv && source .venv/bin/activate) or pipx so SentinelPulse's dependencies stay separate from your system Python.

Option B: from source (to hack on it)

git clone https://github.com/sriroopchakraborty1991-lang/sentinelpulse.git
cd sentinelpulse

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -e ".[dev]"

Upgrade / uninstall

pip install --upgrade sentinelpulse
pip uninstall sentinelpulse          # your brain + config in ~/.sentinelpulse stay untouched

Verify

sentinelpulse version              # → SentinelPulse v0.1.0
sentinelpulse --help
spulse --help                      # short alias, same CLI

⚡ Quick start (5 minutes)

# 1. Create your config file (all keys optional)
sentinelpulse config init

# 2. Feed the brain the last 3 days of CVEs (free feeds, no keys)
sentinelpulse brain ingest --days 3

# 3. Radar a famous CVE: intel, world map, patch files
sentinelpulse radar --cve CVE-2021-44228 --auto-patch

# 4. Tell it what you own (hosts you're authorised to assess)
sentinelpulse assets add-host mycompany.com
sentinelpulse assets discover          # fills your tech stack from banners
sentinelpulse assets add-tech log4j 2.14.1   # add anything banners can't show

# 5. Arm the 24/7 first-responder
sentinelpulse radar --watch --discover --auto-patch

That's it. Steps 1–3 work with zero API keys.

⚙️ Configuration

SentinelPulse reads settings from environment variables first, then from ~/.sentinelpulse/config.toml. Run sentinelpulse config init to create the file, and sentinelpulse config show to see what's set up (values are never printed).

[intel]
nvd_api_key = ""               # optional: faster NVD ingestion

[shodan]
api_key = ""                   # worldwide exposure

[censys]
api_id = ""                    # worldwide exposure (Search API v2 credentials)
api_secret = ""

[fofa]
email = ""                     # worldwide exposure
key = ""

[llm]
openai_api_key = ""            # --llm byok-openai
anthropic_api_key = ""         # --llm byok-anthropic
deepseek_api_key = ""          # --llm byok-deepseek

[alerts]
slack_webhook_url = ""         # Slack incoming webhook
discord_webhook_url = ""       # Discord channel webhook
email_to = "you@example.com, oncall@example.com"
email_from = "sentinelpulse@example.com"

[smtp]
host = "smtp.gmail.com"        # any SMTP provider
port = 587
user = "you@gmail.com"
password = "your-app-password"
security = "starttls"          # starttls (587) | ssl (465) | none

Environment variables & where to get each key

🔐 Keep config.toml private (chmod 600 ~/.sentinelpulse/config.toml) and never commit it.

📖 Feature guide

🛰️ Radar: race the world on one CVE

sentinelpulse radar --cve CVE-2021-44228                          # intel + world map
sentinelpulse radar --cve CVE-2021-44228 --target mycompany.com    # + your host
sentinelpulse radar --cve CVE-2021-44228 --auto-patch --llm byok-anthropic

If the CVE isn't in the brain yet, radar fetches it live from NVD/KEV/EPSS and remembers it forever. Use --static for a non-animated map (handy for logs and CI) and --no-banner to skip the logo.

🧠 The RAG brain

sentinelpulse brain ingest --days 7 --max 500    # last week of CVE activity
sentinelpulse brain stats                        # what it remembers
sentinelpulse brain query "apache log4j jndi"    # full-text search
sentinelpulse brain top --kev                    # most dangerous, actively exploited
sentinelpulse brain recall CVE-2023-38408        # one CVE (fetched live on a miss)

The brain is a single SQLite file (~/.sentinelpulse/brain.db) with an FTS5 full-text index. Results are ranked by EPSS then CVSS. It also stores your asset inventory and the watch-mode poll position, so back up or copy this one file to move SentinelPulse to another machine.

🌐 Worldwide exposure

With any of the Shodan / Censys / FOFA keys set, radar asks each provider for the CVE's exposed-host count by country. It merges them (taking the highest count per country, so nothing is double-counted) and draws a world map:

◉ hot zone · ◍ elevated · ● present · · land

These are lookups in each provider's existing data. SentinelPulse never contacts the exposed hosts. With no keys, the map uses a clearly labelled simulated distribution so the radar still runs.

🎯 Targeted passive analysis

sentinelpulse scan mycompany.com

It connects to 13 common service ports (21, 22, 25, 80, 110, 143, 443, 3306, 5432, 6379, 8080, 8443, 9200), reads only what each service volunteers (HTTP Server / X-Powered-By headers, SSH/FTP/SMTP greetings), extracts product + version, and matches them against the brain.

🗂️ Asset inventory

sentinelpulse assets add-host mycompany.com api.mycompany.com
sentinelpulse assets add-tech nginx 1.18.0
sentinelpulse assets add-tech "http server"      # multi-word names work
sentinelpulse assets list
sentinelpulse assets check                        # CVEs in memory that hit your stack
sentinelpulse assets remove nginx

Once saved, every radar run shows a 🎯 HITS YOUR STACK line and flags it when your exact version is named in the advisory. Saved hosts are scanned automatically (no --target needed). A "hit by this CVE?" column shows which of your services are affected. Use --no-assets to ignore the inventory.

🔍 Stack auto-discovery

sentinelpulse assets discover                  # all saved hosts
sentinelpulse assets discover new-host.io      # scan + save a new host
sentinelpulse assets discover --dry-run        # preview, change nothing
sentinelpulse radar --cve CVE-... --discover   # refresh stack first

• Picks up several products from one banner (Apache/2.4.52 (Ubuntu); PHP/8.1.2 → two entries).
• Converts banner names to the names NVD uses (Apache → apache http server, Microsoft-IIS → iis).
• Never overwrites what you typed. Manual entries show as kept-yours. Discovered entries update when the version changes.
• CDN / edge fronts (Cloudflare, CloudFront, Fastly, BunnyCDN…) are reported but not saved, since they hide the real software behind them.
• assets list shows where every entry came from: manual or discovered:<host>.

👁️ Live watch mode

sentinelpulse radar --watch --discover --auto-patch --interval 300
sentinelpulse radar --watch --min-cvss 9 --keyword "openssl,nginx"

Every --interval seconds it fetches CVEs published since the last poll. It saves them all to the brain with KEV + EPSS scores, then runs the full pipeline on the matching ones, highest-risk first. With a saved stack, only CVEs that hit your stack fire (--all-cves to fire on everything). The poll position is saved, so after a restart it carries on without repeat alerts. Ctrl+C stops it cleanly.

💡 Brand-new CVEs often have no CVSS score yet ("awaiting analysis"). Prefer --keyword or your saved stack over a high --min-cvss so you don't miss day-zero entries.

📣 Watch alerts

Configure any of Slack, Discord or SMTP email (see Configuration), then:

sentinelpulse alerts test          # sample alert to every configured channel
sentinelpulse alerts test -c email # one channel

Each alert contains the CVE, CVSS and severity, EPSS, CISA KEV status, your affected technologies (and whether your version is named), your affected hosts, the patch folder (with --auto-patch) and an NVD link. Slack gets formatted blocks, Discord a colour-coded embed, and email a text + HTML message.

• 🌊 Flood-proof: at most --max-alerts individual alerts per poll. Extra hits go into one summary.
• 🧯 Fail-safe: if one channel is down, the others still send and watch keeps running.

🔧 Patch artifacts

--auto-patch writes a bundle to ./sentinel-patches/<CVE-ID>/ in your current directory:

⚠️ These are review-first templates with placeholder versions (REPLACE_WITH_FIXED_VERSION). Fill in the fixed release from the vendor advisory. Nothing is applied or deployed automatically.

🤖 AI reasoning (bring your own LLM)

Use --model <name> to pick any model your provider offers (recommended if a default has been retired). The AI produces a defensive remediation briefing (it is instructed never to produce exploit code). The briefing is shown in the terminal and saved into REMEDIATION.md. No key? The AI step is skipped and everything else still runs.

🕰️ Running watch mode 24/7

[Unit]
Description=SentinelPulse watch mode
After=network-online.target
Wants=network-online.target

[Service]
WorkingDirectory=%h/sentinelpulse-work
ExecStart=%h/sentinelpulse/.venv/bin/sentinelpulse radar --watch --discover --auto-patch --static --no-banner
Restart=on-failure
RestartSec=30

[Install]
WantedBy=default.target

mkdir -p ~/sentinelpulse-work
systemctl --user daemon-reload
systemctl --user enable --now sentinelpulse
journalctl --user -u sentinelpulse -f        # live logs
loginctl enable-linger $USER                 # keep running after logout

tmux new -s sentinel 'sentinelpulse radar --watch --discover --auto-patch'
# or
nohup sentinelpulse radar --watch --discover --static --no-banner > sentinel.log 2>&1 &

🗂️ Command reference

sentinelpulse radar   --cve <id> [--scope auto|global|target|both] [--target <host>]
                      [--llm <provider>] [--model <name>] [--auto-patch] [--static] [--no-banner]
                      [--discover] [--assets/--no-assets]
sentinelpulse radar   --watch [--interval 300] [--lookback 60] [--min-cvss 0] [--keyword a,b]
                      [--max-per-cycle 5] [--max-cycles 0] [--all-cves] [--discover]
                      [--alert auto|none|slack,discord,email] [--max-alerts 10] [...radar flags]
sentinelpulse scan    <host> [--ingest]
sentinelpulse brain   ingest [--days 3] [--max 300] | recall <cve> | query <text> [-n 8]
                      | top [--kev] [-n 10] | stats
sentinelpulse assets  add-host <host...> | add-tech <name> [version] | remove <name>
                      | list | check [-n 15] | discover [host...] [--dry-run] [--no-save-hosts]
sentinelpulse alerts  test [-c auto|slack|discord|email]
sentinelpulse config  init | show
sentinelpulse version

Every command has --help. spulse is a short alias for sentinelpulse.

🔐 Data & privacy: what leaves your machine

SentinelPulse has no backend, no telemetry and no account. Everything is stored locally in ~/.sentinelpulse/. Network traffic only goes where you point it:

🛡️ Scope, safety & legal

SentinelPulse is a defensive tool built for blue teams, SREs and security researchers.

• ✅ Worldwide mode only looks up existing data in third-party databases. It never touches the hosts it counts.
• ✅ Targeted mode is passive: it reads banners that services publish to every visitor. No exploitation, no fuzzing, no payloads, no brute force.
• ✅ Patches are review-first files. Nothing is applied, deployed or pushed automatically.
• ⚠️ Only scan systems you own or are explicitly authorised to assess. Even passive connections may break an acceptable-use policy or local law. scanme.nmap.org is a safe public test target.
• ⚠️ Respect the terms of service of NVD, Shodan, Censys, FOFA and your LLM provider.

🧪 Honest limitations

• Simulated map without keys. The world map uses a demo distribution unless Shodan, Censys or FOFA keys are set. It is always labelled [simulated].
• Name matching, not version ranges. "Hits your stack" means the CVE names your technology. It doesn't prove your exact version is in the affected range. Always confirm in the advisory (the version named flag helps).
• Banners can lie or hide. Hardened servers often show no version, and CDNs hide the origin. Treat discovery as a head start.
• NVD rate limits. Without NVD_API_KEY, NVD allows about 5 requests per 30 seconds, so big ingests are slow (the CLI waits automatically).
• Provider plans. Shodan's vuln: filter and FOFA's stats API need paid plans. Censys uses the Search API v2 (API ID + secret).
• Targeted scan speed. Closed or filtered ports wait for a timeout, so a full scan can take up to about a minute per host.
• AI defaults age. Model names get retired. Pass --model if your provider rejects a default.

🧭 Project structure

sentinelpulse/
├── cli.py              # Typer CLI: radar, watch, brain, scan, assets, alerts, config
├── banner.py           # gradient ASCII launch logo
├── console.py          # Rich theme + severity colours
├── config.py           # env + config.toml loading (BYOK)
├── worldmap.py         # ASCII world map + hotspots
├── alerts.py           # Slack / Discord / SMTP alerts, summary roll-up
├── intel/              # nvd.py · kev.py · epss.py (live feeds)
├── rag/                # store.py (SQLite+FTS5) · ingest.py · brain.py (retrieval, stack matching)
├── scan/               # worldwide.py · targeted.py (banners) · discover.py (auto-discovery)
├── patch/generators.py # Dockerfile · Ansible · WAF · K8s · REMEDIATION.md
└── llm/__init__.py     # OpenAI · Anthropic · DeepSeek · claude-code
tests/test_smoke.py     # unit + CLI smoke tests
docs/                   # README screenshots, animated demo + generator scripts
config.example.toml     # annotated config template

🛠️ Development

pip install -e ".[dev]"
pytest -q                                              # run the test suite

SENTINELPULSE_HOME=/tmp/sp_shots python docs/make_screenshots.py   # regenerate README screenshots
python docs/make_demo_gif.py                           # regenerate the animated demo (needs Chrome + Pillow)

Releasing a new version

# 1. bump `version` in pyproject.toml and `__version__` in sentinelpulse/__init__.py
rm -rf dist && python -m build && twine check dist/*
twine upload --repository testpypi dist/*   # try it on TestPyPI first
twine upload dist/*                         # then the real PyPI

Use a throwaway SENTINELPULSE_HOME while developing so your real brain and inventory stay untouched.

❓ Troubleshooting & FAQ

🤝 Contributing

Issues and pull requests are welcome. Please keep SentinelPulse defensive: contributions that add exploitation, payload delivery or intrusive scanning won't be accepted. Run pytest -q before opening a PR.

📜 License

MIT © SentinelPulse contributors