# opsx-sec

**Repository Path**: attacker/opsx-sec

## Basic Information

- **Project Name**: opsx-sec
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-18
- **Last Updated**: 2026-10-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpsX-Sec 统一运维安全扫描检查平台

把散落在运维脚本、Agent Skill、手工命令里的安全巡检能力，收敛成一个统一 Web 平台，
提供 **K8s 集群 / Linux 主机 / AWS 云** 三类只读扫描引擎。

> 脱敏声明：本仓库不含任何真实生产凭据、内网 IP、主机名、密钥指纹、Token。
> 所有敏感项走 `.env` / Secret 管理，扫描规则以配置化数据承载（`rules/`）。

## 三大引擎

| 引擎 | 来源能力 | 核心检测 |
|------|----------|----------|
| `engines/k8s_scan` | `/srv/sec` 巡检脚本 | Pod 逐容器 exec 查 5 项：可疑进程/二进制/真外连/可疑 cron/可疑文件 + 外连白名单收敛 |
| `engines/host_scan` | 主机入侵排查 skill | 三层扫描（可疑连接→全量出站→后门持久化）+ IOC + SUID/rootkit + 完整性 |
| `engines/aws_scan` | AWS 取证 skill | IAM/AK 枚举 + CloudTrail 关键事件 + 来源 IP + 安全组开口 + EKS 审计 + GuardDuty |

设计文档：`docs/opsx-sec-platform-design.md`；接口文档：`docs/API.md`（交互式 Swagger 见后端 `/docs`）。

## 目录结构

```
opsx-sec/
├── backend/                 # FastAPI + SQLAlchemy + APScheduler
│   ├── app/
│   │   ├── api/             # 路由（auth/assets/tasks/findings/rules/reports/dashboard）
│   │   ├── services/        # scheduler / task_runner / notifier / engine_factory
│   │   ├── engines/         # k8s_scan / host_scan / aws_scan（只读）
│   │   ├── utils/           # ip_utils / crypto
│   │   ├── models.py schemas.py config.py database.py deps.py main.py
│   └── tests/               # 引擎逻辑冒烟测试
├── frontend/                # Vue 3 + Vite + Element Plus
├── rules/                   # 配置化规则（ioc/ + whitelist/）
└── docs/                    # 设计文档
```

## 快速启动

本机预览在仓库根目录执行 `./run.sh start`，用 `./run.sh status` 查看状态，
用 `./run.sh stop` 停止。首次运行会安装依赖并创建 `backend/.env`；
前端默认访问 `http://127.0.0.1:5174/`，占用时自动顺延到空闲端口
（以 `./run.sh status` 为准）；后端默认使用 8000，端口占用时也会顺延并自动调整前端代理，接口文档地址以实际后端端口为准。
脚本使用根目录 `sqlite3.db`（仅新库，不自动迁移已有 `backend/opsx_sec.db`），
并只监听本机。首次登录 `admin / admin`，请在本机预览后修改默认密码
（右上角头像 → 个人设置 → 修改密码）；
凭据与密钥的正式配置请参照下方说明。可通过 `BACKEND_PORT`、`FRONTEND_PORT`
调整端口，启动脚本会自动设置前端代理。

以下是原有的手工启动方式，其默认数据库仍为 `backend/opsx_sec.db`：

### 1. 后端

```bash
cd backend
cp .env.example .env          # 按需填写 FERNET_KEY / FEISHU_WEBHOOK 等
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

- API 文档：http://localhost:8000/docs
- 健康检查：`GET /api/health`
- 默认账号：`admin / admin`（首次启动自动创建，**请尽快改密**）

### 2. 前端

```bash
cd frontend
npm install
npm run dev        # 开发
npm run build      # 生产构建
```

前端默认代理 `/api` → `http://localhost:8000`（见 `vite.config.js`）。

管理员可在「设置 → 大模型接入」选择 DeepSeek、百炼、智谱、硅基流动、OpenAI、Anthropic 等通用云服务商，或填写自定义模型 ID；服务商及模型目录由后端统一提供。内置型号来自 aiops/opsshell 本地参考，未核实是否为当前官方型号或最新版本。先填写配置并测试连接，测试通过后才能在页面保存；更改服务商、模型、接口或 Key 后需要重新测试。保存后可通过“读取账号模型”查询账号实际返回的 ID（部分服务商可能不开放列表）。OpenAI 使用 Responses API，Anthropic 使用 Messages API，其余预选服务商使用 OpenAI 兼容 Chat API；编码套餐及本地 HTTP 服务未作为通用预选。自定义 OpenAI 兼容接口仅接受 HTTPS；先将其域名加入后端 `LLM_ALLOWED_HOSTS`（逗号分隔），再在页面填写基础地址及该服务商的 API Key。切换服务商或地址需要重新填写 Key。已保存的旧 DeepSeek 配置在启动时保留并补齐服务商和地址；扫描结束后的 AI 研判仍由管理员手动触发，仅发送聚合统计。

### 3. 引擎冒烟测试（无真实凭据）

```bash
cd backend
python tests/engines/test_smoke.py
```

## 配置说明

| 环境变量 | 说明 |
|----------|------|
| `DATABASE_URL` | SQLite（默认）或 MySQL |
| `SECRET_KEY` | JWT 会话签名 |
| `FERNET_KEY` | 凭据加密密钥（`python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"`） |
| `FEISHU_WEBHOOK` | 飞书告警机器人（可空） |
| `RULES_DIR` | 规则目录（默认 `../rules`） |
| `COOLDOWN_MINUTES` | 同告警冷却期（默认 60） |

## 资产与凭据

三类资产（主机/集群/AWS）的凭据字段（SSH 私钥、kubeconfig、AWS AK/SK）全部 Fernet 加密落库，
API 响应一律回显 `******`，编辑留空 = 不修改。

- **主机**：SSH BatchMode 免交互只读扫描，脚本走 `bash -s`（stdin）传入。
- **Kubernetes**：使用 Kubernetes Python 客户端列出 Pod，借助 API `pods/exec` 逐容器采集；外连白名单在平台侧收敛。
- **AWS**：只读 boto3；IAM 事件自动双 region（us-east-1 + 业务 region）查询。

AWS 账号页的“检查”会按需调用 STS 和五类接口，分别展示身份、访问权限和 GuardDuty 是否启用；仅管理员可触发。检查结果只代表本次接口访问，不代表所有区域均已扫描。云账号的“只读标记”不替代 AWS IAM 只读授权。

管理员可在 AWS 账号页点击“同步”，读取配置区域内的 EC2 实例及 EKS 集群清单（需要相应 Describe/List 权限）；记录在独立的 `aws_resources` 表，重复同步按账号、区域、类型和资源 ID 更新，不会生成主机资产或调用云端修改 API。失败类型保留历史元数据，通过上次发现时间辨认旧记录。

资产管理新增 SSH 凭据中心：先录入私钥，再在新增或编辑主机时选择凭据。主机页支持 UTF-8 CSV 批量导入（`name,ip,ssh_user,ssh_port,tags`），预检后确认，按 IP 跳过重复；不会覆盖现有主机。Kubernetes 集群保存 kubeconfig 后可检查接入，新集群需在「巡检范围」中选择命名空间或全集群，保存时默认停用；旧集群继续扫描原命名空间。Token 接入、EC2 自动生成主机暂未实现。升级前请备份 `sqlite3.db`，详见 [资产接入设计](docs/asset-onboarding-sdd.md)与 [Kubernetes 范围设计](docs/kubernetes-scope-sdd.md)。

资产目录现可添加 Cloudflare 账号：保存只读 API Token 后，管理员可以「检查接入」并手动「同步 Zone」，普通登录用户只能读取账号及历史 Zone 清单，Token 不回显。接入检查不触发扫描或飞书通知；Cloudflare 流量/WAF/源站指标扫描仍需确认套餐与 Token 权限后单独开发。参考 [Cloudflare 与 Hermes 集成设计](docs/cloudflare-hermes-sdd.md)。

主机批量导入弹窗可下载 UTF-8 CSV 模板（含示例，示例 IP 必须替换），填写后先预检再确认。主机「检查 SSH」只执行 `id -un`，不会进行安全扫描；严格校验已信任的主机指纹，未知主机密钥会拒绝连接（原扫描引擎仍沿用 `accept-new`，生产扫描前应核实指纹）。AWS「检查权限」只调用只读查询接口，不更新清单；「同步资源」查询配置区域的 EC2/EKS 并更新本地 `sqlite3.db` 清单，**不会修改云资源**；「查看清单」只读本地结果。页面上的“只读标记”不是 AWS IAM 权限控制，实际权限取决于所用云凭据。

扫描任务的「查看终端」显示本次执行的阶段、完成资产数和最终汇总；点击「立即扫描」会自动打开进度窗口。界面轮询任务事件，不展示原始主机命令输出或凭据。旧任务不补写历史事件；设计和恢复说明见 [扫描进度 SDD](docs/scan-progress-sdd.md)。

管理员可在「用户目录」配置仅 LDAPS 的只读绑定，检索 OpenLDAP/AD 用户并批量导入为平台 viewer；导入用户通过目录密码登录，已有本地用户不被接管。使用前需安装更新后的后端依赖、为 LDAPS 配置信任证书链，并备份 `sqlite3.db`；没有可用的测试目录时不能视为已完成真实联调。详见 [LDAP 接入设计](docs/ldap-onboarding-sdd.md)。

扫描任务页的“未执行”表示固定任务入口还没有运行记录；任务详情列出当前引擎检查项、实时阶段事件及本次逐项发现。没有可用资产时不能手动启动，定时触发无资产会记录“未执行扫描”。新运行的发现按运行 ID 存档；旧运行没有逐项快照，只能查看原摘要与告警发现。无发现且采集成功只表示所覆盖检查项未命中异常，不能推断全环境安全。详见 [扫描结果设计](docs/scan-results-sdd.md)。

Kubernetes 资产可使用来自 EKS、ACK、TKE 或自建集群的 kubeconfig 内容。扫描器通过 Kubernetes API 读取配置范围内的 Running Pod，再用 `pods/exec` 在容器内运行只读采集脚本；要求列出 Pod 和创建 `pods/exec` 的 RBAC 权限。接入检查仍使用 `kubectl`，权限检查通过只代表授权，不保证容器内存在 `sh` 或 `ps`。缺少 `sh`、执行失败或结果不完整会记录采集失败，不能视为安全。额外 Shell 进程仅作为低优先级排查线索。kubeconfig 中的 `exec` 认证插件可能在服务端执行本地程序，须仅录入可信配置并隔离运行进程。多云与托管集群边界参见 `docs/multicloud-k8s-sdd.md`。

集群资产的“查询清单”只读取节点与当前默认命名空间的 Pod 元数据，是否允许取节点取决于集群 RBAC；清单不等于容器进程扫描。

## 扫描与告警

- 任务状态机：`pending → running → success / partial / failed / cancelled`。
- 定时：扫描页提供固定的主机、AWS、K8s 入口，无须逐项新建；缺失类型在后端启动时补齐，旧任务及其定时设置保留在“其他已有任务”。支持手动启动确认、编辑五段 cron、启停及查看下次执行时间。新增固定入口默认 Asia/Shanghai，旧 cron 保持 UTC。手动与定时触发均记录独立运行历史，并在服务端拒绝同一任务的重复启动。调度器仍按单实例运行；阶段时间线仅展示采集进度，不包含原始命令输出。
- 告警收敛：`dedup_key = sha1(engine|asset|category|evidence)` 去重，冷却期内不重复推送。
- 「检测规则」中新建 IOC 名称关键字会在下一次扫描中匹配已采集的发现标题和证据；外连 CIDR 白名单仅收敛外连发现。旧 matcher 规则仍展示，但未实现的类型不会在扫描中运行。可在「告警通知」填写飞书/Lark 群机器人 Webhook、可选签名密钥、最低级别并手动试发；平台加密保存秘密、提供投递记录。没有真实机器人地址时不会向群发送消息。详见 [检测与通知设计](docs/detection-notification-sdd.md)。
- **遏制边界**：引擎只产出 Finding；`dispose` 仅记录审计（DisposalRecord），不自动执行破坏性命令。

## 脱敏与安全基线

1. 凭据零硬编码，全走 `.env` / Secret。
2. 接口脱敏：凭据字段回显 `******`。
3. 证据脱敏：AKIA/私钥片段落库前掩码。
4. 规则配置化：静态 `rules/` 与数据库中启用的 name/CIDR 规则在下一次扫描生效。
5. 权限：`admin` 可配置/处置，`viewer` 只读。