oktsec/oktsec
GitHub: oktsec/oktsec
AI 智能体间通信的安全网关，提供身份验证、策略执行、内容扫描和审计追踪。
Stars: 2 | Forks: 0
Oktsec — AI 智能体间通信的安全层
安装 ·
快速开始 ·
网关 ·
OpenClaw ·
NanoClaw ·
审计 ·
仪表盘 ·
SDK ·
规则 ·
配置
AI 智能体消息传递的身份验证、策略执行、内容扫描和审计跟踪。支持 MCP 客户端、OpenClaw 和 NanoClaw。无需 LLM。单一二进制文件。**175 条检测规则。** 基于 [官方 MCP SDK](https://github.com/modelcontextprotocol/go-sdk) 构建。符合 [OWASP Top 10 for Agentic Applications](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications/)。
## 它的功能
Oktsec 位于 AI 智能体之间，执行多层安全管道：
1. **速率限制** — 每个智能体的滑动窗口限流可防止消息泛洪 (ASI02, ASI10)。
2. **身份验证** — Ed25519 签名验证每个消息发送者。无有效签名，不处理 (ASI03)。
3. **智能体暂停** — 被暂停的智能体会立即被拒绝，不再进行后续处理 (ASI10)。
4. **策略** — 基于 YAML 的 ACL 控制哪个智能体可以向谁发送消息。默认拒绝模式会拒绝未知发送者 (ASI03)。
5. **内容扫描** — 175 条检测规则可捕获提示注入、凭据泄露、PII 暴露、数据渗漏、MCP 攻击、供应链风险等 (ASI01, ASI02, ASI05)。
6. **BlockedContent 执行** — 基于类别的每智能体内容阻断，当发现结果与被阻止类别匹配时升级判定 (ASI02)。
7. **多消息升级** — 重复被阻止的智能体会自动升级其判定结果 (ASI01, ASI10)。
8. **审计** — 每条消息都会记录到 SQLite，包含内容哈希、发送者验证状态、策略决策和触发的规则。
9. **异常检测** — 后台风险评分，带有自动警报和可选的自动暂停 (ASI10)。
```
Agent A → sign → POST /v1/message → [Oktsec] → rate limit → verify → suspend check → ACL → scan → blocked content → escalation → deliver/block/quarantine → audit → anomaly check
```
### 支持的平台
| 平台 | 协议 | 发现 | 封装 | 扫描 |
|----------|----------|-----------|------|------|
| Claude Desktop | MCP (stdio) | yes | yes | yes |
| Cursor | MCP (stdio) | yes | yes | yes |
| VS Code | MCP (stdio) | yes | yes | yes |
| Cline | MCP (stdio) | yes | yes | yes |
| Windsurf | MCP (stdio) | yes | yes | yes |
| **OpenClaw** | **WebSocket** | **yes** | **n/a** | **yes** |
| **NanoClaw** | **挂载白名单** | **yes** | **n/a** | **yes** |
## 安装
### 快速安装
```
curl -fsSL https://raw.githubusercontent.com/oktsec/oktsec/main/install.sh | bash
```
将最新的二进制文件安装到 `~/.local/bin`。使用环境变量进行自定义：
```
VERSION=v0.5.0 curl -fsSL https://raw.githubusercontent.com/oktsec/oktsec/main/install.sh | bash
INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/oktsec/oktsec/main/install.sh | bash
```
### 预编译二进制文件
从 [发布页面](https://github.com/oktsec/oktsec/releases) 下载。
### 从源代码构建
```
go install github.com/oktsec/oktsec/cmd/oktsec@latest
```
### Docker
```
docker pull ghcr.io/oktsec/oktsec:latest
docker run -p 8080:8080 ghcr.io/oktsec/oktsec
```
包含配置和密钥持久化：
```
docker run -p 8080:8080 \
-v ./oktsec.yaml:/home/oktsec/oktsec.yaml \
-v ./keys:/home/oktsec/keys \
-v oktsec-data:/home/oktsec/data \
ghcr.io/oktsec/oktsec serve --config /home/oktsec/oktsec.yaml
```
Docker Compose（推荐用于多智能体设置）：
```
docker compose up -d
```
完整示例请参见 [`docker-compose.yml`](docker-compose.yml)。
如需将 Oktsec 与 **Docker Sandboxes**（用于 AI 智能体的隔离微型虚拟机）一起使用，请参阅专用指南：[Oktsec + Docker Sandboxes](guides/docker-sandboxes.md)。Oktsec 支持正向代理模式（`forward_proxy.enabled: true`），可与 Docker Sandbox 的 `--network-proxy` 标志配合使用 —— 所有出站 HTTP 流量都会被透明扫描。
## 快速开始
### 一键设置（推荐）
```
oktsec setup
oktsec serve
```
就是这样。`oktsec setup` 会发现您机器上的所有 MCP 客户端，生成具有合理默认值的配置，创建 Ed25519 密钥对，并通过安全代理封装每个 MCP 服务器 —— 一步完成。
Oktsec 以 **观察模式** 启动 —— 它记录所有内容但不阻止任何内容。使用终端中显示的访问码在 `http://127.0.0.1:8080/dashboard` 的仪表盘中查看活动。重启您的 MCP 客户端（Claude Desktop、Cursor 等）以激活。
要启用 **强制执行模式**（使用 JSON-RPC 错误阻止恶意请求）：
```
oktsec wrap --all --enforce
# 或对于单台服务器：
oktsec proxy --enforce --agent filesystem -- npx @mcp/server-filesystem /data
```
### 分步设置（如果您喜欢掌控细节）
```
oktsec discover # See what's installed
oktsec init # Generate config + keypairs
oktsec wrap claude-desktop # Wrap one client at a time
oktsec serve # Start proxy + dashboard
```
### 手动设置
```
# 生成 agent 密钥对
oktsec keygen --agent research-agent --agent analysis-agent --out ./keys/
# 创建 config
cat > oktsec.yaml <
",
"timestamp": "2026-02-22T10:00:00Z"
}'
```
响应：
```
{
"status": "delivered",
"message_id": "550e8400-e29b-41d4-a716-446655440000",
"policy_decision": "allow",
"rules_triggered": [],
"verified_sender": true
}
```
## OpenClaw 支持
[OpenClaw](https://github.com/openclaw/openclaw) 是最大的 AI 智能体平台（30万+ 用户，14万+ GitHub 星标）。它赋予智能体访问文件系统、Shell、邮件、日历、浏览器和消息通道（WhatsApp、Telegram、Slack、Discord）的权限。CrowdStrike 将其记录为“一种强大的 AI 后门智能体，能够接受敌对者的命令。”每条 DM 都是一个提示注入向量。
**OpenClaw 不使用 MCP。** 它拥有自己的 WebSocket 网关（`ws://127.0.0.1:18789`）和位于 `~/.openclaw/openclaw.json` 的 JSON5 配置。Oktsec 通过专用扫描器检测、解析和分析 OpenClaw 安装。
### 扫描 OpenClaw 安装
```
oktsec scan-openclaw
oktsec scan-openclaw --path ~/.openclaw/openclaw.json
```
输出：
```
Scanning OpenClaw installation: /home/user/.openclaw/openclaw.json
Risk Level: CRITICAL
[!] tools.profile is "full" with no deny list — agents have unrestricted tool access
[!] gateway.bind is "0.0.0.0" — WebSocket gateway exposed to network
[!] dmPolicy is "open" — any external message can reach agents (prompt injection vector)
[!] messaging channels configured (slack, telegram) — each is a prompt injection attack surface
[!] no agents have sandbox enabled — all agents run with full host access
────────────────────────────────────────────────────────────
Summary:
Config risk: CRITICAL
Risk factors: 5
Workspace files: 2 scanned
Content issues: 3 finding(s)
```
### 风险检查
风险评估器检查 7 种模式：
| 检查项 | 严重性 | 触发条件 |
|-------|----------|---------|
| 完整工具配置文件 | Critical | `tools.profile == "full"` 且无拒绝列表 |
| 无沙箱执行 | Critical | `exec`/`shell` 在 tools.allow 中，无沙箱化智能体 |
| $include 中的路径遍历 | Critical | `$include` 路径中包含 `..` |
| 暴露的网关 | High | `gateway.bind` 为 `0.0.0.0`、`lan` 或 `::` |
| 开放 DM 策略 | High | `dmPolicy == "open"` |
| 无沙箱 | High | 没有智能体启用 `sandbox: true` |
| 消息通道 | Medium | 配置了任何通道（攻击面） |
### OpenClaw 检测规则
`openclaw-config` 类别中的 7 条专用规则：
| 规则 | 严重性 | 描述 |
|------|----------|-------------|
| `OCLAW-001` | Critical | 无限制的完整工具配置文件 |
| `OCLAW-002` | High | 网关暴露于网络 |
| `OCLAW-003` | High | 开放 DM 策略 |
| `OCLAW-004` | Critical | 无沙箱的 Exec/Shell 工具 |
| `OCLAW-005` | Critical | `$include` 中的路径遍历 |
| `OCLAW-006` | High | 网关缺少身份验证 |
| `OCLAW-007` | High | 配置中的硬编码凭据 |
### 为什么封装 (Wrap) 对 OpenClaw 无效
MCP 客户端使用 stdio —— oktsec 可以封装命令并拦截 JSON-RPC 流量。OpenClaw 使用 WebSocket 网关，因此封装模型不适用。运行 `oktsec wrap openclaw` 会返回一个清晰的错误，指向 `scan-openclaw` 代替。
## NanoClaw 支持
[NanoClaw](https://github.com/nanoclaw/nanoclaw) 是 OpenClaw 的轻量级替代品，专注于 AI 智能体的文件系统访问。它使用挂载白名单（`~/.config/nanoclaw/mount-allowlist.json`）来控制智能体可以读写哪些目录。
Oktsec 自动检测 NanoClaw 安装并审计其安全配置错误：
```
oktsec discover # Detects NanoClaw automatically
oktsec audit # Includes NanoClaw checks
```
### NanoClaw 检查
部署审计中的 6 项检查：
| 检查 | 严重性 | 触发条件 |
|-------|----------|---------|
| NC-MNT-001 | Critical | 挂载白名单丢失或无法解析 |
| NC-MNT-002 | High | `nonMainReadOnly` 为 false（对所有挂载点具有写权限） |
| NC-MNT-003 | Critical | 白名单中的危险根路径（`/`、`~`、`$HOME`） |
| NC-MNT-004 | Medium | 未配置阻止的文件模式 |
| NC-SEC-001 | High | 白名单文件权限过宽 |
| NC-MNT-005 | High | 敏感路径上的 `allowReadWrite`（`/etc`、`/var`、`~`） |
## 入门流程
### 发现
扫描您的机器以查找 MCP 服务器配置、OpenClaw 和 NanoClaw 安装：
```
oktsec discover
```
输出：
```
Found 2 MCP configuration(s):
Cursor /home/user/.cursor/mcp.json
├── filesystem npx -y @mcp/server-filesystem /data
├── database node ./db-server.js
└── github npx -y @mcp/server-github
OpenClaw /home/user/.openclaw/openclaw.json
├── openclaw-gateway openclaw gateway 0.0.0.0
├── assistant openclaw agent assistant
└── channel-slack openclaw channel slack
OpenClaw risk: CRITICAL
[!] tools.profile is "full" with no deny list — agents have unrestricted tool access
[!] no agents have sandbox enabled — all agents run with full host access
Run 'oktsec scan-openclaw' for full analysis.
NanoClaw ~/.config/nanoclaw/mount-allowlist.json
└── mount-allowlist 6 paths configured
Total: 6 MCP servers across 3 clients
Run 'oktsec init' to generate configuration and start observing.
```
支持的客户端：Claude Desktop、Cursor、VS Code、Cline、Windsurf、OpenClaw、NanoClaw。
### 初始化
自动为每个发现的服务器生成 `oktsec.yaml` 配置和 Ed25519 密钥对：
```
oktsec init
oktsec init --keys ./keys --config ./oktsec.yaml
```
每个服务器根据其能力自动按风险级别分类：
- **Critical** — database、postgres、mysql、sqlite、mongo、redis
- **High** — filesystem、git、github、browser、puppeteer、playwright、openclaw
- **Medium** — slack、discord、email、messaging
- **Unknown** — 其他所有（默认为观察模式）
### 封装 / 解封
修改 MCP 客户端配置以通过 `oktsec proxy` 路由服务器流量：
```
oktsec wrap cursor # Observe mode (log only)
oktsec wrap --enforce cursor # Enforcement mode (block malicious requests)
oktsec unwrap cursor # Restore original client config
```
封装前：
```
{ "command": "npx", "args": ["-y", "@mcp/server-filesystem", "/data"] }
```
封装后：
```
{ "command": "oktsec", "args": ["proxy", "--agent", "filesystem", "--", "npx", "-y", "@mcp/server-filesystem", "/data"] }
```
使用 `--enforce`：
```
{ "command": "oktsec", "args": ["proxy", "--agent", "filesystem", "--enforce", "--", "npx", "-y", "@mcp/server-filesystem", "/data"] }
```
### Stdio 代理
`proxy` 命令封装 MCP 服务器进程，拦截其 JSON-RPC 2.0 stdio 流量。每条消息都通过 Aguara 引擎扫描并记录到审计跟踪：
```
oktsec proxy --agent filesystem -- npx @mcp/server-filesystem /data
oktsec proxy --enforce --agent database -- node ./db-server.js
```
在 **观察模式**（默认）下，无论扫描结果如何，所有消息都会被转发。在 **强制执行模式**（`--enforce`）下，被阻止的客户端→服务器请求不会被转发 —— 而是将 JSON-RPC 2.0 错误响应注入回客户端：
```
{"jsonrpc":"2.0","id":42,"error":{"code":-32600,"message":"blocked by oktsec: IAP-001"}}
```
服务器→客户端响应始终被转发（仅观察）。这就是 `oktsec wrap` 为每个服务器自动配置的内容。
## 部署审计
`audit` 命令检查您的 oktsec 部署和任何检测到的智能体平台是否存在安全配置错误。它跨 Oktsec、OpenClaw、NanoClaw 和发现的 MCP 服务器运行检查，并输出带有补救指导的健康评分：
```
oktsec audit
oktsec audit --json
oktsec audit --sarif # SARIF v2.1.0 for CI integration
```
输出：
```
Deployment Security Audit
═════════════════════════
Health Score: 72 / 100 (Grade: C)
Oktsec (16 checks)
──────────────────
[CRITICAL] require_signature is false — messages accepted without verification
Fix: Set identity.require_signature: true in oktsec.yaml
[HIGH] default_policy is "allow" — unknown agents can send messages
Fix: Set default_policy: deny in oktsec.yaml
OpenClaw (18 checks)
────────────────────
[CRITICAL] tools.profile is "full" with no deny list
Fix: openclaw config set tools.profile restricted
Summary: 2 critical, 3 high, 1 medium, 35 passed
```
`status` 命令提供快速健康摘要：
```
oktsec status
```
## MCP 网关
Oktsec 可以作为 **Streamable HTTP MCP 网关** 运行，前端化一个或多个后端 MCP 服务器，通过完整的安全管道拦截每个 `tools/call`。基于 [官方 MCP SDK](https://github.com/modelcontextprotocol/go-sdk)（v1, Tier 1）构建。
```
oktsec gateway --config ./oktsec.yaml
```
网关位于您的智能体与其 MCP 服务器之间：
```
Agent ──► Oktsec Gateway ──► Backend MCP Server(s)
│
├─ Rate limit
├─ Agent ACL check
├─ Content scan (175 rules)
├─ Rule overrides
├─ Verdict (allow/block/quarantine)
├─ Audit log
└─ Webhook notification
```
在 `oktsec.yaml` 中配置后端 MCP 服务器：
```
gateway:
enabled: true
port: 9090
endpoint_path: /mcp
scan_responses: true # also scan what backends return
mcp_servers:
filesystem:
transport: stdio
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
github:
transport: http
url: https://api.github.com/mcp
```
功能：
- **工具发现** — 自动发现并暴露所有后端的工具
- **工具命名空间** — 冲突的工具名称添加前缀（`backend_toolname`）
- **每智能体工具白名单** — 限制每个智能体可以访问的工具
- **响应扫描** — 在返回给智能体之前可选择扫描后端响应
- **自动端口** — 如果配置的端口繁忙，则回退到相邻端口
## MCP 服务器模式
Oktsec 可以作为 MCP 工具服务器运行，让 AI 智能体直接访问安全操作：
```
oktsec mcp --config ./oktsec.yaml
```
添加到您的 MCP 客户端配置：
```
{
"mcpServers": {
"oktsec": {
"command": "oktsec",
"args": ["mcp", "--config", "./oktsec.yaml"]
}
}
}
```
可用工具 (6)：
| 工具 | 描述 |
|---|---|
| `scan_message` | 扫描内容以检测提示注入、凭据泄露、PII 和 175 种威胁模式 |
| `list_agents` 列出所有智能体及其 ACL 和内容限制 |
| `audit_query` | 使用过滤器查询审计日志（状态、智能体、限制） |
| `get_policy` | 获取特定智能体的安全策略 |
| `verify_agent` | 使用注册的公钥验证来自智能体的 Ed25519 签名 |
| `review_quarantine` | 列出、检查、批准或拒绝隔离的消息 |
## 仪表盘
用于监控智能体活动的实时 Web UI。受 GitHub 风格的本地访问码保护。
```
oktsec serve
```
```
┌──────────────────────────────────────┐
│ OKTSEC v0.7.0 │
│ Security Proxy for AI Agents │
├──────────────────────────────────────┤
│ API: http://127.0.0.1:8080 │
│ Dashboard: http://127.0.0.1:8080/dashboard │
│ Health: http://127.0.0.1:8080/health │
├──────────────────────────────────────┤
│ Access code: 48291057 │
└──────────────────────────────────────┘
```
每次服务器启动时都会重新生成访问码。会话在 8 小时后过期。服务器默认绑定到 `127.0.0.1`（仅本地主机）。使用 `--bind 0.0.0.0` 在网络上公开它。
### 页面
- **概览** — 统计网格（总计、已阻止、已隔离、已标记）、检测率、未签名消息百分比、平均延迟、最常触发的规则、智能体风险评分、每小时活动图表。移动端响应式，带汉堡菜单。
- **事件** — 统一审计日志和隔离视图，带实时 SSE 流、标签过滤器（全部 / 隔离 / 已阻止）、搜索、带可点击规则卡片的人性化事件详情面板
- **规则** — 类别卡片网格，可深入查看单个规则，带内联测试的整页规则详情视图，每规则强制覆盖（阻止/隔离/允许并标记/忽略），带每规则和每类别 Webhook 通知，可自定义 Slack/Discord 模板，自定义规则创建。15 个类别，包括 `openclaw-config` 和 `nanoclaw-config`
- **智能体** — 智能体 CRUD、ACL、内容限制、每智能体 Ed25519 密钥生成、暂停切换
- **图谱** — 智能体通信拓扑可视化，带确定性布局、流量健康评分、威胁评分（介数中心性）、策略违规的阴影边缘检测、边缘深入查看
- **审计** — 部署安全态势：健康评分和等级、每产品发现卡片（Oktsec、OpenClaw、NanoClaw）带严重性细分、内联补救、优先修复
- **发现** — MCP 客户端发现结果，包含检测到的服务器、工具和安全态势
- **设置** — 选项卡式布局，带安全模式（强制/观察）、带撤销的密钥管理、隔离配置、命名 Webhook 通道管理、完整配置编辑
### 隔离队列
触发高严重性规则的消息将被保留以供人工审查。隔离的消息返回带有 `quarantine_id` 的 HTTP 202。审查者可以从仪表盘、CLI 或 MCP 工具批准或拒绝。项目在可配置的时间段后自动过期。
```
oktsec quarantine list # List pending items
oktsec quarantine detail # View full content and triggered rules
oktsec quarantine approve --reviewer ops # Approve and deliver
oktsec quarantine reject --reviewer ops # Reject permanently
```
## 智能体身份
每个智能体获得一个 Ed25519 密钥对：
```
oktsec keygen --agent my-agent --out ./keys/
# 创建：keys/my-agent.key（私钥，保留在 agent 处）
# keys/my-agent.pub（公钥，复制到 proxy）
```
代理在启动时从配置的 `keys_dir` 加载所有 `.pub` 文件。当消息到达时：
1. 查找发送者的公钥
2. 验证签名覆盖 `from + to + content + timestamp`
3. 如果无效：拒绝 (403)，不再进行后续处理
4. 如果有效：继续进行 ACL 检查和内容扫描
签名约 50us，验证约 120us。
### 密钥管理
```
oktsec keys list # List all registered keypairs
oktsec keys rotate --agent my-agent # Generate new keypair, revoke old
oktsec keys revoke --agent my-agent # Revoke without replacement
```
### 渐进入门
设置 `require_signature: false` 以首先将 Oktsec 部署为内容扫描器。没有签名的消息将被接受但记录为 `verified_sender: false`。准备好后启用签名。
## 配置
```
version: "1"
server:
port: 8080
bind: 127.0.0.1 # Default: localhost only
log_level: info # debug, info, warn, error
identity:
keys_dir: ./keys # Directory with .pub files
require_signature: true # Reject unsigned messages
default_policy: deny # "allow" (default) or "deny" — reject unknown senders
custom_rules_dir: ./custom-rules # Directory for org-specific YAML detection rules
agents:
research-agent:
can_message: [analysis-agent] # ACL: allowed recipients
blocked_content: [credentials, pii] # Content categories to always block for this agent
allowed_tools: [read_file, search] # MCP tool allowlist (empty = all allowed)
description: "Research and data gathering"
tags: [research, data]
analysis-agent:
can_message: [research-agent, reporting-agent]
suspended: false # Set to true to reject all messages
quarantine:
enabled: true
expiry_hours: 24 # Auto-expire pending items
retention_days: 30 # Auto-purge audit entries older than N days (0 = keep forever)
rate_limit:
per_agent: 100 # Max messages per window (0 = disabled)
window: 60 # Window size in seconds
anomaly:
check_interval: 60 # Seconds between risk checks
risk_threshold: 50 # Risk score (0-100) to trigger alert
min_messages: 5 # Minimum messages before evaluating risk
auto_suspend: false # Suspend agent when threshold exceeded
forward_proxy:
enabled: false
scan_requests: true # Scan outgoing request bodies
scan_responses: false # Scan upstream response bodies
max_body_size: 1048576 # 1 MB
allowed_domains: [] # Whitelist (empty = all allowed)
blocked_domains: [] # Blacklist (takes precedence)
rules: # Per-rule enforcement overrides
- id: block-relay-injection
severity: critical
action: block # block, quarantine, allow-and-flag, ignore
notify: [slack-security] # Named channels or raw URLs
template: "🚨 *{{RULE}}* — {{RULE_NAME}}\n• *Severity:* {{SEVERITY}} | *Category:* {{CATEGORY}}\n• *Agents:* {{FROM}} → {{TO}}\n• *Match:* '{{MATCH}}'"
category_webhooks: # Default webhooks for entire categories (rules inherit these)
- category: credential-leak
notify: [slack-security]
- category: prompt-injection
notify: [slack-security]
webhooks:
- name: slack-security # Named channel (referenced in rules.notify)
url: https://hooks.slack.com/services/xxx
events: [blocked, quarantined, agent_risk_elevated]
```
验证您的配置：
```
oktsec verify --config oktsec.yaml
```
## 检测规则
Oktsec 包含跨 15 个类别的 **175 条检测规则**：
| 来源 | 数量 | 类别 |
|--------|-------|------------|
| [Aguara](https://github.com/garagon/aguara) | 148 | prompt-injection、credential-leak、exfiltration、command-execution、mcp-attack、mcp-config、supply-chain、ssrf-cloud、indirect-injection、unicode-attack、third-party-content、external-download |
| 智能体间协议 (IAP) | 12 | inter-agent |
| OpenClaw (OCLAW) | 15 | openclaw-config |
### 智能体间协议规则
| 规则 | 严重性 | 描述 |
|------|----------|-------------|
| `IAP-001` | Critical | 中继注入（智能体到智能体劫持） |
| `IAP-002` | High | 智能体消息中的 PII |
| `IAP-003` | Critical | 智能体消息中的凭据 |
| `IAP-004` | High | 通过智能体提取系统提示 |
| `IAP-005` | High | 智能体间的权限提升 |
| `IAP-006` | High | 通过智能体中继的数据渗漏 |
| `IAP-007` | Critical | 工具描述提示注入 |
| `IAP-008` | Critical | 工具描述数据渗漏 |
| `IAP-009` | High | 工具描述权限提升 |
| `IAP-010` | High | 工具描述遮蔽 |
| `IAP-011` | Critical | 工具描述隐藏命令 |
| `IAP-012` | High | 工具名称抢注 |
### OpenClaw 规则
`openclaw-config` 类别中的 15 条规则（OCLAW-001 至 OCLAW-015），涵盖完整工具配置文件、暴露的网关、开放 DM 策略、无沙箱执行、路径遍历、缺少身份验证、硬编码凭据等。
```
oktsec rules # List all 169 rules
oktsec rules --explain IAP-001 # Explain a specific rule
oktsec rules --explain OCLAW-001 # Explain an OpenClaw rule
```
此外，[部署审计](#deployment-audit) 运行 41 项更深入的检查（OpenClaw 18 项、NanoClaw 7 项、Oktsec 16 项），分析配置结构、权限和运行时设置。
## 审计日志
每条消息都记录到 SQLite（`oktsec.db`），包含：
- 内容哈希 (SHA-256)
- 签名验证状态
- 公钥指纹
- 策略决策
- 触发的规则
- 延迟
```
oktsec logs # Last 50 entries
oktsec logs --status blocked # Only blocked messages
oktsec logs --unverified # Messages without valid signature
oktsec logs --agent research-agent # Filter by agent
oktsec logs --since 1h # Last hour
```
### 性能
分析查询使用 24 小时时间窗口和覆盖索引。无论数据库总大小如何，所有仪表盘查询都在 10ms 内完成。
| 指标 | 值 |
|--------|-------|
| 写入吞吐量 | ~90K 插入/秒（批处理） |
| 查询延迟 | <6ms（在 100 万+ 行时） |
| 数据库大小 | 每 100 万条约 400 MB |
## CLI 参考
```
oktsec setup [--enforce] [--skip-wrap] # One-command onboarding: discover + init + wrap all
oktsec discover # Scan for MCP servers, OpenClaw, NanoClaw
oktsec init [--keys ./keys] [--config oktsec.yaml] # Auto-generate config + keypairs
oktsec wrap [--enforce] [--all | ] # Route MCP client(s) through oktsec proxy
oktsec unwrap # Restore original client config
oktsec scan-openclaw [--path ~/.openclaw/openclaw.json] # Analyze OpenClaw installation
oktsec proxy [--enforce] --agent -- [args] # Stdio proxy for single MCP server
oktsec serve [--config oktsec.yaml] [--port 8080] [--bind 127.0.0.1]
oktsec mcp [--config oktsec.yaml] # Run as MCP tool server
oktsec keygen --agent [--agent ...] --out
oktsec keys list|rotate|revoke [--agent ]
oktsec verify [--config oktsec.yaml] # Validate config file
oktsec logs [--status ] [--agent ] [--unverified] [--since ]
oktsec rules [--explain ]
oktsec quarantine list|detail|approve|reject [--status ] []
oktsec agent list # List agents with status
oktsec agent suspend # Suspend an agent
oktsec agent unsuspend # Unsuspend an agent
oktsec audit [--json] [--sarif] # Deployment security audit (41 checks)
oktsec status # Health score, detected products, top issues
oktsec enforce [on|off] # Toggle enforce/observe mode
oktsec version
```
## API
### `POST /v1/message`
通过代理发送消息。
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
| `from` | string | yes | 发送智能体名称 |
| `to` | string | yes | 接收智能体名称 |
| `content` | string | yes | 消息内容 |
| `signature` | string | no* | Base64 Ed25519 签名 |
| `timestamp` | string | no | RFC3339 时间戳 |
| `metadata` | object | no | 任意键值对 |
*当 `require_signature: true` 时必填
### `GET /v1/quarantine/{id}`
轮询被保留消息的隔离状态。
### `GET /health`
返回 `{"status": "ok", "version": "0.5.0"}`。
### `GET /dashboard`
用于监控智能体活动的 Web UI。受启动时显示的访问码保护。
## Go SDK
`sdk` 包提供了一个 Go 客户端，用于通过 oktsec 代理发送消息：
```
import "github.com/oktsec/oktsec/sdk"
// Without signing (observe mode)
c := sdk.NewClient("http://localhost:8080", "my-agent", nil)
resp, err := c.SendMessage(ctx, "recipient", "hello")
// resp.Status: "delivered", resp.PolicyDecision: "allow", resp.RulesTriggered: [...]
// With Ed25519 signing
kp, _ := sdk.LoadKeypair("./keys", "my-agent")
c := sdk.NewClient("http://localhost:8080", "my-agent", kp.PrivateKey)
resp, err := c.SendMessage(ctx, "recipient", "hello")
// With metadata
resp, err := c.SendMessageWithMetadata(ctx, "recipient", "hello", map[string]string{
"task_id": "abc-123",
})
// Health check
health, err := c.Health(ctx)
```
安装：`go get github.com/oktsec/oktsec/sdk`
## OWASP Top 10 for Agentic Applications
Oktsec 符合 [OWASP Top 10 for Agentic Applications](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications/)：
| # | 类别 | 覆盖范围 | 方式 |
|---|----------|----------|-----|
| ASI01 | 过度代理 / 目标劫持 | Partial | 多消息判定升级、内容扫描 |
| ASI02 | 工具滥用 | **Strong** | Stdio 强制执行、每智能体 BlockedContent、速率限制 |
| ASI03 | 权限提升 | **Strong** | Ed25519 身份、默认拒绝策略、ACL |
| ASI04 | 供应链 | Weak | 架构限制（代理，而非包扫描器） |
| ASI05 | 不安全的代码执行 | Partial | Stdio 强制执行阻止工具调用（例如 exec） |
| ASI07 | 智能体间通信 | **Strong** | 签名消息、ACL、内容扫描、审计跟踪 |
| ASI10 | 流氓智能体 | **Strong** | 智能体暂停、速率限制、异常检测、自动暂停 |
## 构建基于
- **[Aguara](https://github.com/garagon/aguara)** — AI 智能体技能的安全扫描器（148 条检测规则、模式匹配、污点跟踪、NLP 注入检测）
- **[MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk)** — 模型上下文协议的官方 Tier 1 Go SDK（v1，Linux Foundation 治理，semver 稳定性）
- **Go stdlib** — `crypto/ed25519`、`net/http`、`log/slog`、`crypto/sha256`
- **[modernc.org/sqlite](https://pkg.go.dev/modernc.org/sqlite)** — 纯 Go SQLite（无 CGO）
## 贡献
开发设置、代码风格和 Pull Request 流程请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
对于安全漏洞，请参见 [SECURITY.md](SECURITY.md)。
## 许可证
Apache License 2.0。参见 [LICENSE](LICENSE)。标签：AI安全, AMSI绕过, Chat Copilot, Ed25519, EVTX分析, Go语言, JSONLines, Lerna, MacOS取证, MCP, PE 加载器, 中间件, 人工智能安全, 企业安全, 内容检查, 单二进制, 合规性, 大模型防护, 威胁检测, 安全网关, 审计日志, 开源, 数据隐私, 无云化, 日志审计, 智能体通信, 本地部署, 流量控制, 消息签名, 程序破解, 策略执行, 网络安全, 网络资产管理, 请求拦截, 配置错误, 隐私保护, 零信任