SafetyMP/FidusGate
GitHub: SafetyMP/FidusGate
FidusGate 是一个面向自主 AI agent 的零信任治理参考项目，通过 Cedar 策略门控、Ed25519 签名凭证和 WASI 沙箱展示安全左移的 agentic 操作管控方案。
Stars: 0 | Forks: 0
# FidusGate
针对**自主 AI agent 操作**的零信任治理和运行时验证的**常青开源参考** — Cedar policy 门控、Ed25519 凭证、MCP 代理强制执行，以及可运行的管理控制台演示。
FidusGate 将安全左移：在活动的 agentic 工作流上进行程序化访问控制、签名验证和沙箱命令审计。它围绕 AI 工具执行建立明确的、受策略强制执行的边界，以减少未经授权的修改、权限提升和由 prompt injection 驱动的妥协。
[](https://github.com/SafetyMP/FidusGate/actions/workflows/docker-publish.yml)
[](https://github.com/SafetyMP/FidusGate/releases)
[](https://scorecard.dev/viewer/?uri=github.com/SafetyMP/FidusGate)
[](LICENSE)
**跳转至：** [演示](#demo) · [快速开始](#-quick-start--execution-guide) · [架构](#-unified-monorepo-architecture) · [文档](docs/README.md) · [贡献](CONTRIBUTING.md) · [安全](SECURITY.md)
## 演示
### 截图
| 账本与交易 | 合规与认证 | Cedar policy 模拟器 |
|-----------------------|--------------------------|-------------------------|
|  |  |  |
| 取证与验证器 | 交互式沙箱 |
|----------------------|---------------------|
|  |  |
- **本地演示：** `npm run bootstrap && npm run dev` → [http://localhost:3000](http://localhost:3000) (dashboard) · gateway API 在 `:3001`
- **容器镜像：** `ghcr.io/safetymp/fidusgate-gateway` 和 `ghcr.io/safetymp/fidusgate-dashboard` (参见 [Docker 发布工作流](.github/workflows/docker-publish.yml))
- **重新生成 GIF/PNG：** 在开发栈运行后执行 `npm run screenshots` — [维护者手册](docs/community/github-presentation.md)
## 🛠️ 状态、成熟度与模拟
FidusGate 旨在作为能力展示和教育参考。它将真实的安全机制与出于演示目的而模拟的组件结合在一起：
* **真实安全控制：**
* **Cedar 访问策略引擎：** 活跃的、文件级的策略门控，解析在 [policy.cedar](./policy.cedar) 策略文件中编写的权限。
* **原生工具拦截与门控：** 严格阻止原生的客户端 IDE 操作（例如 `run_command`、`write_to_file`、`replace_file_content`、`multi_replace_file_content`、`view_file`、`list_dir` 和 `grep_search`），以保证 agent 仅通过 FidusGate MCP 代理 API 执行命令和编辑。
* **加密凭证：** 使用真实的 Ed25519 公钥密码学在客户端 dashboard 上验证签名交易凭证。（注意：虽然 Ed25519 凭证签名本身是真实的，但由于出于演示目的密钥存储在本地数据存储中，不可否认性属性仅为说明性的，不能在此配置中强制执行。）
* **WASI 沙箱运行时：** 使用 Node 原生的 `node:wasi` 库在 gateway 进程内直接执行编译好的 `.wasm` 模块，绕过 Docker VM 启动延迟，并将工具执行开销降低 98%（50ms 以下）。
* **KMS Transit 签名提供程序：** 企业级加密密钥路由集成，支持 GCP KMS、AWS KMS 和 HashiCorp Vault 非对称签名提供程序，在离线开发期间动态回退路由到本地 Ed25519 密钥。
* **文件系统漂移检测：** 使用 Git 底层命令实时跟踪未跟踪/已修改的文件，并提供回滚选项。
* **模拟组件与 Mock：**
* **数据库持久化：** 默认使用本地平面文件 JSON 数据存储，以便于本地设置。通过 Prisma 提供可插拔的 PostgreSQL 集成，但必须在真实使用时进行配置。
* **系统调用审计监控：** 基于命令脚本字符串为系统调用事件建模，而不是附加真实的 eBPF 内核探针。
* **共识密钥聚合：** 通过存储在数据库中的多方认证工作流模拟多签名密钥聚合 (MuSig2)。
* **身份提供者：** 通过联合 dashboard 小部件模拟 OpenID Connect (OIDC) JWT token 发放。
* **集成 (SPIFFE/OIDC)：** 导出审计日志中的存根占位符字段展示了计划中的集成设计，而非生产环境的钩子。
## 🛡️ 威胁模型
### 范围内的安全目标
FidusGate 旨在防御：
1. **Prompt Injection 权限提升：** 攻击者将恶意指令（例如 `rm -rf /`）注入到 agent 的上下文中，导致 agent 执行未经授权的命令。
2. **未经授权的配置修改：** 限制 agent 修改系统策略 (`policy.cedar`) 或关键脚本 (`scripts/*`) 的能力，即使 agent 正在执行仓库中的文件。
3. **供应链攻击/包污染：** 在 gateway 层面阻止动态下载或在主机系统上安装任意包的命令（例如 `curl`、`npm install`）。
4. **审计追踪篡改：** 使用 Ed25519 公钥签名建立已签名、防篡改的仅追加凭证日志，使追溯性的历史修改变得可见（由于本地密钥存储，在此演示环境中仅为说明性；请参见状态、成熟度与模拟）。
### 范围外（我们不防御的内容）
1. **主机级内核受损：** 沙箱环境依赖标准的 Docker container 命名空间。除非配置了活跃的 gVisor 运行时，否则它无法防止底层主机漏洞利用。
2. **受损的管理员凭据：** 管理员拥有最终的绕过权限（例如策略更新或命令覆盖密钥）。FidusGate 无法防御受损的管理员凭据。
3. **对抗性网络流量：** FidusGate 在应用边界过滤工具调用参数；它不是网络级别的防火墙。
## 🚫 已知限制
1. **系统调用审计模拟：** 系统调用审计在应用 gateway 处解析命令字符串，而不是挂钩到活跃的主机级内核探针（例如 eBPF 或原生 `seccomp`）。
2. **单主机沙箱：** 沙箱隔离在本地主机上以容器化方式运行，共享底层操作系统内核。
3. **密钥管理：** 用于多角色共识的加密密钥对存储在数据库层中以用于演示目的，而不是安全地存储在硬件安全模块 (HSM) 或云密钥管理服务 (KMS) 中。
## 🔍 如何进行审查
要验证治理模型和遏制控制：
1. **Cedar 策略模型：** 审查 [policy.cedar](./policy.cedar) 文件以评估风险分层的权限规则。
2. **沙箱边界：** 检查 [scripts/sandbox-execute.sh](./scripts/sandbox-execute.sh) 以评估写时复制 Docker 运行时挂载如何隔离工具执行。
3. **审计日志验证：** 审查 [packages/crypto-utils/src/index.ts](./packages/crypto-utils/src/index.ts) 内部的签名验证循环，以验证防篡改凭证验证。
## 🏛️ 监管与风险控制对齐
FidusGate 在概念上映射到 **NIST SP 800-53、ISO/IEC 27001 和 SOC 2 Common Criteria** 中的控制族，展示了如何将企业合规结构转化为程序化的策略规则。请注意，这是一个说明性的、概念性的映射，FidusGate 本身并不提供经过审计的合规态势或认证。
* **职责分离：** 以编程方式分离代码编译、基础设施修改和安全策略修改。AI agent 被锁定，无法直接修改策略边界 (`policy.cedar`) 或核心脚本 (`scripts/*`)。
* **可审计性与不可否认性：** 为所有 gateway 交易生成加密签名的 **Ed25519 凭证**，建立防篡改的、仅追加的 agent 操作审计日志（由于本地密钥存储，在此演示中不可否认性为说明性的）。
* **访问控制与最小权限：** 根据风险严重程度实时限制工具调用，将高风险终端命令强制放入隔离的 Docker 沙箱中。
* **系统完整性保护：** 自动审计 agentic pipeline，以扫描动态 prompt injection 向量和不安全的运行时变量。
## 📖 文档与手册门户
FidusGate 包含文档和手册，以协助安全官员和开发人员管理 agentic 边界。
* **[文档门户](./docs/README.md)：** 映射所有指南和治理技能的主索引。
* **[Monorepo 架构指南](./docs/ARCHITECTURE.md)：** 深入探讨高级拓扑、组件详细信息和 Docker 沙箱配置。
* **[本地 CI/CD 模拟手册](./docs/local-ci-emulation.md)：** 使用 `act` 进行离线 pipeline 执行和 prompt injection 验证检查。
* **[阶段 3 验证演练](./docs/walkthrough.md)：** 关于文件系统漂移自动调节、Gemini Cedar Co-Pilots 和常规提交标签的具体操作手册。
* **[阶段 4 和 5 验证演练](./docs/walkthrough_v2.md)：** 关于亚毫秒级 WASI 沙箱运行时、Cloud KMS (AWS/GCP) Transit 集成和多 Agent 共识门控的详细操作手册。
## 📐 统一的 Monorepo 架构
工作区构建为模块化的 **npm Workspaces** monorepo，促进严格的依赖范围界定和隔离的边界：
```
graph TD
%% Root Governance Boundaries
subgraph Root [Root Workspace & Governance]
direction TB
RootConfig["package.json & tsconfig.json"]
TurboCache["turbo.json (Task Caching)"]
CedarPolicy["policy.cedar (Cedar Policies)"]
GatewayConfig["protect-mcp.config.json"]
end
%% Application Layer
subgraph Apps [Applications Layer]
direction LR
Gateway["apps/secure-gateway (Port 3001)"]
Dashboard["apps/admin-dashboard (Port 3000)"]
end
%% Shared Library Layer
subgraph Packages [Shared Modules Layer]
direction LR
Types["packages/core-types (Models)"]
Crypto["packages/crypto-utils (Ed25519)"]
DB["packages/database (JSON/Prisma)"]
Action["packages/github-action (CI Gate)"]
Daemon["packages/cedar-daemon (Rust HTTP)"]
end
%% Sandboxed Verification Pipelines
subgraph CI [CI/CD & Verification]
direction TB
Bootstrap["scripts/bootstrap.sh"]
Sandbox["scripts/sandbox-execute.sh"]
CIVerify["scripts/ci-verify.sh (act local CI)"]
GitHook["scripts/pre-commit-ham-audit.sh"]
end
%% Dependencies
Gateway --> Types
Gateway --> Crypto
Gateway --> DB
Gateway --> Daemon
Dashboard --> Types
Action --> Crypto
Action --> Types
%% Flow of Controls
CedarPolicy --> Gateway
Sandbox --> Apps
GitHook --> Root
```
### 组件详情
1. **`packages/core-types`**：为交易、安全发现、日志和可验证凭证声明严格类型的边界。
2. **`packages/crypto-utils`**：封装由 **Ed25519** 公钥密码学支持的加密签名和验证例程。
3. **`packages/database`**：一个演示数据库模块，利用种子化的本地 JSON 存储进行离线能力验证，并为标准 SQL 数据库（例如通过 Prisma 的 PostgreSQL）提供可插拔支持。生产部署需要真实的数据库配置。
4. **`packages/github-action`**：一个自定义的 GitHub Action 防护，用于验证工作流、扫描 prompt injection 并验证提交凭证。
5. **`packages/cedar-daemon`**：一个高性能的 Rust 原生 HTTP 微服务，在端口 50051 上封装了官方 Rust `cedar-policy` 引擎。安全 gateway 查询此服务以执行具有亚毫秒级延迟的零信任策略决策。
6. **`apps/secure-gateway`**：Express 微服务，暴露具有自动 PII（个人身份信息）脱敏和签名签署的交易 API，查询 Cedar Rust 守护进程并回退到本地 TypeScript 解析器。
7. **`apps/admin-dashboard`**：React 操作 dashboard，带有凭证验证器、实时日志、共识认证面板和命令控制台。
## 🔒 风险分层的治理框架
FidusGate 建立了一个十层的风险与合规分类框架。这些类别直接映射到在 gateway 处有状态解析的 Cedar 访问控制策略：
| 风险层级 / 防护 | 操作范围 | Cedar 策略规则 | 强制执行策略 |
| :--- | :--- | :--- | :--- |
| **Tier 0 (隔离区)** | 拒绝隔离 agent 的写入/执行 | 全局 `forbid` 写入/执行 | **遏制门控：** 具有活跃隔离状态的主体被阻止进行所有修改和终端脚本操作，但保留只读工具访问权限以便在询问期间做出响应。 |
| **Tier 1 (低)** | 文件读取、目录列出、正则搜索 | 全局 `permit` 工具调用 | **自动批准：** 只读任务无阻碍运行，防止给开发人员带来摩擦。 |
| **Tier 2 (中)** | 源码目录文件修改 (`apps/*`, `packages/*`) | 针对源码目录 `permit` | **影子强制执行：** 在源码路径中允许，但禁止编辑配置文件 (`policy.cedar`, `protect-mcp.config.json`)。 |
| **Tier 3 (高)** | 终端脚本、编译任务执行 | 严格在沙箱包装器内 `permit` | **沙箱执行：** 要求脚本生成在安全、隔离的沙箱 (`sandbox-execute.sh`) 内进行。原始主机访问被阻止。 |
| **Tier 4 (严重)** | 全局网络、任意包安装 (`npm i`, `curl`) | 全局 `forbid` | **严格禁止：** 在 gateway 层面阻止，以防止攻击和不受信任的包污染。 |
| **Tier 5 (DevOps)** | 分支提交 (`git commit`) 和发布 (`npm publish`) | 除非 pipeline 检查通过，否则 `forbid` | **有状态 Pipeline：** 强制在提交继续之前执行 `ci-verify.sh`、HAM 漂移检查和静态安全审计。 |
| **Tier 6 (IBP)** | 运行高成本沙箱执行或远程脚本 | 如果 token 预算耗尽则 `forbid` | **财务控制：** 监控 token 消耗，如果预估的 token 燃烧量超过 Sprint 分配的 95%，则触发断路器阻止。 |
| **Tier 7 (PLM)** | 源码目录中的任何写入/修改操作 | 除非注册了活跃的 PLM 需求，否则 `forbid` | **可追溯性门控：** 将代码库更改限制为授权的 Jira/linear 式需求 ID，并要求编写关联的单元测试。 |
| **Tier 8 (SME 角色)** | 特定源码路径（DB 迁移、UI 布局等） | 除非由匹配的 SME 签名，否则 `forbid` | **角色门控：** 将文件夹段限制为特定的加密角色签名（例如，schema 的 `backend-sme`，Docker 的 `devops-sme`）。 |
| **Tier 9 (原生工具阻止)** | 原生客户端/IDE 操作 (`run_command`, `write_to_file` 等) | 全局 `forbid` 原生工具 | **MCP 强制执行：** 显式拦截并阻止直接的原生环境操作，强制所有 agent 工具使用通过 FidusGate 代理 API 进行。 |
## 🔍 CI/CD 静态安全审计展示
为了演示扫描控制的稳健性，我们模拟了三种不同的 prompt injection 向量暴露。这些故意被放置在一个独立的演示工作流 (`.github/workflows/ci-agent-pipeline.yml`) 中以展示检测能力，而实时工作流则发布的是加固后的版本。
1. **向量 A（环境变量中介）：** AI prompt 中未经验证的变量，允许外部贡献者劫持审查 agent。
2. **向量 D（PR Target + Checkout）：** 在特权工作流容器内部未经授权地检出 head commit。
3. **向量 H（危险沙箱配置）：** AI agent 配置文件授予管理能力 (`danger-full-access`)。
### 暂存的补救控制
默认情况下，所有工作流都已进行了加固：
* 将触发器从 `pull_request_target` 转换为无特权的 `pull_request` 触发器。
* 强制执行只读内容范围 (`contents: read`)。
* 剥离 AI prompt 中动态插值的环境字符串。
* 加固 agent 运行时设置，以使用严格的 `"sandbox": "workspace-read"` 上下文，且不具备任何执行能力。
## ⚙️ 核心参考与验证功能
FidusGate 包含一套集成到开发人员和管理 dashboard 中的安全策略模拟和可观测性工具：
### 🧬 1. 实时 + 草稿 Cedar 策略模拟器
* **交互式试运行：** 允许开发人员将模拟器切换到 `"Enable Custom Draft Policy Overlay (In-Memory Dry Run)"`，并在 dashboard 上的内存编辑器中编辑 Cedar 策略。
* **诊断：** 针对您的活跃或草稿策略，即时评估模拟的 agent 工具调用（例如 `sb:issuer:agent-80` 调用 `write_file`）。
* **评估日志：** 返回策略评估结果 (`ALLOW` 或 `DENY`) 以及 Cedar 引擎评估的特定匹配规则。
* **范围隔离：** 草稿更改保留在内存中以供测试，确保活跃的本地策略在明确提交之前不会被覆盖。
### 💼 2. 取证 JSON 合规包导出器
* **防篡改日志：** 取证命令时间线跟踪在沙箱执行环境内执行的经过审计的命令。
* **统一包格式：** 允许导出已签名的合规凭证，将沙箱日志、模拟的 SPIFFE 标识符、OIDC 认证声明和 Ed25519 签名编译到结构化的 JSON 信封中。
* **访问控制：** 对取证合规报告的访问权限被限制为 `admin` 或 `auditor` 角色，以防止凭据收割。
### 🤖 3. AI Agent 自动修复建议与建议的自动修复
* **纠正指导：** 当命令审计器拦截到被阻止的命令（例如 agent 尝试运行 `curl http://...`）时，gateway 会返回修复建议（例如*建议配置的镜像或缓存本地文件*）。
* **建议的自动修复：** gateway 返回一个结构化的 `suggestedAutofix` 对象，其中包含 `target` 禁止命令及其安全的 `replacement` 命令（例如，自动重写动态 `pip install` 命令以在沙箱容器内安全运行）。
* **一键控制台横幅：** 如果命令执行失败并带有建议的自动修复，FidusGate 的沙箱控制台 UI 会自动显示一个可折叠的自动修复横幅，其中包含一个交互式的 **"Apply Fix"** 按钮，可一键执行替换命令。
### 📐 4. 可折叠的服务器架构指南
* **Dashboard 集成：** 一个交互式指南，作为可折叠的手风琴部分直接集成在终端控制台之前。
* **交互：** 标题切换可展开或折叠指南正文，并更新状态雪佛龙图标。
* **组件分析：** 显示组件详情（Secure Gateway、Operations Console、Cryptographic Utilities、Database Clients、Core Types 和沙箱执行层），定义其用途、手册参数和关键功能。
### 📡 5. 文件系统漂移检测与自动调节
* **漂移跟踪：** Secure Gateway 利用 `scripts/sandbox-drift-detect.sh` 来跟踪相对于 git 索引状态的工作区内未跟踪、修改或删除的文件（排除环境、node_modules 和缓存文件）。
* **有状态日志记录与 WebSockets：** 将所有漂移文件、更改类型（`added`、`modified`、`deleted`）和原始 diff 记录到数据存储中，通过 WebSockets (`filesystem_drift_detected`) 广播更新以更新 Operations Console UI。
* **一键调节回滚：** 允许管理员从 dashboard 触发 `POST /api/sandbox/reconcile`，在工作区内执行恢复序列 (`git restore . && git clean -fd`) 以将环境恢复到干净的 git 状态，更新数据库记录并刷新 UI 客户端。
### 🧠 6. Gemini 驱动的 Cedar Co-Pilot
* **自然语言到策略的翻译：** 在 `/api/policy/co-pilot` endpoint 内提供会话式策略生成。开发人员可以提交会话式 prompt（例如 *"allow pm-sme to write .md files"*）。
* **Google Gemini API 集成：** 利用 Google Gemini API（具有可配置的模型设置，默认以 `gemini-1.5-pro` 为例）将用户意图转化为语法有效的 Cedar 授权规则和纯文本描述。
* **基于规则的 Mock 回退引擎：** 实现了一个基于规则的 mock 解析器，当未设置 `GEMINI_API_KEY` 时，该解析器会处理关键策略（针对 `pm-sme` 和 `security-sme` 等角色），在离线开发期间提供强大的故障安全机制。
### 🔑 7. 多角色共识认证与执行绕过（阶段 4）
* **认证门控：** 暂停高风险 shell 命令的终端执行，直到获得共识批准。认证是使用存储在数据库中的多角色密钥（Admin、Developer、Auditor）进行模拟的。
* **发起者自我认证阻止：** 以编程方式阻止命令的提议者签署自己的操作（满足职责分离）。
* **共识绕过执行：** 一旦满足批准的加密共识，便绕过 `/api/sandbox/execute` 内的标准白名单阻止。在沙箱控制台中运行命令会在隔离的容器中执行任务，并将操作状态标记为 `completed`。
* **审计员角色与 OIDC 小部件支持：** 使用专门的 OIDC 模拟身份路由扩展联合身份验证小部件，根据所选的角色按钮对齐默认电子邮件，以简化本地审查。
### 📡 8. 模拟的 Seccomp 审计与系统调用流建模（阶段 5）
* **模拟的 Seccomp 审计：** 基于解析的命令字符串，在 Secure Gateway 上对预期的系统调用流（`sys_execve`、`sys_openat`、`sys_read`、`sys_unlinkat`、`sys_fchmodat`）进行建模和追踪。
* **违规锁定：** 每当对关键系统调用进行建模时（例如用于调试探针的 `sys_ptrace`、用于命名空间修改的 `sys_setns`/`sys_unshare`，或未经授权的出站套接字调用），触发模拟的 15 分钟执行锁定。
* **前端 React 集成：** 将沙箱执行 REST 调用返回的建模 `syscalls` 数组连接到动态的 React state hook 中。系统调用监控面板通过视觉指示器和违规原因渲染模拟的 ALLOWED 和 BLOCKED 日志。
### ⚡ 9. 自适应自动限流与 macOS 沙箱兼容性（阶段 5）
* **智能自动限流：** 实施了移动平均延迟跟踪器，当平均沙箱执行时间激增时触发防御性速率限制 (HTTP 429)。配置了 `2000ms` 的窗口，以防止标准的 Docker 容器启动开销导致节流锁定。
* **macOS `timeout` 回退包装器：** 在 `sandbox-execute.sh` 内部构建了一个动态的 bash 助手，用于检测是否缺少标准的 `timeout` 实用程序（在默认的 macOS 上很常见）。它会优雅地路由到 `gtimeout`（如果通过 coreutils 安装）或直接执行，从而解决 Docker 执行环境死锁问题。
* **统一状态重置：** 配置了数据库 `/api/reset` 处理程序，以随合规状态一起原子性地清除移动的延迟平均值，立即解锁活动的节流参数。
### ⚡ 10. 亚毫秒级 WASI 沙箱运行时
* **进程内编译：** 使用 Node 原生的 `node:wasi` 库在 secure gateway 进程内直接生成并执行编译好的 `.wasm` 模块。
* **Docker 绕过逻辑：** 自动将白名单上的编译器和未授权的开发人员命令路由到 WASI 沙箱，与启动冷 Docker 容器相比，将容器化延迟降低了 **98%**（50ms 以下）。
* **离线回退编译：** 如果不存在，则动态编译一个最小的回退 WASM 编译器二进制文件，确保开发人员的工作流完全离线运行。
### 🔑 11. 云支持的 KMS Transit 提供程序
* **HSM 集成：** 直接与企业 HSM 和云密钥管理提供程序连接，包括 AWS KMS、GCP KMS 和 HashiCorp Vault。
* **动态密钥路由：** 配置凭据后，自动将加密签名请求路由到活跃的 KMS 提供程序，并回退到本地 Ed25519 密钥以进行离线本地开发。
### 🚨 12. Agent 隔离系统与询问引擎
* **自动隔离触发：** 自动隔离连续发生三次 Cedar 策略违规的 agent 主体，阻止它们执行任何写入或运行命令。
* **询问门控：** 为被隔离的 agent 保留只读能力（如 `read_file`、`list_directory`、`search_code` 等 Tier 1 工具），使它们能够在人工进行的取证询问期间回答诊断问题。
* **取证档案构建器 (`interview-engine.ts`)：** 当询问发起时，自动编译该 agent 最近命令时间线、违规和上下文数据的档案。
* **净化：** 净化询问日志以剥离 prompt injection 短语，并防止被隔离的 agent 利用询问交互执行间接的注入攻击。
* **数据库管理：** 提供专用的 API 路由和数据库方法（`quarantinePrincipal`、`releaseQuarantine`、`getQuarantineRecord`、`addInterviewLog`）来管理隔离状态并记录询问历史。
## ⚙️ 快速入门与执行指南
### 前置条件
* **Node.js** >= 20.0.0
* **Docker**（可选，用于完整的沙箱隔离）
### 🚀 1. 初始化仓库
运行统一的仓库初始化程序。此脚本配置本地 git hooks，审计运行时工具链，并验证目录范围的内存一致性：
```
npm run bootstrap
```
### 💻 2. 运行应用程序
要并行运行 secure gateway 后端和管理 dashboard：
```
npm run dev
```
* **Admin Dashboard：** [http://localhost:3000](http://localhost:3000)
* **Secure Gateway：** [http://localhost:3001](http://localhost:3001### 📡 2.5. 运行 Rust Cedar 策略守护进程（可选）
要在端口 50051 上启用高速的 Rust 原生 Cedar 授权引擎：
```
# 构建 daemon Docker 镜像
npm run build --workspace=packages/cedar-daemon
# 启动 container
npm run start --workspace=packages/cedar-daemon
```
*如果守护进程离线，Secure Gateway 后端将自动回退到使用 TypeScript 原生的 AST 评估器。*
### 🛡️ 3. 模拟沙箱安全审计
您可以在无特权的 Docker 容器内执行工作流或本地编译的安全静态审计：
```
npm run sandbox
```
### 🧪 4. 本地 CI/CD 模拟
使用 `act` 在 Docker 容器内完全离线运行加固后的工作流：
```
npm run ci
```
### 🚨 5. 加密凭证验证
您可以从 dashboard 日志网格复制任何经过加密签名的交易凭证，将其粘贴到管理门户内的 **Receipt Verifier Tool** 中，或者使用以下命令进行离线验证：
```
node packages/crypto-utils/dist/index.js --verify
```
### 📡 6. 文件系统漂移检测与自动调节
要手动审计沙箱或工作区中的文件系统漂移：
```
bash scripts/sandbox-drift-detect.sh
```
要触发主动回滚并调节所有未跟踪或修改的更改：
```
curl -X POST http://localhost:3001/api/sandbox/reconcile -H "Authorization: Bearer "
```
### 🧠 7. Gemini Cedar 策略 Co-Pilot
使用 Co-Pilot API 从自然语言请求生成 Cedar 策略：
```
curl -X POST http://localhost:3001/api/policy/co-pilot \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{"prompt": "allow pm-sme to write md files"}'
```
## 📦 持续交付与自动化发布
FidusGate 实施了高度标准化的、基于主干的交付模型，该模型由常规提交和自动化发布 pipeline 治理：
* **常规提交合规性：** 代码更改使用语义化范围作为前缀（例如 `feat(secops)`、`chore(release)`、`fix(crypto)`）。这支持确定性的依赖映射和机器可读的更新日志。
* **语义化发布自动化 (`.releaserc.json`)：** 在主分支 pipeline 构建期间利用自动化发布步骤来：
1. 解析提交消息并自动计算下一个语义化版本 (Major/Minor/Patch)。
2. 根据标准模板自动生成详细的更新日志。
3. 将发布标签和草稿直接发布到 GitHub。
* **发布 Pipeline 工作流 (`.github/workflows/release.yml`)：** 在推送到 `main` 分支时运行，执行自动化测试验证 (`npm run test`)、monorepo 类型检查 (`tsc`)，并安全地启动发布运行器。
## 🔬 企业生产与加固指南
虽然 FidusGate 旨在使用本地配置为开发搭建零信任结构，但要过渡到高可用的企业级生产环境，需要升级以下层：
### 1. 数据库架构与持久化策略
* **当前设置**：默认情况下，`@fidusgate/database` 在零依赖的本地 JSON 文件存储模式下运行。但是，使用 **Prisma ORM** 已经集成了完全关系型的数据库功能。
* **过渡到生产环境**：
1. 在 gateway 的 `.env` 文件中定义一个指向您的 PostgreSQL 集群的 `DATABASE_URL`。
2. 运行 `npx prisma db push` 以生成并应用结构化的数据库 schema。
3. 使用高可用、集群化的设置部署 PostgreSQL（例如，使用多可用区部署、Aurora PostgreSQL，或使用 PgBouncer 进行连接池化以在流量高峰期生存）。
4. 实施定期的数据库备份例程和只读副本以进行审计追踪分析。
### 2. 审计日志安全性与仅追加保证
* **当前设置**：将交易凭证存储在 `.memory/receipts` 下，并将日志存储在 `.memory/audit-log.md` 中便于本地检查，但平面文件缺乏防篡改保证、保留合规性或锁并发。
* **过渡到生产环境**：
1. **SIEM / 集中式日志记录**：配置 secure-gateway 的安全日志流，将其直接传输到集中式、安全的审计系统（例如 AWS CloudWatch、Datadog 或 Grafana Loki）。
2. **集中式账本数据库**：集成专用的账本存储（如 Amazon QLDB）或防篡改的区块链账本，以记录加密交易哈希，确保绝对的不可否认性。
3. **哈希链审计**：实施加密链接，其中每个新凭证都包含前一个凭证块的签名，使任何历史删除操作立即可被验证器看到。
4. **保留策略**：配置日志组资源策略以强制执行严格的写一次读多次 (WORM) 参数，并带有标准化的保留规则（例如，SOC 2 / ISO 27001 合规需保留 7 年）。
### 3. Gateway 配置模式
`protect-mcp.config.json` 通过 `"mode"` 键管理 gateway 运行时强制执行行为：
* `"shadow"`：根据 Cedar 访问控制规则评估所有传入的交易请求并记录决策，但不会阻止请求。这对于在强制执行之前针对真实世界开发人员工作流审计和测试策略非常有用。
* `"enforce"`：完全的零信任主动门控。secure-gateway 会主动阻止任何未通过 Ed25519 加密验证或在 Cedar 访问控制下评估为 `"deny"` 的工具执行、凭证提交或控制台命令。
## 🌿 常青参考实现
FidusGate 被设计为针对 AI agent 安全的运行时治理的常青、不断发展的参考实现：
* **持续的演进式交付：** 完全由常规提交和自动化 pipeline 治理，确保最新的安全签名、Cedar 规则和策略映射能够自主编译、版本控制和打标签。
* **真实世界参考能力：** 通过提供具体的模板——包括沙箱命令执行、动态 AST 策略模拟、防篡改的加密日志以及模拟的系统调用建模——FidusGate 建立了一个活跃的、功能性的基准。它推动行业超越理论上的策略 PDF 文档，走向**明确受策略强制执行且在运营上可审计的运行时强制执行**。
* **开源与可扩展核心：** 模块化的 npm workspace monorepo 专为社区扩展而设计。安全架构师可以在 `skills/` 树下编写新的自定义手册，通过我们联合的提供者钩子部署专门的身份验证机制，或者插入基于 LLM 的高级防火墙来评估对抗性的 prompt 参数。
## 🔬 审计与生产质量状态
* **垃圾文件**：100% 已清理。构建目录 (`dist`, `.turbo`)、缓存文件和操作系统噪音已被干净地修剪。
* **密钥检查**：100% 安全。绝对没有提交任何密码、原始私钥或实际开发人员凭据。
* **Lockfile 保真度**：使用 `npm` lockfile (`package-lock.json`) 进行了标准化。
* **测试覆盖率**：使用内置的零依赖 Node.js 测试运行器进行了测试和验证，涵盖了 Ed25519 密码学、Cedar 动态 AST 解析器评估和 shell 命令白名单审计。
## 贡献、安全与许可
| 资源 | 链接 |
|----------|------|
| 贡献 | [CONTRIBUTING.md](CONTRIBUTING.md) |
| 安全 | [SECURITY.md](SECURITY.md) |
| 行为准则 | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) |
| 支持 | [SUPPORT.md](SUPPORT.md) |
| 维护者展示 | [docs/community/github-presentation.md](docs/community/github-presentation.md) |
| 许可 | [Apache 2.0](LICENSE) |标签：AI Agent安全, MITM代理, Streamlit, Web报告查看器, 参考架构, 可视化界面, 策略引擎, 签名验证, 网络安全挑战, 自动化攻击, 访问控制, 请求拦截, 零信任架构