/alibabacloud-ecs-sec-userspace

name: alibabacloud-ecs-sec-userspace
version: 1.4.1  # Keep in sync with VERSION file
date: 2026-05-09
description: >
  Linux 用户态安全入侵检测与取证工具，专为 AI Agent 设计。自动判断服务器是否被入侵，
  提供完整证据链和可执行修复建议。51 个安全分析器覆盖进程/网络/认证/持久化/Rootkit/
  恶意软件/内存取证/容器逃逸等 12 类检测维度，10 个数据采集器全面采集系统状态，
  映射 103+ MITRE ATT&CK 技术，支持 standalone/docker/k8s 三种部署模式。
  与 sec-kernel（内核态 CVE 漏洞检测）互补，共同构成完整的 ECS 安全评估方案。
  当用户询问服务器安全、入侵检测、系统审计、恶意软件检测、安全事件响应时使用。
  每当需要判断服务器是否被入侵、检查后门木马、分析安全事件时，优先使用此技能。
  务必在发现安全异常时主动调用此技能，即使用户没有明确要求安全检查。
allowed-tools:
  - terminal (sudo required for full scan)
  - file-read
  - file-write

sec-userspace

> **Linux 服务器安全入侵检测与取证工具 | Linux Server Security Intrusion Detection & Forensics Tool**

---

First Run Setup | 首次运行

**AI Agent 首次使用本 Skill 时，MUST 执行以下权限申请（一次性，后续无需重复）：**

cd /data/sec-userspace && sudo python3 scripts/setup_permissions.py --auto

这将自动： 1. 检测系统已安装的 AI 工具（Claude Code, Qoder, OpenCode, Windsurf, Cursor, Gemini CLI, Trae） 2. 配置最小权限集（sudo, read all, write workspace） 3. 备份已有配置 4. 验证权限生效

配置完成后重启 AI 工具即可永久生效。验证权限：

cd /data/sec-userspace && python3 scripts/setup_permissions.py --verify

---

Quick Start | 快速开始

**完整流程: 权限申请 → 环境初始化 → 执行扫描 → 反思验证 → 输出结果**

Step 1: 环境初始化（首次）

cd /data/sec-userspace && sudo bash scripts/setup.sh

自动完成：检测/安装 Python >= 3.11、创建 workspace、安装 Skill 到 AI 工具目录。

Step 2: 执行扫描

# 推荐（源码模式）
cd /data/sec-userspace && sudo python3 -m scripts.main --output-dir /data/sec-userspace/workspace

# 编译版（需 Python 3.11 精确匹配）
cd /data/sec-userspace && sudo python3 scripts/main.pyz --output-dir /data/sec-userspace/workspace

> **pyz 失败处理**：若出现 `bad magic number` 错误，详见 [references/python-runtime.md](references/python-runtime.md)

Step 3: 查看报告

报告输出到 `/data/sec-userspace/workspace/{YYYY-MM-DD}/report/`：

| 文件 | 格式 | 用途 | |------|------|------| | `sec-report-{date}.md` | Markdown | 主报告：结论、证据、时间线、修复建议 | | `sec-report-{date}.json` | JSON | 结构化数据，便于程序化处理 | | `attack-chain-{date}.md` | Markdown | 攻击链分析 | | `sec-userspace-log-{date}.log` | Log | 执行日志 |

Step 4: Post-Scan Reflection（MANDATORY）

**扫描完成后，必须先执行反思流程，再向用户汇报结果。** 详见 [Post-Scan Reflection](#post-scan-reflection--扫描后反思)。

---

What Can It Do? | 能做什么？

Detection Capabilities | 检测能力

覆盖 **12 大检测类别**、**51 个安全分析器**、**10 个数据采集器**，映射 **103+ MITRE ATT&CK 技术**。

| 检测类别 | 核心能力 | |----------|----------| | 进程异常 | 隐藏进程、反弹 Shell、进程树异常、代码注入 | | 网络异常 | C2 通信、DNS 隧道、DGA 域名、威胁情报匹配 | | 认证与凭据 | SSH 后门密钥、暴力破解、PAM 后门、凭据泄露 | | 持久化机制 | Crontab/Systemd/Shell 配置后门 | | Rootkit | 内核模块异常、LD_PRELOAD 劫持、io_uring/eBPF Rootkit | | 恶意软件 | 挖矿、勒索软件、RAT、无文件恶意软件 | | 内存取证 | 内存注入、RWX 异常、memfd 无文件攻击 | | 文件系统 | SUID/SGID 异常、Webshell、隐藏文件 | | 横向移动 | SSH 横向、端口转发、时序关联分析 | | 容器/K8s | 容器逃逸、RBAC 风险、运行时行为异常 |

> **完整检测能力列表**（含全部分析器和采集器详情）见 [references/detection-capabilities.md](references/detection-capabilities.md) > > **MITRE ATT&CK 技术映射详表**（80+ 技术编号、14 个战术阶段）见 [references/technique-mappings.md](references/technique-mappings.md)

Key Features | 核心特性

• **51 安全分析器** — 覆盖传统威胁、容器安全、内存取证等多维度检测
• **10 个数据采集器** — 系统/进程/网络/用户/文件/日志/Cron/服务/DNS/软件包 全面采集
• **103+ MITRE ATT&CK 映射** — 每条告警关联 ATT&CK 技术编号
• **环境自适应** — 自动识别服务器角色，智能跳过不适用的检测
• **零系统修改** — 只读操作，不修改系统任何文件
• **IoC 威胁情报** — 内置 base64 编码 IoC 数据库
• **3 种部署模式** — standalone / docker / k8s

---

Prerequisites | 前置条件

| 项目 | 要求 | |------|------| | **架构** | x86_64 (AMD64) | | **操作系统** | Linux (glibc 2.17+: Ubuntu 14.04+, CentOS 7+, Debian 8+) | | **Python** | >= 3.11（`setup.sh` 可自动安装） | | **权限** | root (sudo) | | **网络** | 扫描无需联网；缺少 Python 3.11 时需网络下载 (~30MB) |

Security Model | 安全模型

• **root (sudo)** — 读取 /proc、/sys、系统日志等内核信息
• **只读采集** — 零系统修改，不写入/删除/修改任何系统文件
• **写入仅限 workspace/** — 仅保存扫描日志和报告

Required Permissions | 最小权限集

{
  "permissions": {
    "allow": [
      "Bash(sudo:*)",
      "Bash(python3:*)",
      "Read(**)",
      "Write(/data/sec-userspace/workspace/**)",
      "Write(workspace/**)"
    ]
  }
}

支持的 AI 工具：Claude Code、QoderCLI、OpenCode、Windsurf、Cursor、Gemini CLI、Trae。详见 [references/permissions.md](references/permissions.md)。

---

Command Line | 命令行参考

Core Parameters | 核心参数

# 基本扫描
cd /data/sec-userspace && sudo python3 -m scripts.main --output-dir /data/sec-userspace/workspace

# 指定输出格式
cd /data/sec-userspace && sudo python3 -m scripts.main --format both

# 完整报告（含时间线、攻击链、交叉关联）
cd /data/sec-userspace && sudo python3 -m scripts.main --full-report

# 高负载时强制执行
cd /data/sec-userspace && sudo python3 -m scripts.main --force

# 列出所有分析器
cd /data/sec-userspace && python3 -m scripts.main --list-analyzers

# 查看资产数据
cd /data/sec-userspace && python3 -m scripts.main --show-assets all

# K8s 部署
cd /data/sec-userspace && python3 -m scripts.main k8s-deploy

All Parameters | 完整参数表

| 参数 | 说明 | 默认值 | |------|------|--------| | `--output-dir PATH` | 报告输出目录 | from config | | `--format {markdown,json,both}` | 输出格式 | both | | `--quiet` | 静默模式，适合 crontab | from config | | `--force` | 跳过负载保护，强制执行 | — | | `--list-analyzers` | 列出全部分析器及耗时 | — | | `--show-assets [{all,ioc,whitelist}]` | 显示解码后的资产数据 | all | | `--no-fp-suppression` | 禁用误报抑制（审计模式） | — | | `--force-json` | 强制生成 JSON 报告 | — | | `--full-report` | 启用完整报告：时间线、攻击链、交叉关联、覆盖率 | — | | `--lang {auto,en,zh,both}` | 报告语言 | auto | | `--env {auto,development,production,ci,container}` | 环境上下文 | auto | | `--retention-days N` | 报告保留天数 | 180 | | `--dry-run` | 仅预览，不上报 | — |

Subcommands | 子命令

| 子命令 | 用途 | |--------|------| | `standalone` | 独立模式运行（含内置 LLM 客户端） | | `k8s-deploy` | K8s CronJob 部署、执行、收集结果 | | `whitelist` | 白名单管理（学习 + 用户自定义） | | `perf` | 性能监控与分析 |

Deploy Modes | 部署模式

| 模式 | 路径 | 说明 | |------|------|------| | **standalone** | deploy/standalone/ | 单机直接运行 | | **docker** | deploy/docker/ | Docker 容器，含 Dockerfile + compose | | **k8s** | deploy/k8s/ | CronJob + RBAC + ConfigMap |

---

Understanding Results | 理解扫描结果

Scan Conclusion | 扫描结论

| 结论 | 含义 | 建议操作 | |------|------|----------| | **Compromised** | 确认被入侵 | 立即隔离，执行 P0 修复 | | **Highly Suspic