内置策略 - FailproofAI

failproofai 内置了 30 条策略，用于捕获常见的代理失败模式。每条策略针对特定的钩子事件类型和工具名称触发。其中 9 条策略支持参数配置，无需编写代码即可调整行为。4 条工作流策略会在 Claude 停止前强制执行提交 → 推送 → PR → CI 的完整流程。

概览

策略按类别分组：

类别	策略	钩子类型
危险命令	block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands	PreToolUse
密钥（净化器）	sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens	PostToolUse
环境	block-env-files, protect-env-vars	PreToolUse
文件访问	block-read-outside-cwd, block-secrets-write	PreToolUse
Git	block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged	PreToolUse
数据库	warn-destructive-sql, warn-schema-alteration	PreToolUse
警告	warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install	PreToolUse
工作流	require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-ci-green-before-stop	Stop

block- — 阻止代理继续执行。
warn- — 为代理提供额外上下文，使其能够自我纠正。
sanitize- — 在代理查看工具输出前，清除其中的敏感数据。
require- — 在条件满足之前阻止 Stop 事件。

每条策略均支持在 policyParams 中设置可选的 hint 字段。该提示会附加到 Claude 收到的 deny 或 instruct 消息中，提供可操作的指导，无需修改策略代码。适用于内置策略、自定义策略和约定策略。详见配置 → hint。

危险命令

防止代理执行难以撤销或可能损害宿主系统的操作。

`block-sudo`

事件： PreToolUse (Bash)
默认行为： 拒绝任何包含 sudo 的命令。拦截包含 sudo 关键字的调用。模式匹配基于解析后的命令标记（token），而非原始字符串，以防止通过 shell 运算符注入绕过检测。 参数：

参数	类型	默认值	说明
`allowPatterns`	`string[]`	`[]`	允许通过的命令前缀（精确匹配）。每个条目与解析后的 argv 标记进行匹配。

示例：

{
  "policyParams": {
    "block-sudo": {
      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
    }
  }
}

使用此配置，sudo systemctl status nginx 将被允许，但 sudo rm /etc/hosts 将被拒绝。

模式匹配基于解析后的标记，而非原始命令字符串。这可防止通过追加 shell 运算符进行绕过（例如 sudo systemctl status x; rm -rf / 不会匹配 sudo systemctl status *）。

`block-rm-rf`

事件： PreToolUse (Bash)
默认行为： 拒绝 rm -rf、rm -fr 及类似的递归删除形式。 参数：

参数	类型	默认值	说明
`allowPaths`	`string[]`	`[]`	允许递归删除的安全路径（例如 `/tmp`）。

示例：

{
  "policyParams": {
    "block-rm-rf": {
      "allowPaths": ["/tmp", "/var/cache"]
    }
  }
}

`block-curl-pipe-sh`

事件： PreToolUse (Bash)
默认行为： 拒绝 curl <url> | bash、curl <url> | sh、wget <url> | bash 及类似模式。无参数。

`block-failproofai-commands`

事件： PreToolUse (Bash)
默认行为： 拒绝会卸载或禁用 failproofai 自身的命令（例如 npm uninstall failproofai、failproofai policies --uninstall）。无参数。

密钥（净化器）

防止代理将凭据泄露到其上下文或输出中。净化器策略在 PostToolUse 事件上触发。当 Claude 执行 Bash 命令、读取文件或调用任何工具时，这些策略会在输出返回给 Claude 之前对其进行检查。若检测到密钥模式，策略将返回拒绝决定，阻止输出被传回。

`sanitize-jwt`

事件： PostToolUse（所有工具）
默认行为： 清除 JWT 令牌（三段由 . 分隔的 base64url 编码内容）。无参数。

`sanitize-api-keys`

事件： PostToolUse（所有工具）
默认行为： 清除常见 API 密钥格式：Anthropic（sk-ant-）、OpenAI（sk-）、GitHub PAT（ghp_）、AWS 访问密钥（AKIA）、Stripe 密钥（sk_live_、sk_test_）以及 Google API 密钥（AIza）。 参数：

参数	类型	默认值	说明
`additionalPatterns`	`{ regex: string; label: string }[]`	`[]`	额外需要视为密钥的正则表达式模式。

示例：

{
  "policyParams": {
    "sanitize-api-keys": {
      "additionalPatterns": [
        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" },
        { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" }
      ]
    }
  }
}

`sanitize-connection-strings`

事件： PostToolUse（所有工具）
默认行为： 清除包含内嵌凭据的数据库连接字符串（例如 postgresql://user:password@host/db）。无参数。

`sanitize-private-key-content`

事件： PostToolUse（所有工具）
默认行为： 清除 PEM 块（-----BEGIN PRIVATE KEY-----、-----BEGIN RSA PRIVATE KEY----- 等）。无参数。

`sanitize-bearer-tokens`

事件： PostToolUse（所有工具）
默认行为： 清除 Authorization: Bearer <token> 请求头中长度达到 20 个字符或以上的令牌。无参数。

环境

防止代理读取或暴露敏感的环境配置。

`block-env-files`

事件： PreToolUse（Bash、Read）
默认行为： 拒绝通过 cat .env、以 .env 为文件路径的 Read 工具调用等方式读取 .env 文件。不会拦截 .envrc 或其他与环境相关的文件，仅针对精确命名为 .env 的文件。无参数。

`protect-env-vars`

事件： PreToolUse（Bash）
默认行为： 拒绝打印环境变量的命令：printenv、env、echo $VAR。无参数。

文件访问

将代理的操作范围限制在项目目录内，并远离敏感文件。

`block-read-outside-cwd`

事件： PreToolUse（Read、Bash）
默认行为： 拒绝读取当前工作目录（项目根目录）以外的文件。 参数：

参数	类型	默认值	说明
`allowPaths`	`string[]`	`[]`	即使在工作目录之外也允许访问的绝对路径前缀。

示例：

{
  "policyParams": {
    "block-read-outside-cwd": {
      "allowPaths": ["/shared/data", "/opt/company/config"]
    }
  }
}

`block-secrets-write`

事件： PreToolUse（Write、Edit）
默认行为： 拒绝写入常用于私钥和证书的文件：id_rsa、id_ed25519、*.key、*.pem、*.p12、*.pfx。 参数：

参数	类型	默认值	说明
`additionalPatterns`	`string[]`	`[]`	额外需要阻止的文件名模式（glob 风格）。

示例：

{
  "policyParams": {
    "block-secrets-write": {
      "additionalPatterns": [".token", ".secret"]
    }
  }
}

Git

防止意外推送、强制推送以及难以撤销的分支误操作。

`block-push-master`

事件： PreToolUse（Bash）
默认行为： 拒绝 git push origin main 和 git push origin master。 参数：

参数	类型	默认值	说明
`protectedBranches`	`string[]`	`["main", "master"]`	不允许直接推送的分支名称。

示例：

{
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "master", "release", "prod"]
    }
  }
}

若要允许推送到所有分支（即在不从 enabledPolicies 中移除该策略的情况下禁用它），请将 protectedBranches 设为 []。

`block-work-on-main`

事件： PreToolUse（Bash）
默认行为： 拒绝直接切换到 main 或 master 分支。 参数：

参数	类型	默认值	说明
`protectedBranches`	`string[]`	`["main", "master"]`	不允许直接切换的分支名称。

`block-force-push`

事件： PreToolUse（Bash）
默认行为： 拒绝 git push --force 和 git push -f。无策略专属参数。可使用通用 hint 建议替代方案：

{
  "policyParams": {
    "block-force-push": {
      "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b <new-branch>`) and push that instead."
    }
  }
}

`warn-git-amend`

事件： PreToolUse（Bash）
默认行为： 在运行 git commit --amend 时指示 Claude 谨慎操作。不会阻止命令执行。无参数。

`warn-git-stash-drop`

事件： PreToolUse（Bash）
默认行为： 在运行 git stash drop 前指示 Claude 进行确认。不会阻止命令执行。无参数。

`warn-all-files-staged`

事件： PreToolUse（Bash）
默认行为： 在运行 git add -A 或 git add . 时指示 Claude 检查所暂存的内容。不会阻止命令执行。无参数。

数据库

在破坏性 SQL 操作执行之前进行拦截。

`warn-destructive-sql`

事件： PreToolUse（Bash）
默认行为： 在运行包含 DROP TABLE、DROP DATABASE 或不带 WHERE 子句的 DELETE 的 SQL 语句之前，指示 Claude 进行确认。无参数。

`warn-schema-alteration`

事件： PreToolUse（Bash）
默认行为： 在运行 ALTER TABLE 语句之前，指示 Claude 进行确认。无参数。

警告

在执行潜在风险但非破坏性的操作之前，为代理提供额外的上下文信息。

`warn-large-file-write`

事件： PreToolUse（Write）
默认行为： 在写入超过 1024 KB 的文件之前，指示 Claude 进行确认。 参数：

参数	类型	默认值	说明
`thresholdKb`	`number`	`1024`	触发警告的文件大小阈值（单位：KB）。

示例：

{
  "policyParams": {
    "warn-large-file-write": {
      "thresholdKb": 256
    }
  }
}

钩子处理程序对载荷的 stdin 大小限制为 1 MB。若要使用较小的内容测试此策略，请将 thresholdKb 设置为远低于 1024 的值。

`warn-package-publish`

事件： PreToolUse（Bash）
默认行为： 在运行 npm publish 之前，指示 Claude 进行确认。无参数。

`warn-background-process`

事件： PreToolUse（Bash）
默认行为： 在通过 nohup、&、disown 或 screen 启动后台进程时，指示 Claude 谨慎操作。无参数。

`warn-global-package-install`

事件： PreToolUse（Bash）
默认行为： 在运行 npm install -g、yarn global add 或未在虚拟环境中执行的 pip install 之前，指示 Claude 进行确认。无参数。

AI 行为

检测代理卡住或行为异常的情况。

`warn-repeated-tool-calls`

事件： PreToolUse（所有工具）
默认行为： 当同一工具以相同参数被调用 3 次或以上时，指示 Claude 重新考量——这通常是代理陷入循环的常见信号。无参数。

工作流

强制执行严格的会话结束工作流。这些策略在 Stop 事件上触发，并阻止 Claude 在每个条件满足之前停止。它们遵循自然的依赖链：提交 → 推送 → PR → CI。若某条策略拒绝，链中后续策略将被跳过（拒绝短路机制）。所有工作流策略均为**失败开放（fail-open）**模式：若所需工具不可用（例如 gh 未安装、无 git 远程仓库），策略将允许通过，并附上说明检查被跳过原因的提示信息。

`require-commit-before-stop`

事件： Stop
默认行为： 当存在未提交的更改（已修改、已暂存或未跟踪的文件）时，拒绝停止。当工作目录干净时，返回提示信息。无参数。

`require-push-before-stop`

事件： Stop
默认行为： 当存在未推送的提交或当前分支没有远程跟踪分支时，拒绝停止。若需要，建议使用 git push -u 创建跟踪分支。若未配置远程仓库，则以开放方式失败。 参数：

参数	类型	默认值	说明
`remote`	`string`	`"origin"`	推送的目标远程仓库名称。

示例：

{
  "policyParams": {
    "require-push-before-stop": {
      "remote": "upstream"
    }
  }
}

`require-pr-before-stop`

事件： Stop
默认行为： 当当前分支不存在拉取请求，或已有 PR 处于关闭/已合并状态时，拒绝停止。指示 Claude 使用 gh pr create 创建 PR。无参数。

此策略需要安装并完成身份验证的 GitHub CLI（gh）。请使用具有 repo 权限范围（用于读取拉取请求）的个人访问令牌运行 gh auth login。若 gh 未安装或未完成身份验证，策略将以开放方式失败，并向 Claude 报告原因。

`require-ci-green-before-stop`

事件： Stop
默认行为： 当当前分支的 CI 检查失败或仍在运行时，拒绝停止。同时检查 GitHub Actions 工作流运行和第三方机器人检查（例如 CodeRabbit、SonarCloud、Codecov）。将 skipped 结论视为成功。当所有检查通过时，返回提示信息。无参数。

此策略需要安装并完成身份验证的 GitHub CLI（gh）。请使用具有 repo 权限范围（用于读取 Actions 工作流运行和 Checks API）的个人访问令牌运行 gh auth login。若 gh 未安装或未完成身份验证，策略将以开放方式失败，并向 Claude 报告原因。

禁用单条策略

在配置文件的 enabledPolicies 中移除特定策略，或在控制台的「策略」选项卡中将其关闭。

{
  "enabledPolicies": [
    "block-rm-rf",
    "sanitize-api-keys"
  ]
}

未在 enabledPolicies 中列出的策略不会运行，即使 policyParams 中存在对应条目也不例外。

快速开始

核心概念

CLI

工具

进阶

​概览

​危险命令

​block-sudo

​block-rm-rf

​block-curl-pipe-sh

​block-failproofai-commands

​密钥（净化器）

​sanitize-jwt

​sanitize-api-keys

​sanitize-connection-strings

​sanitize-private-key-content

​sanitize-bearer-tokens

​环境

​block-env-files

​protect-env-vars

​文件访问

​block-read-outside-cwd

​block-secrets-write

​Git

​block-push-master

​block-work-on-main

​block-force-push

​warn-git-amend

​warn-git-stash-drop

​warn-all-files-staged

​数据库

​warn-destructive-sql

​warn-schema-alteration

​警告

​warn-large-file-write

​warn-package-publish

​warn-background-process

​warn-global-package-install

​AI 行为

​warn-repeated-tool-calls

​工作流

​require-commit-before-stop

​require-push-before-stop

​require-pr-before-stop

​require-ci-green-before-stop

​禁用单条策略

概览

危险命令

`block-sudo`

`block-rm-rf`

`block-curl-pipe-sh`

`block-failproofai-commands`

密钥（净化器）

`sanitize-jwt`

`sanitize-api-keys`

`sanitize-connection-strings`

`sanitize-private-key-content`

`sanitize-bearer-tokens`

环境

`block-env-files`

`protect-env-vars`

文件访问

`block-read-outside-cwd`

`block-secrets-write`

Git

`block-push-master`

`block-work-on-main`

`block-force-push`

`warn-git-amend`

`warn-git-stash-drop`

`warn-all-files-staged`

数据库

`warn-destructive-sql`

`warn-schema-alteration`

警告

`warn-large-file-write`

`warn-package-publish`

`warn-background-process`

`warn-global-package-install`

AI 行为

`warn-repeated-tool-calls`

工作流

`require-commit-before-stop`

`require-push-before-stop`

`require-pr-before-stop`

`require-ci-green-before-stop`

禁用单条策略