@kenhkl/agent-moss 0.2.1 → 0.3.0

package/README.md

@@ -1,422 +1,169 @@
-# AgentMoss
+# AgentMoss (TypeScript)
 
-AgentMoss 是一个**可被任意 AI Agent 调用的独立通用安全分析服务**。基于 OS Profile 机制，自动适配 Linux/Windows 的 syscall 检测模式，提供三层防御安全分析（启发式 → 逻辑规则 → LLM 语义分析）。
+AgentMoss TypeScript 实现 — 可被任意 AI Agent 调用的独立通用安全分析服务。三层防御引擎（启发式 → 逻辑规则 → LLM 语义分析），两级快速放行白名单，fail-closed 安全原则。
 
-> v2 更新：新增 OS Profile 系统（Linux/Windows 自适应）、Unix Domain Socket 支持、标准化 API 契约。
+> 当前版本：**v0.2.1** | npm: `@kenhkl/agent-moss`
 
-## 目录
-
-- [架构](#架构)
-- [快速开始](#快速开始)
-- [LLM 配置](#llm-配置)
-- [openEuler 部署](#openeuler-部署)
-- [API 参考](#api-参考)
-- [配置](#配置)
-- [项目结构](#项目结构)
-- [测试](#测试)
-
-## 架构
-
-```
-┌───────────────────────────────────────────┐
-│       调用入口 (HTTP / Unix Socket)         │
-│  POST /api/v1/analyze                     │
-│  GET  /api/v1/health                      │
-├───────────────────────────────────────────┤
-│             ObservableAdapter              │
-│  AgentOS 可观测服务 syscall → 标准格式     │
-├───────────────────────────────────────────┤
-│              OS Profile 选择               │
-│     ┌──────────┐    ┌──────────┐          │
-│     │  Linux   │    │ Windows  │          │
-│     │ Profile  │    │ Profile  │          │
-│     └──────────┘    └──────────┘          │
-├───────────────────────────────────────────┤
-│         安全分析引擎 (三层防御)              │
-│                                            │
-│  层1: 启发式静态检测 (毫秒级)               │
-│    ├── 用户规则匹配                        │
-│    ├── 危险命令正则 (OS Profile 驱动)       │
-│    └── Prompt 注入检测                     │
-│                                            │
-│  层2: 逻辑规则检测 (毫秒级)                 │
-│    ├── read_before_write 原则             │
-│    ├── 意图一致性检测                      │
-│    ├── 敏感路径访问 (OS Profile 驱动)       │
-│    └── 危险操作模式                        │
-│                                            │
-│  层3: LLM + Skill 深度分析                 │
-│    ├── Skill 规则匹配 (12 个 Skill)         │
-│    ├── 脚本内容预扫描                      │
-│    └── LLM 语义安全判断                    │
-└───────────────────────────────────────────┘
-```
-
-### 设计原则
-
-- **适配在 OS 层，不在 Agent 层** — 不同 Agent 最终都会调用操作系统的 syscall，这是确定性的
-- **标准化 I/O 契约** — 任何 Agent 遵循 API 格式即可接入，无需关心内部实现
-- **fail-closed 安全原则** — 不确定时默认拒绝
-
-## 快速开始
-
-### 安装
+## 安装
 
 ```bash
-pip install agent-moss
+npm install @kenhkl/agent-moss
 ```
 
-如需从源码安装：
+从源码构建：
 
 ```bash
-git clone git@gitcode.com:kenhkl/AgentMoss.git
-cd AgentMoss
-pip install -e .
+cd ts
+npm install
+npm run build
 ```
 
-### CLI 使用
+## CLI 使用
 
 ```bash
-# 生成输入模板 (v2: 含 os_type 和 cwd 字段)
-agent-moss init -o input.json
+# 生成输入模板
+npx agent-moss init -o input.json
 
 # 运行安全分析
-agent-moss analyze input.json
-
-# 启动 HTTP 服务 (TCP)
-agent-moss server --port 9090
-
-# 启动 Unix Domain Socket 服务（同机部署推荐）
-agent-moss server --mode socket --socket /var/run/agent_moss/agent_moss.sock
-
-# 指定配置文件
-agent-moss server --mode socket --config /etc/agent_moss/agent_moss.yaml
-```
-
-### API 调用
-
-**HTTP TCP 方式：**
-
-```bash
-curl -X POST http://127.0.0.1:9090/api/v1/analyze \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "session_id": "test-001",
-    "prompt_session": "列出系统文件",
-    "action_history": [],
-    "a_next": {
-      "action_type": "bash",
-      "action_detail": "ls -la /tmp"
-    },
-    "reason": "查看临时目录",
-    "os_type": "",
-    "cwd": "/home/user"
-  }'
-```
-
-**Unix Domain Socket 方式（同机低延迟）：**
-
-```bash
-curl --unix-socket /var/run/agent_moss/agent_moss.sock \
-  -X POST http://localhost/api/v1/analyze \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "session_id": "test-001",
-    "a_next": {
-      "action_type": "bash",
-      "action_detail": "ls -la /tmp"
-    }
-  }'
-```
-
-**响应示例 (Allow)**：
-
-```json
-{
-  "decision": "Allow",
-  "risk_level": "low",
-  "risk_type": "",
-  "violated_layers": [],
-  "confidence": 100,
-  "analysis_duration_ms": 10.8
-}
-```
-
-**响应示例 (Deny)**：
-
-```json
-{
-  "decision": "Deny",
-  "reason": "检测到递归强制删除关键路径 (rm -rf /...)",
-  "risk_level": "critical",
-  "risk_type": "script_execution",
-  "violated_layers": ["1.1"],
-  "confidence": 95,
-  "analysis_duration_ms": 1.2
-}
-```
-
-## LLM 配置
-
-AgentMoss 的三层防御中，层3（LLM 语义分析）是可选的。层1+层2 的静态规则可以独立运行。
-
-### 启用 LLM
-
-**方式 1：环境变量（推荐）**
-
-```bash
-export AGENT_MOSS_LLM_API_KEY="sk-your-key"
-# 可选：自定义模型和 API 端点
-export AGENT_MOSS_LLM_MODEL="glm-5.0"
-export AGENT_MOSS_LLM_BASE_URL="https://api.nextapi.store/v1"
-```
-
-**方式 2：YAML 配置文件**
+npx agent-moss analyze input.json
 
-编辑 `config/agent_moss.yaml`：
-
-```yaml
-llm:
-  provider: "zhipu"
-  model: "glm-5.0"
-  base_url: "https://api.nextapi.store/v1"
-  api_key_env: "AGENT_MOSS_LLM_API_KEY"
-  temperature: 0.1
-  max_tokens: 4096
-
-security:
-  llm_analysis:
-    enabled: true
-```
-
-### 禁用 LLM（仅静态规则）
-
-```bash
-export AGENT_MOSS_DISABLE_LLM=1
-```
-
-### 支持的 LLM Provider
-
-| Provider | 说明 |
-|----------|------|
-| OpenAI | api.openai.com |
-| DeepSeek | api.deepseek.com |
-| 智谱 (GLM) | open.bigmodel.cn |
-| OpenRouter | openrouter.ai |
-| Groq | api.groq.com |
-| 任何 OpenAI 兼容 API | 设置 `base_url` 即可 |
-
-## openEuler 部署
-
-### 前提
-
-- openEuler 22.03 LTS+
-- Python 3.10+
-- root 权限
-
-### 一键安装
-
-```bash
-sudo dnf install -y python3 python3-pip python3-devel
-git clone <repo-url> agent_moss
-cd agent_moss
-sudo bash scripts/install.sh
+# 启动 HTTP 服务（默认端口 9090）
+npx agent-moss server --port 9090
 ```
 
-### 配置 LLM（生产环境）
+## 编程调用
 
-```bash
-# 写入 API Key（文件权限 600）
-echo "AGENT_MOSS_LLM_API_KEY=sk-your-key" | sudo tee /etc/agent_moss/agent_moss.env
-sudo chmod 600 /etc/agent_moss/agent_moss.env
+```typescript
+import { createApp } from '@kenhkl/agent-moss';
 
-# 编辑 LLM model / base_url
-sudo vim /etc/agent_moss/agent_moss.yaml
+const app = createApp();
+// 通过 Hono app.fetch 在 Node.js / Bun / Electron 中调用
 ```
 
-### 启动方式
-
-```bash
-# HTTP TCP 模式（默认，适合跨机/调试）
-sudo systemctl enable --now agent_moss
+或直接 HTTP 调用：
 
-# Unix Socket 模式（同机部署推荐，更低延迟）
-# 编辑 /etc/agent_moss/agent_moss.yaml 中 server.mode: "socket"
-# 或修改 /etc/systemd/system/agent_moss.service 中的 ExecStart
+```typescript
+const resp = await fetch('http://127.0.0.1:9090/api/v1/analyze', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    session_id: 'sess-001',
+    a_next: { action_type: 'bash', action_detail: 'ls -la' },
+    os_type: 'linux',
+    cwd: '/home/user',
+  }),
+});
+const result = await resp.json();
+// → { decision: 'Allow'|'Deny', risk_level: 'low'|'...', ... }
 ```
 
-### 启动与验证
-
-```bash
-sudo systemctl enable --now agent_moss
-
-# HTTP 模式验证
-curl http://127.0.0.1:9090/api/v1/health
-# {"status":"healthy","version":"0.1.0"}
+## 架构
 
-# Socket 模式验证
-curl --unix-socket /var/run/agent_moss/agent_moss.sock \
-  http://localhost/api/v1/health
 ```
+快速放行白名单
+├── 完全安全 (15 bash 模式 + 6 action types) → 跳过 L2+L3
+└── 只读敏感 (15 bash 模式 + 8 action types) → 跳过 L3
 
-### 管理命令
-
-| 命令 | 说明 |
-|------|------|
-| `systemctl start agent_moss` | 启动 |
-| `systemctl stop agent_moss` | 停止 |
-| `systemctl restart agent_moss` | 重启 |
-| `systemctl status agent_moss` | 查看状态 |
-| `journalctl -u agent_moss -f` | 查看日志 |
-| `systemctl disable agent_moss` | 取消开机启动 |
+层1: 启发式静态检测 (<1ms)
+├── 危险命令正则: 30 个模式（rm 分级检测: 5 条严格→宽松规则）
+├── 注入关键词: 56 个中英双语关键词（9 类: 指令覆盖/角色劫持/命令注入/...）
+└── 自定义规则: AGENT_MOSS_CUSTOM_RULES 环境变量注入
 
-### 防火墙（HTTP 模式需要）
+层2: 逻辑规则检测 (<1ms)
+├── Rule 1: read-before-write（有历史但无读取 → flag）
+├── Rule 2: 意图偏离（读取意图 vs 删除动作）
+├── Rule 3: 敏感路径访问（20 条路径，4 级风险: critical/high/medium/low）
+├── Rule 4: 危险操作（通配符删除 + 重定向覆盖 /etc/ /boot/ /proc/）
+├── Rule 5: 提权检测（sudo/su/chmod u+s/setuid）
+└── Rule 6: 横向移动（ssh/scp/rsync，排除 localhost）
 
-```bash
-sudo firewall-cmd --add-port=9090/tcp --permanent
-sudo firewall-cmd --reload
-```
-
-## API 参考
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| `GET` | `/api/v1/health` | 健康检查 |
-| `POST` | `/api/v1/analyze` | 安全分析 |
-
-### POST /api/v1/analyze
-
-**请求体 (v2)**：
-
-```json
-{
-  "session_id": "会话ID (必填)",
-  "prompt_session": "原始任务描述 (可选)",
-  "action_history": [{"action_type": "...", "action_detail": "..."}],
-  "a_next": {
-    "action_type": "bash",
-    "action_detail": "cat /etc/passwd"
-  },
-  "reason": "执行理由 (可选)",
-  "os_type": "",
-  "cwd": "/home/user/project",
-  "metadata": {"agent_id": "...", "sandbox_id": "..."}
-}
+层3: LLM + Skill 深度分析 (2-5s)
+├── 脚本预扫描: 读取 .sh 文件（最多 500 行），16 个可疑模式
+├── Skill 匹配: 12 个 Skill，关键词加权评分，返回 top 3
+├── LLM 缓存: 200 条 FIFO，避免重复调用
+├── Provider 识别: 15+ Provider，自动注入 HTTP Header
+├── LLM 调用: 支持重试（默认 2 次重试 = 3 次尝试）
+└── fail-closed: 失败时拒绝（confidence=60, source='llm_failure'）
 ```
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `session_id` | string | 是 | 会话唯一标识 |
-| `prompt_session` | string | 否 | 原始任务描述 |
-| `action_history` | array | 否 | 历史动作序列 |
-| `a_next.action_type` | string | 是 | 动作类型 (bash/file_read/file_write 等) |
-| `a_next.action_detail` | string | 是 | 命令/动作详情 |
-| `reason` | string | 否 | 执行理由 |
-| `os_type` | string | 否 | **v2 新增** — `"linux"` / `"windows"`，留空自动检测 |
-| `cwd` | string | 否 | **v2 新增** — 当前工作目录 |
-| `metadata` | object | 否 | 扩展元数据 |
-
-**响应字段**：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `decision` | string | `Allow` / `Deny` |
-| `reason` | string | 决策原因 |
-| `risk_level` | string | `low` / `medium` / `high` / `critical` |
-| `risk_type` | string | 风险类别 (file_access, script_execution, data_exfiltration, ...) |
-| `violated_layers` | array | 触发的检测层，如 `["1.1", "1.2"]` |
-| `violated_policy` | string | 违反的具体条款 (Deny 时) |
-| `policy` | string | Cerberus TOML 策略 (Allow 时) |
-| `confidence` | int | 置信度 0-100 |
-| `analysis_duration_ms` | float | 分析耗时（毫秒） |
-
-## 配置
-
-优先级：环境变量 > YAML 配置文件 > 内置默认值
-
-### 环境变量
+## 环境变量
 
 | 变量 | 说明 | 默认值 |
 |------|------|--------|
-| `AGENT_MOSS_DISABLE_LLM` | 设为 `1` 禁用层3 LLM | 未设置 |
-| `AGENT_MOSS_LLM_API_KEY` | LLM API Key | 未设置 |
+| `AGENT_MOSS_LLM_API_KEY` | LLM API Key（回退 `OPENAI_API_KEY`） | 未设置 |
 | `AGENT_MOSS_LLM_MODEL` | LLM 模型名称 | `gpt-4o` |
 | `AGENT_MOSS_LLM_BASE_URL` | LLM API 端点 | `https://api.openai.com/v1` |
+| `AGENT_MOSS_LLM_TEMPERATURE` | 采样温度 | `0.1` |
+| `AGENT_MOSS_LLM_MAX_TOKENS` | 最大输出 token 数 | `4096` |
 | `AGENT_MOSS_LLM_TIMEOUT` | LLM 超时（秒） | `300` |
-| `AGENT_MOSS_ENABLE_POLICY_GEN` | 启用 Policy 生成 | 未设置 |
-| `AGENT_MOSS_CONFIG_PATH` | 配置文件路径 | 内置默认 |
-
-### 配置文件
-
-参考 `config/agent_moss.yaml`。
-
-### v2 新增配置
+| `AGENT_MOSS_LLM_RETRIES` | LLM 调用重试次数 | `2`（共 3 次尝试） |
+| `AGENT_MOSS_DISABLE_LLM` | 设为 `1` 禁用层3 LLM | 未设置 |
+| `AGENT_MOSS_DISABLE_HEURISTIC` | 设为 `1` 禁用层1 启发式 | 未设置 |
+| `AGENT_MOSS_DISABLE_LOGIC_RULES` | 设为 `1` 禁用层2 逻辑规则 | 未设置 |
+| `AGENT_MOSS_CUSTOM_RULES` | 自定义规则 JSON 数组 | `[]` |
 
-```yaml
-# OS Profile 自动选择
-os_profile:
-  type: ""         # 留空自动检测，可手动指定 linux / windows
+### 自定义规则
 
-# 服务调用模式
-server:
-  mode: "http"     # "http" (TCP) 或 "socket" (Unix Domain Socket)
-  socket_path: "/var/run/agent_moss/agent_moss.sock"
-```
+```bash
+export AGENT_MOSS_CUSTOM_RULES='[
+  {"pattern": "kubectl delete namespace", "action": "Deny", "severity": "critical"},
+  {"pattern": "docker rm -f", "action": "Deny", "severity": "high"}
+]'
+```
+
+## 支持的 Provider
+
+| Provider | URL 匹配 | Provider Hint | Header 注入 |
+|----------|---------|---------------|-------------|
+| OpenAI | `api.openai.com` | `openai` | — |
+| Anthropic | `anthropic.com` | `claude` / `anthropic` | — |
+| Google | `generativelanguage.googleapis.com` | `google` / `gemini` | — |
+| DeepSeek | `api.deepseek.com` | `deepseek` | — |
+| 智谱 (GLM) | `open.bigmodel.cn` | `zhipu` / `glm-cn` | — |
+| 智谱 Coding Plan | `api.z.ai` | `zai-coding-plan` | — |
+| OpenRouter | `openrouter.ai` | `openrouter` | Referer + Title |
+| Groq | `api.groq.com` | `groq` | — |
+| Mistral | `api.mistral.ai` | `mistral` | — |
+| Together | `api.together.xyz` | `together` | — |
+| xAI | `api.x.ai` | `xai` / `xai-grok` | Referer |
+| MiniMax | `api.minimaxi.com` | `minimax` | — |
+| GitCode | `api-ai.gitcode.com` | `gitcode` | — |
+| Ollama | `:11434` | `ollama` | — |
+| 任意兼容 | — | `other` / `custom` / `local` | — |
 
 ## 项目结构
 
 ```
-agent_moss/
-├── profiles/         # [v2 新增] OS Profile 系统
-│   ├── base.py           # OSProfile 抽象基类
-│   ├── linux.py          # LinuxProfile
-│   └── windows.py        # WindowsProfile
-├── engine/           # 安全分析引擎
-│   ├── analyzer.py       # 主入口 analyze()
-│   ├── coordinator.py    # AgentMossBot 三层协调器
-│   ├── heuristic.py      # 层1: 启发式检测 (OS Profile 驱动)
-│   ├── logic_rules.py    # 层2: 逻辑规则检测 (OS Profile 驱动)
-│   ├── llm_analyzer.py   # 层3: LLM + Skill 深度分析
-│   ├── skill_engine.py   # Skill 匹配引擎
-│   ├── script_analyzer.py # 脚本内容扫描
-│   └── types.py          # 类型定义
-├── server/           # HTTP API 服务层
-│   ├── app.py            # FastAPI 应用 + 多模式启动
-│   ├── socket_server.py  # [v2 新增] Unix Domain Socket
-│   ├── routes.py         # API 路由
-│   └── models.py         # Pydantic 请求/响应模型
-├── adapters/         # 适配器层
-│   └── observable.py     # AgentOS 可观测服务数据适配器
-├── infra/            # 基础设施
-│   ├── config.py         # 配置管理
-│   ├── llm_client.py     # LLM 客户端 (OpenAI SDK)
-│   └── ...
-├── skills/           # 安全 Skill 规则 (12 个 Markdown)
-├── rules/            # 用户自定义规则
-├── templates/        # Prompt 模板
-└── cli.py            # 命令行工具
-config/
-└── agent_moss.yaml   # YAML 配置模板
-docs/
-├── design.md                          # 基础架构设计
-├── agent_moss_adapter_design_v2.md    # v2 适配方案设计
-└── agent_collector_design_v1.md       # Agent 数据采集服务设计
-tests/
-├── conftest.py       # 共享 fixtures
-├── test_all_cases.py # 全量测试 (48 个用例)
-└── cases/            # 测试用例 JSON
+ts/src/
+├── cli.ts                    # CLI 入口 (init/analyze/server)
+├── config.ts                 # 全局配置 (环境变量 + Provider 识别 + Header 注入)
+├── models.ts                 # Zod 数据模型
+├── routes.ts                 # Hono API 路由 (POST /analyze, GET /health)
+├── server.ts                 # Hono HTTP 服务 (CORS + logger)
+└── engine/
+    ├── types.ts              # 核心类型 (SecurityJudgment, LLMConfig, ...)
+    ├── coordinator.ts        # 三层协调器 + 两级快速放行白名单
+    ├── heuristic.ts          # 层1: 30 危险模式 + 56 注入关键词
+    ├── logic-rules.ts        # 层2: 6 条规则 + 20 敏感路径
+    ├── llm-analyzer.ts       # 层3: LLM 分析 (缓存 + 重试 + fail-closed)
+    ├── script-analyzer.ts    # 脚本内容预扫描 (18 个可疑模式)
+    ├── skill-loader.ts       # Skill 加载与关键词匹配 (12 个 Skill)
+    └── template-loader.ts    # Prompt 模板加载 (3 个模板)
 ```
 
-## 测试
+## 依赖
 
-```bash
-# 前两层测试（不依赖 LLM）
-python3 -m pytest tests/ -v --no-header
+| 包 | 说明 |
+|---|---|
+| `hono` | HTTP 框架 |
+| `@hono/node-server` | Node.js HTTP 适配 |
+| `openai` | LLM API 客户端 |
+| `zod` | 数据校验 |
+| `yaml` | YAML 解析 |
 
-# 包含 LLM 层（需 API Key）
-AGENT_MOSS_LLM_API_KEY="sk-xxx" python3 -m pytest tests/ -v
+## 构建
 
-# 仅运行特定测试
-python3 -m pytest tests/ -k "deny" -v
-python3 -m pytest tests/ -k "profile" -v
+```bash
+npm run build    # tsup 打包到 dist/
+npm run dev      # tsx 热重载开发 (端口 9090)
 ```