Initial ThreatLens release

2026-06-27 21:24:57 -04:00
commit d96e326d4d
27 changed files with 3059 additions and 0 deletions
@@ -0,0 +1,149 @@
+# ☣ VulnForge
+
+> **Security Intelligence Discord Bot** — weekly CVE/KEV threat digests and on-demand vulnerability lookups, wrapped in a dark cyberpunk aesthetic.
+
+VulnForge fuses two authoritative sources — the **NVD CVE API v2** and the **CISA Known Exploited Vulnerabilities (KEV)** catalog — into a single Discord experience built for security researchers and blue/red teams.
+
+---
+
+## ⚡ Features
+
+### 1. Automated Weekly Digest
+Every **Monday @ 09:00 UTC**, VulnForge posts a rich digest to your configured channel:
+- 🆕 Total new CVEs in the last 7 days
+- ☣ How many are already in CISA KEV / newly added to KEV
+- ▶ Top **8** most critical CVEs (sorted by CVSS, color-coded by severity)
+- 🔗 Direct links to NVD and CISA
+
+### 2. Slash Commands
+| Command | Description |
+|---------|-------------|
+| `/cve <cve_id>` | Opens a **modal** to pick output sections (details, KEV, refs, CWE) + add a researcher note, then replies with a rich embed. |
+| `/kev [limit]` | Latest CISA KEV entries (actively exploited in the wild). |
+| `/weekly` | **Admin-only** — force-post the weekly digest now. |
+| `/setup` | **Admin-only** — set the digest channel + notification role. |
+
+### 3. Under the hood
+- **Nextcord** (slash commands, modals, views)
+- **aiohttp** with retry/backoff + on-disk **TTL caching** (rate-limit friendly)
+- **aiosqlite** for guild config + persistent researcher notes
+- Full **logging** and graceful shutdown
+- Severity-coded **cyberpunk embeds** (neon reds/oranges/cyans on near-black)
+
+---
+
+## 📁 Project Structure
+
+```
+vulnforge/
+├── main.py              # Entrypoint: boots bot, wires API + store, loads cogs
+├── config.py            # Env + endpoints + colour palette + tunables
+├── .env.example         # Copy to .env and fill in
+├── requirements.txt
+├── README.md
+├── Dockerfile           # Hardened, non-root production image
+├── docker-compose.yml   # One-command deploy with persistent volume
+├── .dockerignore
+├── cogs/
+│   ├── __init__.py
+│   ├── weekly.py        # Scheduled digest + /weekly
+│   └── cve.py           # /cve modal, /kev, /setup
+├── utils/
+│   ├── __init__.py
+│   ├── api.py           # NVD + CISA KEV async client (cache + retry)
+│   ├── embeds.py        # Cyberpunk embed builders
+│   └── helpers.py       # Severity maps, validation, JSON cache, SQLite store
+└── data/                # Caches + SQLite DB (auto-created)
+```
+
+---
+
+## 🚀 Setup
+
+### 1. Create a Discord application
+1. Go to the [Discord Developer Portal](https://discord.com/developers/applications).
+2. **New Application** → **Bot** → copy the **token**.
+3. Under **Installation / OAuth2**, enable the `bot` and `applications.commands` scopes.
+4. Invite the bot to your server with the **Send Messages** + **Embed Links** permissions.
+
+### 2. Install
+```powershell
+cd vulnforge
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1      # Windows
+# source .venv/bin/activate       # macOS/Linux
+pip install -r requirements.txt
+```
+
+### 3. Configure
+```powershell
+copy .env.example .env            # cp on macOS/Linux
+```
+Edit `.env`:
+- `DISCORD_TOKEN` — **required**
+- `GUILD_ID` — optional; set it for **instant** slash-command sync during development
+- `NVD_API_KEY` — optional but **strongly recommended** ([request one free](https://nvd.nist.gov/developers/request-an-api-key)) to lift rate limits
+
+### 4. Run
+```powershell
+python main.py
+```
+
+### 5. Configure in Discord
+Run `/setup` in your server (needs **Manage Server**) to choose the digest channel and an optional notification role. Then test with `/weekly`.
+
+---
+
+## 🐳 Docker
+
+VulnForge ships with a hardened image (non-root user, healthcheck, persistent volume). It only makes **outbound** calls, so no ports are exposed.
+
+### Compose (recommended)
+```powershell
+copy .env.example .env            # fill in DISCORD_TOKEN
+docker compose up -d --build
+docker compose logs -f            # tail logs
+docker compose down               # stop
+```
+
+### Plain Docker
+```powershell
+docker build -t vulnforge:latest .
+docker run -d --name vulnforge --restart unless-stopped `
+  --env-file .env `
+  -v vulnforge_data:/app/data `
+  vulnforge:latest
+```
+
+The named volume `vulnforge_data` persists the SQLite DB (guild config + researcher notes) and the on-disk API cache across rebuilds. Update `.env` and re-run `docker compose up -d --build` to apply config changes.
+
+---
+
+## 🎨 Severity Colour Legend
+
+| Severity | Marker | Colour |
+|----------|--------|--------|
+| Critical | 🟥 | Neon Red `#FF003C` |
+| High | 🟧 | Hot Orange `#FF6B00` |
+| Medium | 🟨 | Amber `#FFB300` |
+| Low | 🟦 | Cyan `#00E5FF` |
+| KEV / Exploited | 🩸 | Ruby `#E0115F` |
+
+---
+
+## 🔒 Notes & Limits
+- **NVD rate limits**: 5 requests / 30s without a key, 50 / 30s with one. The weekly sweep paginates the full 7-day window — a key makes it noticeably faster. Responses are cached on disk (`data/cache/`).
+- **KEV feed** is cached for 6 hours by default (`config.py → kev_cache_ttl`).
+- Never commit your real `.env` — only `.env.example` belongs in version control.
+- This tool is for **defensive research and awareness**. Use responsibly.
+
+---
+
+## 🛠 Customisation
+- Change the digest day/time in [cogs/weekly.py](cogs/weekly.py#L34) (`RUN_AT` + the Monday guard).
+- Tune `digest_top_n`, cache TTLs, and the colour palette in [config.py](config.py).
+- Embed styling lives entirely in [utils/embeds.py](utils/embeds.py).
+
+---
+
+*VulnForge // Security Intelligence — built with Nextcord.*