prayingperceptions/bloodhound

# 🐺 Bloodhound — Mythos-class Security Agent **Autonomous, Agent-Agnostic smart contract security engine.** Bloodhound is a standalone reasoning engine designed to be used with ANY agentic system (Cursor, Windsurf, Claude Code, etc.) or as a direct CLI. It treats audits as a **state-based reasoning game**, not pattern matching. ## 可移植性与代理集成 Bloodhound is architected for maximum portability. Because it is a pure Python CLI with JSON/Markdown outputs, it can be easily integrated into any AI-driven workflow: - **Cursor / Windsurf**: Add `bloodhound` to your environment and ask the agent to "Run bloodhound hunt on this repo". - **Claude Code / OpenClaw**: Use the CLI commands via terminal to feed high-fidelity findings back into the agent's context. - **CI/CD**: Run as a security gate in your pipeline to generate Code4rena or Immunefi-ready drafts automatically. ## 安装 ``` # 克隆存储库 git clone https://github.com/yourusername/bloodhound cd bloodhound # 作为可编辑包安装（推荐） pip install -e . # 设置 LLM API 密钥（任选其一） export GEMINI_API_KEY="your-key-here" ``` ## 快速开始 ## 架构 ``` bloodhound/ ├── bloodhound.py # CLI entrypoint & Listening Mode ├── config.yaml # LLM, Foundry, heuristics config │ ├── core/ # Engine internals │ ├── state_map.py # Central data model │ ├── solidity_parser.py # Slither + regex fallback parser │ ├── heuristics.py # Domain-specific anomaly detection │ └── mythos_loop.py # 4-step reasoning orchestrator │ ├── skills/ # Atomic skills │ ├── bloodhound_mapper.py # State-space mapper │ ├── bloodhound_reasoner.py # LLM chain-exploit reasoner │ ├── bloodhound_fuzz.py # Foundry test generator + runner │ └── bloodhound_report.py # Code4rena & Immunefi reporter │ ├── templates/ # Jinja2 templates │ ├── invariant_test.sol.j2 # Foundry InvariantTest │ ├── code4rena_high.md.j2 # C4 High/Med finding │ ├── code4rena_qa.md.j2 # C4 QA consolidated │ └── immunefi_report.md.j2 # Immunefi impact-driven │ └── output/ # Generated artifacts ├── state_map.json ├── protocol_diagram.md └── reports/ ``` ## Mythos 推理循环 | Step | Phase | What Happens | |------|-------|-------------| | 1 | **Shadow** | Parse all contracts, build call graph, map state variables | | 2 | **Detect** | Apply domain heuristics to find anomalies | | 3 | **Chain** | LLM reasons about chaining anomalies into exploits | | 4 | **Verify** | Generate & run Foundry invariant tests | ## CLI 命令 ``` # 完整流水线 python bloodhound.py hunt --mode code4rena|immunefi # 各阶段 python bloodhound.py map python bloodhound.py reason python bloodhound.py fuzz python bloodhound.py report --mode immunefi # 交互模式 python bloodhound.py listen ``` ## 支持的 LLM 提供商 | Provider | Env Variable | Config Key | |----------|-------------|------------| | Google Gemini | `GEMINI_API_KEY` | `gemini.api_key` | | OpenAI | `OPENAI_API_KEY` | `openai.model` | | Anthropic | `ANTHROPIC_API_KEY` | `anthropic.model` | | Local (Ollama) | `LOCAL_MODEL_URL` | `local.base_url` | Bloodhound auto-detects the provider from available environment variables. ## 领域启发式 - **Cross-Chain (OFT/LayerZero):** Tracks `amountSentLD` vs inputs, monitors daily limits for rounding drift - **Economic Invariants:** Enforces "No Value Loss" in ERC4626 vaults, share price monotonicity - **Agent-Payment:** Validates cryptographic binding of task signatures to payment releases ## 报告模式 ### Code4rena - High/Medium → individual reports with PoC - Low/QA → consolidated report (`L-01`, `L-02`, ...) - Gas → separate report ### Immunefi - Impact-driven format: `[Attack Vector] in Contract::Function leads to Impact` - Economic collapse path narrative - Full runnable PoC *Built by Project Bloodhound.*

标签：AI工作流集成, API安全, Bloodhound安全引擎, CI/CD安全门, Claude Code集成, Code4rena准备, Cursor集成, ETH安全, EVM审计, Foundry集成, Immunefi准备, JSON输出, LLM安全推理, Markdown输出, Mythos类安全代理, OpenClaw集成, Python CLI, Slither解析器, Solidity解析, Windsurf集成, 代理安全工作流, 代码审计工具, 区块链安全审计, 协议状态机, 原子技能模块化, 可移植安全代理, 启发式检测, 异常检测, 智能合约安全, 模型无关LLM循环, 正则解析回退, 状态映射核心, 状态机推理, 状态空间映射, 自动漏洞假设, 逆向工具, 逻辑缺口识别, 链式异常推理