DoctorGoz/grimnir

# GRIMNIR — 安全测试协调器 **受控侦察、情报管理、网络检查与报告** 一个 Claude Code 协调器，用于协调专门的安全测试代理，以执行全面的渗透测试任务。GRIMNIR 会对目标进行分类，界定测试范围，将任务委派给合适的专家，跟踪进度，在各个代理之间共享情报，并编制统一的报告。 ## 架构 ``` ┌──────────────────────────┐ │ GRIMNIR │ │ PM / Orchestrator │ │ │ │ Classifies & scopes │ │ Tracks state & intel │ │ Delegates & reports │ └─────────────┬────────────┘ │ ┌─────────────┴────────────┐ │ HUGINN │ │ Phase 0 Recon │ │ │ │ subdomains · ports │ │ fingerprint · asset map │ │ intel distribution │ └─────────────┬────────────┘ │ ┌───────────┬───────────┼───────────┬───────────┐ ▼ ▼ ▼ ▼ ▼ ┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────┐ │ HUNTER ││ SPECTER ││ ARTEMIS ││ NIMBUS ││ NOMAD │ │ Network ││ API/Web ││ GenAI ││ Cloud ││ Mobile │ │ & Infra ││ Security ││ & LLM ││ & IaaS ││ iOS/Andr │ └──────────┘└──────────┘└──────────┘└──────────┘└──────────┘ ``` ## 代理 | 代理 | 角色 | 模型 | 命名来源 | |-------|------|-------|-------------| | **GRIMNIR** | 协调器 / PM | opus | 奥丁的面具（“戴兜帽的人”） | | **HUGINN** | 侦察与情报 | sonnet | 奥丁的渡鸦（“思想”） | | **Specter** | API 与 Web 安全 | sonnet | — | | **ARTEMIS** | GenAI 与 LLM 安全 | sonnet | AI 红蓝对抗参与、方法论与情报系统 | | **Hunter** | 网络与基础设施 | sonnet | — | | **Nimbus** | 云与 IaaS 安全 | sonnet | 云（雨云） | | **Nomad** | 移动端安全 | sonnet | 漫游 / 移动设备 | 所有专家代理（Specter、ARTEMIS、Hunter、Nimbus、Nomad）都包含一个**操作协议**，该协议定义了用于状态更新（由阶段转换触发）、情报记录（由跨代理相关发现触发）和情报消费（在启动时检查路由的情报）的事件驱动规则。这确保了代理能够一致地使用数据系统，而无需硬编码的配额。 ## 快速开始 ``` # 通过 wrapper 启动（推荐） grimnir # 或从项目目录 cd ~/workspace/grimnir && claude ``` 启动时，GRIMNIR 会显示可用的命令。你可以使用斜杠命令或自然语言： ``` # Slash 命令 /engage acme-corp # Start engagement (reads project.md if it exists) /full-audit acme-corp # Jump straight to testing # 自然语言 — GRIMNIR 自动检测意图 "I need to pentest acme-corp, details are in project.md" "Test the API at https://api.acme.com" "Resume the acme-corp engagement" ``` ### 项目录入文件 在开始之前创建 `~/workspace//project.md` —— GRIMNIR 会在执行 `/engage` 时自动读取它： ``` # 复制 template mkdir -p ~/workspace/acme-corp cp ~/workspace/grimnir/templates/project.md ~/workspace/acme-corp/project.md # 使用您的目标详情、credentials、scope 等进行编辑。 ``` 录入文件取代了手动问答 —— GRIMNIR 会从中提取目标信息、凭据、范围和优先级。模板位于 `templates/project.md`。如果不存在录入文件，GRIMNIR 会以交互方式询问详细信息。 ## 命令 | 命令 | 描述 | |---------|-------------| | `/engage ` | 开始新测试（分类、界定范围、计划、初始化状态） | | `/scope ` | 定义测试范围和授权 | | `/recon ` | 协调侦察（委派给 HUGINN） | | `/net-audit ` | 网络/基础设施审计 | | `/api-audit ` | API/Web 审计 | | `/genai-audit ` | GenAI/LLM 审计 | | `/cloud-audit ` | 云/IaaS 审计 | | `/mobile-audit ` | 移动端 审计 | | `/full-audit ` | 综合审计 —— 先由 HUGINN 进行侦察，然后交由所有适用的专家处理 | | `/report` | 根据所有代理的发现生成统一报告 | | `/resume [agent]` | 从检查点恢复暂停或中断的测试 | | `/progress` | 测试进度仪表板 | | `/sitrep` | 战略态势报告 | | `/intel` | 查询并管理跨代理情报源 | ## 工作流 ``` /engage target │ ├── Classify target type ├── Define scope & authorization ├── Generate test plan │ ▼ /full-audit target │ ├── Phase 0: HUGINN recon (foreground) │ ├── Passive: subdomains, DNS, certs, URL archives │ ├── Active: port scan, service detection, HTTP probing │ ├── Fingerprint: technologies, WAF, headers, TLS │ ├── Map: crawling, JS analysis, endpoint discovery │ └── Output: asset-map.json + intel.jsonl │ ├── Phase 1: Specialists (parallel) + HUGINN correlator (background) │ ├── Specter: API/web testing (skips recon, uses asset map) │ ├── ARTEMIS: AI/LLM testing (skips recon, uses asset map) │ └── Hunter: Network testing (skips discovery, uses asset map) │ ├── Phase 2: Cross-domain attack chains │ └── Phase 3: Unified reporting ``` ## 核心数据系统 GRIMNIR 包含三个基础数据层，用于实现结构化跟踪、跨代理情报共享和测试的可恢复性。 ### 1. 结构化发现 所有发现均通过 `scripts/finding.sh` 创建为带有配套 Markdown 的 JSON。每个代理都有特定类型的扩展： - **Specter**：endpoint、HTTP 方法、请求/响应、响应码 - **ARTEMIS**：成功率、模型、护栏状态、攻击向量 - **Hunter**：受影响的主机、端口、协议、CVE、获取的访问级别 发现支持**攻击链标记** —— `chain_id` 和 `chain_position` 字段将跨代理的相关发现链接到多步骤攻击叙事中（例如，Hunter 攻陷一台主机 → Specter 利用 Web 应用 → ARTEMIS 提取 AI 系统提示词）。 **验证（证据强度）。** 每一个发现都包含一个 `validation.state`，与分诊 `status` 正交：`theoretical`（推测为真，无复现 PoC）、`validated`（已复现）、`confirmed`（可复现 PoC 加上独立检查）或 `refuted`（已反驳）。新发现默认为 `theoretical`。一旦被证明，`scripts/validate-finding.sh` 会提升该发现的状态，记录其方法、**阴性对照**（区分真正的身份验证绕过与外观相同响应的准则），以及用于视觉/图像确认的可选截图。报告编译器和外部提交流程强制执行一道**门控**：只有 `confirmed`/`validated` 的发现才能进入报告正文；`theoretical` 的发现被保留在“未验证”附录中，且绝不会被提交。这使得“不盲目批准”成为数据的固有属性，而非一种习惯。 发现按代理分别存储（`$PROJECT_DIR//findings/FINDING-NNN.json`），并在生成报告时合并。Schema：`schemas/finding.schema.json`。 ### 2. 测试状态 `scripts/state.sh` 在 `state.json` 中跟踪每个代理的阶段、状态、进度和发现数量。支持： - 带有自动历史记录跟踪的**阶段转换** - 用于会话恢复的**检查点**（已完成的测试、待处理的测试、最后一次操作） - **自动派生状态** —— 根据代理状态计算出的整体测试状态 Schema：`schemas/state.schema.json`。 ### 3. 情报源 `scripts/intel.sh` 管理 `intel.jsonl` —— 一个用于跨代理情报共享的只追加 JSONL 源。发现类型包括端点、服务、凭据、技术、漏洞提示、子域、证书和关系。 情报项被标记以进行路由（`needs-huginn`、`needs-specter`、`needs-artemis`、`needs-hunter`、`high-value`），以便代理可以接收来自其他代理的发现。 HUGINN 会在阶段 0 侦察期间预先填充情报源，以便专家们能在拥有丰富上下文的情况下开始工作。 Schema：`schemas/intel.schema.json`。 ### 4. 交接 Payload `scripts/handoff.sh` 自动将测试状态序列化为结构化的 JSON Payload，用于代理委派。它读取 `state.json`、`scope.md`、`asset-map.json` 和 `intel.jsonl`，然后输出一个单一的 JSON Payload，包含： - 测试 ID、目标信息、范围（包含/排除） - 与代理相关的资产映射部分（Specter 获取端点/WAF，Hunter 获取主机/端口，ARTEMIS 获取 AI 指标） - 路由到目标代理的未处理情报项 - 用于恢复中断工作的检查点数据（`--resume`） - 可选的速率限制、代理配置和截止期限 ``` # 标准 handoff bash scripts/handoff.sh --project-dir $HOME/workspace/acme-corp --agent specter # 从 checkpoint 恢复 bash scripts/handoff.sh --project-dir $HOME/workspace/acme-corp --agent hunter --resume ``` ### 5. 资产映射 HUGINN 生成 `asset-map.json` —— 整个攻击面的结构化清单。包括主机、子域、技术、端点、身份验证机制、AI 指标、WAF 检测、TLS 证书和 JS 分析结果。 专家们会在它们的交接 Payload 中收到相关部分，从而消除重复的侦察工作。 Schema：`schemas/asset-map.schema.json`。 ## 测试数据 所有测试数据均使用绝对路径存储在 `~/workspace/$PROJECT/` 下。这在系统级别、项目级别以及每个代理定义中都被强制执行。 ``` ~/workspace/acme-corp/ (example engagement) ├── project.md # Intake file (target, creds, scope, priorities) ├── scope.md # Authorization and scope ├── classification.md # Target classification ├── test-plan.md # Unified test plan ├── state.json # Engagement state (state.sh) ├── intel.jsonl # Cross-agent intel feed (intel.sh) ├── asset-map.json # HUGINN's asset inventory ├── recon/ # HUGINN's recon output (shared) ├── specter/ # Specter's working directory │ ├── recon/ │ ├── findings/ # FINDING-NNN.json + .md │ └── reports/ ├── artemis/ # ARTEMIS's working directory │ ├── recon/ │ ├── findings/ │ └── reports/ ├── hunter/ # Hunter's working directory │ ├── recon/ │ ├── findings/ │ └── reports/ ├── findings/ # Merged findings (post-dedup) ├── evidence/ # Screenshots, PoCs, captures ├── logs/ # Tool output, scan logs └── report.md # Unified final report ``` ## 项目结构 ``` grimnir/ ├── CLAUDE.md ← Orchestrator identity, workflow, classification rules ├── .claude/ │ ├── agents/ ← Agent definitions (HUGINN, Hunter, Specter, ARTEMIS, report-compiler) │ ├── commands/ ← Slash commands (/engage, /recon, /intel, etc.) │ ├── skills/ ← Target classification, engagement management │ └── settings.json ← Permissions and hooks ├── schemas/ ← JSON schemas (findings, state, intel, asset-map) ├── scripts/ ← Core scripts (finding.sh, validate-finding.sh, state.sh, intel.sh, handoff.sh) ├── docs/ ← Project documentation (landscape analysis, etc.) ├── templates/ ← Report template, finding rendering, project intake template ├── huginn/ ← Reconnaissance & intel agent │ ├── .claude/ ← 8 per-technique recon skills (each ends in Log & Route) │ ├── scripts/ ← 3 scripts (recon-pipeline, asset-map, correlator) │ └── docs/ ← Recon methodology ├── hunter/ ← Network & infrastructure agent │ ├── .claude/ ← 6 commands, 10 skills, settings │ ├── scripts/ ← 6 scripts (discovery, enum, vuln scan, cred spray, SMB, full audit) │ └── wordlists/ ← Ports, credentials, SNMP communities ├── specter/ ← API & web security agent │ ├── .claude/ ← 7 subagents, 21 per-class skills (each ends in Validate & Promote), 10 commands │ ├── scripts/ ← 8 scripts │ ├── wordlists/ ← 9 wordlists │ └── templates/ ← Nuclei templates, checklists ├── artemis/ ← GenAI & LLM security agent │ ├── .claude/ ← 7 subagents, 11 skills (each ends in Validate & Promote), 11 commands │ ├── scripts/ ← 9 scripts │ ├── wordlists/ ← 9 wordlists │ └── references/ ← OWASP, methodology, payloads ├── nimbus/ ← Cloud & IaaS security agent (NIMBUS) │ ├── .claude/ ← 6 per-class cloud skills (each ends in Validate & Promote) │ ├── scripts/ ← 4 scripts (cloud-recon, iam-enum, storage-scan, metadata-probe) │ └── wordlists/ ← bucket permutations, metadata endpoints ├── nomad/ ← Mobile (Android/iOS) security agent (NOMAD) │ ├── .claude/ ← 6 per-class mobile skills (each ends in Validate & Promote) │ ├── scripts/ ← 3 scripts (apk-recon, manifest-audit, mitm-setup) │ └── wordlists/ ← secret patterns, deeplink schemes └── setup/ ← Provisioning system ├── setup.sh ← Main entry point ├── profiles/ ← lite, standard, full └── modules/ ← Modular installers ``` ## 部署配置 ``` # Raspberry Pi / drop box (2-4GB) ./setup/setup.sh --profile lite # Pi 5 / VPS (4-8GB) ./setup/setup.sh --profile standard # Kali workstation (8GB+) ./setup/setup.sh --profile full # 不安装直接预览 ./setup/setup.sh --dry-run --profile lite ``` | 配置 | 代理 | RAM | Metasploit | |---------|--------|-----|------------| | lite | HUGINN + Hunter（仅侦察） | 2-4GB | 否 | | standard | HUGINN + Hunter + Specter | 4-8GB | 可选 | | full | HUGINN + Hunter + Specter + ARTEMIS | 8GB+ | 是 | ## 框架覆盖 | 框架 | 代理 | 类别 | |-----------|-------|-----------| | PTES | Hunter | 网络/基础设施方法论 | | MITRE ATT&CK | Hunter | 对抗战术和技术 | | OWASP API Top 10 (2023) | Specter | API1-API10 | | OWASP WSTG v5.0 | Specter | WSTG-* | | OWASP LLM Top 10 (2025) | ARTEMIS | LLM01-LLM10 | | OWASP Agentic Top 10 (2026) | ARTEMIS | ASI01-ASI10 | | MITRE ATLAS | ARTEMIS | 对抗性 ML 战术 | ## 目标分类 GRIMNIR 会自动对目标进行分类，以决定部署哪些代理。HUGINN 始终首先运行阶段 0 侦察。 | 目标类型 | 专家 | 示例 | |-------------|-------------|---------| | IP / CIDR / 主机名 | Hunter | `10.10.10.0/24`、`server.corp.local` | | REST API | Specter | OpenAPI/Swagger、JSON 端点 | | GraphQL / gRPC | Specter | `/graphql`、HTTP/2 + protobuf | | Web 应用程序 | Specter | HTML 表单、服务器渲染页面 | | LLM 聊天机器人 | ARTEMIS | 聊天界面、AI 响应 | | RAG 应用程序 | ARTEMIS + Specter | 文档上传 + AI + API 层 | | 智能体系统 | ARTEMIS | 具有工具使用的 AI、自主行动 | | 全栈 AI 产品 | Specter + ARTEMIS | API 层 + AI 层 | | 基础设施 + 应用 | Hunter + Specter | 主机上的混合服务 | | 云账户 / 存储 / serverless / K8s | Nimbus | 云凭据、S3/Blob/GCS、Lambda/Functions、EKS/GKE/AKS | | 移动应用 (Android/iOS) | Nomad（+ Specter 负责后端） | APK/IPA、深度链接、应用商店列表 | ## 路线图 - **漏洞利用/CVE 情报库** —— 共享的、跨代理的 CVE 数据、公开 PoC 和活跃漏洞利用（NVD、CISA KEV、searchsploit、nuclei-templates）查询，独立于单次测试的情报 - **无头浏览器** —— 使用 Playwright/Chromium 捕获验证截图，并测试代理无法察觉的客户端/DOM 漏洞 - **主动侦察** —— 在长期知识库上安排定期的 HUGINN 侦察，以便搁置的项目也能受到监控 - **范围强制执行** —— 代理在发送请求前调用 `scripts/scope.sh` 以验证目标 - **复测模式** —— `/retest` 命令，针对已确认的发现重放复现步骤 - **自定义 nuclei 模板** —— 根据已确认的发现 JSON 自动生成模板 - **多提供商支持** —— 适用于 Gemini 和其他 LLM 提供商的模型无关变体 ## 许可证 MIT —— 见 [LICENSE](LICENSE)。仅供授权的安全测试、漏洞赏金和研究使用。

标签：AI智能体编排, GitHub, Homebrew安装, 安全报告生成, 实时处理, 密码管理, 应用安全, 时序数据库