# Runwall
Runwall 为编码代理运行时添加了一层实用的安全防护，用于减少以下风险：提示词注入后果、密钥泄露、不安全命令执行、危险 Git 操作，以及存在风险的 MCP、插件或技能配置。
它现在支持两种模式：
- **审计模式**：扫描代理配置、钩子、MCP 服务器、技能、插件和指令文件
- **运行时模式**：内联执行、提示、阻止和脱敏
它专为独立开发者、初创公司、有安全意识的团队以及希望为 AI 编码工作流提供更安全默认配置的较大型组织设计。
## 为什么选择 Runwall？
编码代理之所以有用，是因为它们可以读取文件、运行 shell 命令、使用 git、连接 MCP 工具，并且越来越多地在多个运行时中工作。
这也正是它们需要护栏的原因。
Runwall 有助于降低以下方面的实际风险：
- 密钥泄露
- 委托的 OAuth 登录、云身份模拟和密钥管理器滥用
- 代理会话窃取和桌面凭据存储访问
- 浏览器远程调试暴露和本地信任存储篡改
- 提示词注入和渗透路径
- 隐藏在文件、网页、shell 输出和 MCP 响应中的间接提示词注入
- 不安全的 shell 执行
- 危险的 git 和仓库操作
- SSH 信任降级和审计规避
- shell 配置文件、计划任务和 SSH 密钥持久化
- hosts 文件和 sudo 策略篡改
- 明文 git、netrc 和注册表凭据存储
- 有风险的 MCP 和工具信任边界
- 恶意技能、命令和指令文档投毒
- 云密钥创建和直接生产环境 shell 访问
- 内联配置密钥粘贴、投毒报告、意外注册表登录和直接生产数据库 shell
- git 远程重连、包源交换、自托管 CI 运行器暴露和 SSH 命令钩子滥用
- 代理工作流中的弱本地默认配置
它实用、透明，专为真实开发者环境设计。
Runwall 现在支持四种集成方式：
- 本地运行时适配器（从现有钩子开始，首先支持 Claude Code）
- 插件或捆绑包安装（用于 Codex 和 OpenClaw）
- 内联 MCP 网关模式（用于 Cursor、Windsurf、Claude Desktop、Claude Cowork、Codex 回退模式和其他支持 MCP 的客户端）
- CLI 评估（用于管道和自动化门控）
## 功能说明
Runwall 帮助您：
- 扫描代理/运行时配置并在安装前生成评分报告
- 在高风险操作运行前阻止它们
- 内联强制执行 MCP 工具调用，在到达上游服务器之前进行拦截
- 在工具输出到达运行时之前扫描 MCP 工具响应
- 脱敏上游工具响应中的密钥或提示词走私内容，同时在可能的情况下保持 JSON 有效
- 在危险响应载荷转化为后续执行之前阻止它们
- 随着时间推移对可信 MCP 服务器和工具进行指纹识别，而不是永远信任同名元数据
- 检测服务器漂移、模式漂移、能力扩展和同名工具冲突，在信任悄然扩大之前发现问题
- 对可疑的多目标 MCP 请求要求本地审查
- 强制执行出站目标策略，涵盖私有 IP、元数据端点、Webhook、粘贴站点、原始 gist 风格主机和非允许列表的出口
- 当工具输出本身包含隐藏的提示词注入或越狱诱饵时发出警告
- 保护密钥、令牌、敏感文件和凭证
- 通过 shell 配置文件、启动项、cron、systemd 和 SSH 授权密钥阻止持久化
- 阻止委托的云登录和角色假设流程静默生成更广泛的访问
- 捕获密钥管理器拉取、内联配置密钥泄露和构建时容器密钥泄露
- 捕获通过远程调试、配置中的包认证密钥和包含密钥的文件进入公共制品的浏览器会话暴露
- 保护可信配置和指令文件免受符号链接劫持或静默清理
- 减少危险的 shell、git 和仓库行为
- 阻止本地信任边界篡改，如 hosts 文件重映射和 sudoers 弱化
- 在信任悄然扩大之前暂停 git 远程重连、包源交换和本地 CA 信任更改
- 防止明文 git、netrc 和注册表凭据被代理访问
- 标记未审查的注册表登录并阻止直接生产数据库 shell 访问
- 收紧 MCP、插件、技能和工具的信任边界
- 阻止云密钥创建、破坏性 Terraform 流、特权容器逃逸、生产环境 shell 紧急突破行为、有风险的生产环境 `kubectl exec` 和直接生产数据转储
- 用脱敏预览、证据、置信度和更安全的替代方案解释每个运行时决策
- 导出脱敏的事件包用于审查、分类和事后交接
- 快速应用更安全的默认配置文件
- 保持安全性的实用性，而不让工作流变成累赘
它在 Claude Code 沙盒模式之上也能很好地工作。沙盒有助于控制损害。Runwall 在该控制层之上添加了防护逻辑。
## 防护家族
Runwall 现在将签名分组为稳定的家族，使产品读起来像一个真正的签名引擎，而不是一个扁平列表：
- `Secrets & Identity`（密钥和身份）：令牌、会话、凭据存储、密钥管理器和委托认证流程
- `Supply Chain & Dependencies`（供应链和依赖项）：注册表、CI、制品、发布路径和提供者信任
- `Git & Source Control`（Git 和源代码管理）：远程、来源、历史安全和基于钩子的仓库滥用
- `MCP, Plugins & Skills`（MCP、插件和技能）：MCP 服务器、工具、插件、技能、指令文件和提示词走私路径
- `Runtime, Network & Egress`（运行时、网络和出口）：dropper、隧道、渗透、元数据和出站控制
- `Infra & Production Access`（基础设施和生产环境访问）：集群、数据库、基础设施工具和生产环境紧急突破行为
- `Trust, Persistence & Evasion`（信任、持久化和规避）：持久化、信任降级、审计擦除、符号链接劫持和边界篡改
- `Quality & Workflow`（质量和工作流）：工作流完整性、上下文策略、测试抑制和破坏性清理
您可以通过以下命令按家族检查活动注册表：
```
./bin/runwall list protections
```
## 适用对象
- 希望本地 AI 编码更安全的独立开发者
- 快速发展但努力避免密钥泄露或破坏仓库的初创公司
- 审查代理风险的安全工程师和 AppSec 团队
- 采用基于 MCP 工具的 DevSecOps 团队
- 需要在企业策略层之前获得更干净基线的较大型组织
对于纯聊天使用场景（不涉及工具、shell、git 或文件操作），它的相关性大大降低。
## 快速安装
最干净的安装路径是您正在使用的运行时的插件或捆绑包路径。
### Claude Code 插件
```
/plugin marketplace add efij/secure-claude-code
/plugin install runwall@runwall
```
### Codex 插件捆绑包
此仓库现在在 [`.codex-plugin/plugin.json`](/Users/efi.jeremiah/projects/secure-claude-code/.codex-plugin/plugin.json) 中提供 Codex 捆绑包清单，并在 [`.mcp.json`](/Users/efi.jeremiah/projects/secure-claude-code/.mcp.json) 中提供共享的 MCP 定义。
如果您的 Codex 支持本地插件或捆绑包安装，直接将此仓库安装为 `runwall` 并重启 Codex。
如果您想要手动回退方案：
```
./bin/runwall generate-runtime-config codex balanced
```
### OpenClaw 插件捆绑包
OpenClaw 可以将此仓库直接安装为兼容的捆绑包，因为它能检测 Claude 和 Codex 捆绑包标记并导入支持的技能和 MCP 工具。
```
openclaw plugins install ./secure-claude-code
openclaw plugins list
openclaw plugins inspect runwall
openclaw gateway restart
```
当您想要配置文件切换、更新、卸载、医生修复、运行时配置生成或单独的本地安装主目录时，请使用 CLI 路径。
### Cursor
生成 Cursor 就绪的 `mcp.json`：
```
./bin/runwall generate-runtime-config cursor balanced
```
然后将该输出放入 Cursor 在您机器上期望的 MCP 配置文件中。
它现在指向内联 Runwall 网关，而不是旧的辅助专用伴侣服务器。
### Windsurf
生成 Windsurf 就绪的 `mcp_config.json`：
```
./bin/runwall generate-runtime-config windsurf balanced
```
然后将该输出放入 Windsurf 在您机器上期望的 MCP 配置文件中。
它现在指向内联 Runwall 网关，而不是旧的辅助专用伴侣服务器。
### Claude Desktop
生成 Claude Desktop 就绪的 `claude_desktop_config.json`：
```
./bin/runwall generate-runtime-config claude-desktop balanced
```
然后将该输出合并到您的 Claude Desktop MCP 配置中。
它现在指向内联 Runwall 网关，而不是旧的辅助专用伴侣服务器。
### macOS / Linux
```
curl -fsSL https://raw.githubusercontent.com/efij/secure-claude-code/main/scripts/bootstrap.sh | bash -s -- --repo efij/secure-claude-code --ref main --profile balanced
```
### Windows
```
irm https://raw.githubusercontent.com/efij/secure-claude-code/main/scripts/bootstrap.ps1 | iex; Install-Runwall -Repo "efij/secure-claude-code" -Ref "main" -Profile "balanced"
```
### 本地检出
```
git clone https://github.com/efij/secure-claude-code.git
cd secure-claude-code
./bin/runwall install balanced
```
`install.sh`、`update.sh` 和 `uninstall.sh` 仍然存在，但它们只是围绕主 CLI 的薄兼容性包装器## 快速开始
### 应用更安全的基线
```
./bin/runwall install balanced
```
### 先运行审计
```
./bin/runwall audit .
./bin/runwall audit . --format html --output runwall-audit.html
./bin/runwall audit . --format sarif --output runwall-audit.sarif --fail-on high
```
### 验证设置
```
./bin/runwall doctor
./bin/runwall validate
```
### 查看活动防护
```
./bin/runwall list protections
```
输出按防护家族分组，然后按防护 ID 和操作类型分组。
### 查看支持的运行时
```
./bin/runwall list runtimes
```
### 检查最近的阻止和警告
```
./bin/runwall logs 20
./bin/runwall logs 50 --json
```
### 启动内联网关和仪表板
```
./bin/runwall gateway serve strict --config ./config/gateway.json --api-port 9470
```
然后打开 `http://127.0.0.1:9470` 检查事件、脱敏和待批准项。
仪表板现在明确显示三种流程：
- 请求侧阻止和提示（在上游执行之前）
- 响应侧脱敏、提示和阻止（在工具输出到达运行时之前）
- 出站目标决策（针对元数据端点、私有 IP、Webhook、粘贴站点、gist 风格主机和非允许列表出口）
它还显示：
- 带有基线与当前差异的工具和服务器身份漂移
- 默认脱敏的请求和响应预览
- 可导出的单事件、漂移审查或运行时调查的事件包
### 生成基线 CI 工作流
```
./bin/runwall init .
```
这会创建：
- `.runwall/audit-baseline.json`
- `.github/workflows/runwall-audit.yml`
## 多运行时支持
Runwall 现在围绕运行时适配器、捆绑包安装和内联 MCP 网关构建：
- `Claude Code`：本地钩子模式，具有直接的预工具和后工具强制执行
- `Codex`：插件捆绑包加内联网关回退模式
- `OpenClaw`：兼容的捆绑包安装，将 Runwall 技能和 MCP 工具映射到 OpenClaw
- `Cursor`：生成的 `mcp.json` 网关配置
- `Windsurf`：生成的 `mcp_config.json` 网关配置
- `Claude Desktop`：生成的 `claude_desktop_config.json` 网关配置
- `通用 MCP 客户端`：用于 Claude Cowork 和类似客户端的共享内联网关模式
- `CI/CD`：生成的 GitHub Actions 片段加 CLI 策略评估（用于高风险命令）
策略是：
1. 在运行时暴露钩子的地方进行本地强制执行
2. 在运行时可以直接使用 Runwall 的地方进行插件或捆绑包安装
3. 在运行时使用 MCP 但没有等效钩子的地方使用内联 MCP 网关模式
4. 用于管道和自动化门控的 CLI 评估
有关运行时矩阵和集成说明，请参阅 [RUNTIMES.md](
标签：AI安全, API接口, Chat Copilot, CISA项目, Claude Code, DevSecOps, DNS信息、DNS暴力破解, Guardrails, MCP, Model Context Protocol, OAuth安全, Shell命令安全, YARA规则, 上游代理, 代码代理安全, 代码分析, 凭证管理, 安全护栏, 审计模式, 密钥泄露防护, 工作流安全, 提示注入防护, 插件安全, 敏感信息保护, 数据外泄防护, 文档结构分析, 时序数据库, 本地优先, 机器学习安全, 结构化查询, 自动化安全
