# ☣ 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.*