msaad00/quiver


Quiver — 131 个面向云和 AI 的生产级安全技能，逐一精心打造。遵循 OCSF 规范，支持 MCP，经过 HITL 审计，沙箱化运行，同一技能包可在所有环境运行。

## 从这里开始 | 需求 | 首选阅读 | 验证产物 | |---|---|---| | 运行本地流水线 | [`docs/QUICKSTART.md`](docs/QUICKSTART.md) | 基于测试夹具数据的 `findings.sarif` | | 挑选技能 | [`docs/SKILL_INDEX.md`](docs/SKILL_INDEX.md) | 包含 `SKILL.md`、`src/`、`tests/` 的技能包 | | 接入 Agent | [`docs/AGENT_QUICKSTART.md`](docs/AGENT_QUICKSTART.md) | 通过 `.mcp.json` 的 MCP 工具调用 | | 治理 Agentic SOC 工作流 | [`docs/HARNESS.md`](docs/HARNESS.md) | LangGraph 配置文件、审计账本、评估报告 | | 构建数据仓库湖 | [`docs/CLICKHOUSE_DATA_LAKE.md`](docs/CLICKHOUSE_DATA_LAKE.md) 或 [`docs/SNOWFLAKE_DATA_LAKE.md`](docs/SNOWFLAKE_DATA_LAKE.md) | 仅追加的湖表及重放查询适配器 | ## 为什么选择它 - **60 秒即插即用** — 仓库内置的 `.mcp.json` 可直接在 Claude Code 中使用；在 [`docs/AGENT_QUICKSTART.md`](docs/AGENT_QUICKSTART.md) 中提供了适用于 Claude Desktop、Cursor、Windsurf、Codex、Cortex、Zed 的复制粘贴配置。 - **每个技能都是单一关注点包** — 包含 `SKILL.md + src/ + tests/`，你可以将其作为 stdin/stdout 单行命令、MCP 工具、CI 步骤、webhook、库调用或持久化 runner 运行。同一个包，没有针对不同运行界面的差异。 - **专为 Agent 而非仅为人类设计** — 传输过程遵循 OCSF 1.8 规范，采用 HMAC 链式审计，并由包装器强制执行 HITL 门控和白名单交集——因此 LLM 无法绕过信任契约。 - **专为闭环安全工作设计** — 归一化、检测、评估、审查、预演、修复，并将审计/证据行写回归操作者所有的数据湖。 ## 快速入门 ``` # 1 · 克隆带标签的 release git clone --branch v0.11.0 https://github.com/msaad00/quiver.git cd quiver # 2 · 仅安装你需要运行的 skills 所需的 deps uv sync --group dev --group aws # or --group gcp / --group azure / --group mcp / --group iam_departures / --group langgraph / --group webhook — see docs/INSTALL.md # 3 · 对捕获的 fixture 运行检测（无需 cloud creds） python skills/ingestion/ingest-cloudtrail-ocsf/src/ingest.py \ skills/detection-engineering/golden/cloudtrail_raw_sample.jsonl \ | python skills/detection/detect-aws-access-key-creation/src/detect.py \ | python skills/view/convert-ocsf-to-sarif/src/convert.py \ > findings.sarif # 4 · 通过 MCP 接入任意 agent — 仓库内置的 .mcp.json 可在 Claude Code 中直接使用。 # 对于 Claude Desktop、Cursor、Windsurf、Codex、Cortex、Zed：请参阅 docs/integrations/。 ``` 六个运行界面，同一个技能包：**CLI · CI · MCP · webhook 接收器 · 库 · 持久化 runner**。相同的 `SKILL.md + src/ + tests/`，没有针对不同运行界面的差异。 ## 本仓库为您提供 **131 个已发布的技能包** — 原子化、确定性、单一关注点。其中十二个是受保护的写入路径；其余为只读技能或仅追加的源/输出适配器。将其放入流水线、Agent、Step Function 或 `python ... | python ...` 单行命令中即可使用。 | 层级 | 数量 | 目的 | 输出 | |---|---:|---|---| | **接入** | 22 | 归一化原始云 / 身份 / K8s / MCP / SaaS 信号 | OCSF 1.8（原生可选） | | **发现** | 5 | 清单 · 图 · AI BOM · 证据 · IAM 离职规划 | 原生 / 桥接 JSON | | **检测** | 71 | 带有 MITRE ATT&CK / ATLAS / OWASP 标签的确定性规则 | OCSF Detection Finding 2004 | | **评估** | 12 | 跨越 CIS / NIST / NIST AI RMF / SOC 2 的 143 项态势和基准检查 | 合规性结果 | | **修复** | 12 | 受保护的写入路径 — 3 个云平台的 IAM 离职，3 个网络撤销，4 个会话/凭证清理，2 个 K8s，MCP 工具隔离 | 受审计的操作轨迹 | | **视图** | 2 | 发现结果 → 审查格式 | SARIF · Mermaid | | **输出** | 3 | 仅追加接收器 | S3 · Snowflake · ClickHouse | | **来源** | 4 | 数据仓库查询适配器 | S3 Select · Snowflake · Databricks · ClickHouse | **总计：131 个已发布技能。** 实时计数和各框架覆盖率见 [`docs/COVERAGE_SNAPSHOT.md`](docs/COVERAGE_SNAPSHOT.md)（自动生成，CI 门控）。 **寻找技能：** [`docs/SKILL_INDEX.md`](docs/SKILL_INDEX.md) 按**环境**（AWS · GCP · Azure/Entra · K8s · 身份 · AI/MCP · Web · 跨环境）和**目的**（接入 / 发现 / 检测 / 评估 / 修复 / 视图 / 输出 / 来源）对所有已发布的技能进行分组，并指向用于控制目录枢纽的框架映射文档。 **今天哪些供应商信号归一化为了 OCSF？** [`docs/INGEST_COVERAGE.md`](docs/INGEST_COVERAGE.md) — 标准的供应商 × 来源 × OCSF 类别矩阵，**已发布 22 个接入技能**（AWS · GCP · Azure · Entra · K8s · Okta · Workspace · MCP · **GitHub · Slack · Workday · Salesforce · SAP**），外加明确的尚未发布的行（原生 ClickHouse 审计、AWS Web 应用数据外泄流水线以及 Workspace Drive / Mobile 深度检测）。 **为什么使用这些技能而不是临时的 Agent 代码？** [`docs/WHY.md`](docs/WHY.md) 比较了运行时 Python、提交 LLM 编写的技能以及从头构建目录的方法。简短版本如下： | 需求 | 本仓库已经为您提供 | |---|---| | Agent 可调用的执行 | 同一技能包上的 MCP、CLI、CI、webhook、库和 runner，以及在此基础上的 Agent SDK 和 LangGraph 示例 | | 信任契约 | HITL 门控、三层沙箱、HMAC 链式审计、白名单交集、OCSF 传输锁定 | | 维护的安全内容 | 真实语料库阈值、OCSF 版本升级、MITRE 目录更新、供应商 schema 偏移处理 | | 成本基准 | 约需 12 个工程师周的测试框架开发，加上约 240 小时的检测器内容，才能达到 v0.10.0 的同等水平，这还不包括后续的持续维护 | **独立的安全评分。** [`docs/SECURITY_GRADES.md`](docs/SECURITY_GRADES.md) — 自动生成，每周由 `scripts/regen_security_grades.py` 重新生成：Bandit（代码发现）、pip-audit（CVE）、agent-bom（技能信任 + 来源）、14 个仓库内信任契约验证器。综合评分位于文档顶部。 ## 架构 外部信号通过两个接入层进入，经过两个分析层，通过两个行动层退出，并通过一个输出层持久化。MCP、CLI、CI、webhook、库调用和 runner 都调用同一个技能包——运行界面只是传输方式，而不是行为本身。  CLI、CI、MCP、webhook、库、runner 等运行界面记录在下方的 [`Agent 集成`](#agent-integrations) 表中；它们都导入相同的技能包，因此不需要绘制第二个契约。 更多图表（Mermaid 源码位于 [`docs/diagrams/`](docs/diagrams/) 下，GitHub 支持内联渲染）： - [`skill-hierarchy.mmd`](docs/diagrams/skill-hierarchy.mmd) — 每个已发布的层 × 每个已发布的技能，按子域（AWS / GCP / Azure / 身份 / K8s / AI-MCP / Web）分组 - [`surface-comparison.mmd`](docs/diagrams/surface-comparison.mmd) — 六个已发布的运行界面（CLI · CI · MCP · webhook · 库 · runner）以及其背后隐藏的八个信任控制 - [`pipeline-blast-radius.mmd`](docs/diagrams/pipeline-blast-radius.mmd) — 按能力进行颜色编码，以便一目了然地查看信任边界 - [`mcp-trust-boundary.mmd`](docs/diagrams/mcp-trust-boundary.mmd) — 包装器生命周期序列（每个守卫，每个短路分支） - [`agent-topology.mmd`](docs/diagrams/agent-topology.mmd) — 本地 stdio 客户端 vs 远程 / HTTP / 库 / runner - [`agentic-soc-orchestrator.mmd`](docs/diagrams/agentic-soc-orchestrator.mmd) — 基于确定性技能和不可绕过信任轨道的可选 LangGraph / LangChain 工作流 - [`langgraph-agent-harness.mmd`](docs/diagrams/langgraph-agent-harness.mmd) — 具有 HITL、重试、升级和审计/评估路由的多 Agent LangGraph 测试框架 深入阅读：[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) · [`docs/HARNESS.md`](docs/HARNESS.md) · [`docs/SKILL_CONTRACT.md`](docs/SKILL_CONTRACT.md) · [`docs/SKILL_COMPOSITION.md`](docs/SKILL_COMPOSITION.md) 设计原则刻意保持简单：确定性技能拥有证据、schema、映射、置信度、策略、写入意图和审计。可选的协调器拥有工作流状态、节点排序、模型选择、重试、升级和检查点。 ## Agentic SOC 编排 当技能保持确定性，而 LangGraph / LangChain 作为可选的工作流引擎位于其上时，该仓库能发挥最强效能。这比 让每个技能都原生支持 LangGraph 更好：CVSS、MITRE、EPSS、KEV、OCSF schema、 租户范围、白名单、置信度、预演状态和审计记录保持为 可重现的代码路径，而由图决定接下来调用哪个已批准的运行界面。 已发布的 [`examples/agents/langgraph_security_graph.py`](examples/agents/langgraph_security_graph.py) 展示了作为实际可选 LangGraph `StateGraph` 的参考模式： 每个技能层对应一个图节点，一个有限的多 Agent 框架，显式 状态，一个 Agent 运行账本，用于 HITL/重试/升级/回写的条件 边，以及在修复之前的硬性 HITL 节点。端到端路线为 `接入 -> 归一化 -> 丰富 -> 关联 -> 置信度评分 -> MITRE/CVSS/EPSS/KEV 映射 -> LLM 分诊 -> 分析师审查 -> 预演修复 -> 重试/升级/回写 -> 审计/评估`， 而无需将信任转移到提示词中。 操作者自定义是基于配置文件的：请参阅 [`examples/agents/harness_profiles/`](examples/agents/harness_profiles/) 了解 只读 SOC、分析师分诊和 HITL 门控的预演修复配置文件。 配置文件设置白名单、调用者上下文、身份提示和模型元数据； 它们从不存储机密或授予权限。 [`examples/agents/evals/`](examples/agents/evals/) 中的黄金评估夹具 离线重放这些路线，并针对框架偏差输出通过率报告。 可选的 LLM 适配器路径受 schema 限制：模型输出可以对分诊理由进行排序和起草， 但尝试设置审批、CVSS/MITRE/EPSS/KEV 事实、 租户范围、幂等键或写入意图的操作将被拒绝，并回退到 确定性分诊。 Token 的使用由相同的框架配置控制：针对有限任务的 小模型路由，分诊前的提示词压缩，每个节点的预算，以及 针对通过率和成本偏差的评估回写。完整性哈希、幂等键 以及可重试与终止的 API 错误路由保持在确定性状态中，而不是在 模型输出中。  | 层级 | 归属 | 原因 | |---|---|---| | 事实、schema、评分、映射 | `quiver` | 可重现、可测试、CI 门控，与技能契约绑定 | | 工作流状态与分支 | LangGraph / LangChain / SOAR | 节点、边、重试、升级、检查点 | | LLM 输出 | 协调器 | 排序、总结、解释和起草；对于策略或审计从不具有权威性 | | 写入批准 | HITL 门控 + 修复技能 | 先预演，有限的爆炸半径，经过审计的操作者上下文 | | Agentic 关注点 | 执行位置 | |---|---| | 数据源选择 | 框架配置：原始接入、安全数据湖重放或夹具 | | Token 与模型预算 | 模型路由器 + 配置限制，在 LLM 分诊前进行压缩 | | 完整性与幂等性 | 归一化的状态哈希和修复幂等键 | | API 失败 | 在回写之前进行确定性的可重试与终止路由 | | 无虚构事实 | 受 schema 限制的 LLM 适配器；映射和评分来自代码 | ## 基于 ClickHouse 的安全数据湖（核心用例） 本仓库在 ClickHouse 上提供了一个端到端、闭环的案例：OCSF 接入技能通过 `sink-clickhouse-jsonl` 进行写入，检测器在只读 SQL 白名单下从 `source-clickhouse-query` 重放，修复审计记录可以落回同一个数据湖中。无状态技能，有状态的数据湖，具备用于支持感知重复数据重放的稳定 UID。  | 阶段 | 技能 | 角色 | |---|---|---| | 写入 | [`sink-clickhouse-jsonl`](skills/output/sink-clickhouse-jsonl/SKILL.md) | 仅追加插入 · 默认预演 · 验证标识符 | | Schema | [`packs/clickhouse/`](packs/clickhouse/) | 一次性 DDL · 物化视图 · 行级策略 · TTL | | 读取 | [`source-clickhouse-query`](skills/ingestion/source-clickhouse-query/SKILL.md) | 只读 SQL 白名单 · 仅限 `SELECT` / `WITH` / `SHOW` / `DESCRIBE` | | 重放 | 任何 `detect-*` / `view-*` / `discover-control-evidence` | 针对历史数据湖行重新运行相同的技能包 | | 循环 | `sink-clickhouse-jsonl` → 发现结果 / 证据 / 审计 | 重放输出落回仅追加表中 | 为什么选择 ClickHouse 作为此数据湖 — 操作者拥有部署权、MergeTree 表、物化视图汇总、无需外部生命周期服务的 `TTL` 数据保留，以及用于多租户隔离的行级策略。完整的案例详解：[`docs/CLICKHOUSE_DATA_LAKE.md`](docs/CLICKHOUSE_DATA_LAKE.md)。当客户已经标准化使用另一个数据仓库或对象存储湖契约时，使用另一条已发布的接收器/源通道。 ## 基于 Snowflake 的安全数据湖（核心用例） 相同的闭环以仓库原生的形式在 Snowflake 上发布，适用于在那里运行其企业湖屋的客户：OCSF 接入技能通过 `sink-snowflake-jsonl` 写入，检测器在只读 SQL 白名单下从 `source-snowflake-query` 重放，修复审计记录落回同一个数据湖。基于当前的 Snowflake 构建 — 动态表汇总、行访问策略以及可选的 Snowflake 管理的 Apache Iceberg 变体，以便数据湖保持开放格式，并可通过 Horizon Catalog 被 Spark/Trino 读取。  | 阶段 | 技能 | 角色 | |---|---|---| | 写入 | [`sink-snowflake-jsonl`](skills/output/sink-snowflake-jsonl/SKILL.md) | 仅追加插入 · 默认预演 · 验证标识符 | | Schema | [`packs/snowflake/`](packs/snowflake/) | 一次性 DDL · 动态表汇总 · 行访问策略 · 托管 Iceberg 选项 | | 读取 | [`source-snowflake-query`](skills/ingestion/source-snowflake-query/SKILL.md) | 只读 SQL 白名单 · 仅限 `SELECT` / `WITH` / `SHOW` / `DESCRIBE` | | 重放 | 任何 `detect-*` / `view-*` / `discover-control-evidence` | 针对历史数据湖行重新运行相同的技能包 | | 循环 | `sink-snowflake-jsonl` → 发现结果 / 证据 / 审计 | 重放输出落回仅追加表中 | 为什么选择 Snowflake 作为此数据湖 — 托管弹性、统一的 Horizon Catalog 治理、原生 Trust Center 安全态势信号，以及避免引擎锁定的开放式 Apache Iceberg 存储。完整的案例详解：[`docs/SNOWFLAKE_DATA_LAKE.md`](docs/SNOWFLAKE_DATA_LAKE.md)。如果要选择自托管、低延迟且操作者拥有的数据湖，请改用 ClickHouse 通道。 ## Agent 集成 每个 Agent / IDE 都通过相同的 stdio MCP 包装器。审计跟踪、HITL 门控、白名单、RLIMIT 强制执行和超时在不同客户端中完全一致。 | 客户端 | 文档 | 传输方式 | |---|---|---| | Claude Code (CLI) | 仓库根目录 [`.mcp.json`](.mcp.json) — 已内置 | stdio | | Claude Desktop | [`docs/integrations/claude-desktop.md`](docs/integrations/claude-desktop.md) | stdio | | Claude.ai (Web) | [`docs/integrations/claude-ai-web.md`](docs/integrations/claude-ai-web.md) | 不适用 — 指向桌面版 / 代码版 | | Cursor · Windsurf · Codex · Cortex · Zed | [`docs/integrations/`](docs/integrations/) | stdio | | Continue · Cody · 通用 MCP 客户端 | [`docs/integrations/ide-agents.md`](docs/integrations/ide-agents.md) | stdio | | Anthropic Agent SDK · OpenAI SDK · LangGraph | [`examples/agents/`](examples/agents/) | stdio + Python 框架 | | Webhook (S3 EventBridge / 供应商回调 / API 网关) | [`runners/webhook-receiver/`](runners/webhook-receiver/) | HTTP，HMAC + bearer | | 库（任何 Python 应用） | [`skills/_shared/library.py`](skills/_shared/library.py) | 进程内子进程 | 针对四个已发布的用例，在 [`presets/`](presets/) 下提供了预制的 MCP 白名单 — CSPM 只读 · 仅检测 · 事件响应 · AI 运行时。相关的工作流位于 [`examples/workflows/`](examples/workflows/) 下。 ## 信任态势 | 层级 | 内容 | |---|---| | **审计** | 每次调用一条持久的 JSONL 记录 · HMAC-SHA-256 链 · 防篡改验证器 ([`docs/MCP_AUDIT_CONTRACT.md`](docs/MCP_AUDIT_CONTRACT.md)) | | **白名单** | 操作者环境 ∩ 调用者上下文 ∩ 工作流预设；在 webhook 界面上默认拒绝 | | **默认只读** | 基于类别派生；AST 门控拒绝在只读技能中进行云写入调用 | | **写入路径** | 预演优先 · HITL 门控 · 在子进程触发前强制执行 `min_approvers` | | **RLIMIT** | 限制每个子进程：1 GB 虚拟内存，100 MB 单个文件写入，CPU = 包装器超时 + 宽限期 | | **容器** | 非 root 用户 UID 65532 · 只读 rootfs · `--cap-drop=ALL` · `no-new-privileges` · 默认 seccomp | | **重试** | 结构上受限制：≤ 10 次尝试，≤ 600 秒挂钟时间预算，无递归重试 ([`skills/_shared/retry.py`](skills/_shared/retry.py)) | | **无硬编码机密** | CI grep 检查，仅使用工作负载身份 | 阅读 [`SECURITY.md`](SECURITY.md) · [`SECURITY_BAR.md`](SECURITY_BAR.md) · [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md) · [`docs/RUNTIME_ISOLATION.md`](docs/RUNTIME_ISOLATION.md)。 ## 合规框架 OCSF 1.8 · MITRE ATT&CK v14 · MITRE ATLAS · OWASP Top 10 · OWASP LLM Top 10 · OWASP MCP Top 10 · NIST CSF 2.0 · NIST AI RMF 1.0 (GOVERN · MAP · MEASURE · MANAGE) · CIS AWS / GCP / Azure / K8s / 容器 / Docker / Controls v8 · SOC 2 TSC · ISO 27001:2022 · PCI DSS 4.0 · CycloneDX ML-BOM。 实时覆盖表（技能 × 框架 × 云平台 × 层级）：[`docs/COVERAGE_SNAPSHOT.md`](docs/COVERAGE_SNAPSHOT.md)。各技能的映射：[`docs/FRAMEWORK_MAPPINGS.md`](docs/FRAMEWORK_MAPPINGS.md)。

为什么不同层使用不同的格式

OCSF 1.8 是 SIEM 互操作传输格式——其价值正好体现在事件流向下游分析器的地方。它并不是通用的内部格式，本仓库如实说明了它的适用场景： | 层级 | 默认 | 理由 | |---|---|---| | **接入** · **检测** | OCSF 1.8 | SIEM 可以原生消费它 | | **评估** | 原生（可选 OCSF 2003） | 运维仪表盘偏好原生格式；SIEM 可选择开启 | | **发现** | 原生 / CycloneDX ML-BOM / 桥接 | 资产清单图不是事件 | | **修复** | 原生 | 状态更改，带有操作者拥有的审计跟踪 | | **视图** | 输入 OCSF，输出 SARIF / Mermaid | 其核心目的是将 OCSF 渲染给人类 | | **输出（接收器）** | 透传 | 接收器写入生产者发出的任何内容 | 完整讨论：[`docs/ARCHITECTURE.md §3 + §6`](docs/ARCHITECTURE.md)。锁定的 OCSF 契约：[`skills/detection-engineering/OCSF_CONTRACT.md`](skills/detection-engineering/OCSF_CONTRACT.md)。

闭环覆盖 — 哪些检测配有相应的修复


## 安装 · 运行时 · 信任契约 - [`docs/INSTALL.md`](docs/INSTALL.md) — 下载、验证、安装、运行 - [`docs/HARNESS.md`](docs/HARNESS.md) — 六个运行界面 · 自定义旋钮 · 范围边界 · Anthropic 对齐 - [`docs/SUPPLY_CHAIN.md`](docs/SUPPLY_CHAIN.md) — SBOM、签名、来源 - [`docs/CREDENTIAL_PROVENANCE.md`](docs/CREDENTIAL_PROVENANCE.md) — 工作负载身份优先 - [`docs/RELEASE_CHECKLIST.md`](docs/RELEASE_CHECKLIST.md) — 发布门控 ## 路线图 实时更新：[`docs/COVERAGE_SNAPSHOT.md`](docs/COVERAGE_SNAPSHOT.md) 包含自动生成的框架 × 云 × 层覆盖率。路线图追踪实时发布在 GitHub Issues 中 — 参见 [`#253`](../../issues/253) (MITRE ATT&CK)、[`#254`](../../issues/254) (CIS 深度)、[`#255`](../../issues/255) (MITRE ATLAS · OWASP LLM · OWASP MCP)。 ## 与 agent-bom 集成 本仓库提供安全自动化功能。[`agent-bom`](https://github.com/msaad00/agent-bom) 提供持续扫描和统一图谱。将它们结合使用可实现检测和响应。 ## 贡献 · 许可证 欢迎提交 PR — 阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md) 了解技能标准，并查看 [`docs/SKILL_CONTRACT.md`](docs/SKILL_CONTRACT.md) 了解各技能检查清单。Apache 2.0 许可证；通过 [`SECURITY.md`](SECURITY.md) 进行协调披露。

标签：AI安全, Chat Copilot, Python, URL发现, 安全检测, 无后门, 模块化设计, 自动化修复, 逆向工具