@kenhkl/agent-gate 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +354 -0
  2. package/package.json +3 -2
package/README.md ADDED
@@ -0,0 +1,354 @@
1
+ # AgentGate
2
+
3
+ > AI Agent 数据采集与安全分析中间层服务
4
+
5
+ AgentGate 是一个**独立常驻服务**,位于 AI Agent 与 [AgentMoss](https://atomgit.com/kenhkl/AgentMoss) 之间:接收 Agent 的工具调用数据,采集系统上下文,转换格式后提交 AgentMoss 安全分析,回传 Allow/Deny 决策。
6
+
7
+ ```
8
+ ┌──────────────┐ HTTP/Unix Socket ┌──────────────────┐ HTTP/Unix Socket ┌─────────────┐
9
+ │ AI Agent │ ── AgentGateInput ──────▶│ AgentGate │ ── AnalyzeRequest ────▶│ AgentMoss │
10
+ │ (任意Agent) │ │ (独立服务) │ │ (安全分析) │
11
+ │ │◀─ AgentGateResponse ────│ · 系统上下文采集 │◀─ AnalyzeResponse ────│ │
12
+ └──────────────┘ │ · 格式标准化 │ └─────────────┘
13
+ │ · 决策缓存 │
14
+ │ · Session 存储 │
15
+ └──────────────────┘
16
+ ```
17
+
18
+ ---
19
+
20
+ ## 1. 安装
21
+
22
+ ```bash
23
+ pip install agent-gate-sec
24
+ ```
25
+
26
+ 安装后 `agent-gate` 命令即可用。如需从源码安装:
27
+
28
+ ```bash
29
+ git clone git@gitcode.com:kenhkl/AgentGate.git
30
+ cd AgentGate
31
+ pip install -e ".[dev]"
32
+ ```
33
+
34
+ ## 2. 启动服务
35
+
36
+ AgentGate 依赖 AgentMoss 做安全分析,需要**先启动 AgentMoss,再启动 AgentGate**。
37
+
38
+ ### 2.1 启动 AgentMoss
39
+
40
+ ```bash
41
+ # HTTP 模式(默认端口 9090)
42
+ agent-moss server --mode http --port 9090
43
+ ```
44
+
45
+ 验证:
46
+ ```bash
47
+ curl http://127.0.0.1:9090/api/v1/health
48
+ # → {"status": "ok", ...}
49
+ ```
50
+
51
+ ### 2.2 启动 AgentGate
52
+
53
+ ```bash
54
+ cd /home/hkl/gitcode/AgentGate
55
+
56
+ # HTTP 模式(默认端口 9100)
57
+ agent-gate server --mode http --port 9100
58
+
59
+ # 或指定数据库路径
60
+ agent-gate server --mode http --port 9100 --db-path /tmp/agent_gate.db
61
+
62
+ # Unix Socket 模式(同机更低延迟)
63
+ agent-gate server --mode socket --socket /var/run/agent_gate/agent_gate.sock
64
+ ```
65
+
66
+ 验证:
67
+ ```bash
68
+ curl http://127.0.0.1:9100/api/v1/health
69
+ # → {"status": "ok", "version": "0.1.0"}
70
+ ```
71
+
72
+ ### 2.3 数据存储路径
73
+
74
+ `db_path` 默认为 `"auto"`,根据运行环境自动选择:
75
+
76
+ | 场景 | 实际路径 |
77
+ |------|----------|
78
+ | 开发(git clone 中运行) | `data/agent_gate.db` |
79
+ | 用户安装(`pip install`) | `~/.local/share/agent_gate/agent_gate.db` |
80
+ | 系统服务(systemd) | 显式 `--db-path /var/lib/agent_gate/agent_gate.db` |
81
+
82
+ ---
83
+
84
+ ## 3. 验证联调效果
85
+
86
+ ### 3.1 端到端测试(自动启动双服务)
87
+
88
+ ```bash
89
+ python3 examples/opendesk/test_e2e.py
90
+ ```
91
+
92
+ 自动启动 AgentMoss + AgentGate,执行安全命令和危险命令,验证:
93
+ - 危险命令 `rm -rf /` → **Deny** (critical)
94
+ - 危险命令 `curl | bash` → **Deny** (high)
95
+ - Session 历史自动累积
96
+ - 系统上下文完整采集
97
+
98
+ ### 3.2 手动 curl 测试
99
+
100
+ ```bash
101
+ # 安全命令
102
+ curl -s -X POST http://127.0.0.1:9100/api/v1/analyze \
103
+ -H "Content-Type: application/json" \
104
+ -d '{"agent_type":"test","session_id":"sess-001",
105
+ "tool_name":"bash","command":"ls -la","cwd":"/tmp"}' | python3 -m json.tool
106
+
107
+ # 危险命令
108
+ curl -s -X POST http://127.0.0.1:9100/api/v1/analyze \
109
+ -H "Content-Type: application/json" \
110
+ -d '{"agent_type":"test","session_id":"sess-001",
111
+ "tool_name":"bash","command":"rm -rf /","cwd":"/root"}' | python3 -m json.tool
112
+ ```
113
+
114
+ ---
115
+
116
+ ## 4. 三方 Agent 如何调用 AgentGate
117
+
118
+ ### 4.1 Python Agent(SDK)
119
+
120
+ ```python
121
+ from agent_gate.sdk import GateClient
122
+
123
+ client = GateClient(base_url="http://127.0.0.1:9100")
124
+
125
+ # 安全分析
126
+ response = client.analyze(
127
+ agent_type="my-agent",
128
+ session_id="sess-001",
129
+ tool_name="bash",
130
+ command="ls -la",
131
+ cwd="/home/user/project",
132
+ )
133
+
134
+ if response["decision"] == "Allow":
135
+ # 执行命令
136
+ print("允许执行")
137
+ else:
138
+ print(f"被阻止: {response['reason']}")
139
+ ```
140
+
141
+ ### 4.2 TypeScript / Electron Agent(SDK)
142
+
143
+ ```typescript
144
+ import { GateClient } from './gate_client';
145
+
146
+ const client = new GateClient({ baseUrl: 'http://127.0.0.1:9100' });
147
+
148
+ const result = await client.analyze({
149
+ agentType: 'opendes',
150
+ sessionId: 'sess-001',
151
+ toolName: 'executeBash',
152
+ command: 'ls -la',
153
+ cwd: '/home/user/project',
154
+ });
155
+
156
+ if (result.decision === 'Allow') {
157
+ // 执行命令
158
+ } else {
159
+ console.error(`被阻止: ${result.reason}`);
160
+ }
161
+ ```
162
+
163
+ ### 4.3 任意 Agent(HTTP / curl)
164
+
165
+ ```bash
166
+ curl -s -X POST http://127.0.0.1:9100/api/v1/analyze \
167
+ -H "Content-Type: application/json" \
168
+ -d '{
169
+ "agent_type": "my-agent",
170
+ "agent_version": "1.0",
171
+ "session_id": "sess-abc",
172
+ "tool_name": "bash",
173
+ "command": "rm -rf /tmp/cache",
174
+ "cwd": "/home/user/project",
175
+ "description": "清理缓存",
176
+ "user_prompt": "清理项目临时文件"
177
+ }'
178
+ ```
179
+
180
+ ### 4.4 Shell 包装器(无代码接入)
181
+
182
+ ```bash
183
+ # 通过环境变量配置
184
+ export AGENT_GATE_URL=http://127.0.0.1:9100
185
+ export AGENT_SESSION_ID=shell-session-001
186
+
187
+ # 用包装器执行命令
188
+ agent-gate-wrap ls -la # Allow → 正常执行
189
+ agent-gate-wrap rm -rf / # Deny → 阻断并退出 126
190
+ ```
191
+
192
+ ### 4.5 OpenDesk 集成
193
+
194
+ 参考 `examples/opendesk/`:
195
+ - `agent_gate_plugin.ts` — 插件代码(放到 OpenDesk 源码中)
196
+ - `README.md` — 3 步集成指南
197
+ - `TESTING.md` — 分层测试指南
198
+ - `test_e2e.py` — 端到端自动测试
199
+
200
+ 核心:在 OpenDesk 的 `afterParseToolcall` 钩子中调用 AgentGate API,返回 `reject` 即可阻断工具执行。
201
+
202
+ ---
203
+
204
+ ## 5. API 接口
205
+
206
+ | 方法 | 路径 | 说明 |
207
+ |------|------|------|
208
+ | `POST` | `/api/v1/analyze` | 安全分析(核心接口) |
209
+ | `GET` | `/api/v1/health` | 健康检查 |
210
+ | `GET` | `/api/v1/sessions/{id}/traces` | 查询 session 完整调用轨迹 |
211
+ | `GET` | `/api/v1/agents/{id}/sessions` | 查询某 agent 所有 session |
212
+ | `GET` | `/api/v1/tool_calls` | 条件查询工具调用记录 |
213
+
214
+ ### 请求格式
215
+
216
+ ```json
217
+ {
218
+ "agent_type": "opendes",
219
+ "session_id": "session-abc",
220
+ "tool_name": "bash",
221
+ "command": "rm -rf /tmp/cache/*",
222
+ "cwd": "/home/user/project",
223
+ "description": "清理缓存",
224
+ "user_prompt": "清理项目临时文件",
225
+ "action_history": [],
226
+ "metadata": {}
227
+ }
228
+ ```
229
+
230
+ > `action_history` 可选 — AgentGate 从 SQLite 自动累积同一 session 的历史。
231
+
232
+ ### 响应格式
233
+
234
+ ```json
235
+ {
236
+ "decision": "Deny",
237
+ "reason": "检测到递归强制删除操作",
238
+ "risk_level": "high",
239
+ "risk_type": "dangerous_command",
240
+ "violated_layers": ["1.2"],
241
+ "confidence": 97,
242
+ "analysis_duration_ms": 12.5,
243
+ "collected_context": {
244
+ "os": { "system": "linux", "distribution": "Ubuntu 24.04", ... },
245
+ "resources": { "cpu_count": 8, "memory_total_gb": 31.2, ... },
246
+ "process": { "pid": 12345, "name": "opendesk", ... },
247
+ "user": { "uid": 1000, "username": "developer", ... }
248
+ },
249
+ "source": "agent_moss"
250
+ }
251
+ ```
252
+
253
+ ---
254
+
255
+ ## 6. 关键设计
256
+
257
+ | 特性 | 说明 |
258
+ |------|------|
259
+ | **Fail-Closed** | AgentMoss 不可用时 AgentGate 返回 Deny(安全优先) |
260
+ | **决策缓存** | LRU 缓存 Allow 决策(同 session+同 cwd+同 command 可复用) |
261
+ | **Deny 不缓存** | 每次 Deny 都重新分析,确保安全 |
262
+ | **Session 持久化** | SQLite 存储全量 tool_call 记录,Agent 无需自维护 history |
263
+ | **action_history 自动累积** | 同一 session_id 的调用序列自动拼接,传给 AgentMoss |
264
+ | **系统上下文采集** | 5 模块并行(OS/进程/网络/用户/环境变量),< 50ms |
265
+ | **环境变量安全过滤** | 白名单机制,自动排除 KEY/TOKEN/SECRET 等敏感变量 |
266
+
267
+ ---
268
+
269
+ ## 7. 测试
270
+
271
+ ```bash
272
+ # 单元测试(42 项)
273
+ python3 -m pytest tests/test_server.py -v
274
+
275
+ # 端到端测试(AgentMoss + AgentGate 联调)
276
+ python3 examples/opendesk/test_e2e.py
277
+ ```
278
+
279
+ ---
280
+
281
+ ## 8. 高权限需求
282
+
283
+ | 采集模块 | 所需权限 | 读取路径 |
284
+ |----------|----------|----------|
285
+ | system_info | 普通用户 | `/proc/version`, `/etc/os-release` |
286
+ | process_info | `CAP_SYS_PTRACE` | `/proc/*/status`, capabilities |
287
+ | env_info | 普通用户 | 自身进程环境变量 |
288
+ | network_info | `CAP_NET_ADMIN` | `/proc/net/*` |
289
+ | user_info | 普通用户 | `/etc/passwd`, `/etc/group` |
290
+
291
+ 推荐以专用 `agent-gate` 用户 + Linux capabilities 运行,不使用 root。
292
+
293
+ ---
294
+
295
+ ## 9. Dashboard 可视化面板
296
+
297
+ AgentGate 内置实时 Dashboard(`http://localhost:9100/dashboard/`),提供:
298
+
299
+ - 实时统计卡片(Agents / Sessions / Tool Calls / Allow / Deny / Avg Latency)
300
+ - Risk Distribution 风险分布条
301
+ - Recent Tool Calls 操作记录表格
302
+ - Agent 类型分布
303
+ - Timeline 折线图(过去 60 分钟 Allow/Deny 趋势)
304
+
305
+ ### 在 OpenDesk 中查看
306
+
307
+ AgentGate 已集成到 OpenDesk 桌面端作为侧边栏应用,点击图标即可在应用内查看 Dashboard。
308
+
309
+ ---
310
+
311
+ ## 10. 项目结构
312
+
313
+ ```
314
+ AgentGate/
315
+ ├── agent_gate/ # 主包
316
+ │ ├── cli.py # 命令行入口 (agent-gate server / clean)
317
+ │ ├── config.py # YAML 配置 + XDG 路径自动适配
318
+ │ ├── normalizer.py # AgentGateInput → AgentMoss AnalyzeRequest
319
+ │ ├── sdk.py # Python SDK
320
+ │ ├── server/ # FastAPI 服务
321
+ │ │ ├── app.py # HTTP / Unix Socket 双模式
322
+ │ │ ├── routes.py # /analyze /traces /tool_calls /health
323
+ │ │ ├── models.py # Pydantic 数据模型
324
+ │ │ └── middleware.py # 请求日志
325
+ │ ├── collector/ # 系统数据采集(5 模块并行)
326
+ │ │ ├── system_info.py # OS/内核/CPU/内存/磁盘
327
+ │ │ ├── process_info.py # PID/capabilities/cgroup
328
+ │ │ ├── env_info.py # 环境变量白名单过滤
329
+ │ │ ├── network_info.py # 网络接口/连接数
330
+ │ │ └── user_info.py # UID/GID/用户组
331
+ │ ├── client/ # AgentMoss 客户端
332
+ │ │ ├── moss_client.py # 异步 HTTP + Fail-Closed
333
+ │ │ └── cache.py # LRU 决策缓存
334
+ │ └── storage/ # SQLite 持久化
335
+ │ ├── db.py # 建表/迁移/WAL 模式
336
+ │ └── repository.py # CRUD (agents/sessions/tool_calls)
337
+ ├── sdk/ # 客户端 SDK
338
+ │ ├── python/gate_client.py # Python SDK
339
+ │ └── typescript/ # TypeScript SDK (package.json + tsconfig)
340
+ ├── examples/opendesk/ # OpenDesk 集成
341
+ │ ├── agent_gate_plugin.ts # 插件(afterParseToolcall 钩子)
342
+ │ ├── test_integration.py # 接口测试(不改 OpenDesk)
343
+ │ ├── test_e2e.py # 端到端测试(自动启双服务)
344
+ │ ├── README.md # 集成指南
345
+ │ └── TESTING.md # 分层测试指南
346
+ ├── config/agent_gate.yaml # YAML 配置模板
347
+ ├── scripts/agent-gate-wrap.sh # Shell 包装器
348
+ ├── tests/test_server.py # 单元 + 集成测试(42 项)
349
+ └── docs/agent_collector_design_v1.md # 设计文档
350
+ ```
351
+
352
+ ## 许可证
353
+
354
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kenhkl/agent-gate",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "AI Agent data collection & security analysis gateway (TypeScript)",
5
5
  "type": "module",
6
6
  "main": "dist/cli.js",
@@ -8,7 +8,8 @@
8
8
  "agent-gate": "dist/cli.js"
9
9
  },
10
10
  "files": [
11
- "dist"
11
+ "dist",
12
+ "README.md"
12
13
  ],
13
14
  "scripts": {
14
15
  "build": "tsup",