zhexulong/ai-agent-prompt-injection-guard

# AI Agent Prompt Injection Guard AIPIG 是一个本地防护工具，用于拦截 AI-agent prompt injection 横幅、proxy 附加的响应文本、可疑的 tool-result 文本以及 token-padding 伪影。 主要支持的部署路径是作为 CLIProxyAPI 响应拦截器。当 Claude Code、OpenCode 或 Codex 通过 CLIProxyAPI 进行通信时，AIPIG 可以在客户端存储已知注入的响应文本之前，以及在下一个模型请求读取它之前将其移除。 ## 它的功能 - 剥离 CLIProxyAPI 响应中已知的响应文本注入。 - 在宿主程序暴露安全 hook 的直接宿主适配器中，标记或重写 tool-result 注入。 - 将正向和反向指纹保存在同一个 `fingerprints.json` 文件中。 - 在重复出现相同的 session 模式后，建议有边界的 regex 指纹。 - 在本地编写告警和待处理建议日志。 - 通过 CLIProxyAPI 为 Claude 和 OpenCode 提供 real-chain eval。 ## 快速开始 前置条件： - Bun - Go 工具链，用于构建原生 CLIProxyAPI 插件桥接 - 带有插件支持的 CLIProxyAPI v7 安装依赖并构建插件： ``` npm install bun run aipig -- build-plugin ``` 创建配置文件： ``` bun run aipig -- init --config .opencode/aipig.jsonc ``` 编辑 `.opencode/aipig.jsonc` 并设置： ``` { "cliproxy": { "cpaRoot": "/absolute/path/to/cliproxyapi", "port": 8317, "pluginName": "cliproxy-aipig" } } ``` 检查安装计划： ``` bun run aipig -- cliproxy doctor --config .opencode/aipig.jsonc bun run aipig -- cliproxy diff --config .opencode/aipig.jsonc ``` 安装： ``` bun run aipig -- cliproxy install --config .opencode/aipig.jsonc --write ``` 安装过程会将原生插件和打包的 JS 入口复制到 CLIProxyAPI 的 `plugins/` 目录中，在 CLIProxyAPI 目录下写入运行时的 `.opencode/aipig.jsonc`，修改 `config.yaml`，并等待 CLIProxyAPI 热重载。默认情况下它不会重启 CPA。 回滚命令： ``` bun run aipig -- cliproxy uninstall --config .opencode/aipig.jsonc --write bun run aipig -- cliproxy restore --config .opencode/aipig.jsonc --backup /path/to/config.yaml.aipig-backup-... --write ``` ## 配置文件 AIPIG 使用其自己的配置文件，而不是将防护设置放入 `opencode.json`。 配置文件按以下顺序加载，后加载的文件会覆盖先前的文件： 1. Linux/macOS 全局：`~/.config/opencode/aipig.jsonc` 或 `aipig.json` 2. Windows 全局：`%APPDATA%\opencode\aipig.jsonc` 或 `aipig.json` 3. 自定义配置目录：`$OPENCODE_CONFIG_DIR/aipig.jsonc` 或 `aipig.json` 4. 项目配置：`.opencode/aipig.jsonc` 或 `aipig.json` 5. 显式文件：`AIPIG_CONFIG=/path/to/aipig.jsonc` 或 `--config /path/to/aipig.jsonc` 重要的环境变量覆盖： - `AIPIG_CONFIG`：显式的 `aipig.jsonc` 或 `aipig.json` 路径 - `AIPIG_FINGERPRINTS_PATH`：指纹库，默认为 `fingerprints.json` - `AIPIG_ALERTS_PATH`：告警日志，默认为 `alerts.jsonl` - `AIPIG_PENDING_SUGGESTIONS_PATH`：待处理建议的滚动 JSON 数组，默认为 `pending-suggestions.json` - `AIPIG_NOTIFY_LEVEL`：`first`、`always` 或 `never` - `AIPIG_ALERT_LIMIT`：告警环形缓冲区大小，默认为 `100` - `AIPIG_CLIPROXY_CPA_ROOT`：CLIProxyAPI 目录 - `AIPIG_CLIPROXY_PORT`：CLIProxyAPI 端口，默认为 `8317` - `AIPIG_JUDGE_BASE_URL`, `AIPIG_JUDGE_API_KEY`, `AIPIG_JUDGE_MODEL`：可选的 Tier 1 评判器 ## Windows 配置加载器支持 `%APPDATA%\opencode\aipig.jsonc`。 原生插件构建脚本输出： - Linux: `dist/cliproxy-aipig.so` - macOS: `dist/cliproxy-aipig.dylib` - Windows: `dist/cliproxy-aipig.dll` Windows 的 real-chain 验证尚未完成。安装路径已经实现，但在称其已具备发布条件之前，应在真实的 Windows 宿主机上验证 Windows。 ## 当前覆盖范围 | 工具 | 路径 | 响应文本注入 | Tool Result 注入 | 用户视图 | 下一次 AI 轮次 | 证据 | | --- | --- | --- | --- | --- | --- | --- | | Claude Code | CLIProxyAPI | 在 Claude 存储之前移除 | 尚未在 proxy 路径上覆盖 | 注入的横幅已从响应中剥离 | 携带清理后的响应文本 | [矩阵](eval/reports/anti-injection-matrix.md#claude-proxy) | | Claude Code | 直接 hooks | 只能从显示中隐藏 | 在 Claude 读取 tool 输出之前移除 | tool 输出注入已移除；响应横幅可能仅在屏幕上隐藏 | tool 结果已清理；响应文本可能仍保留在宿主上下文中 | [矩阵](eval/reports/anti-injection-matrix.md#claude-direct) | | OpenCode | CLIProxyAPI | 在 OpenCode 存储之前移除 | 尚未在 proxy 路径上覆盖 | 注入的横幅已从响应中剥离 | 携带清理后的响应文本 | [矩阵](eval/reports/anti-injection-matrix.md#opencode-proxy) | | OpenCode | 直接插件 | 由插件移除 | 由插件移除 | 注入的响应和 tool-result 文本已移除 | 清理后的内容被发送出去 | [矩阵](eval/reports/anti-injection-matrix.md#opencode-direct) | | Codex | CLIProxyAPI | 在 Codex 接收之前移除 | 尚未在 proxy 路径上覆盖 | 注入的横幅已从响应中剥离 | 携带清理后的响应文本 | [矩阵](eval/reports/anti-injection-matrix.md#codex-proxy) | | Codex | 直接 hooks | 仅告警；Codex 无法在此重写助手响应 | 使用 hook 反馈为模型进行替换 | 响应横幅可能仍然出现；tool-result 替换通过 hook 反馈呈现 | 响应横幅可能保留；tool 结果已清理 | [矩阵](eval/reports/anti-injection-matrix.md#codex-direct) | 仅用于占位的 token-padding 不会被重写。它会被记录并作为告警呈现。 ## Real Chain Eval real-chain eval 会临时向 CLIProxyAPI 添加本地 eval 密钥/upstream，等待热重载，为每个启用的宿主运行两轮，编写本地报告，恢复原始的 CPA 配置，然后再次等待热重载。 ``` bun run aipig -- build-plugin bun run eval:real-chain -- --config .opencode/aipig.jsonc ``` 仅在您的 CPA 构建中无法使用热重载时才使用 `--restart`： ``` bun run eval:real-chain -- --config .opencode/aipig.jsonc --restart ``` 报告路径默认为 `report/real-chain-eval.json`。`report/` 是本地证据，不应被提交。 ## 历史回放 回放是本地且只读的。它会流式传输显式的输入文件，默认解析 10,000 条记录，仅写入此代码库，且从不写入 `fingerprints.json`。 ``` bun run eval/history-replay.ts --input /absolute/path/to/history.jsonl --max-records 10000 ``` 您可以使用合成的注入覆盖层来叠加复制的本地 fixture： ``` bun run eval/history-replay.ts \ --input /absolute/path/to/copied-history.jsonl \ --input eval/fixtures/history-overlays/middlebox-injections.jsonl \ --max-records 1200 ``` 报告输出： ``` eval/reports/history-replay.md ``` 受信任的 system-prompt 容器（例如 Codex `session_meta.base_instructions`）在回放期间会被忽略。如果相同的类似 system-prompt 的文本出现在 `response_text` 或 `tool_result` 中，它仍然是可疑的。 ## 开发 运行检查： ``` ./node_modules/.bin/tsc --noEmit bun run verify bun run build:cliproxy-plugin ``` `verify` 会运行单元/集成测试和 Bun 构建。它不会运行 real-chain eval 或原生插件构建。

标签：AI代理, Bun, 人工智能, 代理拦截, 大语言模型防护, 日志审计, 用户模式Hook绕过, 自动化攻击