## https://sploitus.com/exploit?id=1371A338-7DF8-534F-B254-F22A16F0A2D0
# cve-researcher
**AI-powered CVE research in your terminal** โ point it at a CVE ID or a technology name and get a structured security report in seconds.
This tool demonstrates agentic AI applied to AppSec research: a Claude AI agent autonomously calls four threat-intelligence data sources in parallel, reasons over the results, and synthesizes a publication-quality vulnerability report โ all from a single CLI command.
---
## What it does
`cve-researcher` is a Python CLI tool that accepts a CVE ID (e.g. `CVE-2021-44228`) or a technology keyword (e.g. `"log4j"`), dispatches a Claude AI agent to query NVD, GitHub, CISA KEV, and Exploit-DB in parallel, and synthesizes the results into a structured Markdown security research report. The agent infers MITRE ATT&CK technique mappings from the vulnerability type and evaluates real-world exploitation status before writing its conclusions. Reports are saved to disk and a color-coded Rich summary panel is printed to the terminal.
---
## Demo
```
$ cve-researcher CVE-2021-44228
โ Researching CVE-2021-44228...
```
```
โญโโโโโโโโโโโโโโโโโโโโโโโ CVE-2021-44228 โโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ CRITICAL | CVSS 10.0 โ
โ โ
โ Apache Log4j2 2.0-beta9 through 2.14.1 JNDI features used in โ
โ configuration, log messages, and parameters do not protect โ
โ against attacker-controlled LDAP and other JNDI related... โ
โ โ
โ โ IN CISA KEV โ actively exploited โ
โ GitHub PoCs: 5 repositories found โ
โ Exploit-DB: 3 verified exploits โ
โ Report saved: reports/CVE-2021-44228.md โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
```
See [`examples/CVE-2021-44228.md`](examples/CVE-2021-44228.md) for a full sample report (Log4Shell).
---
## Setup
```bash
git clone https://github.com/ericfurspan/cve-researcher.git
cd cve-researcher
python -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env
# Edit .env and add your API keys
```
---
## Configuration
Copy `.env.example` to `.env` and fill in your keys:
| Variable | Required | Description |
|---|---|---|
| `ANTHROPIC_API_KEY` | Required | Anthropic API key. Powers the Claude AI agent. Get one at [console.anthropic.com](https://console.anthropic.com). |
| `GITHUB_TOKEN` | Required | GitHub personal access token. Unauthenticated GitHub Search is severely rate-limited (10 req/min vs 30 req/min authenticated). |
| `NVD_API_KEY` | Optional | NIST NVD API key. Raises the NVD rate limit from 5 to 50 requests per 30 seconds. Free at [nvd.nist.gov/developers/request-an-api-key](https://nvd.nist.gov/developers/request-an-api-key). |
---
## Usage
```bash
# Research a specific CVE
cve-researcher CVE-2024-1234
# Keyword search โ the agent resolves to the most significant matching CVE
cve-researcher "log4j"
# Print summary only, do not save report to disk
cve-researcher CVE-2024-1234 --no-save
# Save report to a custom directory
cve-researcher CVE-2024-1234 --output ./my-reports/
```
Reports are saved to `reports/.md` by default. Report `.md` files in `reports/` are gitignored โ the directory itself is tracked so it exists after cloning.
---
## Architecture
```
typer CLI
โโโ Claude AI agent (tool-use loop)
โโโ search_nvd โโ
โโโ search_github โโ dispatched in parallel
โโโ check_cisa_kev โ via asyncio.gather()
โโโ search_exploit_db โโ
โ
โโโ Claude synthesizes results
โโโ Rich terminal summary panel
โโโ Markdown report saved to disk
```
- **Prompt caching** (`cache_control: ephemeral`) reduces input token costs on repeated research runs by caching the system prompt prefix โ effective within the 5-minute cache TTL window.
- **Parallel tool dispatch** โ all four tool calls are fired with `asyncio.gather()`, so total latency is bounded by the slowest single source rather than the sum.
- **Structured raw results** are passed through the stack alongside Claude's prose, so the terminal summary panel can extract typed fields (CVSS score, severity, KEV status) without parsing Markdown.
---
## How the agent works
The agent runs a standard **tool-use loop** against Claude's API:
1. The user's query (CVE ID or keyword) is sent as the first user message.
2. Claude decides which tools to call and returns `tool_use` blocks.
3. The tool functions execute (in parallel where possible) and return structured JSON.
4. Tool results are appended to the conversation as `tool_result` messages.
5. Claude reads all four sources and produces its final `end_turn` response.
The system prompt instructs Claude to always call all four tools before writing its report โ preventing premature synthesis from incomplete data. If a keyword is supplied instead of a CVE ID, the agent first calls NVD to resolve the keyword to a concrete CVE ID, then researches it fully.
**MITRE ATT&CK inference** is performed by Claude during the synthesis step. The system prompt maps vulnerability classes (RCE via web app โ T1190, SQL injection โ T1190, privilege escalation โ T1068, etc.) and Claude picks the best-fit technique based on the vulnerability description and attack vector from NVD.
The agent caps at 10 iterations and surfaces a warning if the token limit is hit mid-response, so it degrades gracefully rather than hanging or silently truncating.
---
## Data sources
| Source | What it provides |
|---|---|
| **NVD** (NIST National Vulnerability Database) | Official CVE record: CVSS score, severity, vector string, affected CPEs, description, published/modified dates, references |
| **GitHub** | Public PoC exploit repositories (keyword + CVE search), GitHub Security Advisories (GHSA), repository star counts as a rough exploitation-interest signal |
| **CISA KEV** (Known Exploited Vulnerabilities) | Authoritative list of CVEs confirmed actively exploited in the wild; includes date added and required remediation deadline for federal agencies |
| **Exploit-DB** | Verified public exploit code with EDB IDs, exploit type (remote/local/DoS/webapps), platform, and direct URLs |
---
## Portfolio context
This project is part of a hands-on AppSec portfolio that also includes a Wazuh SIEM home lab with custom detection rules, an OWASP Juice Shop penetration testing workspace with documented findings, and a DevSecOps CI/CD pipeline integrating SAST/DAST tooling. Each project is designed to demonstrate practical security engineering skills across the detection, offense, and engineering pillars of modern AppSec.