agent-moss 0.2.0__tar.gz

agent_moss-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentMoss Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_moss-0.2.0/MANIFEST.in

@@ -0,0 +1,4 @@
+recursive-include agent_moss/templates *
+recursive-include agent_moss/skills *.md
+recursive-include agent_moss/rules *.json
+include agent_moss/infra/config.json

agent_moss-0.2.0/PKG-INFO

@@ -0,0 +1,432 @@
+Metadata-Version: 2.4
+Name: agent-moss
+Version: 0.2.0
+Summary: Multi-layer security analysis engine for AI agents
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.0
+Requires-Dist: httpx>=0.25
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Requires-Dist: pydantic>=2.0
+Requires-Dist: tenacity>=8.0
+Requires-Dist: loguru>=0.7
+Requires-Dist: fastapi>=0.100
+Requires-Dist: uvicorn[standard]>=0.20
+Requires-Dist: pyyaml>=6.0
+Dynamic: license-file
+
+# AgentMoss
+
+AgentMoss 是一个**可被任意 AI Agent 调用的独立通用安全分析服务**。基于 OS Profile 机制，自动适配 Linux/Windows 的 syscall 检测模式，提供三层防御安全分析（启发式 → 逻辑规则 → LLM 语义分析）。
+
+> v2 更新：新增 OS Profile 系统（Linux/Windows 自适应）、Unix Domain Socket 支持、标准化 API 契约。
+
+## 目录
+
+- [架构](#架构)
+- [快速开始](#快速开始)
+- [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 -e .
+```
+
+### CLI 使用
+
+```bash
+# 生成输入模板 (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 方式：**
+
+```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 配置文件**
+
+编辑 `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
+```
+
+### 配置 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
+
+# 编辑 LLM model / base_url
+sudo vim /etc/agent_moss/agent_moss.yaml
+```
+
+### 启动方式
+
+```bash
+# 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
+```
+
+### 启动与验证
+
+```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
+```
+
+### 管理命令
+
+| 命令 | 说明 |
+|------|------|
+| `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 模式需要）
+
+```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": "..."}
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `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 新增配置
+
+```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"
+```
+
+## 项目结构
+
+```
+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
+```
+
+## 测试
+
+```bash
+# 前两层测试（不依赖 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
+```