dnzgrkn/WardHound
GitHub: dnzgrkn/WardHound
WardHound 是一款将 NAC、PAM、Active Directory 和防火墙事件关联为跨系统安全事件并执行人工审批响应的 SOAR 管线。
Stars: 1 | Forks: 0
# WardHound
*将企业安全事件追溯至根本原因。*
WardHound 是一款安全事件关联、根因分析和响应编排的 MVP，面向跨 NAC、PAM、Active Directory 和防火墙基础设施的运维人员。它将来自各个独立控制点的标准化信号转化为可解释的事件、确定性的风险评分以及可审查的响应请求。
这种刻意设计的职责划分很简单：规则决定关联的内容和风险评分方式；AI 负责解释保留的证据，但不能发出任意命令；安全状态的变更必须由人工批准；除非明确满足特定集成的安全门控，否则外部变更将被禁用。
## 架构
```
flowchart LR
Sources["NAC / PAM / AD / firewall events"]
Collectors["Collectors
tested parsing + normalization logic
scheduled JumpServer polling"] Normalize["NormalizedEvent contract"] Engines["Correlation → policy → risk
deterministic engines"] Store["Event + incident + analysis stores
IN-MEMORY / lost on restart"] AI["AI analysis engine
on demand / structured output"] Response["Response engine
human approval for privileged actions
seven gated integrations + real approval audit"] Dashboard["Dashboard
REST + WebSocket"] Infra[("PostgreSQL + Redis + Celery
durable infrastructure present
not connected to incident state")] Telemetry["Cross-cutting telemetry
Prometheus + Grafana + Jaeger"] Sources --> Collectors --> Normalize --> Engines --> Store Store --> AI --> Response --> Dashboard Store --> Dashboard Infra -. "health / infrastructure only" .-> Store Collectors -.-> Telemetry Engines -.-> Telemetry AI -.-> Telemetry Response -.-> Telemetry Dashboard -.-> Telemetry classDef memory fill:#fff3cd,stroke:#a66f00,color:#332200; classDef simulated fill:#fde2e2,stroke:#a12828,color:#3b1010; classDef durable fill:#dff3e4,stroke:#26733a,color:#102d18; class Store memory; class Response simulated; class Infra durable; ``` 图例：黄色代表进程本地状态，红色代表受安全门控控制的响应行为，绿色代表持久化基础设施。绿色服务并不意味着当前的 incident 工作流会持久化到其中。 ## 运行演示 前置条件包括 Docker 和 Docker Compose，且需要可用端口 3000、3001、8000、9090 和 16686。 1. 将 [`.env.example`](.env.example) 复制到 `.env`。 2. 替换该本地文件中所有必填的占位符。如果不需要 AI 分析，请将 `ANTHROPIC_API_KEY` 留空；不要提交 `.env`。 3. 构建并启动技术栈： docker compose up --build 4. 在 打开仪表板。在标准化安全事件被摄入且关联 pipeline 接收到完整的证据链之前，仪表板会保持空白。
在获得授权的实验室环境中，使用针对 [Active Directory](scripts/ingest_ad_events.py)、[PacketFence](scripts/ingest_packetfence_live.py) 和 [JumpServer](scripts/ingest_jumpserver_live.py) 的收集器桥接脚本来填充真实证据。每个脚本都记录了其所需的环境和命令行选项。您也可以直接通过 `POST /api/v1/events` 提交标准化事件；有关请求 schema，请参阅交互式的 [OpenAPI 文档](http://localhost:8000/docs)。
如果没有 Anthropic key，关联的事件和实时更新仍然可用，但由于建议来自 AI 分析，仪表板无法启动其由建议驱动的响应工作流。在 `.env` 中设置 `ANTHROPIC_API_KEY`，重启 API，打开一个关联的事件，并明确请求分析以调用配置好的 Anthropic 模型。分析成功后，其建议的操作将显示在仪表板中；提交操作将创建一条审计记录。特权操作需要批准。在未配置集成设置的情况下，每一个外部响应都将停留在其模拟路径上。只有当 `PACKETFENCE_BASE_URL`、`PACKETFENCE_API_TOKEN`、租户特定的 `PACKETFENCE_ISOLATION_SECURITY_EVENT_ID` 以及 `PACKETFENCE_REAL_EXECUTION=true` 全部设置完毕后，PacketFence 的执行才是真实的。只有当 `AD_LDAP_URL`、`AD_BIND_DN`、`AD_BIND_PASSWORD`、`AD_USER_SEARCH_BASE_DN` 以及 `AD_REAL_EXECUTION=true` 全部设置完毕后，Active Directory 的禁用操作才是真实的。只有当 `FMC_BASE_URL`、`FMC_USERNAME`、`FMC_PASSWORD`、`FMC_BLOCKLIST_NETWORK_GROUP_ID` 以及 `FMC_REAL_EXECUTION=true` 全部设置完毕后，FMC 的黑名单成员资格才是真实的；在执行强制拦截之前，部署 FMC 仍然是运维人员明确的职责。只有当 `JUMPSERVER_BASE_URL`、`JUMPSERVER_API_TOKEN` 以及 `JUMPSERVER_REAL_EXECUTION=true` 全部设置完毕后，JumpServer 的终止操作才是真实的；WardHound 会在终止任务被接受后确认 `is_finished`。只有当 `DUO_API_HOSTNAME`、`DUO_INTEGRATION_KEY`、`DUO_SECRET_KEY` 以及 `DUO_REAL_EXECUTION=true` 全部设置完毕后，Duo 才会发送并确认即时的验证推送；它不会宣称能重置所有已记住设备的会话。只有当 `NOTIFY_WEBHOOK_URL` 和 `NOTIFY_REAL_EXECUTION=true` 均设置时，管理员通知才会使用兼容 Slack 的 webhook。只有当 `TICKETING_WEBHOOK_URL` 和 `TICKETING_REAL_EXECUTION=true` 均设置，且成功要求返回非空的 `ticket_id` 时，才会使用独立的、与供应商无关的 webhook 来创建外部工单。请将这两个 webhook URL 视为 bearer-token 凭据：仅将它们保留在环境中，切勿记录到日志中。手动批准不需要集成门控：一旦 `ResponseEngine.approve()` 持久化了 Auth0 principal 和决定时间，其处理程序就会报告已完成的 checkpoint 及 `mode=real`。如果 Anthropic key 为空，分析请求将返回明确的 `503 analysis_not_configured`；确定性的数据摄入和 incident 视图仍将保持功能正常。
这是一个**本地配置演示**，而不是字面意义上的零配置启动：Compose 会有意拒绝启动，直到 `.env.example` 中引用的必填的本地数据库、broker、API key 和 Grafana 值都存在。该 API key 由前端和后端共享，仅适用于这种单运维人员环境。
### 暴露的访问端点
| 端点 | 地址 | 用途 |
| --- | --- | --- |
| Dashboard | | Incident 分流、分析和响应审批 |
| API / OpenAPI | | 交互式 REST API 文档 |
| Grafana | | 预配置的 WardHound 运维仪表板 |
| Prometheus | | 指标抓取与查询 |
| Jaeger | | 分布式 trace 探索 |
| 原始 API 指标 | | Prometheus 抓取 endpoint |
`/metrics` 专供私有网络下的 Prometheus 抓取使用，特意取消了身份验证。任何非本地部署都必须在网络边界对其进行隔离。Grafana、Prometheus 和 Jaeger 也会暴露运维安全数据，需要配置生产环境的访问控制。
要停止技术栈，请运行 `docker compose down`。仅在您有意要删除本地 PostgreSQL 和 Grafana 卷时才添加 `--volumes` 参数；因为无论何时，只要 API 进程重启，WardHound 的 incident 状态就已经丢失了。
### 前端开发
如需使用独立的 Vite 开发服务器，请将 `frontend/.env.example` 复制到 `frontend/.env.local`，使用与后端相同的 API key，然后运行：
```
cd frontend
npm install
npm run dev
```
前端的质量检查命令包括 `npm run lint`、`npm run typecheck`、`npm run test:run` 和 `npm run build`。
### 身份设置
查看 incident 和使用读取/报告路由时，Auth0 是可选的。如果没有配置 Auth0，
静态的 `WARDHOUND_API_KEY` 依然可以授权标准化事件摄入、incident 读取、按需
分析、操作历史读取以及实时的 WebSocket 通知。请求、批准或
拒绝响应操作需要 Auth0 access token。
要在 Auth0 免费版租户上启用特权操作：
1. 在 **Applications → APIs** 中，创建一个名为 `WardHound API` 的 API。使用 URI 样式的标识符，例如
`https://wardhound-api.example`，并将签名算法保持为 RS256。启用 **RBAC** 和
**Add Permissions in the Access Token**。
2. 添加 API 权限 `request:actions` 和 `approve:actions`。
3. 在 **User Management → Roles** 中，创建一个包含 `request:actions` 权限的 `analyst` 角色。创建一个
同时包含这两个权限的 `approver` 角色，然后将测试用户分配到相应的角色。
4. 在 **Applications → Applications** 中，为 React
仪表板创建一个 **Single Page Application**。Auth0 React SDK 是一个公共的浏览器客户端，绝不能使用 client secret；如果没有服务器端的后端服务于前端，则 Regular Web Application 是不合适的。
5. 将 Allowed Callback URLs、Allowed Logout URLs 和 Allowed Web Origins 配置为
`http://localhost:3000`。复制应用程序的 Client ID 和租户域名。
6. 在根目录的 `.env` 中设置 `AUTH0_DOMAIN`、`AUTH0_AUDIENCE` 和 `AUTH0_CLIENT_ID`。Compose 会
将这些公共值作为 `VITE_AUTH0_DOMAIN`、`VITE_AUTH0_AUDIENCE` 和
`VITE_AUTH0_CLIENT_ID` 传递给前端。对于独立的前端开发，请使用 `frontend/.env.example` 作为模板，在 `frontend/.env.local` 中设置这些 `VITE_` 值。
域名值不包含 `https://`；audience 必须与 API 标识符完全匹配。前端环境或源代码控制中不得包含任何 Auth0 client secret。这些步骤遵循 Auth0 的
[FastAPI API 快速入门](https://auth0.com/docs/quickstart/backend/fastapi)、
[React SPA 快速入门](https://auth0.com/docs/quickstart/spa/react) 以及
[核心 RBAC 指南](https://auth0.com/docs/manage-users/access-control/configure-core-rbac/roles)。
## 验证案例研究
WardHound 的收集器格式和调查工作流程已针对来自一家中型企业 Zero Trust 项目的经过脱敏处理的 PacketFence NAC、JumpServer PAM 和 Active Directory 分层事件数据进行了验证。本代码库中不包含任何客户身份或生产环境标识符。具体的证据链和结果记录在[匿名案例研究](docs/CASE_STUDY.md)中。
## 工程原则与决策
WardHound 将确定性的安全决策与概率性的解释分离开来，在各层之间使用类型化的不可变 contract，将基础设施注入到小型接口之后，并要求在进行任何特权响应之前必须经过人工审查。决策历史记录了这些权衡：
- [ADR 0001](docs/adr/0001-record-architecture-decisions.md) — 记录重要的架构决策。
- [ADR 0002](docs/adr/0002-event-schema-and-collector-interface.md) — 共享事件 schema、实体模型和收集器边界。
- [ADR 0003](docs/adr/0003-collector-parsing-assumptions.md) — 经过验证的 PacketFence、JumpServer 和 AD 解析格式。
- [ADR 0004](docs/adr/0004-correlation-policy-risk-design.md) — 确定性关联、策略评估和风险评分。
- [ADR 0005](docs/adr/0005-ai-analysis-engine-design.md) — 结构化的、按需的、引用证据的 AI 分析。
- [ADR 0006](docs/adr/0006-response-engine-design.md) — 审批工作流和仅限模拟的响应边界。
- [ADR 0007](docs/adr/0007-incident-api-design.md) — Incident API、内存存储、静态 key 身份验证和实时更新。
- [ADR 0008](docs/adr/0008-observability-and-hardening.md) — 有边界的 telemetry、tracing、metrics 和测试强化。
- [ADR 0010](docs/adr/0010-auth0-identity-federation.md) — Auth0 联合身份验证、API 权限和可归因的响应决策。
- [ADR 0011](docs/adr/0011-real-packetfence-integration.md) — 经过安全门控的真实 PacketFence 隔离。
- [ADR 0012](docs/adr/0012-real-active-directory-disable.md) — 经过确认和安全门控的 Active Directory 账户禁用。
- [ADR 0013](docs/adr/0013-real-fmc-block-ip.md) — 带有明确部署状态的已确认 Cisco FMC 黑名单成员资格。
- [ADR 0014](docs/adr/0014-real-jumpserver-close-session.md) — 经过确认和安全门控的 JumpServer 会话终止。
- [ADR 0015](docs/adr/0015-real-duo-require-mfa.md) — 经过确认的、HMAC 签名的 Duo 验证挑战。
- [ADR 0016](docs/adr/0016-real-webhook-notification.md) — 经过安全门控、数据最小化的管理员 webhook 投递。
- [ADR 0017](docs/adr/0017-real-ticketing-webhook.md) — 经过确认的、与供应商无关的外部工单创建。
- [ADR 0018](docs/adr/0018-manual-approval-audit-accuracy.md) — 对已持久化的手动批准 checkpoint 的准确归因。
- [ADR 0019](docs/adr/0019-secrets-provider-interface.md) — 行为保持不变的、基于环境的异步 secret 检索接缝。
- [ADR 0020](docs/adr/0020-daily-security-digest.md) — 确定性的每日安全摘要聚合与可选的 AI 叙述。
- [ADR 0021](docs/adr/0021-real-collector-evidence-ingestion.md) — 经过三个实时并发系统验证的真实收集器证据摄入。
有关更广泛的设计和明确推迟的生产工作，请参阅[产品规范](docs/SPEC.md)、[路线图](docs/ROADMAP.md)和[威胁模型](docs/THREAT_MODEL.md)。
tested parsing + normalization logic
scheduled JumpServer polling"] Normalize["NormalizedEvent contract"] Engines["Correlation → policy → risk
deterministic engines"] Store["Event + incident + analysis stores
IN-MEMORY / lost on restart"] AI["AI analysis engine
on demand / structured output"] Response["Response engine
human approval for privileged actions
seven gated integrations + real approval audit"] Dashboard["Dashboard
REST + WebSocket"] Infra[("PostgreSQL + Redis + Celery
durable infrastructure present
not connected to incident state")] Telemetry["Cross-cutting telemetry
Prometheus + Grafana + Jaeger"] Sources --> Collectors --> Normalize --> Engines --> Store Store --> AI --> Response --> Dashboard Store --> Dashboard Infra -. "health / infrastructure only" .-> Store Collectors -.-> Telemetry Engines -.-> Telemetry AI -.-> Telemetry Response -.-> Telemetry Dashboard -.-> Telemetry classDef memory fill:#fff3cd,stroke:#a66f00,color:#332200; classDef simulated fill:#fde2e2,stroke:#a12828,color:#3b1010; classDef durable fill:#dff3e4,stroke:#26733a,color:#102d18; class Store memory; class Response simulated; class Infra durable; ``` 图例：黄色代表进程本地状态，红色代表受安全门控控制的响应行为，绿色代表持久化基础设施。绿色服务并不意味着当前的 incident 工作流会持久化到其中。 ## 运行演示 前置条件包括 Docker 和 Docker Compose，且需要可用端口 3000、3001、8000、9090 和 16686。 1. 将 [`.env.example`](.env.example) 复制到 `.env`。 2. 替换该本地文件中所有必填的占位符。如果不需要 AI 分析，请将 `ANTHROPIC_API_KEY` 留空；不要提交 `.env`。 3. 构建并启动技术栈： docker compose up --build 4. 在
标签：PAM, SOAR, Streamlit, 安全运营, 扫描框架, 搜索引擎查询, 日志关联分析, 测试用例, 版权保护, 自定义请求头, 访问控制, 请求拦截, 逆向工具