vuln-research-agent

vuln-research-agent

An open-source vulnerability research agent for detection engineers. Give it a CVE ID (or a product name plus version) and it returns one triage row per CVE:

It is available in three forms, all using the same stdlib-only Python core (no pip installs):

Data sources

App Type, Auth and Vector come from the CVSS vector (AV/PR) plus CPE part and description keyword heuristics. Before research, the agent asks the user to choose ASCII table, vertical table, HTML file, or plain text unless the request already names a format.

API and X setup

Copy .env.example to .env for GitHub, NVD, GreyNoise and VirusTotal keys. X uses the official xurl OAuth store rather than .env. Full instructions: docs/SETUP.md.

cp .env.example .env
chmod 600 .env
python3 scripts/check_config.py

Quick start

python3 skills/vuln-research/scripts/vulnresearch.py CVE-2021-44228 CVE-2024-3400
python3 skills/vuln-research/scripts/vulnresearch.py --product "Apache Tomcat" --version 9.0.30 --limit 10 --format markdown
python3 skills/vuln-research/scripts/vulnresearch.py CVE-2024-3400 --format json   # includes _evidence

Formats: ascii, vertical, html, plain, markdown, csv, json; table is an alias for ascii. Use --output PATH to create a file, especially with HTML.

User-facing choices:

• ASCII table: best for multi-CVE comparison in a wide terminal.
• Vertical table: best for one CVE, narrow terminals, or phone screens.
• HTML file: best for browser viewing, sharing, or printing.
• Plain text: best for email, tickets, SIEM cases, and copy/paste.

Every field is kept precise: prose over two sentences is converted to bullets. The IoCs field contains only concrete indicators, formatted as type: value — one-line source/context. GreyNoise results must be CVE-linked and unrestricted; VirusTotal contributes file hashes/detection counts, structured indicators, and concrete IP/hash values extracted from clearly labeled unverified community comments. Detection ideas and generic log strings do not count as IoCs.

Optional env vars:

• GITHUB_TOKEN: higher GitHub search limits
• NVD_API_KEY: 10x NVD rate limit (free key)
• GREYNOISE_API_KEY: GreyNoise GNQL scanner IPs associated with the CVE (requires GNQL entitlement)
• VIRUSTOTAL_API_KEY: VirusTotal file/comment/indicator search. Public keys may have less coverage than Intelligence.
• THREATFOX_API_KEY: ThreatFox (abuse.ch) malware/C2 IOCs tagged with the CVE. Free account at https://auth.abuse.ch/.

Exploit-DB, AlienVault OTX, GitHub Security Advisories, OSV.dev, and Shodan CVEDB need no key and are always queried.

Without the GreyNoise, VirusTotal, or ThreatFox key, the IoCs column says not queried rather than incorrectly claiming no IoCs exist. Never query sensitive/private indicators in VirusTotal; queried or submitted indicators may become visible to its community.

X support: install xurl and run xurl auth oauth2 yourself. Without it, X is reported as n/a and the agent skill falls back to web search.

Install as a skill

Hermes Agent:

cp -r skills/vuln-research ~/.hermes/skills/security/

For Claude Code and other Agent Skills-compatible agents, copy skills/vuln-research into that agent's skills directory.

Install as MCP tools

{
  "mcpServers": {
    "vulnresearch": { "command": "python3", "args": ["/abs/path/vuln-research-agent/mcp/vulnresearch_mcp.py"],
                      "env": { "GITHUB_TOKEN": "", "NVD_API_KEY": "", "GREYNOISE_API_KEY": "", "VIRUSTOTAL_API_KEY": "", "THREATFOX_API_KEY": "" } }
  }
}

Hermes (~/.hermes/config.yaml):

mcp_servers:
  vulnresearch:
    command: python3
    args: [/abs/path/vuln-research-agent/mcp/vulnresearch_mcp.py]

Tools: research_cve(cve_ids[], include_social, format) and research_product(product, version, limit, include_social, format).

Tests

python3 -m unittest discover -s tests -v   # offline, mocked

Caveats

• Not being in KEV does not mean a CVE hasn't been exploited. The tool reports "Not observed".
• GitHub "PoC" repos are sometimes fake or malicious. Review them before running anything.
• App Type is a heuristic. Treat it as a first pass.

License

MIT