Sengathirmcse/sigil-guardian
GitHub: Sengathirmcse/sigil-guardian
面向 AI 编码代理的安全可观测性层，通过哈希锚定审计链和沙箱意图推理，映射并缓解代理执行高危操作的风险。
Stars: 0 | Forks: 0
# AgentShield：AI 编码代理安全与合规卫士
[](https://sengathirmcse.github.io/sigil-guardian/)
**AgentShield** 是面向 AI 驱动的编码代理（包括 Claude Code、Codex、Gemini CLI 和 Cursor）的新一代安全可观测性层，它通过哈希锚定的权限链和沙箱意图推理，对代理防护面漏洞进行映射、监控和缓解。
[](LICENSE)
[](https://www.python.org/downloads/)
[](https://nodejs.org/)
[]()
## 为什么需要 AgentShield
想象一下，你的 AI 编码代理就像一个拥有 root 访问权限且毫无冲动控制能力的超级智能实习生——它能在几秒钟内写出出色的代码，但也可能以同样的热情对你的整个基础设施执行 `rm -rf /`。AgentShield 就是位于你的代理野心和生产环境之间的**意图防火墙**。
传统的安全工具监视人类。而 AgentShield 监视的是以机器速度做出决策的*机器*，在执行危险命令链之前将其拦截，并创建一个**关于每个代理操作的加密账本**，以供审计、回滚或重放。
## 系统架构
```
flowchart TB
subgraph "Agent Ecosystem"
A[Claude Code] -->|API Calls| B[AgentShield Proxy]
C[Codex] -->|API Calls| B
D[Gemini CLI] -->|API Calls| B
E[Cursor] -->|IDE Hooks| B
end
subgraph "Guard Surface Engine"
B --> F{Hook Interceptor}
F -->|Hash Chain| G[Intent Analyzer]
F -->|Permission Check| H[Sandbox Validator]
G --> I{Risk Score Calculator}
H --> I
I -->|Pass| J[Execute Command]
I -->|Fail| K[Quarantine & Log]
I -->|Uncertain| L[Human Approval Queue]
end
subgraph "Compliance Layer"
J --> M[Action Ledger]
K --> M
L --> M
M --> N[Hash-Anchor Registry]
M --> O[Audit Trail API]
M --> P[Rollback Engine]
end
subgraph "External Integrations"
O --> Q[SIEM Systems]
O --> R[Compliance Reports]
P --> S[Git Restore Points]
end
```
## 核心能力
### 1. 哈希锚定权限链 🔗
每个代理操作都会接收到一个加密指纹，该指纹与前一个操作相链接。如果有人（或什么东西）试图修改历史记录，整个链条就会断裂——从而立即被检测到。
- 带有 SHA-3 哈希的**防篡改审计追踪**
- 每次启动时的**链验证**
- 可导出用于 SOC 2 审计的**完整性证明**
### 2. 沙箱意图推理 🏖️
AgentShield 不仅仅监视代理*做*了什么——它还通过对照已知攻击模式分析命令序列，来预测*它想要做什么*。
- 每个代理会话的**行为分析**
- 每个命令的**意图评分** (0-100)
- 超过阈值时的**自动隔离**
### 3. 多代理防护面 🛡️
| 代理 | Hook 级别 | 权限范围 | 沙箱深度 |
|-------|-----------|-----------------|---------------|
| Claude Code | Shell + 文件系统 | 读/写/执行 | 完整容器 |
| Codex | API 包装器 | 默认只读 | 进程受限 |
| Gemini CLI | Socket 代理 | 白名单命令 | 用户命名空间 |
| Cursor | IDE 扩展 | 仅工作区 | no_new_privs |
### 4. 响应式威胁仪表板 📊
实时可视化代理活动，可深入查看每个哈希锚定的操作。支持移动端响应，方便进行“凌晨 3 点事件”检查。
## 功能概览
- 支持 Claude Code、Codex、Gemini CLI 和 Cursor 的**多代理支持**
- 带有加密验证的**哈希锚定审计链**
- 使用行为 ML 模型的**沙箱意图推理**
- 具有精细控制（文件、网络、进程、变量）的**权限防护面**
- 针对可疑命令序列的**自动回滚**
- **合规报告生成**（SOC 2, ISO 27001, FedRAMP 模式）
- **多语言界面**（英语、日语、德语、西班牙语、法语）
- 通过集成工单系统提供 **24/7 客户支持**
- **OpenAI API 和 Claude API 集成**，用于自然语言规则创建
- 适用于移动仪表板和壁挂式屏幕的**响应式 UI**
## 操作系统兼容性
| 操作系统 | 状态 | 备注 |
|----------------|--------|-------|
| 🐧 Linux (Ubuntu 22.04+) | ✅ 全面支持 | 原生性能事件 |
| 🍎 macOS 13+ | ✅ 全面支持 | 感知系统完整性保护 |
| 🪟 Windows 11 | ✅ 全面支持 | 为 Linux 代理提供 WSL2 集成 |
| 🐧 Debian 11+ | ✅ 支持 | 需要额外的内核模块 |
| 🍎 macOS 12 | ⚠️ 有限支持 | 无内存执行监控 |
| 🪟 Windows 10 | ⚠️ 有限支持 | 无 eBPF 支持 |
## 示例配置文件
在你的项目根目录下创建一个名为 `agentshield.profile.yaml` 的文件：
```
name: Production-Codex-Guard
agent: Codex
version: 2026.1
permissions:
filesystem:
read: ["/src", "/config", "/data"]
write: ["/src/temp", "/output"]
execute: ["/usr/local/bin/*"]
network:
allowed_hosts: ["api.github.com", "pypi.org"]
blocked_hosts: ["*internal*", "localhost:8080"]
shell:
allowed_commands: ["git", "npm", "pip", "docker", "python"]
block_patterns: ["rm -rf", "chmod 777", "sudo"]
sandbox:
type: container
image: python:3.12-slim
memory_limit: 2GB
cpu_limit: 1.5
network: isolated
volumes:
- source: /src
target: /workspace
readonly: true
hooks:
pre_command:
- endpoint: http://localhost:9090/hooks/pre
timeout: 500ms
post_command:
- endpoint: http://localhost:9090/hooks/post
async: true
intent_analysis:
model: behavioral-v2
sensitivity: medium
quarantine_threshold: 85
human_approval_range: [60, 84]
hash_anchoring:
algorithm: SHA3-512
chain_file: /var/agentshield/chain.dat
verify_on_load: true
logging:
level: info
audit_retention_days: 365
compliance_exports: ["soc2", "iso27001"]
```
## 示例控制台调用
```
# 使用 Claude Code agent 启动 AgentShield
agentshield start --agent claude-code --profile production-claude.yaml
# 观看实时 agent 活动
agentshield watch --live --filter risk>70
# 验证 hash chain 完整性
agentshield audit verify --chain /var/agentshield/chain.dat
# 生成 compliance report
agentshield audit export --format soc2 --output ./reports/soc2_2026_q1.pdf
# 回滚最后 5 个 agent 操作
agentshield rollback --count 5 --reason "Suspicious npm install chain"
# 查询 intent 历史
agentshield query --agent "codex" --since "2026-01-01" --intent-score >80
```
## OpenAI API 和 Claude API 集成
AgentShield 利用大型语言模型 (LLM) 使安全规则能够以通俗易懂的英语理解：
### 自然语言规则创建
无需编写复杂的 YAML，只需描述你的意图：
```
# 使用 OpenAI
agentshield rule create --llm openai --prompt "Block any command that could delete production databases"
# 使用 Claude API
agentshield rule create --llm claude --prompt "Never let npm install packages from untrusted registries"
```
AgentShield 会将这些意图转化为可执行的防护策略，并附带哈希锚定的规则定义。
### 智能异常解释
当代理操作触发隔离时，AgentShield 会将上下文发送给 LLM 进行人类可读的分析：
```
[AgentShield: Claude Code blocked on "rm -rf /app/db" at 14:23:01 UTC]
Reasoning: Intent score 94/100 (quarantine threshold 85)
LLM Analysis: "This command appears to be a database cleanup operation,
but the '-rf' flag combined with the absolute root path `/app/db` instead
of a relative path suggests either an insider threat attempt or a copy-paste
error. The agent's previous action (git pull origin main) escalated
permissions unexpectedly. Recommend denial pending human review."
```
## 安全模型：玻璃堡垒
将 AgentShield 视为你 AI 代理的**玻璃堡垒**：
1. **默认透明** - 每个操作在哈希锚定账本中均可见
2. **设计坚固** - 意图分析能捕捉到表面规则遗漏的问题
3. **篡改即碎** - 任何修改尝试都会破坏链条完整性
该模型之所以有效，是因为 AI 代理不会疲倦、情绪化或被收买——但它们确实会感到困惑、被赋予过多权限或被劫持。AgentShield 提供了**认知摩擦**，将有用的自动化与灾难性的自动化区分开来。
## 快速入门 🚀
[](https://sengathirmcse.github.io/sigil-guardian/)
### 快速安装
```
# macOS / Linux
curl -sSL https://agentshield.dev/install.sh | bash
# Windows (PowerShell Admin)
iwr -useb https://agentshield.dev/install.ps1 | iex
# 验证安装
agentshield --version
# 输出：AgentShield v2026.04.12
```
### 首次运行
```
# 使用默认 profile 初始化
agentshield init --agent claude-code
# 开始监控
agentshield start --name "My First Agent Guard"
# 连接你的 agent（以 Claude Code 为例）
CLAUDE_CODE_ARGS="--agentshield http://localhost:9443" claude
```
## 合规与治理
AgentShield 专为需要**可审计 AI 代理操作**的组织而设计：
- **SOC 2 Type II** 报告生成（每季度自动生成）
- **ISO 27001** 控制映射（参考附录 A）
- **GDPR** 数据处理日志（支持解释权）
- **FedRAMP** 中等基线模式
- 支付环境的 **PCI DSS** 命令隔离
每次合规性导出都包含哈希锚定链，作为数据完整性的加密证明。
## 多语言支持 🌐
AgentShield 界面支持：
- **English** (英语，默认)
- **日本語** (日语) - 针对术语宽度进行了优化
- **Deutsch** (德语) - 精确的复合词处理
- **Español** (西班牙语) - 完整的 RTL 支持
- **Français** (法语) - 带变音符号的感知搜索
仪表板、CLI 输出和合规报告会自动检测系统语言，或者接受显式的 `--lang` 标志。
## 24/7 客户支持
| 渠道 | 可用性 | 响应时间 |
|---------|--------------|---------------|
| 应用内聊天 | 24/7/365 | <30 秒 |
| 电子邮件 | 24/7 | <2 小时 |
| Discord | 工作时间 | <15 分钟 |
| 电话（紧急） | 企业版 24/7 | <5 分钟 |
企业版计划包含专属支持工程师，他们既了解 AI 代理行为，又精通安全合规。
## 2026 路线图
- **2026 年第一季度**：发布 v1.0，支持 Claude Code、Codex
- **2026 年第二季度**：Gemini CLI、Cursor 集成；意图分析 v2
- **2026 年第三季度**：多代理协调防护；跨代理哈希链
- **2026 年第四季度**：联邦代理安全网格；零信任代理架构
## 免责声明
**AgentShield** 是一款安全增强工具，不能替代全面的安全实践。没有任何软件可以保证免受所有威胁，包括零日漏洞、高级持续性威胁或针对 AI 代理的社会工程学攻击。
哈希锚定链提供了加密完整性验证，但无法防止最初的入侵事件。请始终保持离线备份，遵循代理权限的最小权限原则，并定期审计代理活动日志——即使部署了 AgentShield。
AgentShield 不会检查或存储代理的提示词或响应；仅保留命令执行元数据和意图分数以用于合规目的。在启用完整审计功能之前，请查看你所在组织的数据保留政策。
使用风险自负。对于因使用或 misuse 本软件而产生的损害，开发者不承担任何责任。
## 许可证
该项目基于 MIT License 授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
[](https://sengathirmcse.github.io/sigil-guardian/)
*AgentShield：因为到了 2026 年，你的 AI 编码代理不应该在无人监管的情况下拥有 root 访问权限。* 🔒
标签：AI编程助手, Docker镜像, GNU通用公共许可证, Node.js, Petitpotam, Python, 代理防护, 后端开发, 安全合规, 审计监控, 无后门, 沙箱, 网络代理, 请求拦截