150 lines
5.6 KiB
Markdown
Executable File
150 lines
5.6 KiB
Markdown
Executable File
# ☣ 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.*
|