Esoterics611/custody-control-assurance-lab

# custody-control-assurance-lab [](https://github.com/Esoterics611/custody-control-assurance-lab/actions/workflows/ci.yml) 一个**合成的、纯防御性**的入侵与攻击模拟 (BAS) 实验室，它对机构数字资产 **托管**平台的治理栈进行建模——包括交易授权策略 (TAP) 引擎、签名前合规筛查、 带有职责分离的 RBAC，以及针对策略更改的管理员法定人数门控——然后 **持续攻击这些控制措施以证明它们有效**，对严重性加权的**风险态势**进行评分， 并将覆盖范围映射到 **MITRE ATT&CK** 和 **NIST CSF 2.0**。本仓库中任何地方都 **没有真实的密钥、没有真实的制裁数据源，也没有真实的交易所或 API 凭证**； 每次模拟验证的都是某个控制措施是否**拦截、升级、检测或标记**了攻击者的行为 ——它永远不会攻击真实的系统。  ## 它的功能 1. **对托管治理栈进行建模** (`src/cal/custody/`) —— *被测系统*：一个纯 TAP 策略引擎、 合规筛查、RBAC + 四眼原则、管理员法定人数治理器，以及重放保护，全部连接到一个 `submit()` pipeline 中。 2. **运行 16 个入侵与攻击模拟** (`src/cal/assurance/`) —— 每个控制目标对应一个攻击 场景——并断言每个控制措施表现正常。 3. **验证真实的链上协议** (`src/cal/onchain/`) —— 对部署在 Base Sepolia 上的 `nexus-protocol` 合规/治理合约进行 5 项只读检查，包括**连线完整性漂移检测** （黑名单/KYC 门控是否仍然连接？）。 4. **风险态势评分与报告** —— 严重性加权的态势评分 (0–100) + 评级， 按 ATT&CK 技术和 CSF 功能划分的覆盖率，**相对于基线的漂移**，以及**态势趋势** ——作为独立的深色 HTML 控制台、JSON、**ATT&CK Navigator 层**、**SARIF** （GitHub Security 选项卡）和 **JUnit** 输出。 5. 通过 **pytest**（84 项控制/API/导出测试）和 **Playwright**（E2E，严格的 Page Object Model）执行，并配有 **GitHub Actions** CI、**Prometheus** `/metrics` endpoint 以及 **Docker** 镜像。 ## 架构 — submit pipeline 每个阶段都是一个由保障层验证的控制措施： ``` submit(tx) → [0 replay] → [1 RBAC] → [2 screening] → [3 TAP policy] → [4 approval/quorum] → [5 mock signer] dup id authz fail sanction→BLOCK rule→ALLOW/ needs X-of-Y & only if fully → BLOCK → BLOCK risk→BLOCK BLOCK/ESCALATE four-eyes/quorum ALLOWed travel-rule flag ``` ``` src/cal/ ├── models.py Decimal money, enums, results ├── clock.py injectable clock — no wall-clock in business logic ├── custody/ ← SYSTEM UNDER TEST (TAP engine, screening, RBAC, quorum, pipeline) ├── assurance/ ← VALIDATION FRAMEWORK │ ├── controls.py registry + MITRE ATT&CK + NIST CSF 2.0 + severity │ ├── simulations.py 16 BAS scenarios (one per control) │ ├── runner.py orchestrate, coverage, drift, posture score │ ├── report.py standalone dark HTML (grid, coverage, drift, trend) │ ├── exports.py ATT&CK Navigator layer · SARIF · JUnit │ └── history.py append-only run history (continuous monitoring) ├── onchain/ ← LIVE TARGET (read-only eth_call against Base Sepolia) └── api/ FastAPI + /metrics (Prometheus) · console/index.html (E2E target) ``` ## 控制目录（16 个模拟 + 5 个链上） | ID | 控制目标 | 阶段 | 严重性 | MITRE | NIST CSF 2.0 | |----|------------------|-------|-----|-------|--------------| | C-01 | 默认拒绝：未匹配的 tx 被拦截 | Policy | high | T1567 | PR.AA / GV.PO | | C-02 | 目标白名单生效 | Policy | high | T1567 | PR.AA | | C-03 | 金额限制 → 审批（边界正确） | Policy | high | T1657 | GV.PO | | C-04 | 滚动窗口上的速率上限 | Policy | high | T1657 | DE.CM | | C-05 | 规则排序/遮蔽：预期规则优先 | Policy | medium | T1657 | GV.PO | | C-06 | 类型混淆绕过被拦截 | Policy | high | T1657 | PR.PS | | C-07 | 受制裁目标被拦截并报警 | Screening | **critical** | T1657 | DE.AE / RS.MA | | C-08 | 高风险评分被拦截（边界正确） | Screening | high | T1657 | DE.AE | | C-09 | 超过阈值的 Travel Rule 被标记 | Screening | medium | — | GV.OC | | C-10 | RBAC：非发起者无法提交 | Access | high | T1078 | PR.AA | | C-11 | 四眼原则：发起者无法自我审批 | Approval | **critical** | T1548 | GV.RR | | C-12 | 修改策略需要管理员法定人数 | Governance | **critical** | T1098 | GV.RR / GV.PO | | C-13 | 重放/幂等性：已执行的请求无法重放 | Pipeline | **critical** | T1565 | PR.DS | | C-14 | 十进制精度完整性（无浮点货币） | Policy | medium | — | PR.DS | | C-15 | 地址规范化：大小写不同的制裁被拦截 | Screening | high | T1657 | DE.AE | | C-16 | 审批人集合完整性：重复项无法增加计数 | Approval | high | T1548 | GV.RR | | OC-01..05 | Base Sepolia 上的实时 nexus-protocol：可达性、**限制列表与 KYC 连线完好**、黑名单暴露面、铸造上限 | On-chain | 最高至 **critical** | T1565/T1657 | PR.PS / DE.CM / DE.AE … | 完整描述：[`atlas/CONTROL_CATALOG.md`](atlas/CONTROL_CATALOG.md) · 威胁模型： [`atlas/THREAT_MODEL.md`](atlas/THREAT_MODEL.md)。 ## 快速开始 ``` make install # uv sync + Playwright chromium make test # pytest -n auto (84 tests) make assure # BAS suite -> reports/ + posture table make serve # API + console at http://127.0.0.1:8000/ make e2e # Playwright E2E (Page Object Model) # 实时 on-chain target（可选附加项；只读，公开 testnet）： uv sync --extra onchain uv run python scripts/run_assurance.py --target both ``` `make assure` 会写入 `reports/assurance.{html,json}`、一个 **ATT&CK Navigator layer** (`navigator-layer.json`)、**SARIF** (`assurance.sarif`)、**JUnit** (`assurance-junit.xml`)， 追加到运行历史中，如果有任何控制失败则以非零状态退出（跳过的链上控制不会导致 运行失败）。CI 还会将实时的 HTML 报告发布到 **GitHub Pages**。 ## 漂移循环（核心部分） ``` ./scripts/demo.sh # baseline → regress the policy → harness catches drift → restore ``` 削弱一个限制，测试框架就会将受影响的控制变为**红色**，将它们报告为漂移， 并且**态势分数会下降**（关键控制的回归比中等的危害更大）： | 所有控制均为绿色（态势 100 · A） | 检测到回归（态势 57 · D） | |---|---| |  |  | ## 实时链上验证 同样的原则，指向 Base Sepolia 上**真实部署的** `nexus-protocol` （公共测试网，严格只读——无密钥，无交易）。OC-02/OC-03 确认 `TransferRestrictions` 合约仍然连接到预期的 `RestrictionList`/`KYCRegistry` ——即黑名单和 KYC 门控没有被悄悄断开（生产环境状态上的漂移）。离线或没有 web3 时， 它们会报告 **SKIPPED**，永远不会失败。  ## 可观测性与互操作性 - **Prometheus** —— `GET /metrics` 暴露 `cal_posture_score`、`cal_controls_*` 以及 每个控制的 `cal_control_pass{control,severity}` gauges。 - **运行历史与趋势** —— 每次运行都会追加到 `reports/history.jsonl`；HTML 报告会 渲染一个态势迷你图。`GET /assurance/history` 提供此数据。 - **MITRE ATT&CK Navigator** —— 将 `navigator-layer.json` 加载到官方 Navigator 中。 - **SARIF** —— 失败的控制将显示在 GitHub 的 **code-scanning / Security** 选项卡中。 - **Docker** —— `docker build -t cal . && docker run -p 8000:8000 cal` 提供控制台服务。 ## 这如何映射到安全保障实践 控制验证 / 持续保障 · 入侵与攻击模拟 · MITRE ATT&CK + NIST CSF 2.0 映射与覆盖率 · 严重性加权风险态势 · 漂移检测（模拟 *与*链上） · 纵深防御 · 可观测性（指标/历史） · CI 原生证据 (SARIF/JUnit/Navigator)。 ## 范围与安全性 一切都是**合成的且防御性的**。没有真实的私钥，没有真实的制裁/OFAC 数据源 （`data/sanctions.sample.json` 是虚构的，并标记为 `SYNTHETIC TEST DATA`），没有交易所/ API 凭证，也没有任何攻击真实系统的工具——链上目标是针对公共测试网的 只读 `eth_call`。金额始终是 `decimal.Decimal`；业务逻辑永远不会读取系统时间。控制 *语义*是基于真实的、独立构建的机构数字资产合规层（OFAC 风格的限制列表、KYC 注册表、每个 minter 的铸造上限，以及 Governor/Timelock）建模的，在这里重新表达为一个小巧 诚实的模型，以便可以对控制措施进行攻击和验证。

标签：AV绕过, BAS攻击模拟, FastAPI, Playwright, 安全合规与治理, 安全规则引擎, 数字资产托管, 文档安全, 特征检测, 自定义请求头, 请求拦截, 逆向工具, 防御性安全测试