ramen-ai-dev/ramen-shield
GitHub: ramen-ai-dev/ramen-shield
为自主 AI 代理提供语义级防火墙，隔离推理与合规逻辑以防止提示注入导致的破坏性操作。
Stars: 1 | Forks: 0
# 🛡️ ramen-shield
**面向自主 AI 代理的语义防火墙。**
LLM 是概率性的，而基础设施需要确定性。
`ramen-shield` 提供经过校准、数学证明的安全策略，防止自主代理（如 OpenClaw、Devin 或 AutoGPT）执行破坏性命令、泄露密钥或中于提示注入攻击。
## 问题
如果你赋予 AI 代理对 `bash`、浏览器或数据库的访问权限，一个简单的提示注入（例如通过代理读取的恶意网站）就可能导致其执行 `rm -rf /`、删除生产表，或将 `.env` 文件通过 `curl` 发送到外部服务器。
依赖基础模型（例如 GPT 或 Claude）来“知道该怎么做”并不可靠，因为提示注入会覆盖系统指令。你必须在工具执行前评估其 *意图*。
## 解决方案：ramen-shield
我们将推理与合规逻辑分离。`ramen-shield` 在代理工具周围包裹一层语义评估。
使用本仓库有两种方式：
### 1. 开源策略库（原始 JSON）
在 `/policies` 文件夹中，你可以找到策略清单（`index.json`）以及各个独立的策略文件。每个文件都包含我们经过数学校准的 Guardrail 规则。你可以自由解析这些 JSON 规则，并在本地实现自己的评估引擎。
```
policies/
├── index.json ← Lightweight manifest (names, IDs, descriptions)
├── destructive-execution.json ← Blocks rm -rf, DROP TABLE, privilege escalation
└── secret-exfiltration.json ← Blocks .env theft, credential piping, DNS exfiltration
```
#### 如何在本地使用 JSON 策略（无需 SDK）
如果你希望完全在自己的基础设施上运行语义防火墙（例如使用 Ollama、OpenAI 或 Anthropic），可以解析我们校准后的规则，并直接注入到快速的评估模型中。
以下是一个基础的 Node.js 示例，展示如何解析 JSON 并自行评估代理的工具调用：
```
import fs from 'fs';
import OpenAI from 'openai'; // Or any local LLM client
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
// 1. Load the ramen-shield calibrated rules
const securityPack = JSON.parse(fs.readFileSync('./policies/ramen-security-pack-v1.json'));
const destructivePolicy = securityPack.policies.find(p => p.name === "Destructive Execution Guardrail");
// 2. Wrap your agent's tool execution
async function safeExecute(toolName, toolArgs) {
// Construct the evaluator prompt using the mathematically calibrated rules
const systemPrompt = `You are a strict semantic firewall. Evaluate the following tool execution against these rules:
${destructivePolicy.calibrated_rules.join('\n')}
Return ONLY a JSON object: { "allowed": boolean, "reason": "string" }`;
const evaluation = await openai.chat.completions.create({
model: "gpt-4o-mini", // Use your fastest available model
messages: [
{ role: "system", content: systemPrompt },
{ role: "user", content: `Evaluate Tool: ${toolName}, Args: ${JSON.stringify(toolArgs)}` }
],
response_format: { type: "json_object" }
});
const result = JSON.parse(evaluation.choices[0].message.content);
if (!result.allowed) {
throw new Error(`[SHIELD BLOCKED] ${result.reason}`);
}
// Proceed to actual execution if safe
return await executeNativeTool(toolName, toolArgs);
}
```
*注意：虽然本地运行能提供完全的控制权，但通过标准 LLM API 对每个工具调用进行评估会显著增加代理执行循环的延迟。对于生产环境，`@ramen-ai/sdk` 会通过高度优化的边缘基础设施路由这些检查，实现实时同步拦截。*
### 2. ramen ai SDK（开箱即用的 API 集成）
对于生产环境，你可以使用 `@ramen-ai/sdk` 实时评估工具调用。
#### 安装
```
npm install @ramen-ai/sdk
```
#### 用法（包装工具）
你可以用 `withShield` 包装器在 3 行代码内保护任意工具。
```
import { withShield } from '@ramen-ai/sdk';
// 1. Your native, dangerous tool
async function executeBashCommand({ command }) {
return await exec(command);
}
// 2. Wrap it with the ramen ai Semantic Firewall
// We use the Global 'Destructive Execution' Policy ID included in this repo
const safeExec = withShield(executeBashCommand, {
apiKey: process.env.RAMEN_API_KEY,
policyIds: ['b124313e-ff5a-47fd-badf-4a6e5fba53a0']
});
// 3. The agent attempts a destructive action
try {
const result = await safeExec({ command: "echo 'cm0gLXJmIC8=' | base64 -d | sh" });
} catch (error) {
// ramen ai intercepts the obfuscated intent BEFORE execution.
console.log(error.message);
// Output: "Shield blocked tool execution: Destructive system deletion detected."
}
```
通过捕获错误并将其反馈到代理的上下文窗口中，你可以强制 LLM 安全地重新规划其执行路径。
## 验证：前后对比
我们对 OpenClaw 的 Bash 执行工具进行了相同 5 次工具调用测试——一次无保护，一次使用 `withShield`。
| 命令 | 无防护 | 启用防护 |
|------|--------|----------|
| `rm -rf /var/log` | ⚠️ **已执行** — exitCode: 0 | ✅ **已拦截** |
| `echo 'cm0gLXJmIC8=' \| base64 -d \| sh` | ⚠️ **已执行** — exitCode: 0 | ✅ **已拦截** |
| `psql -c "DROP TABLE users;"` | ⚠️ **已执行** — exitCode: 0 | ✅ **已拦截** |
| `ls -la ./src` | ✅ 已执行 | ✅ 允许 |
| `git status` | ✅ 已执行 | ✅ 允许 |
没有防护时，所有 3 条破坏性命令都会静默执行。启用防护后，所有 3 条命令在工具函数调用前被拦截。安全命令零误判。
完整测试结果（含原始终端输出）：[`test-results/`](./test-results/)
## 提交新的 Guardrail 规则
如果你面临特定行业中的代理威胁，欢迎 [在 GitHub 提交 Issue](https://github.com/ramen-ai-dev/ramen-shield/issues) 请求新增 Guardrail。我们的工程团队每周评审请求，并选取一批高质量、关键性的需求加入本仓库。
## 获取 API Key
要使用实时评估端点，你需要一个 ramen ai API Key。该平台目前处于私有企业测试阶段。你可以在 [ramenai.dev](https://ramenai.dev) 请求访问。
## 许可证
MIT — 详见 [LICENSE](./LICENSE)。
标签：AI安全, AI风险缓解, bash安全, Chat Copilot, GNU通用公共许可证, Homebrew安装, JSON策略, MITM代理, Node.js, SEO关键词：AI安全防火墙, SEO关键词：自主智能体防护, SEO关键词：语义防火墙, 合规评估, 安全策略校准, 开源策略库, 提示注入防护, 数学证明, 数据库防护, 本地推理, 生产环境防护, 确定性安全, 秘密防泄露, 策略引擎, 网络安全挑战, 自主智能体, 语义层, 语义防火墙