模型起草On-Call命令，只读验证保安全

运维手册（runbook）中最危险的部分往往不是长篇大论，而是排障时最先输入的那几条命令。一个错误的参数就可能把一次响应变成第二次事故。本文介绍一种将“模型起草”与“安全验证”分离的流水线：用YAML定义命令块，用约120行Python构建只读性验证器，再通过回放确保命令仍然匹配告警上下文。整个过程可以集成到CI中，在下一个轮班前做好准备。

为什么首批命令风险最高

根据对公开运维手册的评审，四类失败模式反复出现，而它们都与知识缺失无关：

• 看似读取实则写入的命令：例如 curl -X POST https://api.internal/health/refresh 返回JSON，读起来像探针，却在凌晨3点悄悄将任务加入队列。
• 遗留的缓解措施：事故中有人添加了重启命令，因为当时有帮助，事后却没有将其降级到升级部分。
• 会执行的管道：为了格式化方便，命令以 | sh 或 xargs ... kubectl delete pod 结尾，导致手册改变系统状态。
• 过时的参数标志：命令对旧版API正确，于是失败方式看起来像全新的故障症状。

因此，解决方案是建立一个三阶段门禁：起草、验证、回放。任何人都能完成第一阶段；第二和第三阶段才是让手册可以安全交给疲惫工程师的关键。

kubectl 的“读”与“写”边界并不总在动词上。 文中提到的 kubectl get pods -o wide、kubectl logs 属于公认的只读子命令，但 kubectl apply、kubectl patch、kubectl rollout restart 都会改变工作负载状态；更隐蔽的是 kubectl exec——它本身不直接修改对象，却能在容器内执行任意进程，因此验证器把它与 delete、scale 一并列入拒绝词。理解这一点有助于解释为什么 linter 采用“允许列表 + 拒绝词”的双重策略：允许列表决定哪些二进制和子命令可以出现，拒绝词则兜住那些被包装在管道、变量或子 shell 里的写操作。

| sh 与 xargs 的风险来自解释器的二次执行。 一条以 kubectl get ... | sh 结尾的命令，在静态文本上看起来只调用了 kubectl，但真正执行的是管道右侧的 shell，其内容完全不受允许列表约束。xargs kubectl delete pod 同理：xargs 把上游输出拼成新的命令行，使写动词出现在 linter 难以按位置识别的参数里。因此验证器直接拒绝 | sh、| bash、xargs、eval 以及 > /、>> 这类重定向，把“会执行”的管道从手册的首批命令中整体排除。

分离起草与执行的Runbook模式

模式比模型更重要，因为模式决定了机器能检查什么。以下是一个推荐的起始版本：

service: checkout-api
owner: payments-oncall

alerts:
  - name: CheckoutApiHighLatency
    signal: p99_latency_ms > 900 for 10m
    severity: page
  - name: CheckoutApiErrorBudgetBurn
    signal: burn_rate_1h > 14.4
    severity: page

first_commands: |
  date -u
  kubectl get pods -n checkout -l app=checkout-api -o wide
  kubectl logs -n checkout deploy/checkout-api --tail=80 --since=15m
  aws cloudwatch get-metric-statistics --namespace AWS/ELB \
    --metric-name TargetResponseTime --period 60 --statistics p99

escalation:
  - after: 10m
    if: error_rate still above 2%
    to: payments-oncall-secondary
  - after: 25m
    if: no mitigation applied
    to: payments-incident-commander

freeze:
  declared_by: incident-commander
  scope: [deploys, schema_migrations, feature_flags]
  max_duration: 60m
  unfreeze_requires:
    - two consecutive green 5xx SLO windows
    - follow_up_ticket_id present
    - secondary_oncall_ack within 15m

几个刻意选择：first_commands 是单个块字符串，便于作为整体进行差异比较和静态检查；escalation 是结构化数据，用 after、if、to 字段描述，值班人员可以像看表格一样快速阅读；freeze 也是数据，这引出了大多数手册常犯的错误。

冻结规则应是状态，而非句子

“事故期间冻结部署”不是规则，而是一种情绪。将冻结记录为对象，包含声明者、范围、有效期和明确的解冻条件，这样只需五行脚本就能回答“我们现在是否处于冻结状态”，无需询问人类。每个 unfreeze_requires 条目必须是可计算的——绿色的SLO窗口、工单ID、确认时间戳。如果条件无法计算，那只是愿望，而愿望正是凌晨4点10分人们争论的东西。

验证器：五十行代码说“不”

验证器刻意保持枯燥。它允许特定的二进制程序和子命令，直接拒绝写操作动词，拒绝管道到shell，对任何不认识的内容采取失败关闭策略。

#!/usr/bin/env python3
"""runbook_lint.py - prove the first_commands block is read-only."""
import re
import shlex
import sys
from pathlib import Path

import yaml

ALLOWED_SUBCOMMANDS = {
    "kubectl": {"get", "describe", "logs", "top", "events", "explain", "version", "api-resources"},
    "aws": {"describe", "list", "get"},
    "gcloud": {"describe", "list", "get-iam-policy"},
}

PLAIN_READ_ONLY = {"date", "hostname", "uptime", "dig", "ss", "df", "free"}

DENY_TOKENS = (
    " delete ", " apply ", " patch ", " scale ", " rollout restart ", " rollout undo ",
    " exec ", " cordon ", " drain ", " taint ", " edit ",
)

DENY_SHELL = ("| sh", "| bash", "|sh", "|bash", "xargs ", "eval ", "> /", ">>")


def split_block(block: str):
    out = []
    for raw in block.strip().splitlines():
        line = raw.strip().lstrip("-").strip()
        if not line or line.startswith("#"):
            continue
        for part in re.split(r"&&|\|\|", line):
            if part.strip():
                out.append(part.strip())
    return out


def violations(command: str):
    hits = []
    padded = f" {command} "
    for token in DENY_TOKENS:
        if token in padded:
            hits.append(f"write verb {token.strip()!r}")
    for token in DENY_SHELL:
        if token in command:
            hits.append(f"pipe or redirect {token!r}")
    try:
        argv = shlex.split(command)
    except ValueError as exc:
        return hits + [f"unparsable command: {exc}"]
    if not argv:
        return hits
    binary = Path(argv[0]).name
    if binary in PLAIN_READ_ONLY:
        return hits
    allowed = ALLOWED_SUBCOMMANDS.get(binary)
    if allowed is None:
        return hits + [f"unknown binary {binary!r}: allowlist it or drop the command"]
    sub = argv[1] if len(argv) > 1 else ""
    if not any(sub.startswith(prefix) for prefix in allowed):
        hits.append(f"{binary} {sub!r} is not an allowlisted read-only subcommand")
    return hits


def main(path: str) -> int:
    doc = yaml.safe_load(Path(path).read_text())
    block = doc.get("first_commands", "")
    if not isinstance(block, str) or not block.strip():
        print(f"FAIL {path}: no first_commands block")
        return 1
    failures = 0
    for command in split_block(block):
        for hit in violations(command):
            failures += 1
            print(f"FAIL {command!r}: {hit}")
    print(f"{'PASS' if failures == 0 else 'FAIL'} {path}: {failures} violation(s)")
    return 0 if failures == 0 else 1


if __name__ == "__main__":
    sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else "runbook.yaml"))

在本地运行，然后针对CI中的所有手册执行：

python -m pip install pyyaml
python runbook_lint.py runbooks/checkout-api.yaml
for f in runbooks/*.yaml; do python runbook_lint.py "$f" || exit 1; done

退出码就是契约。失败的检查会阻止合并，意味着没有人能匆忙中悄悄向页面路径添加变更操作。

为什么用 shlex.split 而不是简单字符串匹配。 命令块里可能出现带引号的参数、转义空格或内联环境变量，直接按空格切分会把 --since=15m 之类的参数切错，也会让引号内的 delete 被误判。shlex.split 按 shell 的词法规则解析，使验证器拿到接近真实执行时的 argv；解析失败时返回 unparsable command 并以失败关闭处理，避免畸形命令绕过检查。拿到 argv 后，验证器先看可执行文件名（Path(argv[0]).name，从而兼容 /usr/local/bin/kubectl 这类绝对路径），再核对子命令前缀是否落在 ALLOWED_SUBCOMMANDS 中。

“失败关闭”（fail-closed）是这套设计的安全前提。 对于不在允许列表里的二进制，验证器不会默认放行，而是直接报 unknown binary 并计为违规。这意味着新增工具必须显式加入允许列表，代价是一次人工评审，收益是未知命令不会因为“没匹配到拒绝词”而悄悄通过。退出码在这里承担契约角色：main 在存在违规时返回 1，CI 据此阻止合并，使静态检查成为页面路径上不可绕过的门禁，而不是一条仅供参考的提示。

用录制的载荷回放命令块

通过静态检查的命令仍可能对今天的集群不正确，因此增加带有fixture的回放阶段。捕获经过脱敏的告警载荷以及每个只读命令的输出，然后断言手册仍然产生其声称的观察结果。

1. 在手册旁边存储 fixtures/CheckoutApiHighLatency/alert.json、pods.txt 和 logs.txt。
2. 针对dry-run kubeconfig或录制命名空间运行每个命令，绝不针对生产环境。
3. 断言手册推理的字段——pods_ready、error_rate、p99_latency_ms——确实存在于解析输出中。
4. 指定fixture刷新的负责人，因为过时的fixture与过时的手册是同样的缺陷。

对于五条命令来说，这听起来像很多仪式？这大约相当于一个事后行动项的工作量，并且在你拥有的每个页面上都可复用。

fixture 回放的核心是“可断言字段”。 回放并不重新执行真实查询，而是把脱敏后的告警载荷（alert.json）和命令输出（pods.txt、logs.txt）存成固定样本，再断言手册所依赖的观察值——pods_ready、error_rate、p99_latency_ms——确实能从这些样本中解析出来。这样做的价值在于捕获“命令语法仍然合法、但对当前集群或当前 API 版本已不再产生预期输出”的漂移，例如参数标志随版本更名后命令依旧通过 linter，却让值班人员看到空结果。

dry-run kubeconfig 与录制命名空间是回放的安全边界。 回放阶段被明确要求绝不针对生产环境运行，而是使用指向录制数据的 kubeconfig 或隔离命名空间。这把“验证手册是否正确”与“在真实系统上执行命令”彻底分开，避免验证行为本身引入变更。fixture 需要指定刷新负责人，因为过时的样本会和过时的手册一样制造虚假的安全感；刷新频率应与告警信号或服务接口的变更节奏挂钩。

免费模型访问和免费服务器在哪里真正有帮助

这个循环中两部分足够乏味且判断力要求低，可以委托：从告警载荷和服务README起草 first_commands，以及在事故中将长输出摘要为三个观察到的事实。

披露：本文是作为MonkeyCode产品推广的一部分准备的。

MonkeyCode是一个开源项目，其运营者表示提供免费模型访问——目前宣传为1000万token的免费额度——以及免费服务器选项，足以在第一天无需付费账户即可端到端运行这个循环。在依赖任何具体数字之前，请核实当前条款，因为免费层数字会变动，并且将每个能力声明视为需要重新检查的内容，而非我能代表他们承诺的事项。

具体来说，免费层适合此工作流中的三项任务：

• 起草：发送告警名称、信号表达式以及服务暴露的只读工具列表，要求按上述模式生成命令块。
• 夜间静态检查：在免费服务器上对 runbooks/*.yaml 运行linter，当命令开始失败时打开issue，让漂移在周二而不是凌晨3点浮现。
• 事故笔记摘要：粘贴你已经读过的文本；保持进程环境不含写凭据和长期云令牌。

我不会弯曲的规则：模型输出在通过linter之前绝不接触人类。价值在于更快的初稿，而非权威，你的值班人员仍应在运行每条命令前阅读它。如果你想在将任何内容连接到生产之前排练起草部分，免费模型访问和免费服务器选项足以闭合循环。

决策表：委托什么

任务	交给模型？	合并前门禁
从载荷+README起草 first_commands	是	runbook_lint.py 通过，人类阅读每一行
选择升级阈值	否	SLO负责人决定，手册记录数字
事故中摘要40行输出转储	是	只读文本输入，环境中无凭据
重写 unfreeze_requires	否	事故指挥官拥有标准
生成后续工单骨架	是	人类将工单ID签入手册

局限性与谁不应使用此方法

拒绝列表不是沙盒。linter能捕获已知写动词和未知二进制程序；它无法理解自定义CLI中 status 意味着“应用待定更改”。只读也不等于可以安全粘贴——get secrets 输出是只读的，但仍然是凭据泄露，因此将这类命令完全排除在块之外。如果你的团队没有审查习惯，这种自动化主要产生看起来自信的绿色对勾。

如果你的手册没有机器可检查的命令块、环境气隙无法使用托管服务器选项，或者你需要正式的安全保证而非护栏，则应跳过此方法。该技术是为在错误时间醒着的人类准备的减速带。

拒绝列表与沙盒的区别在于能否约束语义。 沙盒通过内核级隔离限制进程能做什么，而拒绝列表只对命令文本做模式匹配，无法理解某个自定义 CLI 中 status 子命令背后是否隐含“应用待定更改”。因此文中明确说这是“护栏而非正式安全保证”：它能拦住已知的写动词、未知二进制和会执行的管道，却不能证明一条命令在任何环境下都绝对只读。需要正式安全保证的团队应依赖权限控制、只读凭据和网络隔离，而非仅靠 linter。

只读与可安全粘贴是两个独立维度。 kubectl get secrets -o yaml 完全只读，却会输出凭据内容，把它放进首批命令等于在事故频道里泄露密钥。同理，日志和环境变量输出也可能夹带令牌。因此除只读性外还需一条内容规则：涉及 secrets、 Secret 对象或含凭据的环境变量转储的命令应整体排除在命令块之外，而不是指望验证器去判断输出是否敏感。这条边界也解释了为什么事故摘要任务要求“只读文本输入、环境中无写凭据和长期云令牌”。

二十分钟采用清单

1. 将一个页面的前五条命令作为单个块移入 first_commands。
2. 复制 runbook_lint.py，安装PyYAML，修复它标记的任何内容。
3. 将冻结句子转换为带有有效期和可计算解冻标准的 freeze 对象。
4. 将lint调用添加到CI，并使其成为手册更改的必需检查。
5. 从真实、脱敏的告警中捕获一组fixture，并添加回放步骤。
6. 可选地，将起草提示指向免费模型访问，并将其输出与已审查的块进行差异比较。

如果你的手册要求每条命令在呼叫任何人之前都必须通过linter，它会是什么样子？可能更短，肯定更可读，并且更不可能成为下一次事故。