ormasoftchile/gert

# gert — 受控可执行 Runbook 引擎 [](https://go.dev) [](LICENSE) 一个轻量级执行内核，用于结构化、受控、可重放的 runbook，具备完全的可追溯性、安全的扩展性以及多种宿主界面（CLI、TUI、MCP server）。 ## 功能特性 ### 内核 (Track 1) - **基于 effects 的治理** — `effects: [network, kubernetes]` + `writes: [pods]` 分类法取代了布尔值 `side_effects`。风险源自 effects + writes + 幂等性 + 确定性。治理规则基于契约属性匹配，而非工具名称。 - **7 种步骤类型** — tool, manual, assert, branch, parallel, end, extension - **Extension 执行** — `type: extension` 步骤运行 JSON-RPC 2.0 二进制文件 (initialize/execute/shutdown)。每次运行复用 Runner，5s 优雅关闭 + 强制终止，步骤级超时（默认 60s）。 - **可恢复审批** — 带有 `Submit()/Wait()` 的 `ApprovalProvider`，基于工单的流程，用于异步恢复的状态持久化，多方审批强制执行，签名验证。 - **作用域状态** — `scope` 用于变量命名空间隔离，`export` 将输出提升至全局，带有 allow/deny glob 模式的 `visibility`。来自 `repeat` 内部步骤的变量在块完成后提升。 - **键控扇出** — `for_each.key` 生成 map 结构的输出而非列表。 - **Repeat 块** — 带有 `max` + `until` 提前退出的有界多步迭代。 - **输入解析** — 内核拥有的 `ResolveInputs()` API，解析顺序：CLI vars → providers → defaults → error。所有宿主使用相同路径。 - **Trace 完整性** — 每个事件的 SHA-256 哈希链，`run_complete` 上的 HMAC 签名，`gert trace verify` 检测篡改。 - **Contract 违规检测** — 未声明的输出被剥离，缺失的输出发出警告，`contract_violations: deny` 治理规则将其提升为错误。 - **Probe 模式** — `--mode probe` 执行只读工具，跳过写入操作。 - **Stdin 管道** — 工具操作上的 `stdin:` 字段通过进程 stdin 传输模板值，绕过操作系统对大输入的 argv 限制。 - **模板工具名称** — `tool: "{{ .role.tool }}"` 在运行时解析，支持 `for_each` 迭代中的按角色工具选择。 - **`json` 模板函数** — `{{ json .map }}` 将 map/slice 序列化为 JSON，而不是 Go 的 `map[k:v]` 格式。 - **Package 解析** — 带有 `require: { pkg: ../path }` 的 `gert.yaml` 从外部包解析工具。本地工具覆盖包工具。 - **Extension 二进制解析** — `extension: gert-ext-foo` 在 baseDir、projectRoot、cwd 和系统 PATH（Windows 上 +`.exe`）中搜索 `extensions//`。 - **Secret 脱敏** — 声明的 secret 在 trace 和记录的场景中自动脱敏。 - **Run 身份** — `run_start` 包含 actor, host, gert_version, runbook_hash, tool_hashes, 和 extension_hashes（每个二进制文件的 SHA-256 用于审计追踪）。 - **3 阶段验证** — 结构（严格 YAML）→ 语义（JSON Schema）→ 领域（25+ 条规则，包括变量解析、end-step 可达性、contract 收紧、scope/export/repeat 验证、extension 二进制存在性）。 - **跨平台** — Windows + Linux + macOS。工具定义声明 `meta.platform` 约束。 - **覆盖 11 个内核包的 140 个测试，覆盖 6 个 runbook 的 14 个场景回放测试。** ### 生态 (Track 2) - **gert CLI** — exec, validate, test, resume, trace verify, watch, diff, outcomes。`--progress stderr` 流式传输实时执行事件。 - **gert-tui** — Bubble Tea 终端 UI，包含步骤列表、状态图标、实时 trace 事件、回放模式。 - **gert-mcp** — MCP server，将 gert/validate, gert/exec, gert/test, gert/schema 作为工具暴露给 AI 代理。 - **自动录制** — 包装 `ToolExecutor` 的 `Recorder` 将响应捕获为可重放场景，并脱敏 secret。 - **表格格式化** — 结果元数组自动渲染为对齐表格（检测并解析 JSON 字符串数组）。 ## 快速开始 ``` # 构建所有二进制文件 go build -o gert ./cmd/gert go build -o gert-kernel ./cmd/gert-kernel go build -o gert-tui ./cmd/gert-tui go build -o gert-mcp ./cmd/gert-mcp # 验证 runbook ./gert validate runbooks/service-health-diagnostic.yaml # 对真实主机执行 ./gert exec runbooks/service-health-diagnostic.yaml --var hostname=google.com # 试运行 (显示 contracts、governance、inputs — 不执行 tools) ./gert exec runbooks/service-health-diagnostic.yaml --var hostname=google.com --mode dry-run # 带 trace 输出 + actor identity ./gert exec runbooks/service-health-diagnostic.yaml --var hostname=google.com --trace run.jsonl --as oncall@team.com # 实时进度流 (stderr 上的 JSON events) ./gert exec runbooks/service-health-diagnostic.yaml --var hostname=google.com --progress stderr # 验证 trace 完整性 ./gert trace verify run.jsonl # 运行 scenario replay 测试 ./gert test runbooks/service-health-diagnostic.yaml # TUI — 真实执行 ./gert-tui runbooks/service-health-diagnostic.yaml --mode real --var hostname=google.com # TUI — replay 模式 (固定响应，无需 tools) ./gert-tui runbooks/service-health-diagnostic.yaml --mode replay --scenario healthy # Watch 模式 — 按间隔重复 ./gert watch runbooks/service-health-diagnostic.yaml --interval 30s --var hostname=google.com --stop-on escalated # MCP server (用于 AI agents) ./gert-mcp # Extension 执行 (JSON-RPC 2.0 runner) go build -o extensions/gert-ext-echo/gert-ext-echo ./examples/tools/echo-ext/ ./gert-kernel exec examples/extension-echo.yaml --var greeting=hello ``` ## CLI 命令 | 命令 | 描述 | |---------|-------------| | `gert validate ` | 3 阶段验证（runbook 或 tool）。通过 `apiVersion` 自动检测。 | | `gert exec ` | 执行 runbook。`--mode real\|dry-run\|probe`。`--var`, `--trace`, `--as`, `--progress stderr`。 | | `gert test ` | 运行场景回放测试。`--scenario`, `--json`, `--fail-fast`。 | | `gert resume --run ` | 从持久化状态恢复暂停的运行。 | | `gert trace verify ` | 验证哈希链完整性 + 可选 HMAC 签名。 | | `gert watch ` | 按间隔重复执行。`--interval`, `--stop-on`, `--var`。 | | `gert diff ` | 重新运行场景并报告结果变更。 | | `gert outcomes` | 从 trace 文件聚合结果。`--json`。 | | `gert schema runbook\|tool` | 导出 JSON Schema (Draft 2020-12)。 | | `gert version` | 打印版本信息。 | ## Runbooks 包含 5 个 runbook 及 11 个场景测试： | Runbook | 描述 | 场景 | |---------|-------------|-----------| | `service-health-diagnostic` | Ping + HTTP 检查，带有分支结果 | healthy, degraded, unknown | | `dns-http-chain` | DNS 解析 → HTTP 检查，带有变量传递 | reachable, unreachable | | `k8s-pod-restart` | Kubernetes pod 重启，带有审批门控 | restart-success, not-running | | `incident-triage` | 多分支严重性路由，带有人工调查 | p1-critical, p3-low | | `multi-endpoint-sweep` | 端点健康检查，带有分支 | all-healthy, some-degraded | ## 工具包 7 个带有基于 effects 契约的工具定义： | Tool | Effects | 描述 | |------|---------|-------------| | `curl` | `[network]` | HTTP GET/POST/HEAD/download。支持 `stdin:` 用于大负载。 | | `ping` | `[network]` | ICMP 可达性检查 | | `nslookup` | `[network]` | DNS 解析 | | `kubectl` | `[kubernetes]` | K8s get/delete/apply (delete 操作 writes: pods) | | `az` | `[azure]` | Azure VM list/restart | | `jq` | `[]` | JSON 处理（纯函数，无 effects） | | `stdin-echo` | `[]` | 读取 stdin，回显到 stdout（用于 stdin 管道的测试工具） | ## Runbook 格式 ``` apiVersion: kernel/v0 meta: name: service-health-diagnostic inputs: hostname: { type: string, required: true } constants: health_path: "/" governance: rules: - effects: [network] action: allow - effects: [kubernetes] writes: [pods] action: require-approval - default: allow secrets: - env: SERVICE_AUTH_TOKEN required: false tools: - curl - ping steps: - id: check type: tool tool: curl action: get inputs: url: "https://{{ .hostname }}{{ .health_path }}" - id: triage type: branch branches: - condition: '{{ eq .status_code "200" }}' label: healthy steps: - type: end outcome: { category: no_action, code: service_healthy } - condition: default label: unknown steps: - type: end outcome: { category: escalated, code: unknown_status } ``` ### 步骤类型 | Type | 用途 | |------|---------| | `tool` | 执行工具操作（stdio 传输） | | `manual` | 人工证据收集 | | `assert` | 一等断言评估 | | `branch` | 条件流分叉 — 执行一个分支 | | `parallel` | 并发执行，带有状态隔离 | | `end` | 结构化结果声明 | | `extension` | 通过具有声明契约的 JSON-RPC runner 执行自定义行为 | ### 流程控制 | 机制 | 用途 | |-----------|---------| | `when` | 步骤级守卫 — 运行或跳过 | | `branch` | 流级分叉 — 执行一个分支 | | `next` | 受限 goto — 始终向前，向后有界（`max`） | | `for_each` | 列表迭代 — 顺序或并行，可选 `key` 用于 map | | `repeat` | 带有 `max` + `until` 的有界多步循环 | | `scope` | 变量命名空间隔离 | | `export` | 将作用域本地输出提升至全局 | | `visibility` | 变量访问的 allow/deny glob 模式 | | `timeout` | 每步持续时间限制（例如 `60s`）— 到期时终止进程 | ## 架构 ``` cmd/ gert/ Core CLI (exec, validate, test, resume, watch, diff, ...) gert-kernel/ Kernel-only CLI (same commands, no ecosystem deps) gert-tui/ Bubble Tea terminal UI gert-mcp/ MCP server for AI agents pkg/kernel/ Kernel packages (11 packages) contract/ Contract model (risk, effects, tightening, conflicts, merge) schema/ Runbook + Tool types, YAML loader, scope normalization, JSON Schema validate/ 3-phase validation pipeline (25+ domain rules, extension binary checks) engine/ Sequential + parallel execution, scoped state, repeat, probe, extensions eval/ Go text/template evaluator + json/toJSON functions executor/ Tool dispatch (stdio, stdin piping) + extension runner (JSON-RPC) format/ Outcome meta display (table formatting for homogeneous arrays) governance/ Contract-driven policy engine (effects + writes matching) trace/ Append-only JSONL audit trail (22 event types) + hash chain verification replay/ Scenario-based replay with canned responses testing/ Test harness (spec, assertions, runner with package resolution) pkg/ecosystem/ Ecosystem packages (4 packages) tui/ Bubble Tea model + engine integration mcp/ MCP server handlers + tool registration recorder/ Auto-record tool responses with secret redaction approval/stdin/ Default stdin approval provider pkg/schema/ Project manifest (gert.yaml loading, package resolution) tools/ 7 tool packs (curl, ping, nslookup, kubectl, az, jq, stdin-echo) runbooks/ 5 runbooks with scenarios/ test directories extensions/ Extension binaries (gert-ext-echo, gert-ext-slow) examples/ Example runbooks (extension, stdin, repeat, package resolution) schemas/ JSON Schema definitions (gert-project.json, runbook, tool) ``` ### 内核边界 内核 (`pkg/kernel/`) 是执行语义的唯一来源。生态包 (`pkg/ecosystem/`) 消费内核接口但绝不修改内核行为。依赖方向：ecosystem → kernel，永不反向。 ## 测试 ``` # 运行所有 kernel 测试 (11 个 packages 中的 140 个测试) go test ./pkg/kernel/... -v # 运行所有 runbooks 的 scenario replay 测试 ./gert test runbooks/service-health-diagnostic.yaml ./gert test runbooks/dns-http-chain.yaml ./gert test runbooks/k8s-pod-restart.yaml ./gert test runbooks/incident-triage.yaml ./gert test runbooks/multi-endpoint-sweep.yaml # 运行 extension 示例 ./gert-kernel exec examples/extension-echo.yaml --var greeting=hello # 验证所有 tools ./gert validate tools/curl.tool.yaml ./gert validate tools/kubectl.tool.yaml ``` ## 设计 设计文档保存在本地（不在 git 中追踪）。 ## 许可证 MIT

标签：DevSecOps工具, EVTX分析, EVTX分析, Golang, JSON-RPC, MCP服务器, PE 加载器, TUI, 剧本编排, 可执行Runbook, 安全编程, 完整性校验, 审批流, 审计追踪, 插件扩展, 日志审计, 流程治理, 状态管理, 自动化运维, 运维自动化