hyperdope - Hyperdope is a suite of autonomous agents that aud

项目说明

<di="center">

!image

MCP Server for Ad Security Research

!npm
!Node
!License
!MCP
!ESM

A 6-phase agentic security research pipeline exposed as MCP tools - from attack surface profiling to coordinated disclosure. Runs inside Claude Code, Cursor, or any MCP host. Bring your own LLM.

Installation · Quick Start · Agent Config · Pipeline · Tools · Session Resume · Pro · Troubleshooting · Disclaimer

</div>

---

<a id="installation"></a>

Installation

Global install (recommended)

Run without installing

De

---

<a id="quick-start"></a>

Quick Start

Step 1 - Copy the example agent config

Step 2 - Register with your MCP host

For Claude Code - add to .mcp.json in your project root:

For global registration, use ~/.claude/claude_desktop_config.json with the same structure.

If running from a local clone, replace "npx" + "args": ["hyperdope"] with:

Step 3 - Run the full pipeline

That's it. Hyperdope runs all 6 phases sequentially, chains context automatically, and writes a session file to .hyperdope/sessions/.

---

<a id="agent-config"></a>

Agent Config

Copy agent.example.yaml to agent.yaml. Hyperdope resolves it in this order:

1. --agent path/to/agent.yaml CLI flag
2. HYPERDOPE_AGENT en
3. ./agent.yaml in the current working directory
4. Error with instructions

Full annotated schema:

En resolution - any ${VAR} reference in the YAML is resolved at runtime. Missing throw with the name in the error message.

---

<a id="pipeline"></a>

Pipeline

Each phase's output context field is the exact input for the next phase's context argument. hd_run handles this automatically. Indi tools can be called standalone for custom workflows.

---

<a id="tools"></a>

Tools

hd_profile - Phase 1: Attack Surface Profile

Maps the target's complete attack surface across all relevant categories.

What it covers: trust boundaries, parser differentials, deserialization paths, supply chain dependencies, authentication and authorization flows, LLM-specific surfaces (prompt injection entry points, tool call abuse, RAG poisoning, agentic multi-hop chains), file system race conditions, cryptographic weaknesses, SSRF-reachable internal endpoints.

Input

Output

---

hd_audit - Phase 2: Hunt

Systematically reasons through applicable classes for each surface category found in Phase 1.

What it covers:

Findings are rated by exploitability: confirmed, likely, or theoretical.

Input

Output

---

hd_confirm - Phase 3: PoC Generation

Writes a minimal, self-contained, deterministic Proof of Concept for a specific audit finding.

PoC output structure:

Input

Output
python\nimport pickle, requests\n...\n

---

hd_assess - Phase 4: CVSS v3.1 + CWE Scoring

Scores the using chain-of-thought reasoning through each CVSS v3.1 metric before committing to a numeric score. Ne - reasons through AV, AC, PR, UI, S, C, I, A indi.

C reasoned through:

| Metric | Options | Key question |
| --- | --- | --- |
| Attack (AV) | N / A / L / P | How far can the attacker be? |
| Attack Complexity (AC) | L / H | Are special conditions required? |
| Pri Required (PR) | N / L / H | What account level does the attacker need? |
| User Interaction (UI) | N / R | Does a need to act? |
| Scope (S) | U / C | Does impact cross component boundaries? |
| Confidentiality (C) | N / L / H | How much data is exposed? |
| Integrity (I) | N / L / H | Can data be modified? |
| A (A) | N / L / H | Can the system be disrupted? |

Input

Output

---

hd_draft_ghsa - Phase 5: GHSA Draft

Produces a GitHub Security Ad draft following the GitHub Ad Database schema exactly.

Schema fields produced:
ghsa_id (PENDING) · se · summary (≤100 chars) · details (full markdown) · affected (package + ranges) · references · published: null · withdrawn: null · aliases: [] · database_specific (cwes, c + score)

Input

Output
yaml\nghsa_id: PENDING\nse: CRITICAL\nsummary: \"RCE deserialization in upload endpoint\"\n...\n

---

hd_disclose - Phase 6: Coordinated Disclosure Package

Produces three distinct documents in a single LLM call, each calibrated for a different audience.

| Output | Audience | Content |
| --- | --- | --- |
| Executi | CISO, VP Eng, Board | 2 paragraphs, no CVE IDs or C - business impact + recommended response |
| Technical Ad | Security engineers, devs, IR | Root cause, affected , CVSS, CWE, attack scenario, detection IoCs, remediation steps, timeline |
| Email Template | 's security team | Professional tone, summary, C, 90-day disclosure timeline, PoC offer under embargo |

Input

Output

---

hd_scan — Phase 0: Dependency & Supply-Chain Scan

Scans a local directory against the OSV.dev C.
No API key or agent config required — runs entirely local + public APIs.

What it covers: npm (package-lock.json / package.json), Python
(requirements.txt / poetry.lock / Pipfile.lock), Go (go.mod), Rust (Cargo.lock),
hardcoded secrets (AWS keys, GitHub PATs, Anthropic/OpenAI keys, PEM blocks),
npm lifecycle hooks (postinstall / preinstall), dependency confusion suspects,
ghost endpoints (remo still in git history), SBOM-lite generation.

Input

Output — findings[] contains OSV CVEs, secrets, hooks, ghost endpoints, confusion suspects.
meta contains package counts, ecosystem list, and SBOM. sbom contains the full SBOM-lite object.

---

hd_ — Patch Phase

Determines whether pre reported are actually fixed in a
patched . Uses a 4-question methodology:

1. Root cause identification — what exact code path caused the original finding?
2. Change analysis — does the patch close that exact path, or only a symptom?
3. bypass check — are there alternati that bypass the fix?
4. Sibling site audit — are there other locations in the codebase with the same pattern?

: PATCHED · STILL_ · PARTIAL_FIX · CANNOT_

Run after hd_assess (or hd_confirm) when a patch is a.

Input

---

hd_run - Full Pipeline (all 6 phases)

Runs phases 1–6 sequentially. Context is chained automatically - no manual wiring needed.

Input

Output

---

<a id="session-resume"></a>

Session Resume

Every hd_run execution writes a session file to .hyperdope/sessions/{timestamp}.json. The file is append-safe - resuming ne completed phases.

To resume from any phase:

1. Open the session file:

2. Copy the context object from the last completed phase's result.

3. Call the next phase tool with that context:

Indi phase tool calls (hd_audit, hd_confirm, etc.) also write their results to the session file when a context argument is passed in.

---

<a id="pro"></a>

Pro

| provider value | SDK | Notes |
| --- | --- | --- |
| claude | -ai/sdk | Anthropic Claude (Sonnet, Opus, Haiku) |
| openai | openai | GPT-4o, GPT-4 Turbo, o1, etc. |
| gemini | /generative-ai | Gemini 1.5 Pro, Flash, 2.0 |
| ollama | fetch | Local models at localhost:11434 |
| glm | openai + base_url | Zhipu GLM-4, openai-compatible |
| kimi | openai + base_url | Moonshot Kimi, openai-compatible |
| qwen | openai + base_url | Alibaba Qwen, openai-compatible |

Any OpenAI-compatible endpoint works with provider: openai + base_url pointing to the API.

Provider config examples:

---

<a id="troubleshooting"></a>

Troubleshooting

| Problem | Fix |
| --- | --- |
| Cannot read agent config: ... | Check the path in --agent or HYPERDOPE_AGENT. File must exist and be valid YAML. |
| Missing required en : CLAUDE_API_KEY | Export the before starting the host: export CLAUDE_API_KEY=sk-ant-... or add it to the MCP host's env block. |
| Unknown provider: "..." | Check provider: in agent.yaml - valid : claude, openai, gemini, ollama, glm, kimi, qwen. |
| Tool returns "status": "partial" | The LLM response didn't produce parseable JSON. The full response is still in raw. Check the model's output or lower temperature. |
| MCP host doesn't see the tools | Restart the host after editing .mcp.json. node -- ≥ 20. |
| Ollama connection refused | Start Ollama: ollama serve. Confirm the model is pulled: ollama pull llama3.1:70b. |
| Rate limit / 429 errors | Add temperature and max_tokens guards in agent.yaml, or switch to a provider with higher limits. |
| Session file not created | hd_run writes to .hyperdope/sessions/ relative to the cwd where the MCP host launched the server. Check launch directory. |

---

<a id="disclaimer"></a>

Disclaimer

Hyperdope is for authorized security research, penetration testing, disclosure programs, and CTF competitions only. You must ha written authorization before targeting any system you do not own.

The built-in prompts are designed for ad research. PoC output from hd_confirm should be handled as sensiti. Ad drafts from hd_draft_ghsa and hd_disclose should follow responsible disclosure practices - notify the before public release.

The authors assume no liability for misuse.

---

License

MIT

项目信息

开发语言：JavaScript

Star 数：8

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Hyperdope is a suite of autonomous agents that audit code, hunt 0days, and ship coordinated-disclosure advisories - the way a top-tier research team works, at machine speed.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。