mirror of
https://github.com/Ed1s0nZ/CyberStrikeAI.git
synced 2026-07-18 18:07:32 +02:00
Add files via upload
This commit is contained in:
公明
@@ -133,7 +133,7 @@ CyberStrikeAI connects planning, execution, human oversight, evidence, and repla
|
||||
|
||||
- 📁 **Conversation management** provides grouping, pinning, renaming, and batch organization.
|
||||
- 📂 **Projects and attack chains** connect cross-session facts, risk scoring, graph views, and step-by-step replay.
|
||||
- 🗂️ **Asset management** normalizes and deduplicates domains, IP addresses, ports, and services while tracking scan coverage, linked vulnerabilities, and risk state. See the [Asset Management guide](docs/en-US/asset-management.md).
|
||||
- 🗂️ **Asset management** normalizes and deduplicates domains, IP addresses, ports, and services; supports XLSX/CSV import and export, advanced filters and saved views, ownership and business metadata, cross-page bulk maintenance, and duplicate merging; and tracks scan coverage, linked vulnerabilities, and risk state. See the [Asset Management guide](docs/en-US/asset-management.md).
|
||||
- 🛡️ **Vulnerability management** provides severity classification, lifecycle tracking, filtering, and statistics.
|
||||
- 📋 **Batch tasks** provide queued execution, editing, status tracking, and retained results.
|
||||
- 📱 **Chatbots** connect Personal WeChat, WeCom, DingTalk, Lark, Telegram, Slack, Discord, and QQ Bot.
|
||||
|
||||
+1
-1
@@ -132,7 +132,7 @@ CyberStrikeAI 将规划、执行、人工监督、证据与复盘连接在同一
|
||||
|
||||
- 📁 **对话管理**：支持分组、置顶、重命名和批量管理。
|
||||
- 📂 **项目与攻击链**：关联跨会话事实、风险评分、图谱视图和步骤回放。
|
||||
- 🗂️ **资产管理**：统一归档和去重域名、IP、端口与服务，跟踪扫描覆盖、关联漏洞和风险状态。详见[资产管理指南](docs/zh-CN/asset-management.md)。
|
||||
- 🗂️ **资产管理**：统一归档和去重域名、IP、端口与服务，支持 XLSX/CSV 导入导出、高级筛选与保存视图、责任和业务属性、跨页批量维护、重复资产合并，并跟踪扫描覆盖、关联漏洞和风险状态。详见[资产管理指南](docs/zh-CN/asset-management.md)。
|
||||
- 🛡️ **漏洞管理**：支持严重程度分级、状态流转、过滤和统计看板。
|
||||
- 📋 **批量任务**：支持任务队列、编辑、状态跟踪和结果留存。
|
||||
- 📱 **机器人接入**：支持个人微信、企业微信、钉钉、飞书、Telegram、Slack、Discord 和 QQ。
|
||||
|
||||
@@ -151,3 +151,52 @@ curl -k "https://127.0.0.1:8080/api/audit/logs/export" \
|
||||
```
|
||||
|
||||
Exported logs may contain sensitive operational data. Store encrypted.
|
||||
|
||||
## Recipe 11: Bulk Import Assets
|
||||
|
||||
Create `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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Submit it:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```json
|
||||
{"created":2,"updated":0,"skipped":0}
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- The caller needs `asset:write`.
|
||||
- Each asset requires at least one of `host`, `ip`, or `domain`.
|
||||
- One request supports up to 100,000 assets. For large payloads, use a file with `--data-binary` instead of embedding JSON in the command line.
|
||||
- An existing “target + port + protocol” is merged and counted in `updated`.
|
||||
- To work from XLSX/CSV, use **Asset Inventory → Bulk Import** in the Web UI. The API itself accepts JSON rather than multipart files.
|
||||
|
||||
@@ -55,6 +55,132 @@ Streaming endpoints are long-lived. Clients should:
|
||||
- disable proxy buffering;
|
||||
- pass `conversationId` when continuing a conversation.
|
||||
|
||||
## Asset Management and Bulk Import
|
||||
|
||||
Asset endpoints:
|
||||
|
||||
- `GET /api/assets`: list and filter assets;
|
||||
- `GET /api/assets/selection`: resolve cross-page selection from the current filters, up to 10,000 rows;
|
||||
- `GET /api/assets/stats`: retrieve statistics; `days` accepts only `7`, `30`, or `90`;
|
||||
- `POST /api/assets/import`: create or deduplicate and update up to 100,000 assets;
|
||||
- `POST /api/assets/scan-links`: record up to 10,000 scan links;
|
||||
- `PUT /api/assets/bulk`: atomically update up to 10,000 assets;
|
||||
- `PUT /api/assets/project-binding`: bind up to 10,000 asset IDs to a project;
|
||||
- `POST /api/assets/batch-delete`: atomically delete up to 10,000 assets;
|
||||
- `POST /api/assets/merge`: merge 2-100 duplicate assets with a shared identity;
|
||||
- `PUT /api/assets/:id`: update an asset;
|
||||
- `DELETE /api/assets/:id`: delete an asset.
|
||||
|
||||
`GET /api/assets` and `GET /api/assets/selection` share filters and sorting. `selection` ignores pagination and returns all matching rows, up to 10,000:
|
||||
|
||||
| Category | Parameters |
|
||||
| --- | --- |
|
||||
| Pagination (list only) | `page`, `page_size` (maximum: 100) |
|
||||
| Common | `q`, `status`, `project_id`, `risk_level`, `min_vulnerabilities`, `max_vulnerabilities` |
|
||||
| Target and source | `host`, `ip`, `domain`, `port`, `protocol`, `source`, `tag` |
|
||||
| Responsibility and business | `responsible_person`, `department`, `business_system`, `environment`, `criticality` |
|
||||
| Location | `country`, `province`, `city` |
|
||||
| Scan | `scan_state=never|scanned`, `scan_overdue_days`, `last_scan_before`, `last_scan_after` |
|
||||
| Discovery time | `first_seen_before`, `first_seen_after`, `last_seen_before`, `last_seen_after` |
|
||||
| Sort | `sort_by`, `sort_order=asc|desc` |
|
||||
|
||||
Time parameters accept RFC3339 or `YYYY-MM-DD`. Supported `sort_by` values are `last_seen_at`, `last_scan_at`, `first_seen_at`, `created_at`, `updated_at`, `host`, `port`, `risk_level`, and `vulnerability_count`.
|
||||
|
||||
`POST /api/assets/import` accepts JSON, not an XLSX/CSV upload. The Web UI parses the template in the browser, previews it, and converts valid rows to this request:
|
||||
|
||||
```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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Request rules:
|
||||
|
||||
- `assets` must contain between 1 and 100,000 entries;
|
||||
- at least one of `host`, `ip`, or `domain` must be non-empty for each asset;
|
||||
- `port` must be between `0` and `65535`;
|
||||
- `status` must be `active` or `inactive`;
|
||||
- `environment` may be empty or `production`, `staging`, `testing`, `development`, or `other`;
|
||||
- `criticality` may be empty or `critical`, `high`, `medium`, or `low`;
|
||||
- an asset may have up to 30 tags, each no longer than 64 characters;
|
||||
- a non-empty `project_id` must reference a project accessible to the caller;
|
||||
- the caller needs `asset:write`;
|
||||
- the server deduplicates by “target + port + protocol” and processes the request in one transaction.
|
||||
|
||||
Successful response:
|
||||
|
||||
```json
|
||||
{
|
||||
"created": 120,
|
||||
"updated": 8,
|
||||
"skipped": 2
|
||||
}
|
||||
```
|
||||
|
||||
`created` counts new records, `updated` counts deduplicated merges, and `skipped` counts empty or inaccessible existing records. Validation errors return `400` with the failing asset position in `error`; inaccessible projects return `403`. See [Asset Management](asset-management.md#import-from-a-spreadsheet) for the template and UI workflow.
|
||||
|
||||
Bulk edit example:
|
||||
|
||||
```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"]
|
||||
}
|
||||
```
|
||||
|
||||
All patch fields are optional; omitted fields retain their current values. `add_tags` and `remove_tags` are deduplicated inside the transaction. Bulk edit, project binding, and batch deletion validate access to every requested asset first, so a missing or inaccessible ID fails the entire operation.
|
||||
|
||||
Duplicate merge example:
|
||||
|
||||
```http
|
||||
POST /api/assets/merge
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"asset_ids": ["<primary-id>", "<duplicate-id>"],
|
||||
"primary_id": "<primary-id>"
|
||||
}
|
||||
```
|
||||
|
||||
Every record being removed must share a domain, IP address, or Host with the primary asset. Existing primary values win, empty fields are filled from the other records, and tags are unioned. The caller needs permission to update the primary and delete the other assets.
|
||||
|
||||
## Stability Tiers
|
||||
|
||||
| API type | Stability | Recommendation |
|
||||
@@ -62,6 +188,7 @@ Streaming endpoints are long-lived. Clients should:
|
||||
| `/api/auth/*` | high | safe to integrate |
|
||||
| `/api/eino-agent*` | high | preferred chat entry |
|
||||
| `/api/openapi/spec` | high | client generation |
|
||||
| `/api/assets/*` | high | asset management and bulk import |
|
||||
| `/api/config*` | medium | admin automation only |
|
||||
| `/api/c2/*`, `/api/webshell/*` | medium | high-risk, restrict access |
|
||||
| frontend private calls | low | avoid plugin dependency |
|
||||
@@ -70,6 +197,7 @@ Streaming endpoints are long-lived. Clients should:
|
||||
|
||||
- Conversations: `/api/conversations`
|
||||
- Projects/facts: `/api/projects`
|
||||
- Assets and bulk import: `/api/assets`
|
||||
- Vulnerabilities: `/api/vulnerabilities`
|
||||
- Knowledge: `/api/knowledge/*`
|
||||
- Roles: `/api/roles`
|
||||
@@ -101,3 +229,5 @@ curl -k https://127.0.0.1:8080/api/eino-agent \
|
||||
- OpenAPI: `internal/handler/openapi.go`
|
||||
- Single-agent: `internal/handler/eino_single_agent.go`
|
||||
- Multi-agent: `internal/handler/multi_agent.go`
|
||||
- Asset endpoints: `internal/handler/asset.go`
|
||||
- Asset storage and deduplication: `internal/database/asset.go`
|
||||
|
||||
@@ -11,11 +11,13 @@ Asset management consolidates domains, IP addresses, ports, and services discove
|
||||
Asset management provides three main views:
|
||||
|
||||
- **Overview**: asset totals, IPs, domains, ports, recent changes, scan coverage, and protocol distribution.
|
||||
- **Asset inventory**: identity, service details, source, tags, project ownership, scan history, and risk state.
|
||||
- **Asset inventory**: identity, service details, source, tags, project ownership, responsibility and business metadata, scan history, and risk state.
|
||||
- **Reconnaissance**: search FOFA and save confirmed results individually or in batches.
|
||||
|
||||
Assets can launch single-target analysis or batch scans. After an Agent records findings and completes the scan callback, the inventory displays related vulnerability counts, risk level, and latest scan time.
|
||||
|
||||
The overview can show the last 7, 30, or 90 days. It includes added/inactive asset trends, vulnerability discovery trends (including critical/high findings), total and 30-day scan coverage, never-scanned and stale counts, and the top eight protocols. Every statistic is restricted to the current user's accessible assets.
|
||||
|
||||
## Asset fields
|
||||
|
||||
An asset can include:
|
||||
@@ -23,6 +25,7 @@ An asset can include:
|
||||
- host, IP address, domain, port, and protocol;
|
||||
- page title and service or product fingerprint;
|
||||
- country/region, state/province, and city;
|
||||
- responsible person, department, business system, environment, and criticality;
|
||||
- source, source query, and tags;
|
||||
- active or inactive status;
|
||||
- project and owner;
|
||||
@@ -45,11 +48,56 @@ example.com
|
||||
[2001:db8::1]:443
|
||||
```
|
||||
|
||||
The system attempts to identify the URL, domain, IP address, port, and protocol. You can then add a project, tags, title, service fingerprint, location, and status.
|
||||
The system attempts to identify the URL, domain, IP address, port, and protocol. You can then add a project, tags, title, service fingerprint, location, responsible person, department, business system, environment, criticality, and status.
|
||||
|
||||
### Import from a spreadsheet
|
||||
|
||||
Go to **Asset Management → Asset Inventory** and select **Bulk Import**:
|
||||
|
||||
1. Download the XLSX (recommended) or CSV template.
|
||||
2. Enter assets in the `Assets` sheet without changing the header row.
|
||||
3. Choose the completed file or drop it onto the upload area.
|
||||
4. Review row-level validation. Duplicates, invalid values, and inaccessible projects are marked as errors.
|
||||
5. Select **Import valid rows**. Invalid rows are not submitted. When the file contains more than 100 rows, the preview shows the first 100 while submission processes every valid row.
|
||||
6. Review the created, updated, and skipped counts.
|
||||
|
||||
Template columns:
|
||||
|
||||
| Column | Required | Description |
|
||||
| --- | --- | --- |
|
||||
| `target` | Conditional | URL, domain, IPv4, IPv6, or a target with a port; required when `host`, `ip`, and `domain` are all empty |
|
||||
| `project` | No | Exact name or ID of an existing project; leave blank for no project |
|
||||
| `tags` | No | Comma, semicolon, or pipe-separated; up to 30 tags and 64 characters per tag |
|
||||
| `host` | Conditional | Full URL or host; may supplement `target` |
|
||||
| `ip` | Conditional | Valid IPv4 or IPv6 address |
|
||||
| `domain` | Conditional | Valid domain; internationalized domains are normalized |
|
||||
| `port` | No | `0-65535`; may be inferred from `target` |
|
||||
| `protocol` | No | Such as `http`, `https`, or `ssh`; may be inferred from a URL or common port |
|
||||
| `title` | No | Page title, up to 500 characters |
|
||||
| `server` | No | Service or product fingerprint |
|
||||
| `country` / `province` / `city` | No | Location metadata |
|
||||
| `responsible_person` | No | Responsible person, up to 255 characters |
|
||||
| `department` | No | Responsible department, up to 255 characters |
|
||||
| `business_system` | No | Owning business system, up to 255 characters |
|
||||
| `environment` | No | `production`, `staging`, `testing`, `development`, or `other` |
|
||||
| `criticality` | No | `critical`, `high`, `medium`, or `low` |
|
||||
| `status` | No | `active` or `inactive`; defaults to `active` |
|
||||
|
||||
The parser recognizes the template's English headers and common Chinese aliases. Environment and criticality columns also accept their corresponding Chinese values. Automated exports should keep the English headers and enum values to avoid ambiguous mappings.
|
||||
|
||||
Limits and behavior:
|
||||
|
||||
- One XLSX/CSV file may contain up to 100,000 rows and be up to 100 MB.
|
||||
- One `/api/assets/import` request may contain up to 100,000 assets.
|
||||
- Later rows with the same “target + port + protocol” in one file are marked as duplicates and are not submitted.
|
||||
- The Web UI parses and previews the file; the server remains responsible for authorization, validation, normalization, deduplication, and transactional writes.
|
||||
- Existing assets receive non-empty incoming fields and a refreshed last-seen time instead of a duplicate record.
|
||||
- Bulk import requires `asset:write`. Referenced projects must also be accessible to the current user.
|
||||
- Do not remove the server-side row limit. Split larger datasets and import them during a low-traffic window.
|
||||
|
||||
### Import from FOFA
|
||||
|
||||
1. Configure the FOFA email and API key in settings or the configuration file. You can also use the `FOFA_EMAIL` and `FOFA_API_KEY` environment variables.
|
||||
1. Configure the FOFA API key in the configuration file or under **System Settings → Asset Management**. You can also use the `FOFA_API_KEY` environment variable.
|
||||
2. Open **Asset Management → Reconnaissance**.
|
||||
3. Enter or generate a FOFA query and confirm its scope.
|
||||
4. Run the query, select results whose ownership has been verified, and choose **Save Selected**.
|
||||
@@ -73,18 +121,40 @@ Assets use “target + port + protocol” as the service-level deduplication key
|
||||
|
||||
When an existing asset is imported again, non-empty incoming fields and the last-seen time are updated. Existing fields omitted by the new record and the original first-seen time are preserved.
|
||||
|
||||
## Search and filters
|
||||
## Search, filters, and views
|
||||
|
||||
The Web UI searches hosts, IP addresses, domains, titles, services, and tags, with status and project filters. The backend and Agent tools additionally support:
|
||||
Keyword search in the Web UI covers hosts, IP addresses, domains, titles, services, tags, responsible people, departments, and business systems. Status and project are the primary filters; advanced filters can combine:
|
||||
|
||||
- source, tags, port, and protocol;
|
||||
- scanned and never-scanned states;
|
||||
- first-seen, last-seen, and latest-scan time ranges;
|
||||
- allowlisted sort fields such as latest scan time;
|
||||
- paginated queries.
|
||||
- risk level and minimum vulnerability count;
|
||||
- protocol, port, source, and exact tag;
|
||||
- scanned, never scanned, or not scanned for 30/60/90 days;
|
||||
- country/region, state/province, city, responsible person, department, and business system;
|
||||
- environment, criticality, first-seen dates, and last-seen dates;
|
||||
- sorting by last seen, latest scan, risk, vulnerability count, first seen, target name, or port.
|
||||
|
||||
Sorting by latest scan time in ascending order places never-scanned assets first, making coverage gaps visible.
|
||||
|
||||
Frequently used combinations can be saved as filter views. Saved views use the current browser's `localStorage`; they are not synchronized to the server, other browsers, or other users.
|
||||
|
||||
The HTTP API and `query_assets` additionally support `max_vulnerabilities`, latest-scan time ranges, and allowlisted creation/update sort fields. HTTP lists allow up to 100 rows per page, while Agent queries allow up to 50.
|
||||
|
||||
## Bulk maintenance and export
|
||||
|
||||
After selecting assets, you can act on the current page or select every result matching the current filters. Cross-page selection resolves the filters again on the server and is limited to 10,000 assets; narrow the filters when the result exceeds that limit.
|
||||
|
||||
Available actions:
|
||||
|
||||
- **Bind project**: replace the project binding for all selected assets;
|
||||
- **Bulk edit**: change status, responsible person, department, business system, environment, and criticality, and add or remove tags;
|
||||
- **Create scan task / Send to chat**: apply one prompt template to the selected assets;
|
||||
- **Export CSV / XLSX**: export the currently selected rows in the browser, including ownership, risk, vulnerability count, and timestamp fields;
|
||||
- **Merge duplicates**: keep the first selected asset as primary, fill its empty fields from the other records, and union their tags;
|
||||
- **Batch delete**: permanently delete the selected assets.
|
||||
|
||||
Bulk edit, project binding, and batch delete are all-or-nothing transactions. If any requested asset is missing or outside the caller's scope, the entire operation fails without a partial update.
|
||||
|
||||
Merge is only allowed when every duplicate shares a domain, IP address, or Host with the primary asset, and accepts 2-100 selected records. Existing primary values win, tags are unioned subject to the 30-tag limit, and the other records are deleted. It requires both `asset:write` and `asset:delete`; confirm the primary record and the scan history you need to retain before merging.
|
||||
|
||||
## Scanning and risk updates
|
||||
|
||||
### Scan one asset
|
||||
@@ -128,6 +198,8 @@ Six built-in tools expose asset operations to Agents:
|
||||
|
||||
`query_assets` returns 20 summaries by default and allows at most 50 per page. Use `get_asset` for full details so large inventories do not consume the model context.
|
||||
|
||||
Both `create_asset` and `update_asset` accept responsibility and business metadata, and `query_assets` can filter by those fields. Agent writes go through the same normalization, validation, deduplication, and authorization checks as the HTTP API.
|
||||
|
||||
## Access control
|
||||
|
||||
Asset permissions are separated into:
|
||||
@@ -138,6 +210,16 @@ Asset permissions are separated into:
|
||||
|
||||
Server-side authorization considers the asset owner, explicit resource assignments, the linked project, and permission scope (`all`, `assigned`, or `own`). When a conversation is linked to a project, Agent asset queries are restricted to that project and tool arguments cannot widen the boundary.
|
||||
|
||||
Asset batch endpoint limits:
|
||||
|
||||
- `POST /api/assets/import`: up to 100,000 assets per request;
|
||||
- `GET /api/assets/selection`: resolve up to 10,000 matching assets;
|
||||
- `POST /api/assets/scan-links`: up to 10,000 links per request;
|
||||
- `PUT /api/assets/bulk`: up to 10,000 asset IDs per request;
|
||||
- `PUT /api/assets/project-binding`: up to 10,000 asset IDs per request;
|
||||
- `POST /api/assets/batch-delete`: up to 10,000 asset IDs per request;
|
||||
- `POST /api/assets/merge`: merge 2-100 asset IDs per request.
|
||||
|
||||
## Recommended workflow
|
||||
|
||||
1. Define an explicitly authorized set of domains, IP addresses, or network ranges.
|
||||
|
||||
@@ -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 或网段。
|
||||
|
||||
Reference in New Issue
Block a user