extractumio/ag3ntum

# Ag3ntum：Agent 系统管理员 + DevOps + 网站管理员。沙箱化。 **您的专属运维工程师 —— 构建时充分考虑了安全性与可靠性。**

Ag3ntum 是一个自托管的 **Agentic 平台**，专为 Linux 服务器和网站设计。它执行服务器配置、安全加固、日志分析、网站故障排查和日常维护 —— 方法论严谨、可追溯，并在 6 层安全沙箱内运行。 通过 API 调用、安排周期性任务，或通过 Web UI 提交作业。Ag3ntum 以完全透明和领域专业度执行任务，报告每一步操作，并在进行敏感更改前请求您的批准。完整的审计追踪。完整的会话回放。所有数据均保留您的基础设施中。 **模型无关。** 自带 Anthropic Claude 支持，并内置 LLM 代理，可路由至任何 OpenAI 兼容 API —— OpenRouter、Azure OpenAI、Amazon Bedrock（通过网关）、Google Vertex AI（通过网关）、Ollama、llama.cpp、vLLM，或任何本地推理服务器。无需更改代码即可按任务切换模型。

## 安装 **稳定版本**（推荐）： ``` curl -fsSL https://raw.githubusercontent.com/extractumio/ag3ntum/release/install.sh | bash ``` **最新开发版**（main 分支）： ``` curl -fsSL https://raw.githubusercontent.com/extractumio/ag3ntum/main/install.sh | bash ``` 构建完成后打开 **http://localhost:50080**。有关 API 密钥设置和创建首位用户，请参阅 [QUICK-START-GUIDE.md](QUICK-START-GUIDE.md)。 **系统要求：** Docker + Docker Compose | 2 GB+ 内存 | Linux 或 macOS ## 功能特性 ### 服务器管理 - **安全加固** — SSH 配置审计、防火墙审查、fail2ban 设置、SUID 二进制文件扫描、用户账户审计 - **补丁管理** — 清单待处理更新，经批准后应用，验证服务是否正常重启 - **日志分析** — 解析 nginx、syslog、auth.log、应用程序日志。检测异常，关联事件，生成可操作的摘要 - **健康评估** — 服务状态、磁盘/内存/CPU 使用率、SSL 证书到期情况、开放端口枚举 - **事件响应** — 诊断中断，识别根本原因，应用修复，验证恢复，生成结构化报告 ### 网站维护 - **CMS 生命周期** — WordPress/Joomla/Drupal 插件和核心更新，兼容性检查，失败时回滚 - **恶意软件修复** — 扫描 PHP/JS 文件中的注入代码，隔离感染，移除后门，加固文件权限 - **数据库优化** — 清理 transient，优化表，识别慢查询，减少膨胀 - **SSL 管理** — 监控各域名证书到期情况，处理续期，验证安装 - **性能诊断** — 识别瓶颈，审查缓存配置，分析资源利用率 ### DevOps 与基础设施 - **容器审查** — Docker Compose 分析，资源利用率，镜像优化，规格调整 - **配置漂移** — 比较环境，标记不一致，记录差异 - **依赖审计** — 过时的软件包，已知 CVE，许可证合规性 - **部署支持** — 分析失败原因，检查依赖，审查应用程序日志 - **基础设施文档化** — 服务清单，端口审计，cron 作业列表，自动化系统文档 ### 文档处理 支持在 Web UI 中直接上传和处理文档 —— PDF 文本提取、Office 文档（DOCX、XLSX、PPTX）、压缩包（ZIP、TAR、7z）以及表格数据（CSV、Excel、Parquet）。 ## 工作原理 ``` Operator ─── Web UI / REST API ─── Ag3ntum ─── Infrastructure (describe task) (execute) (local mounts, SSH, SFTP) ``` 1. **部署** — 在您的服务器上使用 Docker Compose。从零开始运行仅需 15 分钟。 2. **描述** — 用通俗英语陈述目标。无需 Playbook，无需 DSL。 3. **观察** — 实时流式传输每一条命令、输出和决策。 4. **批准** — 破坏性操作会暂停以等待明确的人工确认。 5. **审计** — 完整的会话记录，可深入查看每一次工具调用。 ## 安全架构 六层独立的深度防御层。每一层都自主运行 —— 攻破一层不会削弱其他层。 ``` Request → [WAF] → [Docker] → [Bubblewrap+UID] → [PathValidator] → [CommandFilter] → [SecureOutput] │ │ │ │ │ │ Size limits Container Per-user OS Workspace 140+ blocked Secrets DoS block boundary identity (UID) boundary only patterns auto-redacted ``` | 层级 | 执行策略 | |-------|------------| | **WAF** | 请求体大小限制，上传过滤，Content-Length 欺骗预防，DoS 缓解 | | **Docker** | 容器边界，资源限制，只读源挂载（`:ro`），容器级 seccomp 配置 | | **Bubblewrap + UID** | 每用户 Linux UID（50000–60000），PID/IPC/mount 命名空间隔离，`--clearenv`，每会话 seccomp | | **PathValidator** | 所有文件操作限制在会话工作区内，符号链接逃逸检测，在内核级别阻止跨用户访问 | | **命令过滤器** | 跨越 16 个类别的 140+ 正则表达式模式：权限提升、破坏性操作、容器逃逸、数据渗透、持久化机制 | | **安全输出** | API 密钥、Token 和密码在文件预览和命令输出中自动脱敏。等长替换。 | ### 实际遏制效果 | 攻击向量 | 结果 | |--------|---------| | `rm -rf /` | 执行前被命令过滤器阻止 | | 读取 `~/.ssh/id_rsa` | 路径未挂载在沙箱中 —— 对 Agent 不可见 | | `sudo chmod 777 /etc/passwd` | 命令过滤器阻止；seccomp 在内核级别拒绝 | | `curl http://169.254.169.254/` | 云元数据 IP 被域名过滤器阻止 | | 跨用户文件访问 | 内核强制 UID 分离 + PathValidator | | Fork 炸弹 `:(){ :\|:& };:` | 命令过滤器 + 命名空间资源限制 | | `env` / `printenv` | `--clearenv` 剥离所有主机环境变量 | AI 模型会产生幻觉。这是该技术的一个已知属性。Ag3ntum 无法解决幻觉 —— 它解决的是幻觉的**波及范围**。当模型犯错时，沙箱会在影响到达您的系统之前将其遏制。 ## 多租户隔离 租户分离由 Linux 内核强制执行，而非应用程序逻辑。绕过应用层不会授予跨租户访问权限。 | 层级 | 机制 | |-------|-----------| | **OS 身份** | 每用户唯一的 Linux UID（50000–60000 范围），在创建账户时分配 | | **文件系统** | 每会话工作区，每用户主目录，660/770 权限（无全局访问） | | **进程** | PID 命名空间隔离 —— 用户无法枚举或向彼此的进程发送信号 | | **环境** | 每用户的 API 密钥和密钥仅注入到沙箱中，对其他租户不可见 | | **审计** | 完整的每用户会话历史，防篡改（Agent 无法修改自己的日志） | ## Web 界面 - **实时流** — Server-Sent Events，带基于序列的去重，自动重连（指数退避），轮询回退 - **工具调用透明度** — 展开任何操作以检查确切的命令、stdin、stdout、stderr、退出代码 - **文件浏览器** — 浏览工作区文件，支持语法高亮预览、拖放上传、一键下载 - **人在环路** — Agent 在执行破坏性操作前暂停并提示批准。答案持久保存 —— 即使数小时后响应也不会阻塞资源 - **会话管理** — 完整历史，恢复中断的会话，每会话成本和 Token 跟踪 - **LLM 模型选择** — 通过下拉菜单按会话切换模型。无需重启即可路由至任何已配置的提供商。 ## 平台 | 功能 | 详情 | |---------|---------| | **任务队列** | Redis 支持的优先级队列。默认配额：4 个全局并发，每用户 2 个，每日 50 个。均可配置。 | | **自动恢复** | 关闭时进行中的任务在容器重启时自动恢复 | | **成本跟踪** | 每会话输入/输出/缓存 Token 计数及 USD 成本估算 | | **检查点** | 每次工具调用时捕获文件状态 —— 可回退到任何先前的状态 | | **自定义技能** | 可复用的操作模板（全局或每用户），Agent 在运行时可发现 | | **外部挂载** | 只读或读写主机目录访问，具有每用户授权 | | **动态挂载** | 每会话挂载请求，具有白名单/黑名单授权和子路径深度限制 | | **自定义角色** | Jinja2 提示词模板，按部署或按任务定义 Agent 行为 | | **LLM 代理** | 内置多提供商路由 —— Anthropic（原生）、OpenAI、OpenRouter、Azure OpenAI，或任何 OpenAI 兼容端点（Ollama、llama.cpp、vLLM）。在 YAML 中配置。 | | **REST API** | 每个 UI 操作均可通过编程方式使用。JWT 认证。完整的会话和事件 API。 | | **子 Agent** | 将子任务委托给具有限定工具访问权限和隔离上下文的专用 Agent | ## 目标受众 | 细分市场 | 规模 | 主要痛点 | Ag3ntum 价值 | |---------|-------|-------------|---------------| | **网站运营商** | 1–20 个站点，WordPress/WooCommerce/Joomla | 午夜宕机、恶意软件、插件冲突、SSL 过期 | 按命令诊断并修复站点问题。管理更新。清理感染。 | | **VPS / 服务器所有者** | 3–10 台服务器，开发-运维混合角色 | 补丁堆积、日志未检查、SSH 加密被推迟 | 有条不紊地处理维护积压。修补、审计、加固 —— 您只需审查结果。 | | **托管公司** | 40+ 台服务器，500+ 客户站点 | 3 人运维团队在一线运维上遭遇瓶颈 | 多租户自动化，具有每客户 UID 隔离和可导出的审计追踪。 | ## 技术栈 | 组件 | 技术 | |-----------|------------| | Runtime | Python 3.13+, FastAPI, Uvicorn | | 前端 | React 18, TypeScript 5.6, Vite | | 数据库 | SQLite（会话、用户、事件） | | 缓存与事件 | Redis 7（实时流、任务队列、速率限制） | | 沙箱 | Bubblewrap, seccomp profiles（3 个层级）, Linux namespaces | | Agent 核心 | Claude Code Agent SDK 及 11 个自定义 MCP 工具 | | LLM 代理 | 多提供商路由（Anthropic、OpenAI-compatible、OpenRouter） | | 部署 | Docker Compose on Ubuntu 24.04 | ## 快速参考 ``` ./run.sh build # Build image, start all services ./run.sh restart # Restart (picks up code/config changes) ./run.sh rebuild # Full teardown and rebuild ./run.sh create-user # Provision user account with UID allocation ./run.sh test # Run full test suite (backend + security + UI) ./run.sh test --quick # Skip E2E and slow tests ./run.sh shell # Interactive shell into API container ``` **构建后：** Web UI 位于 `http://localhost:50080` | API 位于 `http://localhost:40080` ## 升级 使用 `upgrade.sh` 进行安全、自动化的升级，包含备份和迁移： ``` ./upgrade.sh # Full upgrade: backup, pull, migrate, build, validate ./upgrade.sh --dry-run # Preview changes without modifying anything ./upgrade.sh --check # Health diagnostics only ./upgrade.sh --rollback # Restore from most recent backup ``` 升级脚本处理备份创建、依赖变更检测、数据库迁移（通过 Alembic）、配置模式迁移以及升级后的健康验证。备份存储在 `backups/` 中（保留 3 个）。 **请勿** 直接使用 `git pull && ./run.sh build` —— 它会跳过备份、配置迁移和依赖变更检测。有关完整详情，请参阅 [docs/how-to-upgrade.md](docs/how-to-upgrade.md)。 ## 许可证 - **AGPL-3.0** — 开源及个人使用 - **商业许可证** — 托管公司、SaaS、企业部署 **联系方式：** [info@extractum.io](mailto:info@extractum.io) 基于 Claude Code Agent SDK 构建

标签：AIOps, Awesome, BurpSuite集成, Claude, CVE检测, Docker, GitHub Advanced Security, IT运维, Linux服务器, LLM代理, OpenAI兼容, Python, Socks5代理, TCP SYN 扫描, Web UI, 人工智能, 例行维护, 安全加固, 安全沙箱, 安全防御评估, 审计追踪, 搜索引擎查询, 数据主权, 无后门, 服务器配置, 模型无关, 用户模式Hook绕过, 系统管理, 网站故障排查, 自动化运维, 自托管, 请求拦截, 运维工程师, 逆向工具, 透明度, 镜像安全