🔍 Holmes Security Skill

Sherlock Holmes Evidence-Driven Penetration Testing

将福尔摩斯探案方法论注入渗透测试的 Claude Code SKILL + Python 引擎

"当你排除了不可能之后，剩下的，无论多么不可信，必定是真相。" — 夏洛克·福尔摩斯

---

✨ 核心特性

特性	说明
🕵️ 三角色架构	麦考夫（流程监督）、福尔摩斯（推理引擎）、华生（执行与记录）协同工作
📋 五阶段方法论	勘察现场 → 异象识别 → 假设矩阵 → 排除验证 → 证据链闭环
🎯 四级证据体系	铁证 / 强证据 / 线索 / 传闻，每份证据严格分级、可追溯
🧠 v2 概率推理引擎	贝叶斯假设更新、证据网络置信度传播、元认知自我批判、信息增益最优测试选择
📚 自进化知识库	结案自动提取知识 → 验证 → 入库 → 淘汰，让福尔摩斯越测越聪明
🔐 安全边界硬化	CTF / Live 双模式、高危操作门控、Git 全程审计留痕

---

🚀 快速开始

安装

git clone https://github.com/aitippro/holmes-security-skill.git
cd holmes-security-skill
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

CLI 命令参考

案件管理

# 开案 — 正式渗透模式（回合制，每阶段需确认）
holmes investigate https://target.com

# CTF 模式（全自动推进，高危操作自动放行）
holmes investigate https://ctf.target.com --mode ctf

# 指定执行模式（覆盖默认行为：CTF→auto, Live→interactive）
holmes investigate https://target.com --mode live --exec auto

选项	说明	默认值
target	目标 URL / IP / 代码仓库路径（必填）	—
--mode, -m	live（正式渗透）或 ctf（竞赛模式）	live
--exec, -e	auto（全自动）或 interactive（回合制）	CTF→auto, Live→interactive
--output, -o	案件档案输出目录	cases/

# 列出所有案件
holmes list

# 推进案件到下一阶段（门控检查）
holmes advance CASE-20260101-120000-a1b2c3d4

# 指定角色推进
holmes advance CASE-20260101-120000-a1b2c3d4 --persona watson

# 生成结案报告（支持 markdown / mermaid 格式）
holmes report CASE-20260101-120000-a1b2c3d4
holmes report CASE-20260101-120000-a1b2c3d4 --format mermaid

# 结案（须在 EVIDENCE_CHAIN 阶段）
holmes close CASE-20260101-120000-a1b2c3d4

知识库管理

# 健康状态报告
holmes evolution report

# 性能指标与工具可用性检查
holmes evolution perf

# 审计并清理陈旧条目
holmes evolution prune        # 仅预览
holmes evolution prune --yes  # 执行清理

---

🧩 在 Claude Code 中加载 SKILL

方法一：注册为项目 SKILL（推荐）

在项目根目录执行：

claude skills register /path/to/holmes-security-skill

或在 Claude Code 交互界面中使用 /skills 命令搜索并加载。

方法二：手动配置 settings

在 ~/.claude/settings.json 中添加：

{
  "enabledSkills": {
    "sherlock": "/path/to/holmes-security-skill"
  }
}

触发词

加载后，以下关键词自动触发 SKILL：

触发词	示例
sherlock	"sherlock, 开案调查 http://target.com"
福尔摩斯	"福尔摩斯，帮我分析这个站"
渗透测试	"对 http://target.com 进行渗透测试"
开案 / 勘察现场	"勘察现场 http://target.com"
holmes investigate	直接 CLI 调用

Agent 强制约束

项目 .claude/settings.local.json 配置了 PreToolUse Hook，所有裸安全工具调用（curl、nmap、sqlmap 等）在没有活跃案件时被物理阻断。Agent 必须先 holmes investigate 开案。

---

🏗️ 架构概览

┌─────────────────────────────────────────────────────────────┐
│                        CLI Layer                            │
│  holmes investigate / list / report / advance / close      │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                    Case Manager (case.py)                   │
│         案件生命周期 · 阶段门控 · 角色权限检查              │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐   ┌─────────────────┐   ┌─────────────────┐
│  v2 推理引擎  │   │   证据系统       │   │  工具集成层      │
│  (core/)      │   │  (evidence.py)  │   │ (tools/scanner) │
├───────────────┤   ├─────────────────┤   ├─────────────────┤
│ Abduction     │   │ 四级证据分级     │   │ nmap / curl     │
│ HypothesisSpace│  │ 证据链完整性     │   │ ffuf / sqlmap   │
│ EvidenceNetwork│  │ Oracle 验证器   │   │ nuclei ...      │
│ TestStrategy  │   └─────────────────┘   └─────────────────┘
│ Metacognition │
│ PatternCompletion│
└───────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────────────┐
│              Knowledge Base (knowledge/)                    │
│  CWE 图谱 · Pattern 库 · 预测模板 · 测试策略库 · SQLite 索引 │
└─────────────────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────────────┐
│           Evolution Loop (evolution/)                       │
│  Extract → Validate → Ingest → Prune (自进化闭环)            │
└─────────────────────────────────────────────────────────────┘

---

📂 项目结构

holmes-security-skill/
├── src/holmes/
│   ├── cli.py                 # CLI 入口 (Typer + Rich)
│   ├── case.py                # 案件管理 + 阶段门控
│   ├── evidence.py            # 四级证据分级与验证
│   ├── wiki.py                # Git-backed LLM-Wiki 引擎
│   ├── oracle.py              # Oracle 置信度验证器
│   ├── recorder.py            # 证据录制器
│   ├── report.py              # 报告生成器
│   ├── core/                  # v2 概率推理引擎
│   │   ├── abduction.py       # 贝叶斯溯因推理
│   │   ├── hypothesis_space.py# 假设空间 + Shannon 熵
│   │   ├── evidence_network.py# 证据网络置信度传播
│   │   ├── test_strategy.py   # 信息增益最优测试选择
│   │   ├── pattern_completion.py # 模式匹配与"顿悟"
│   │   └── metacognition.py   # 元认知 + 8 种推理缺陷检测
│   ├── evolution/             # 自进化知识闭环
│   │   ├── extractor.py       # 知识提取
│   │   ├── validator.py       # 回溯验证
│   │   ├── ingester.py        # 双区入库
│   │   ├── pruner.py          # 知识淘汰
│   │   └── reporter.py        # 状态报告
│   ├── knowledge/             # 知识库实现
│   │   ├── cwe_graph.py       # CWE 知识图谱
│   │   ├── pattern_library.py # 漏洞模式库
│   │   ├── sqlite_index.py    # SQLite 加速索引
│   │   └── test_strategy_library.py
│   ├── tools/
│   │   └── scanner.py         # 安全工具统一封装
│   ├── personas/              # 三角色运行时人格
│   └── agents/                # Claude Code 角色指令
│       ├── mycroft.md
│       ├── holmes.md
│       └── watson.md
├── templates/                 # 案件档案模板
├── tests/                     # 单元 + 集成测试
├── SKILL.md                   # Claude Code SKILL 定义
├── SPEC.md                    # 技术规格
└── README.md                  # 本文件

---

🧪 开发

# 运行测试
pytest tests/ -v

# 代码检查
ruff check src/ tests/
mypy src/
black src/ tests/

---

⚠️ 安全与法律声明

本工具仅用于授权的安全测试、CTF 竞赛和安全研究。

• ❌ 禁止测试政府、军用、关键基础设施等未授权目标
• ❌ 禁止伪造或篡改证据
• ✅ 始终遵守目标授权范围和法律法规
• ✅ Live 模式下高危操作需人工确认

---

Built with 🎩 deduction and 🔬 evidence.