SecAgentX · 企业安全智能体 v3.1.0

多智能体协同安全检测系统，支持 OpenAI / Anthropic 兼容协议及主流云端、本地模型，采用 Agentic-RAG 实现知识增强检索，并支持默认关闭、按需启用的自动威胁响应。

安装 CLI

推荐通过 Python 发行包安装；SecAgentX 的后端、预构建 Web、前端脚手架和知识库会一起进入 wheel，不需要用户再安装 Node 才能启动默认界面。

# 正式发布到 PyPI 后
pipx install secagentx

# 直接从仓库安装（仓库需包含已构建的 frontend/dist）
pipx install "git+https://github.com/songruifeng1010/secagent.git"

secagentx onboard
secagentx
secagentx dashboard

npm 只用于开发或定制 Vue 前端；CLI/后端的权威安装入口是 pipx/Python wheel，避免把 Python 服务伪装成 Node 包。

Windows CMD 源码快速开始

cd /d C:\path\to\secagent
py -3 -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
.venv\Scripts\python.exe -m pip install -e . --no-deps

rem 首次选择厂商、填写 API Key，并进行真实连通验证
secagentx onboard

rem 终端多轮对话；也可直接运行项目内置的 secagentx.cmd
secagentx
secagentx ask "分析这条安全告警"

rem 启动并自动打开 Web 控制台
secagentx dashboard

API Key 默认保存到 Windows 用户级 DPAPI 加密凭据库（安装可选 keyring 后也可使用系统 Keyring），不会写入项目或明文 JSON。只有 Provider 完成一次真实请求验证后才会成为活动配置。Web 控制台使用 HttpOnly Cookie、一次性 refresh token 轮换和 CSRF 校验，浏览器不再把令牌写入 localStorage；CLI/API 客户端继续支持 Bearer Token。

内置预设包括 DeepSeek、通义千问、OpenAI、Anthropic、Azure OpenAI、Gemini、OpenRouter、xAI、Kimi、Ollama 和 LM Studio；其他厂商可选择“自定义 OpenAI/Anthropic 兼容接口”，填写 API Base 与模型 ID。运行 secagentx providers 查看档案，secagentx providers --use PROFILE_ID 切换。

当前可用状态

生产部署（推荐 Docker）

# 在项目根目录显式设置强凭据；Compose 不提供默认密码。
export SECAGENTX_PASSWORD='replace-with-a-strong-password'
export SECAGENTX_JWT_SECRET='replace-with-a-random-secret-at-least-32-chars'
export POSTGRES_PASSWORD='replace-with-a-strong-random-postgres-password'
docker compose up -d
# 访问 http://localhost:8000

开发模式启动

# 核心运行时
pip install -r requirements.txt
# 开发、测试与 CI
pip install -r requirements-dev.txt
# 可选：向量化与机器学习能力
pip install -r requirements-ml.txt
# 可选：阿里云、腾讯云、AWS 防火墙适配器
pip install -r requirements-cloud.txt

# 首次启动前配置管理员凭据（示例值请替换）
export SECAGENTX_PASSWORD='replace-with-a-strong-password'

# 启动 API 服务
python3 -m backend.interface.api_server

# 启动前端（新终端）
cd frontend && npm ci && npm run dev

统一 CLI 与 Web 启动

CLI 与 Web 服务使用同一套 Agent、认证隔离和知识库代码，可交互运行，也可输出机器可读 JSON：

# 首次配置（会验证 Provider 后再保存）
secagentx onboard

# 交互模式
secagentx

# 一次性查询
secagentx ask "什么是 SQL 注入？"

# 自动化脚本/CI 使用
secagentx ask "分析 45.33.32.156" --json

# 启动 Web；默认只监听 127.0.0.1
secagentx dashboard

# 诊断配置，--live 会发起一次真实模型请求
secagentx doctor
secagentx doctor --live

未配置真实 LLM Key 时可显式设置 LLM_PROVIDER=mock 验证启动链路；此模式只用于开发，不代表真实研判能力。Windows PowerShell 使用 $env:LLM_PROVIDER='mock'，Linux/macOS 使用 export LLM_PROVIDER=mock。

搭建自己的前端

secagentx ui init C:\work\my-secagentx-ui
cd /d C:\work\my-secagentx-ui
npm ci
npm run dev

rem 构建后让 SecAgentX 托管自定义界面
npm run build
secagentx dashboard --ui C:\work\my-secagentx-ui\dist

ui init 不复制 node_modules、dist 或覆盖非空目录。监听非回环地址时必须显式添加 --allow-remote，并在企业环境配置 TLS 反向代理、防火墙和 SECAGENTX_CORS_ORIGINS。

验证

python -m compileall -q backend tests scripts
pytest -m "not slow" --timeout=60
python scripts/quality/knowledge_health.py --strict --score
cd frontend && npm test && npm run build

真实威胁 IP 缓存不是核心启动前置条件。网络可用时运行 python scripts/update_threat_ips.py 获取；若所有远程源失败，脚本会返回失败并保留已有缓存，不会写入空库。

生产数据原则

事件、资产和处置记录只来自 API/Webhook、日志接入器或数据库中的实际记录。空数据库会在 Web 中显示空状态，不会自动注入演示告警。MITRE ATT&CK 和 NVD/CISA KEV 为带来源的公开知识快照，合规/处置内容为静态参考指南，都不代表企业的实时业务数据。威胁情报未配置外部 API 时会明确标注覆盖不足。

架构

                         用户 (Web/CLI/Webhook)
                                │
                   ┌────────────┴────────────┐
     │   TrueReAct 循环调度引擎   │  ← 活动模型 Provider
                   └────────────┬────────────┘
                                │
          ┌─────────────────────┼─────────────────────┐
          │           │                 │             │
     Analyst        Intel          Responder    Knowledge
   (统一 Provider) (统一 Provider) (统一 Provider) (Provider+RAG)
          │           │                 │             │
          └───────────┴─────────────────┴─────────────┘
                                │
                     ┌──────────┴──────────┐
                     │  Tools (6 个安全工具) │
                     │ threat_intel /       │ → iptables/Cloud API
                     │ firewall / geoip /   │
                     │ cve_search /         │
                     │ log_analyzer /       │
                     │ alert_filter         │
                     └──────────┬──────────┘
                                │
          ┌─────────────────────┼─────────────────────┐
          │                     │                     │
    PostgreSQL/SQLite      ChromaDB向量库       Docker Compose
    (事件/用户/日志)        (可选语义RAG)       (应用 + PostgreSQL)

核心能力

内置知识与可选数据

数据更新命令

# 单独更新威胁 IP
python3 scripts/update_threat_ips.py

API 端点一览（51 个 HTTP/WebSocket 路由）

项目结构

secagentx/
├── backend/
│   ├── agents/           # 7 个安全 Agent 实现
│   ├── orchestrator/     # TrueReAct 循环总调度
│   ├── tools/            # 6 个注册安全工具（含多种防火墙后端）
│   ├── llm/              # 多厂商 LLM 兼容层（OpenAI / Anthropic / Mock）
│   ├── ml_model/         # 可选 ML 训练与检测流水线
│   ├── knowledge/        # MITRE / CVE / 合规 / 剧本 / 威胁情报
│   ├── storage/          # PostgreSQL/SQLite + Chroma 向量库
│   ├── security/         # 认证/脱敏/熔断器/审计/限流
│   ├── federation/       # 跨区域联邦同步
│   └── interface/        # CLI + FastAPI + WebSocket
├── frontend/             # Vue 3 + Naive UI + ECharts (10 视图)
├── knowledge_data/       # 知识库数据 (1,674 KEV / 365 MITRE / 14 合规 / 23 剧本)
├── Dockerfile            # 前端构建 + Python 运行时多阶段镜像
├── docker-compose.yml    # SecAgentX + PostgreSQL 生产部署
├── scripts/              # 运维/数据注入脚本
├── tests/                # 后端单元与集成测试
└── data/                 # 运行时 SQLite 数据库与可选缓存

版本历史