ichiorca/gateweave

# Gateweave Gateweave 是一个可移植的策略引擎，用于决定允许接入哪些编码代理（coding-agent）工具，以及已接入的代理可以调用哪些操作。Codex 是其主打的头等目标，通过 Codex 适配器提供初步的深度集成。 ## Gateweave 为何存在 编码代理可以读取源代码、运行 shell 命令、访问凭据和 网络，以及加载 MCP 服务器、技能、插件和自定义工具。控制 这些能力的机制通常分散在某个代理的配置中， 而代码仓库的安全意图则写在其他地方——或者根本没写。 这造成了两种危险的盲区：团队无法轻易 证明代码仓库允许了什么，而且他们可能会误将某个策略决策或某个 工具的权限声明，当作所选代理实际能够提供的保护。 Gateweave 是介于代码仓库意图和 代理特定执行层面之间的策略控制平面：它足够轻便可用于 CI 和嵌入， 又足够具体以生成经过审查的 Codex 计划。 Gateweave 的存在是为了让这个边界变得可审查且可测试。它为 代码仓库提供了一套确定性的策略和证据工作流，用于回答： - **允许什么？** 使用稳定的 `allow`、 `ask` 或 `deny` 决策以及明确的优先级、原因和证据来评估调用请求。 - **信任什么进入？** 检查并前瞻性地接纳诸如 MCP 服务器、技能、插件和自定义工具等制品，而无需执行它们； 分别保留声明的能力、观察到能力和实际有效能力； 并在证据发生偏移时重新评估锁。 - **目标可以执行什么？** 发现已安装的 Codex 目标， 编译受支持的控制规则，并为每条规则报告基于版本/平台限制的执行 评级，而不是暗示仅仅通过评估就能提供原生 保护。 其核心价值在于提供了一条从代码仓库意图到 目标证据的单一本地优先控制路径：为开发者提供策略文件和测试，为 CI 和嵌入提供稳定的 JSON 和 Go SDK，经过验证的 Codex 计划/diff/应用/回滚生命周期， 以及可选的 Console Security Center（用于清单管理、发现项、出处溯源、准入控制、锁状态、偏移检测和审计支持的活动追踪）。捆绑的黑客松体验之旅通过无活性的测试夹具（inert fixtures）端到端地展示了这些组件，且无需任何模型、 托管服务或实时制品。 Gateweave 的定位非常明确。它不是沙箱、恶意软件扫描器、 托管注册中心或代理编排器的替代品；它是这些系统可以使用的确定性策略、 证据和目标协调层。 ## 60 秒预览 无需安装 Codex、模型、网络、凭据或实时端点： ``` go build -buildvcs=false -o ./bin/gateweave.exe ./cmd/gateweave ./bin/gateweave.exe demo --fixture bundled ``` 九项确定性检查将针对无活性的夹具运行，并输出一个稳定的 JSON 封装包：策略测试、显式的 shell 允许、策略拒绝、 凭据基线底线、受限的制品检查、准入拒绝、规范锁 验证、MCP 合约偏移重新评估，以及 Codex 覆盖快照。 退出码 `0`，无 stderr 输出，字节级稳定的输出。 要查看如何将这种可移植策略编译为真实的 Codex 原生控制并再次还原， 请参阅 [`JUDGE_TESTING.md`](JUDGE_TESTING.md) 中的完整生命周期。 ## 当前可用功能 | 功能 | 状态 | |---|---| | 可移植策略内核 — schema、IR、分层合并、`allow`/`ask`/`deny` 优先级、原因代码 | 可用 | | 任何策略层都无法削弱其强度的内置凭据基线 | 可用 | | 版本化的语义模式目录（`rm -rf`、pipe-to-shell、force-push 等） | 可用 | | 策略单元测试、决策审计，以及对记录的决策执行 `explain` | 可用 | | 制品准入 — 受限的静态 `inspect`、前瞻性的 `admit`、lockfile、MCP 偏移 `monitor` | 可用，设计上为只读 | | Codex 适配器 — discovery、`compile`、`diff`、`apply`、`verify`、`rollback` | 可用；输出原生 `execpolicy` 规则 | | 五级执行报告（`enforced_native` → `unsupported`）包含命名的绕过条件 | 可用 | | 稳定的 JSON 协议 + 用于 CI 和嵌入的 Go SDK | 可用 | | `gateweave-review` Codex 插件 — 五项受限的非权威技能 | 可用 | | Mission Control 控制台 — 基于公共 CLI/JSON 的本地展示层 | 可用 | | 凭据基线目标执行 | `unsupported`；Windows 包装器路径已被隔离，等待经过验证的启动边界和一致性证据 | 严格编译在设计上会拒绝生成计划，前提是某项必需的规则 超出了目标可以执行的范围。Gateweave 会报告 `unsupported`，而 不是默默地将凭据基线拒绝降级为审批提示。这种 拒绝本身就是产品的功能，而不是缺陷 —— 详见 [docs/enforcement-matrix.md](docs/enforcement-matrix.md)。 **Gateweave 根据证据（而非假设）对其自身的执行情况进行评级。** Codex 没有针对凭据基线的原生控制，因此严格编译会失败。 实验性的 Windows AppContainer 代码目前尚未具备可信的启动 路径或版本控制的一致性证据，因此被刻意隔离： ``` ./bin/gateweave.exe codex wrapper-probe --out wrapper-evidence.json # exits 5: unsupported_enforcement ./bin/gateweave.exe codex compile --policy ./fixtures/policy/m0-shell-wrapper.yaml ` --codex-home $codexHome --repository-root $repositoryRoot --strict # exits 5: required gap ``` `--wrapper-evidence` 仅作为明确拒绝的兼容性 标志被保留；提供它也会退出并返回 `5`。目前 Gateweave 不会输出 `enforced_wrapper` 凭据覆盖。可移植的评估器仍然会强制执行内置 凭据基线；这是在编译为 Codex 目标时存在的一个客观差距。 Codex `execpolicy` 原生覆盖仅限于直接的 argv 匹配。复合的 PowerShell/控制流语句可以规避这种匹配，这是一个已公开的 绕过方式，而不是隐藏的例外。为了进行后续的检测探查，可以引入受限的 Codex `--json` 流，而无需持久化命令文本、文件路径或输出内容： ``` ./bin/gateweave.exe observe --target codex --events codex-events.jsonl ` --policy gateweave.policy.yaml --workspace-root $PWD ``` `observe` 仅报告针对直接凭据读取、工作区外读取以及复合 shell 控制流风险的、经过脱敏处理的事后发现项。它不会 运行事件、检查工作区、写入审计记录，也不会声称 已阻止该操作。 制品审查命令始终是只读的：检查永远不会执行 对象，接纳不会创建锁，监控也不会建立 基线或更改批准状态。具体的 JSON 契约和手动命令请参见 [docs/p3-artifact-review.md](docs/p3-artifact-review.md)。 ## 开发快速入门 要求：Go 1.26 或更高版本。策略 YAML 边界使用了已锁定的、 已检入的 `github.com/goccy/go-yaml` 依赖；所有其他 M0 运行时行为 均使用标准库。 ``` go test ./... go vet ./... go build -buildvcs=false -o ./bin/gateweave ./cmd/gateweave ``` 在 Windows 上运行 `pwsh -NoProfile -File ./scripts/check.ps1`，或在 macOS/Linux 上运行 `sh ./scripts/check.sh` 以执行完整的本地检查。 可移植的 CLI 使用稳定的 JSON，并使用与公共 Go facade 相同的允许/拒绝/需要批准的 退出代码。在不覆盖现有输入的前提下启动项目： ``` ./bin/gateweave init ./bin/gateweave lint --policy gateweave.policy.yaml ./bin/gateweave test --policy gateweave.policy.yaml --suite gateweave.tests.yaml ./bin/gateweave check --policy gateweave.policy.yaml --request request.json ``` 如果不存在，`init` 会创建 `.gateweave/` 决策状态以及最小化的策略和测试 文件；`.gateweave/` 被 Git 刻意忽略。为了持久化一份源码安全的决策记录并随后解释确切的已记录决策， 请向 `check` 传递一个显式的审计接收器（audit sink），然后使用其返回的 `decision_id`： ``` ./bin/gateweave check --policy gateweave.policy.yaml --request request.json --audit .gateweave/audit/events.jsonl ./bin/gateweave explain --audit .gateweave/audit/events.jsonl ``` `explain --policy --request ` 依然可用于全新的 评估。评估器会报告 `unsupported` 执行状态，因为它仅 评估策略；它不会配置目标。 在未安装 Codex、没有模型、 网络、凭据或实时制品端点的情况下运行捆绑的端到端夹具： ``` ./bin/gateweave demo --fixture bundled ``` 稳定的 JSON 封装包会验证策略测试、显式的策略规则允许和策略 拒绝决策、凭据基线、受限的制品检查和 接纳、规范锁验证、MCP 偏移重新评估，以及纯粹的 严格 Codex 0.144.4/Windows/CLI 覆盖快照。它永远不会创建 Gateweave 状态或更改目标。相同的路径也被专注的 `cmd/gateweave` 演示测试所使用。 Mission Control 是可选的本地 Next.js 展示层，基于这些 公共 CLI/SDK 边界构建。从 代码仓库根目录运行 `./scripts/launch-console.ps1 -Build` 并打开 `/demo` 以获取引导式故事；请参阅 [`apps/console/README.md`](apps/console/README.md) 了解 Explore 路由和 离线回退行为。移除 `apps/console` 不会改变 Go 的 发布路径。 如需安全的公共评审演示，[`apps/judge-demo`](apps/judge-demo) 是一个 独立的静态证据重放器，专为 Cloudflare Pages 设计。它不包含 Console API、本地运行程序、工作区注册、用户输入或实时目标 声明：它的交互控件仅重放源码安全的且已检入的夹具 证据。请勿将仅限环回（loopback-only）的 Mission Control Console 公开发布。 对于选定的 M0 Codex 候选者，`gateweave codex compile`、`diff`、 `apply`、`verify` 和 `rollback` 针对现有且隔离的 `--codex-home` 和 `--repository-root` 目录实现了文档化的规则文件生命周期。 严格的计划会在未读取内容的情况下拒绝处于活跃状态的配置层。 `apply` 和 `rollback` 需要同时具备经过审查的计划摘要和 `--confirm`。准确的隔离配置文件 命令、已安装的目标测试、残留的绕过方式以及认证范围，请参见 [docs/codex-m0-spike.md](docs/codex-m0-spike.md)。 目标中立的嵌入示例位于 [examples/embedding](examples/embedding) 下；隔离的 Codex 示例和 兼容性说明位于 [examples/codex](examples/codex) 下。 拥有指定的 Go `1.26.3` 发布工具链的维护者可以通过以下命令创建可重现的 Windows 评审包： `pwsh -NoProfile -File ./scripts/release.ps1 -Version v0.1.0 -Output dist`（或者 `sh ./scripts/release.sh v0.1.0 dist`）。该包包含预构建的 二进制文件、校验和、预期输出的清单、声明、无活性的夹具，以及 可安装的插件捆绑包。具体的免构建流程请见 [`JUDGE_TESTING.md`](JUDGE_TESTING.md)。独立的 [提交清单](SUBMISSION_CHECKLIST.md) 和 [短视频脚本](docs/submission-video-script.md) 将代码仓库证据与所有者控制的提交字段区分开来。 ## 文档 从[离线快速入门](docs/quickstart.md)开始，然后阅读 [策略指南](docs/policy-guide.md)、[Codex 适配器指南](docs/adapter-guide.md)、 [五级执行矩阵](docs/enforcement-matrix.md)以及 [固定兼容性矩阵](docs/compatibility-matrix.md)。 [威胁模型](docs/threat-model.md)、[局限性](docs/limitations.md)和 [故障排除指南](docs/troubleshooting.md)陈述了信任边界、 残留风险、清理和回滚行为。 ## Codex 开发工具链 从代码仓库根目录启动 Codex，以便本地 hook 命令仅解析已检入的 Go 代码。Codex 会自动发现 `.agents/skills/` 下专注的工作流。 项目 hook 只有在代码仓库受信任且确切的 hook 定义经过审查后才会运行。在 Codex 中打开 `/hooks`，审查来自 `.codex/hooks.json` 的 `SessionStart` 处理程序，如果本地的 `go run ./tools/codex-harness` 命令是可以接受的，就信任它。该 hook 不会进行网络访问或写入代码仓库；它仅验证工具链文件并将代码仓库护栏注入到会话上下文中。 已检入的 `.codex/config.toml` 刻意没有扩大沙箱、网络或审批权限。 ## 仓库导航图 查看可视化的[架构指南](docs/architecture.md)以了解所有权、信任、决策和变更边界，以及查看[使用手册](docs/cookbook.md)获取关于离线执行、策略、制品审查、偏移、Codex、嵌入和 CI 的可执行方案。持久的 Codex 指南位于 `AGENTS.md` 中，可重用的工作流位于 `.agents/skills/` 中，受信任的项目会话 hook 位于 `.codex/` 中。 动态的、按依赖关系排序的交付路线图是 [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md)。它将每一项 PRD 功能需求映射到工作包和可执行的验收证据。 ## 使用 Codex 和 GPT-5.6 构建 Gateweave 是在 Build 提交期间使用 Codex 和 GPT-5.6 构建的。 代码仓库是在时间窗口内初始化的 —— 不存在 预先存在的基础代码，每一次提交都是被评判的工作。 **主要的 `/feedback` Codex 会话 ID：** `TODO — 所有者需在提交前记录` **Codex 和 GPT-5.6 完成的工作。** 大部分核心功能 是在 Codex 会话中实现的：策略内核的解析器、规范 IR、 分层合并和优先级引擎；确定性评估器和原因代码 词汇表；语义模式目录及其夹具；准入 管道、lockfile 规范化和 MCP 工具目录偏移摘要； Codex 适配器的发现、编译、安全变更、验证和 回滚路径；稳定的 JSON 协议和 Go SDK 边界；以及 Mission Control 控制台。对于该产品所包含的机械但极为严密的工作 —— 规范摘要计算、跨平台 路径处理、表驱动的一致性夹具，以及保持 JSON 契约 及其 schema 步调一致 —— Codex 在速度上具有显著优势。一些与安全相关的行为是 通过 Codex 的审查过程产生的，而不是最初设计的一部分：针对每个发现项的已解析主题绑定、已验证签名到制品的绑定，以及强制的 MCP 偏移基线。 **由人类决定的内容。** PRD 中的产品范围和非目标； 接纳与调用的区分；内核绝不进行 运行时模型调用的决定；五级执行词汇表以及不受支持的规则会导致严格编译失败而非默默降级的规则；将凭据基线作为绝对底线；模块路径 `github.com/ichiorca/gateweave`；以及 Apache-2.0 许可证。Codex 提出了 实现方案；但它从来都不是决定 Gateweave 应该承诺什么的权威。 带有日期的会话、范围和实质性成果记录在 [BUILD_WEEK_EVIDENCE.md](BUILD_WEEK_EVIDENCE.md) 中。

标签：AI代理, EVTX分析, Go语言, Homebrew安装, Streamlit, 开发辅助工具, 日志审计, 程序破解, 策略引擎, 网络安全挑战, 访问控制