@kenhkl/agent-moss 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.
- package/README.md +422 -0
- package/package.json +3 -2
package/README.md
ADDED
|
@@ -0,0 +1,422 @@
|
|
|
1
|
+
# AgentMoss
|
|
2
|
+
|
|
3
|
+
AgentMoss 是一个**可被任意 AI Agent 调用的独立通用安全分析服务**。基于 OS Profile 机制，自动适配 Linux/Windows 的 syscall 检测模式，提供三层防御安全分析（启发式 → 逻辑规则 → LLM 语义分析）。
|
|
4
|
+
|
|
5
|
+
> v2 更新：新增 OS Profile 系统（Linux/Windows 自适应）、Unix Domain Socket 支持、标准化 API 契约。
|
|
6
|
+
|
|
7
|
+
## 目录
|
|
8
|
+
|
|
9
|
+
- [架构](#架构)
|
|
10
|
+
- [快速开始](#快速开始)
|
|
11
|
+
- [LLM 配置](#llm-配置)
|
|
12
|
+
- [openEuler 部署](#openeuler-部署)
|
|
13
|
+
- [API 参考](#api-参考)
|
|
14
|
+
- [配置](#配置)
|
|
15
|
+
- [项目结构](#项目结构)
|
|
16
|
+
- [测试](#测试)
|
|
17
|
+
|
|
18
|
+
## 架构
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
┌───────────────────────────────────────────┐
|
|
22
|
+
│ 调用入口 (HTTP / Unix Socket) │
|
|
23
|
+
│ POST /api/v1/analyze │
|
|
24
|
+
│ GET /api/v1/health │
|
|
25
|
+
├───────────────────────────────────────────┤
|
|
26
|
+
│ ObservableAdapter │
|
|
27
|
+
│ AgentOS 可观测服务 syscall → 标准格式 │
|
|
28
|
+
├───────────────────────────────────────────┤
|
|
29
|
+
│ OS Profile 选择 │
|
|
30
|
+
│ ┌──────────┐ ┌──────────┐ │
|
|
31
|
+
│ │ Linux │ │ Windows │ │
|
|
32
|
+
│ │ Profile │ │ Profile │ │
|
|
33
|
+
│ └──────────┘ └──────────┘ │
|
|
34
|
+
├───────────────────────────────────────────┤
|
|
35
|
+
│ 安全分析引擎 (三层防御) │
|
|
36
|
+
│ │
|
|
37
|
+
│ 层1: 启发式静态检测 (毫秒级) │
|
|
38
|
+
│ ├── 用户规则匹配 │
|
|
39
|
+
│ ├── 危险命令正则 (OS Profile 驱动) │
|
|
40
|
+
│ └── Prompt 注入检测 │
|
|
41
|
+
│ │
|
|
42
|
+
│ 层2: 逻辑规则检测 (毫秒级) │
|
|
43
|
+
│ ├── read_before_write 原则 │
|
|
44
|
+
│ ├── 意图一致性检测 │
|
|
45
|
+
│ ├── 敏感路径访问 (OS Profile 驱动) │
|
|
46
|
+
│ └── 危险操作模式 │
|
|
47
|
+
│ │
|
|
48
|
+
│ 层3: LLM + Skill 深度分析 │
|
|
49
|
+
│ ├── Skill 规则匹配 (12 个 Skill) │
|
|
50
|
+
│ ├── 脚本内容预扫描 │
|
|
51
|
+
│ └── LLM 语义安全判断 │
|
|
52
|
+
└───────────────────────────────────────────┘
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### 设计原则
|
|
56
|
+
|
|
57
|
+
- **适配在 OS 层，不在 Agent 层** — 不同 Agent 最终都会调用操作系统的 syscall，这是确定性的
|
|
58
|
+
- **标准化 I/O 契约** — 任何 Agent 遵循 API 格式即可接入，无需关心内部实现
|
|
59
|
+
- **fail-closed 安全原则** — 不确定时默认拒绝
|
|
60
|
+
|
|
61
|
+
## 快速开始
|
|
62
|
+
|
|
63
|
+
### 安装
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
pip install agent-moss
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
如需从源码安装：
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
git clone git@gitcode.com:kenhkl/AgentMoss.git
|
|
73
|
+
cd AgentMoss
|
|
74
|
+
pip install -e .
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### CLI 使用
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
# 生成输入模板 (v2: 含 os_type 和 cwd 字段)
|
|
81
|
+
agent-moss init -o input.json
|
|
82
|
+
|
|
83
|
+
# 运行安全分析
|
|
84
|
+
agent-moss analyze input.json
|
|
85
|
+
|
|
86
|
+
# 启动 HTTP 服务 (TCP)
|
|
87
|
+
agent-moss server --port 9090
|
|
88
|
+
|
|
89
|
+
# 启动 Unix Domain Socket 服务（同机部署推荐）
|
|
90
|
+
agent-moss server --mode socket --socket /var/run/agent_moss/agent_moss.sock
|
|
91
|
+
|
|
92
|
+
# 指定配置文件
|
|
93
|
+
agent-moss server --mode socket --config /etc/agent_moss/agent_moss.yaml
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### API 调用
|
|
97
|
+
|
|
98
|
+
**HTTP TCP 方式：**
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
curl -X POST http://127.0.0.1:9090/api/v1/analyze \
|
|
102
|
+
-H 'Content-Type: application/json' \
|
|
103
|
+
-d '{
|
|
104
|
+
"session_id": "test-001",
|
|
105
|
+
"prompt_session": "列出系统文件",
|
|
106
|
+
"action_history": [],
|
|
107
|
+
"a_next": {
|
|
108
|
+
"action_type": "bash",
|
|
109
|
+
"action_detail": "ls -la /tmp"
|
|
110
|
+
},
|
|
111
|
+
"reason": "查看临时目录",
|
|
112
|
+
"os_type": "",
|
|
113
|
+
"cwd": "/home/user"
|
|
114
|
+
}'
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
**Unix Domain Socket 方式（同机低延迟）：**
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
curl --unix-socket /var/run/agent_moss/agent_moss.sock \
|
|
121
|
+
-X POST http://localhost/api/v1/analyze \
|
|
122
|
+
-H 'Content-Type: application/json' \
|
|
123
|
+
-d '{
|
|
124
|
+
"session_id": "test-001",
|
|
125
|
+
"a_next": {
|
|
126
|
+
"action_type": "bash",
|
|
127
|
+
"action_detail": "ls -la /tmp"
|
|
128
|
+
}
|
|
129
|
+
}'
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
**响应示例 (Allow)**：
|
|
133
|
+
|
|
134
|
+
```json
|
|
135
|
+
{
|
|
136
|
+
"decision": "Allow",
|
|
137
|
+
"risk_level": "low",
|
|
138
|
+
"risk_type": "",
|
|
139
|
+
"violated_layers": [],
|
|
140
|
+
"confidence": 100,
|
|
141
|
+
"analysis_duration_ms": 10.8
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
**响应示例 (Deny)**：
|
|
146
|
+
|
|
147
|
+
```json
|
|
148
|
+
{
|
|
149
|
+
"decision": "Deny",
|
|
150
|
+
"reason": "检测到递归强制删除关键路径 (rm -rf /...)",
|
|
151
|
+
"risk_level": "critical",
|
|
152
|
+
"risk_type": "script_execution",
|
|
153
|
+
"violated_layers": ["1.1"],
|
|
154
|
+
"confidence": 95,
|
|
155
|
+
"analysis_duration_ms": 1.2
|
|
156
|
+
}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
## LLM 配置
|
|
160
|
+
|
|
161
|
+
AgentMoss 的三层防御中，层3（LLM 语义分析）是可选的。层1+层2 的静态规则可以独立运行。
|
|
162
|
+
|
|
163
|
+
### 启用 LLM
|
|
164
|
+
|
|
165
|
+
**方式 1：环境变量（推荐）**
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
export AGENT_MOSS_LLM_API_KEY="sk-your-key"
|
|
169
|
+
# 可选：自定义模型和 API 端点
|
|
170
|
+
export AGENT_MOSS_LLM_MODEL="glm-5.0"
|
|
171
|
+
export AGENT_MOSS_LLM_BASE_URL="https://api.nextapi.store/v1"
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
**方式 2：YAML 配置文件**
|
|
175
|
+
|
|
176
|
+
编辑 `config/agent_moss.yaml`：
|
|
177
|
+
|
|
178
|
+
```yaml
|
|
179
|
+
llm:
|
|
180
|
+
provider: "zhipu"
|
|
181
|
+
model: "glm-5.0"
|
|
182
|
+
base_url: "https://api.nextapi.store/v1"
|
|
183
|
+
api_key_env: "AGENT_MOSS_LLM_API_KEY"
|
|
184
|
+
temperature: 0.1
|
|
185
|
+
max_tokens: 4096
|
|
186
|
+
|
|
187
|
+
security:
|
|
188
|
+
llm_analysis:
|
|
189
|
+
enabled: true
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### 禁用 LLM（仅静态规则）
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
export AGENT_MOSS_DISABLE_LLM=1
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
### 支持的 LLM Provider
|
|
199
|
+
|
|
200
|
+
| Provider | 说明 |
|
|
201
|
+
|----------|------|
|
|
202
|
+
| OpenAI | api.openai.com |
|
|
203
|
+
| DeepSeek | api.deepseek.com |
|
|
204
|
+
| 智谱 (GLM) | open.bigmodel.cn |
|
|
205
|
+
| OpenRouter | openrouter.ai |
|
|
206
|
+
| Groq | api.groq.com |
|
|
207
|
+
| 任何 OpenAI 兼容 API | 设置 `base_url` 即可 |
|
|
208
|
+
|
|
209
|
+
## openEuler 部署
|
|
210
|
+
|
|
211
|
+
### 前提
|
|
212
|
+
|
|
213
|
+
- openEuler 22.03 LTS+
|
|
214
|
+
- Python 3.10+
|
|
215
|
+
- root 权限
|
|
216
|
+
|
|
217
|
+
### 一键安装
|
|
218
|
+
|
|
219
|
+
```bash
|
|
220
|
+
sudo dnf install -y python3 python3-pip python3-devel
|
|
221
|
+
git clone <repo-url> agent_moss
|
|
222
|
+
cd agent_moss
|
|
223
|
+
sudo bash scripts/install.sh
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
### 配置 LLM（生产环境）
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
# 写入 API Key（文件权限 600）
|
|
230
|
+
echo "AGENT_MOSS_LLM_API_KEY=sk-your-key" | sudo tee /etc/agent_moss/agent_moss.env
|
|
231
|
+
sudo chmod 600 /etc/agent_moss/agent_moss.env
|
|
232
|
+
|
|
233
|
+
# 编辑 LLM model / base_url
|
|
234
|
+
sudo vim /etc/agent_moss/agent_moss.yaml
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
### 启动方式
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
# HTTP TCP 模式（默认，适合跨机/调试）
|
|
241
|
+
sudo systemctl enable --now agent_moss
|
|
242
|
+
|
|
243
|
+
# Unix Socket 模式（同机部署推荐，更低延迟）
|
|
244
|
+
# 编辑 /etc/agent_moss/agent_moss.yaml 中 server.mode: "socket"
|
|
245
|
+
# 或修改 /etc/systemd/system/agent_moss.service 中的 ExecStart
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
### 启动与验证
|
|
249
|
+
|
|
250
|
+
```bash
|
|
251
|
+
sudo systemctl enable --now agent_moss
|
|
252
|
+
|
|
253
|
+
# HTTP 模式验证
|
|
254
|
+
curl http://127.0.0.1:9090/api/v1/health
|
|
255
|
+
# {"status":"healthy","version":"0.1.0"}
|
|
256
|
+
|
|
257
|
+
# Socket 模式验证
|
|
258
|
+
curl --unix-socket /var/run/agent_moss/agent_moss.sock \
|
|
259
|
+
http://localhost/api/v1/health
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
### 管理命令
|
|
263
|
+
|
|
264
|
+
| 命令 | 说明 |
|
|
265
|
+
|------|------|
|
|
266
|
+
| `systemctl start agent_moss` | 启动 |
|
|
267
|
+
| `systemctl stop agent_moss` | 停止 |
|
|
268
|
+
| `systemctl restart agent_moss` | 重启 |
|
|
269
|
+
| `systemctl status agent_moss` | 查看状态 |
|
|
270
|
+
| `journalctl -u agent_moss -f` | 查看日志 |
|
|
271
|
+
| `systemctl disable agent_moss` | 取消开机启动 |
|
|
272
|
+
|
|
273
|
+
### 防火墙（HTTP 模式需要）
|
|
274
|
+
|
|
275
|
+
```bash
|
|
276
|
+
sudo firewall-cmd --add-port=9090/tcp --permanent
|
|
277
|
+
sudo firewall-cmd --reload
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
## API 参考
|
|
281
|
+
|
|
282
|
+
| 方法 | 路径 | 说明 |
|
|
283
|
+
|------|------|------|
|
|
284
|
+
| `GET` | `/api/v1/health` | 健康检查 |
|
|
285
|
+
| `POST` | `/api/v1/analyze` | 安全分析 |
|
|
286
|
+
|
|
287
|
+
### POST /api/v1/analyze
|
|
288
|
+
|
|
289
|
+
**请求体 (v2)**：
|
|
290
|
+
|
|
291
|
+
```json
|
|
292
|
+
{
|
|
293
|
+
"session_id": "会话ID (必填)",
|
|
294
|
+
"prompt_session": "原始任务描述 (可选)",
|
|
295
|
+
"action_history": [{"action_type": "...", "action_detail": "..."}],
|
|
296
|
+
"a_next": {
|
|
297
|
+
"action_type": "bash",
|
|
298
|
+
"action_detail": "cat /etc/passwd"
|
|
299
|
+
},
|
|
300
|
+
"reason": "执行理由 (可选)",
|
|
301
|
+
"os_type": "",
|
|
302
|
+
"cwd": "/home/user/project",
|
|
303
|
+
"metadata": {"agent_id": "...", "sandbox_id": "..."}
|
|
304
|
+
}
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
| 字段 | 类型 | 必填 | 说明 |
|
|
308
|
+
|------|------|------|------|
|
|
309
|
+
| `session_id` | string | 是 | 会话唯一标识 |
|
|
310
|
+
| `prompt_session` | string | 否 | 原始任务描述 |
|
|
311
|
+
| `action_history` | array | 否 | 历史动作序列 |
|
|
312
|
+
| `a_next.action_type` | string | 是 | 动作类型 (bash/file_read/file_write 等) |
|
|
313
|
+
| `a_next.action_detail` | string | 是 | 命令/动作详情 |
|
|
314
|
+
| `reason` | string | 否 | 执行理由 |
|
|
315
|
+
| `os_type` | string | 否 | **v2 新增** — `"linux"` / `"windows"`，留空自动检测 |
|
|
316
|
+
| `cwd` | string | 否 | **v2 新增** — 当前工作目录 |
|
|
317
|
+
| `metadata` | object | 否 | 扩展元数据 |
|
|
318
|
+
|
|
319
|
+
**响应字段**：
|
|
320
|
+
|
|
321
|
+
| 字段 | 类型 | 说明 |
|
|
322
|
+
|------|------|------|
|
|
323
|
+
| `decision` | string | `Allow` / `Deny` |
|
|
324
|
+
| `reason` | string | 决策原因 |
|
|
325
|
+
| `risk_level` | string | `low` / `medium` / `high` / `critical` |
|
|
326
|
+
| `risk_type` | string | 风险类别 (file_access, script_execution, data_exfiltration, ...) |
|
|
327
|
+
| `violated_layers` | array | 触发的检测层，如 `["1.1", "1.2"]` |
|
|
328
|
+
| `violated_policy` | string | 违反的具体条款 (Deny 时) |
|
|
329
|
+
| `policy` | string | Cerberus TOML 策略 (Allow 时) |
|
|
330
|
+
| `confidence` | int | 置信度 0-100 |
|
|
331
|
+
| `analysis_duration_ms` | float | 分析耗时（毫秒） |
|
|
332
|
+
|
|
333
|
+
## 配置
|
|
334
|
+
|
|
335
|
+
优先级：环境变量 > YAML 配置文件 > 内置默认值
|
|
336
|
+
|
|
337
|
+
### 环境变量
|
|
338
|
+
|
|
339
|
+
| 变量 | 说明 | 默认值 |
|
|
340
|
+
|------|------|--------|
|
|
341
|
+
| `AGENT_MOSS_DISABLE_LLM` | 设为 `1` 禁用层3 LLM | 未设置 |
|
|
342
|
+
| `AGENT_MOSS_LLM_API_KEY` | LLM API Key | 未设置 |
|
|
343
|
+
| `AGENT_MOSS_LLM_MODEL` | LLM 模型名称 | `gpt-4o` |
|
|
344
|
+
| `AGENT_MOSS_LLM_BASE_URL` | LLM API 端点 | `https://api.openai.com/v1` |
|
|
345
|
+
| `AGENT_MOSS_LLM_TIMEOUT` | LLM 超时（秒） | `300` |
|
|
346
|
+
| `AGENT_MOSS_ENABLE_POLICY_GEN` | 启用 Policy 生成 | 未设置 |
|
|
347
|
+
| `AGENT_MOSS_CONFIG_PATH` | 配置文件路径 | 内置默认 |
|
|
348
|
+
|
|
349
|
+
### 配置文件
|
|
350
|
+
|
|
351
|
+
参考 `config/agent_moss.yaml`。
|
|
352
|
+
|
|
353
|
+
### v2 新增配置
|
|
354
|
+
|
|
355
|
+
```yaml
|
|
356
|
+
# OS Profile 自动选择
|
|
357
|
+
os_profile:
|
|
358
|
+
type: "" # 留空自动检测，可手动指定 linux / windows
|
|
359
|
+
|
|
360
|
+
# 服务调用模式
|
|
361
|
+
server:
|
|
362
|
+
mode: "http" # "http" (TCP) 或 "socket" (Unix Domain Socket)
|
|
363
|
+
socket_path: "/var/run/agent_moss/agent_moss.sock"
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
## 项目结构
|
|
367
|
+
|
|
368
|
+
```
|
|
369
|
+
agent_moss/
|
|
370
|
+
├── profiles/ # [v2 新增] OS Profile 系统
|
|
371
|
+
│ ├── base.py # OSProfile 抽象基类
|
|
372
|
+
│ ├── linux.py # LinuxProfile
|
|
373
|
+
│ └── windows.py # WindowsProfile
|
|
374
|
+
├── engine/ # 安全分析引擎
|
|
375
|
+
│ ├── analyzer.py # 主入口 analyze()
|
|
376
|
+
│ ├── coordinator.py # AgentMossBot 三层协调器
|
|
377
|
+
│ ├── heuristic.py # 层1: 启发式检测 (OS Profile 驱动)
|
|
378
|
+
│ ├── logic_rules.py # 层2: 逻辑规则检测 (OS Profile 驱动)
|
|
379
|
+
│ ├── llm_analyzer.py # 层3: LLM + Skill 深度分析
|
|
380
|
+
│ ├── skill_engine.py # Skill 匹配引擎
|
|
381
|
+
│ ├── script_analyzer.py # 脚本内容扫描
|
|
382
|
+
│ └── types.py # 类型定义
|
|
383
|
+
├── server/ # HTTP API 服务层
|
|
384
|
+
│ ├── app.py # FastAPI 应用 + 多模式启动
|
|
385
|
+
│ ├── socket_server.py # [v2 新增] Unix Domain Socket
|
|
386
|
+
│ ├── routes.py # API 路由
|
|
387
|
+
│ └── models.py # Pydantic 请求/响应模型
|
|
388
|
+
├── adapters/ # 适配器层
|
|
389
|
+
│ └── observable.py # AgentOS 可观测服务数据适配器
|
|
390
|
+
├── infra/ # 基础设施
|
|
391
|
+
│ ├── config.py # 配置管理
|
|
392
|
+
│ ├── llm_client.py # LLM 客户端 (OpenAI SDK)
|
|
393
|
+
│ └── ...
|
|
394
|
+
├── skills/ # 安全 Skill 规则 (12 个 Markdown)
|
|
395
|
+
├── rules/ # 用户自定义规则
|
|
396
|
+
├── templates/ # Prompt 模板
|
|
397
|
+
└── cli.py # 命令行工具
|
|
398
|
+
config/
|
|
399
|
+
└── agent_moss.yaml # YAML 配置模板
|
|
400
|
+
docs/
|
|
401
|
+
├── design.md # 基础架构设计
|
|
402
|
+
├── agent_moss_adapter_design_v2.md # v2 适配方案设计
|
|
403
|
+
└── agent_collector_design_v1.md # Agent 数据采集服务设计
|
|
404
|
+
tests/
|
|
405
|
+
├── conftest.py # 共享 fixtures
|
|
406
|
+
├── test_all_cases.py # 全量测试 (48 个用例)
|
|
407
|
+
└── cases/ # 测试用例 JSON
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
## 测试
|
|
411
|
+
|
|
412
|
+
```bash
|
|
413
|
+
# 前两层测试（不依赖 LLM）
|
|
414
|
+
python3 -m pytest tests/ -v --no-header
|
|
415
|
+
|
|
416
|
+
# 包含 LLM 层（需 API Key）
|
|
417
|
+
AGENT_MOSS_LLM_API_KEY="sk-xxx" python3 -m pytest tests/ -v
|
|
418
|
+
|
|
419
|
+
# 仅运行特定测试
|
|
420
|
+
python3 -m pytest tests/ -k "deny" -v
|
|
421
|
+
python3 -m pytest tests/ -k "profile" -v
|
|
422
|
+
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kenhkl/agent-moss",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "Multi-layer security analysis engine for AI agents (TypeScript)",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/cli.js",
|
|
@@ -8,7 +8,8 @@
|
|
|
8
8
|
"agent-moss": "dist/cli.js"
|
|
9
9
|
},
|
|
10
10
|
"files": [
|
|
11
|
-
"dist"
|
|
11
|
+
"dist",
|
|
12
|
+
"README.md"
|
|
12
13
|
],
|
|
13
14
|
"scripts": {
|
|
14
15
|
"build": "tsup",
|