Add files via upload

2026-09-04 09:00:51 +02:00 · 2026-07-17 17:17:10 +08:00
parent 5a282c8ed9
commit c915abf310
8 changed files with 547 additions and 22 deletions
@@ -151,3 +151,52 @@ curl -k "https://127.0.0.1:8080/api/audit/logs/export" \
 ```

 导出文件可能包含敏感操作信息，应加密保存。
+
+## Recipe 11：批量导入资产
+
+先准备 `assets.json`：
+
+```json
+{
+  "source": "api-import",
+  "source_query": "cmdb-export-2026-07",
+  "assets": [
+    {
+      "domain": "app.example.com",
+      "port": 443,
+      "protocol": "https",
+      "tags": ["production", "internet"],
+      "status": "active"
+    },
+    {
+      "ip": "192.0.2.10",
+      "port": 22,
+      "protocol": "ssh",
+      "status": "active"
+    }
+  ]
+}
+```
+
+提交：
+
+```bash
+curl -k https://127.0.0.1:8080/api/assets/import \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  --data-binary @assets.json
+```
+
+返回示例：
+
+```json
+{"created":2,"updated":0,"skipped":0}
+```
+
+注意：
+
+- 调用者需要 `asset:write` 权限。
+- 每条资产至少填写 `host`、`ip` 或 `domain`。
+- 单次最多 100000 条；大批量请求建议使用文件配合 `--data-binary`，不要把 JSON 直接写进命令行。
+- 已存在的“目标 + 端口 + 协议”会合并更新并计入 `updated`。
+- 如需从 XLSX/CSV 操作，使用 Web 端 **资产库 → 批量导入**；接口本身接收 JSON，不接收 multipart 文件。
@@ -89,6 +89,136 @@ Content-Type: application/json
 - `GET /api/attack-chain/:conversationId`
 - `POST /api/attack-chain/:conversationId/regenerate`

+## 资产管理与批量导入
+
+资产接口：
+
+- `GET /api/assets`：分页查询资产；
+- `GET /api/assets/selection`：按当前筛选条件解析跨页选择，最多返回 10000 条；
+- `GET /api/assets/stats`：获取资产统计，`days` 仅支持 `7`、`30` 或 `90`；
+- `POST /api/assets/import`：新增或去重更新资产，单次最多 100000 条；
+- `POST /api/assets/scan-links`：批量记录扫描关联，单次最多 10000 条；
+- `PUT /api/assets/bulk`：原子批量更新最多 10000 个资产；
+- `PUT /api/assets/project-binding`：批量绑定项目，单次最多 10000 个资产 ID；
+- `POST /api/assets/batch-delete`：原子批量删除最多 10000 个资产；
+- `POST /api/assets/merge`：合并 2-100 个具有共同身份的重复资产；
+- `PUT /api/assets/:id`：更新资产；
+- `DELETE /api/assets/:id`：删除资产。
+
+`GET /api/assets` 和 `GET /api/assets/selection` 使用相同的筛选与排序参数；`selection` 会忽略分页参数并返回全部匹配项（最多 10000 条）：
+
+| 类别 | 参数 |
+| --- | --- |
+| 分页（仅列表） | `page`、`page_size`（最大 100） |
+| 常用 | `q`、`status`、`project_id`、`risk_level`、`min_vulnerabilities`、`max_vulnerabilities` |
+| 目标与来源 | `host`、`ip`、`domain`、`port`、`protocol`、`source`、`tag` |
+| 责任与业务 | `responsible_person`、`department`、`business_system`、`environment`、`criticality` |
+| 地理 | `country`、`province`、`city` |
+| 扫描 | `scan_state=never|scanned`、`scan_overdue_days`、`last_scan_before`、`last_scan_after` |
+| 发现时间 | `first_seen_before`、`first_seen_after`、`last_seen_before`、`last_seen_after` |
+| 排序 | `sort_by`、`sort_order=asc|desc` |
+
+时间参数接受 RFC3339 或 `YYYY-MM-DD`。`sort_by` 支持 `last_seen_at`、`last_scan_at`、`first_seen_at`、`created_at`、`updated_at`、`host`、`port`、`risk_level` 和 `vulnerability_count`。
+
+`POST /api/assets/import` 接收 JSON，而不是 XLSX/CSV 文件。Web 端会在浏览器中解析模板、预览并转换为该请求格式：
+
+```http
+POST /api/assets/import
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "source": "manual-import",
+  "source_query": "asset-import-2026-07.xlsx",
+  "assets": [
+    {
+      "host": "https://app.example.com:443",
+      "domain": "app.example.com",
+      "port": 443,
+      "protocol": "https",
+      "title": "Example App",
+      "server": "nginx",
+      "project_id": "<project-id>",
+      "responsible_person": "Alice",
+      "department": "Security",
+      "business_system": "Customer Portal",
+      "environment": "production",
+      "criticality": "critical",
+      "tags": ["production", "internet"],
+      "status": "active"
+    },
+    {
+      "ip": "192.0.2.10",
+      "port": 22,
+      "protocol": "ssh",
+      "status": "active"
+    }
+  ]
+}
+```
+
+请求规则：
+
+- `assets` 必须包含 `1-100000` 条；
+- 每条资产的 `host`、`ip`、`domain` 至少一项非空；
+- `port` 范围为 `0-65535`；
+- `status` 仅支持 `active` 或 `inactive`；
+- `environment` 支持空值或 `production`、`staging`、`testing`、`development`、`other`；
+- `criticality` 支持空值或 `critical`、`high`、`medium`、`low`；
+- 标签最多 30 个，单个最多 64 个字符；
+- `project_id` 非空时，调用者必须有权访问该项目；
+- 需要 `asset:write` 权限；
+- 服务端按“目标 + 端口 + 协议”去重，并在同一事务中处理本次请求。
+
+成功响应：
+
+```json
+{
+  "created": 120,
+  "updated": 8,
+  "skipped": 2
+}
+```
+
+- `created`：新建数量；
+- `updated`：命中去重键并合并更新的数量；
+- `skipped`：空记录或因资源归属不可更新而跳过的数量。
+
+字段校验失败返回 `400`，且响应 `error` 会包含出错资产的顺序。项目无权访问返回 `403`。批量导入的模板字段和 UI 操作见[资产管理指南](asset-management.md#从表格批量导入)。
+
+批量编辑示例：
+
+```http
+PUT /api/assets/bulk
+Content-Type: application/json
+
+{
+  "asset_ids": ["<asset-id-1>", "<asset-id-2>"],
+  "responsible_person": "Alice",
+  "department": "Security",
+  "environment": "production",
+  "criticality": "high",
+  "add_tags": ["internet-facing"],
+  "remove_tags": ["untriaged"]
+}
+```
+
+批量字段均为可选；未提供的字段保持原值。`add_tags` 和 `remove_tags` 会在事务内去重处理。批量编辑、项目绑定和批量删除会先验证全部资产的可访问性，任一 ID 不存在或无权访问时整批失败。
+
+重复资产合并示例：
+
+```http
+POST /api/assets/merge
+Content-Type: application/json
+
+{
+  "asset_ids": ["<primary-id>", "<duplicate-id>"],
+  "primary_id": "<primary-id>"
+}
+```
+
+每个待删除记录必须与主资产共享域名、IP 或 Host。主资产已有字段优先，空字段从其他记录补齐，标签取并集；调用者需要更新主资产和删除其余资产的权限。
+
 ## 工具、MCP、配置

 配置：
@@ -208,6 +338,7 @@ C2：
 | `/api/auth/*` | 高 | 可直接集成 |
 | `/api/eino-agent*` | 高 | 推荐外部对话入口 |
 | `/api/openapi/spec` | 高 | 用于生成客户端 |
+| `/api/assets/*` | 高 | 资产管理与批量导入 |
 | `/api/config*` | 中 | 管理工具使用，谨慎自动化 |
 | `/api/c2/*`、`/api/webshell/*` | 中 | 高风险，必须加权限边界 |
 | 前端私有调用细节 | 低 | 不建议插件依赖 |
@@ -237,3 +368,5 @@ curl -k https://127.0.0.1:8080/api/eino-agent \
 - OpenAPI：`internal/handler/openapi.go`
 - 单代理：`internal/handler/eino_single_agent.go`
 - 多代理：`internal/handler/multi_agent.go`
+- 资产接口：`internal/handler/asset.go`
+- 资产存储与去重：`internal/database/asset.go`
@@ -11,11 +11,13 @@
 资产管理包含三个主要入口：

 - **资产概览**：统计资产总量、IP、域名、端口、近期变化、扫描覆盖率和协议分布。
- **资产库**：维护资产身份、服务信息、来源、标签、项目归属、扫描记录和风险状态。
+- **资产库**：维护资产身份、服务信息、来源、标签、项目归属、责任与业务属性、扫描记录和风险状态。
 - **信息收集**：查询 FOFA，并将确认归属的结果单条或批量写入资产库。

 资产可以进一步发起单目标分析或批量扫描。Agent 保存漏洞并完成扫描回写后，资产列表会同步展示相关漏洞数量、风险等级和最近扫描时间。

+概览支持切换最近 7、30 或 90 天，展示新增/停用资产趋势、漏洞发现趋势（含严重和高危）、扫描覆盖率、30 天内覆盖率、从未扫描与过期资产数量，以及协议 Top 8 分布。所有统计均受当前用户的资产访问范围约束。
+
 ## 资产字段

 每条资产可记录：
@@ -23,6 +25,7 @@
 - Host、IP、域名、端口和协议；
 - 页面标题、服务或产品指纹；
 - 国家/地区、省份/州和城市；
+- 负责人、部门、业务系统、环境和重要性；
 - 来源、来源查询条件和标签；
 - 活跃或停用状态；
 - 所属项目和所有者；
@@ -45,11 +48,56 @@ example.com
 [2001:db8::1]:443
 ```

-系统会尽量识别 URL、域名、IP、端口和协议。保存前可继续补充项目、标签、标题、服务指纹、地理位置和状态。
+系统会尽量识别 URL、域名、IP、端口和协议。保存前可继续补充项目、标签、标题、服务指纹、地理位置、负责人、部门、业务系统、环境、重要性和状态。
+
+### 从表格批量导入
+
+进入 **资产管理 → 资产库**，点击 **批量导入**：
+
+1. 下载 XLSX（推荐）或 CSV 模板。
+2. 在 `Assets` 工作表中填写资产；不要修改表头。
+3. 上传文件，或将文件拖入上传区域。
+4. 查看逐行校验结果。文件内重复、格式错误和无权访问的项目会标为错误。
+5. 点击 **导入有效数据**。错误行不会提交，预览超过 100 行时只展示前 100 行，但提交会处理全部有效行。
+6. 根据提示核对新增、更新和跳过数量。
+
+模板字段：
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `target` | 条件必填 | URL、域名、IPv4、IPv6 或带端口目标；当 `host`、`ip`、`domain` 均为空时必填 |
+| `project` | 否 | 已有项目的精确名称或项目 ID；留空表示不绑定 |
+| `tags` | 否 | 逗号、中文逗号、分号或竖线分隔；最多 30 个，单个最多 64 个字符 |
+| `host` | 条件必填 | 完整 URL 或 Host；可与 `target` 配合补充 |
+| `ip` | 条件必填 | 合法 IPv4 或 IPv6 |
+| `domain` | 条件必填 | 合法域名，国际化域名会规范化 |
+| `port` | 否 | `0-65535`；留空时可从 `target` 推断 |
+| `protocol` | 否 | 如 `http`、`https`、`ssh`；留空时可从 URL 或常用端口推断 |
+| `title` | 否 | 页面标题，最多 500 个字符 |
+| `server` | 否 | 服务或产品指纹 |
+| `country` / `province` / `city` | 否 | 地理归属信息 |
+| `responsible_person` | 否 | 负责人，最多 255 个字符 |
+| `department` | 否 | 责任部门，最多 255 个字符 |
+| `business_system` | 否 | 所属业务系统，最多 255 个字符 |
+| `environment` | 否 | `production`、`staging`、`testing`、`development` 或 `other` |
+| `criticality` | 否 | `critical`、`high`、`medium` 或 `low` |
+| `status` | 否 | `active` 或 `inactive`，也接受“活跃”“停用”；默认 `active` |
+
+表头同时识别模板中的英文字段和常用中文别名；环境和重要性也接受模板列中对应的中文值。为避免不同系统导出的列名产生歧义，自动化流程仍建议使用模板中的英文表头和枚举值。
+
+限制与处理规则：
+
+- 单个 XLSX/CSV 文件最多 100000 行、100 MB。
+- `/api/assets/import` 单次请求最多 100000 条资产。
+- 文件内相同“目标 + 端口 + 协议”的后续行会标记为重复，不会提交。
+- Web 端负责文件解析、预览和即时格式提示；服务端仍会执行权限检查、字段校验、规范化、去重和事务写入。
+- 已存在的资产会合并本次提供的非空字段并更新最近发现时间；不会创建重复记录。
+- 批量导入需要 `asset:write` 权限。填写项目时，当前用户还必须有权访问该项目。
+- 不建议取消服务端条数上限。更大规模的数据应拆分文件并在低峰期导入。

 ### 从 FOFA 导入

-1. 在配置文件或系统设置中填写 FOFA 邮箱和 API Key，也可使用 `FOFA_EMAIL`、`FOFA_API_KEY` 环境变量。
+1. 在配置文件或 **系统设置 → 资产管理** 中填写 FOFA API Key，也可使用 `FOFA_API_KEY` 环境变量。
 2. 进入 **资产管理 → 信息收集**。
 3. 输入或生成 FOFA 查询语句，并确认查询范围。
 4. 执行查询，选择确认归属的结果后点击 **入库所选**。
@@ -73,18 +121,40 @@ example.com

 重复资产再次入库时，系统会更新本次提供的非空字段和最近发现时间，保留未提供的原有信息，不会重置首次发现时间。

-## 查询与筛选
+## 查询、筛选与视图

-Web 端支持搜索 Host、IP、域名、标题、服务和标签，并按状态或项目筛选。后端和 Agent 工具还支持：
+Web 端的关键字搜索覆盖 Host、IP、域名、标题、服务、标签、负责人、部门和业务系统。常用筛选包括状态和项目；展开高级筛选后还可以组合：

- 来源、标签、端口和协议；
- 已扫描、从未扫描等扫描状态；
- 首次发现、最近发现和最近扫描时间范围；
- 按最近扫描时间等白名单字段排序；
- 分页查询。
+- 风险等级和最少漏洞数；
+- 协议、端口、来源和精确标签；
+- 已扫描、从未扫描，以及 30/60/90 天未扫描；
+- 国家/地区、省份/州、城市、负责人、部门和业务系统；
+- 环境、重要性、首次发现和最近发现日期范围；
+- 最近发现、最近扫描、风险、漏洞数、首次发现、目标名称或端口排序。

 按最近扫描时间升序排列时，从未扫描的资产优先显示，便于识别覆盖盲区。

+常用筛选组合可以保存为筛选视图。筛选视图保存在当前浏览器的 `localStorage` 中，不会同步到服务端、其他浏览器或其他用户。
+
+HTTP API 和 `query_assets` 还支持 `max_vulnerabilities`、最近扫描时间范围，以及创建/更新时间等白名单排序字段。HTTP 列表每页最多 100 条，Agent 查询每页最多 50 条。
+
+## 批量维护与导出
+
+选择资产后，可以对当前页执行操作，也可以选择当前筛选条件命中的全部结果。跨页选择由服务端重新解析当前筛选条件，最多返回 10000 条；超过上限时需要进一步缩小范围。
+
+可用操作：
+
+- **绑定项目**：为所选资产统一替换项目归属；
+- **批量编辑**：修改状态、负责人、部门、业务系统、环境和重要性，并增删标签；
+- **创建扫描任务 / 发送到对话**：复用同一提示词模板处理所选资产；
+- **导出 CSV / XLSX**：在浏览器中导出当前已选择的资产，包含责任属性、风险、漏洞数量和时间字段；
+- **合并重复资产**：保留第一个所选资产为主资产，以其他记录的非空字段补齐主资产并合并标签；
+- **批量删除**：永久删除所选资产。
+
+批量编辑、项目绑定和批量删除采用全有或全无的事务：只要其中一个资产不存在或超出调用者权限，整批操作就会失败，不会留下部分更新。
+
+合并仅适用于具有共同域名、IP 或 Host 的记录，每次可选择 2-100 条。主资产已有值优先，标签取并集且仍受 30 个标签限制，其余记录会被删除。该操作同时需要 `asset:write` 和 `asset:delete`；合并前应确认主资产选择以及需要保留的扫描历史。
+
 ## 扫描与风险回写

 ### 单资产扫描
@@ -128,6 +198,8 @@ Web 端支持搜索 Host、IP、域名、标题、服务和标签，并按状态

 `query_assets` 默认每页返回 20 条、最多 50 条摘要。需要完整信息时使用 `get_asset`，避免大量资产数据占用模型上下文。

+`create_asset` 和 `update_asset` 均支持责任与业务属性；`query_assets` 也可以按这些字段筛选。Agent 写入仍经过与 HTTP API 相同的规范化、字段校验、去重和权限检查。
+
 ## 权限控制

 资产权限分为：
@@ -138,6 +210,16 @@ Web 端支持搜索 Host、IP、域名、标题、服务和标签，并按状态

 服务端会同时检查资产所有者、显式资源授权、所属项目及权限 Scope（`all`、`assigned`、`own`）。当对话绑定项目后，Agent 的资产查询会被限制在该项目内，工具参数不能扩大访问范围。

+资产批量接口限制：
+
+- `POST /api/assets/import`：单次最多 100000 条；
+- `GET /api/assets/selection`：最多解析 10000 条匹配资产；
+- `POST /api/assets/scan-links`：单次最多 10000 条；
+- `PUT /api/assets/bulk`：单次最多 10000 个资产 ID；
+- `PUT /api/assets/project-binding`：单次最多 10000 个资产 ID；
+- `POST /api/assets/batch-delete`：单次最多 10000 个资产 ID；
+- `POST /api/assets/merge`：单次合并 2-100 个资产 ID。
+
 ## 推荐使用流程

 1. 划定一组明确授权的域名、IP 或网段。