agent-moss 0.2.0

Multi-layer security analysis engine for AI agents

AgentMoss

AgentMoss 是一个可被任意 AI Agent 调用的独立通用安全分析服务。基于 OS Profile 机制，自动适配 Linux/Windows 的 syscall 检测模式，提供三层防御安全分析（启发式 → 逻辑规则 → LLM 语义分析）。

v2 更新：新增 OS Profile 系统（Linux/Windows 自适应）、Unix Domain Socket 支持、标准化 API 契约。

目录

• 架构
• 快速开始
• LLM 配置
• openEuler 部署
• 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 安全原则 — 不确定时默认拒绝

快速开始

安装（开发环境）

pip install -e .

CLI 使用

# 生成输入模板 (v2: 含 os_type 和 cwd 字段)
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 方式：

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 方式（同机低延迟）：

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)：

{
  "decision": "Allow",
  "risk_level": "low",
  "risk_type": "",
  "violated_layers": [],
  "confidence": 100,
  "analysis_duration_ms": 10.8
}

响应示例 (Deny)：

{
  "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：环境变量（推荐）

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 配置文件

编辑 config/agent_moss.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（仅静态规则）

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 权限

一键安装

sudo dnf install -y python3 python3-pip python3-devel
git clone <repo-url> agent_moss
cd agent_moss
sudo bash scripts/install.sh

配置 LLM（生产环境）

# 写入 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

# 编辑 LLM model / base_url
sudo vim /etc/agent_moss/agent_moss.yaml

启动方式

# HTTP TCP 模式（默认，适合跨机/调试）
sudo systemctl enable --now agent_moss

# Unix Socket 模式（同机部署推荐，更低延迟）
# 编辑 /etc/agent_moss/agent_moss.yaml 中 server.mode: "socket"
# 或修改 /etc/systemd/system/agent_moss.service 中的 ExecStart

启动与验证

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

管理命令

命令	说明
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	取消开机启动

防火墙（HTTP 模式需要）

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)：

{
  "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": "..."}
}

字段	类型	必填	说明
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_MODEL	LLM 模型名称	gpt-4o
AGENT_MOSS_LLM_BASE_URL	LLM API 端点	https://api.openai.com/v1
AGENT_MOSS_LLM_TIMEOUT	LLM 超时（秒）	300
AGENT_MOSS_ENABLE_POLICY_GEN	启用 Policy 生成	未设置
AGENT_MOSS_CONFIG_PATH	配置文件路径	内置默认

配置文件

参考 config/agent_moss.yaml。

v2 新增配置

# 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"

项目结构

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

测试

# 前两层测试（不依赖 LLM）
python3 -m pytest tests/ -v --no-header

# 包含 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