From 4349742b12ad9f5584b153af5870be965e6e41f4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=85=AC=E6=98=8E?=
 <83812544+Ed1s0nZ@users.noreply.github.com>
Date: Thu, 16 Jul 2026 21:37:30 +0800
Subject: [PATCH] Add files via upload

---
 README.md                      |   1 +
 README_CN.md                   |   1 +
 docs/en-US/README.md           |   2 +-
 docs/en-US/asset-management.md | 151 +++++++++++++++++++++++++++++++++
 docs/zh-CN/README.md           |   2 +-
 docs/zh-CN/asset-management.md | 151 +++++++++++++++++++++++++++++++++
 6 files changed, 306 insertions(+), 2 deletions(-)
 create mode 100644 docs/en-US/asset-management.md
 create mode 100644 docs/zh-CN/asset-management.md

diff --git a/README.md b/README.md
index c0f1a03a..d3a4b185 100644
--- a/README.md
+++ b/README.md
@@ -133,6 +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).
 - 🛡️ **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.
diff --git a/README_CN.md b/README_CN.md
index 09ed51f1..c1bcb333 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -132,6 +132,7 @@ CyberStrikeAI 将规划、执行、人工监督、证据与复盘连接在同一
 
 - 📁 **对话管理**：支持分组、置顶、重命名和批量管理。
 - 📂 **项目与攻击链**：关联跨会话事实、风险评分、图谱视图和步骤回放。
+- 🗂️ **资产管理**：统一归档和去重域名、IP、端口与服务，跟踪扫描覆盖、关联漏洞和风险状态。详见[资产管理指南](docs/zh-CN/asset-management.md)。
 - 🛡️ **漏洞管理**：支持严重程度分级、状态流转、过滤和统计看板。
 - 📋 **批量任务**：支持任务队列、编辑、状态跟踪和结果留存。
 - 📱 **机器人接入**：支持个人微信、企业微信、钉钉、飞书、Telegram、Slack、Discord 和 QQ。
diff --git a/docs/en-US/README.md b/docs/en-US/README.md
index 8ffdb73c..2f53b7d1 100644
--- a/docs/en-US/README.md
+++ b/docs/en-US/README.md
@@ -17,7 +17,7 @@
 
 ## Feature guides
 
-- [Knowledge Base](knowledge-base.md) · [Robot / Chatbot](robot.md) · [Vision](VISION.md)
+- [Asset Management](asset-management.md) · [Knowledge Base](knowledge-base.md) · [Robot / Chatbot](robot.md) · [Vision](VISION.md)
 - [WebShell](webshell.md) · [C2](c2.md) · [MCP Federation](mcp-federation.md)
 
 ## Operations and reference
diff --git a/docs/en-US/asset-management.md b/docs/en-US/asset-management.md
new file mode 100644
index 00000000..9f15dacd
--- /dev/null
+++ b/docs/en-US/asset-management.md
@@ -0,0 +1,151 @@
+# Asset Management
+
+[中文](../zh-CN/asset-management.md)
+
+Asset management consolidates domains, IP addresses, ports, and services discovered through manual entry, FOFA, HTTP APIs, and Agent tasks into a maintainable baseline. It answers three questions: what assets exist, which assets have been assessed, and where risk is concentrated.
+
+> This feature is designed for security testing and attack-surface governance. It is not a replacement for a full enterprise CMDB. Add and scan only systems you own or are explicitly authorized to test.
+
+## Overview
+
+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.
+- **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.
+
+## Asset fields
+
+An asset can include:
+
+- host, IP address, domain, port, and protocol;
+- page title and service or product fingerprint;
+- country/region, state/province, and city;
+- source, source query, and tags;
+- active or inactive status;
+- project and owner;
+- first seen, last seen, created, and updated timestamps;
+- latest scan time and linked conversation, task queue, and subtask;
+- related vulnerability count and current risk level.
+
+At least one of `host`, `ip`, or `domain` is required.
+
+## Build an asset baseline
+
+### Add an asset manually
+
+Go to **Asset Management → Asset Inventory** and select **Add Asset**. Supported target forms include:
+
+```text
+https://example.com:8443
+example.com
+192.0.2.10:443
+[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.
+
+### 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.
+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**.
+5. Review the created, updated, and skipped counts.
+
+Internet search results are not automatically your assets. Narrow the query with organization domains, certificates, network ranges, or product fingerprints, then verify authorization before saving results.
+
+## Normalization and deduplication
+
+Different sources may describe the same target in different forms. The system:
+
+- trims surrounding whitespace;
+- normalizes IP addresses, domains, and protocols to lowercase;
+- extracts hostname, protocol, and port from URL-like hosts;
+- fills default HTTP/HTTPS ports when omitted;
+- converts internationalized domains to ASCII/Punycode;
+- removes empty or duplicate tags;
+- supplies default source and status values.
+
+Assets use “target + port + protocol” as the service-level deduplication key. The preferred target is the domain, followed by the IP address, then the host. As a result, `80/http` and `443/https` on the same host remain separate assets.
+
+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
+
+The Web UI searches hosts, IP addresses, domains, titles, services, and tags, with status and project filters. The backend and Agent tools additionally support:
+
+- 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.
+
+Sorting by latest scan time in ascending order places never-scanned assets first, making coverage gaps visible.
+
+## Scanning and risk updates
+
+### Scan one asset
+
+Select **Scan** from the asset inventory. The system:
+
+1. creates a conversation containing the target and asset ID;
+2. links the conversation to the asset;
+3. prompts the Agent to inspect exposed services and authorized risks;
+4. stores confirmed findings with `record_vulnerability`;
+5. updates scan state with `complete_asset_scan`.
+
+Scan prompts support `{{asset_id}}`, `{{target}}`, `{{host}}`, `{{ip}}`, `{{domain}}`, and `{{port}}`. Adjust scope, ports, test intensity, and validation methods to match the authorization before starting.
+
+### Batch scans
+
+Select multiple assets and choose **Create Scan Task**. The system creates one subtask per asset and links each asset to its queue and subtask.
+
+The current defaults use manual scheduling, one concurrent task, and Eino single-Agent mode to limit load on targets and the local host. You must still confirm the test window, request rate, permitted validation methods, and approval requirements.
+
+### Risk calculation
+
+Asset risk is calculated dynamically from open vulnerabilities in the latest linked scan:
+
+- `critical`, `high`, `medium`, `low`, or `info`: an open finding at that level exists;
+- `normal`: the asset was scanned and has no open risk;
+- `unassessed`: no scan has completed.
+
+Resolved, false-positive, and ignored findings remain in historical counts but no longer increase the current risk level.
+
+## Agent tools
+
+Six built-in tools expose asset operations to Agents:
+
+- `create_asset`: create or deduplicate and update an asset;
+- `get_asset`: retrieve full details by ID;
+- `query_assets`: filter, sort, and paginate assets;
+- `update_asset`: partially update an asset;
+- `delete_asset`: delete an asset;
+- `complete_asset_scan`: record scan completion.
+
+`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.
+
+## Access control
+
+Asset permissions are separated into:
+
+- `asset:read`: view assets and statistics;
+- `asset:write`: create, import, edit, and update scan state;
+- `asset:delete`: delete assets.
+
+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.
+
+## Recommended workflow
+
+1. Define an explicitly authorized set of domains, IP addresses, or network ranges.
+2. Add a few critical targets manually and verify normalization and deduplication.
+3. Use tags to separate production, testing, critical-business, and internet-facing scopes.
+4. Configure FOFA, begin with narrow queries, and verify ownership.
+5. Test scanning and vulnerability callbacks on one low-risk target.
+6. Use never-scanned and over-30-day filters to identify coverage gaps.
+7. After validating the workflow, expand gradually with small batch tasks.
+
+A small, verified baseline is usually more valuable than a large inventory with unclear ownership and inconsistent sources.
diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md
index 0a1901cb..2b2b4dec 100644
--- a/docs/zh-CN/README.md
+++ b/docs/zh-CN/README.md
@@ -17,7 +17,7 @@
 
 ## 功能指南
 
-- [知识库](knowledge-base.md) · [机器人接入](robot.md) · [视觉分析](VISION.md)
+- [资产管理](asset-management.md) · [知识库](knowledge-base.md) · [机器人接入](robot.md) · [视觉分析](VISION.md)
 - [WebShell](webshell.md) · [C2](c2.md) · [MCP 联邦](mcp-federation.md)
 
 ## 运维与参考
diff --git a/docs/zh-CN/asset-management.md b/docs/zh-CN/asset-management.md
new file mode 100644
index 00000000..f7693c8e
--- /dev/null
+++ b/docs/zh-CN/asset-management.md
@@ -0,0 +1,151 @@
+# 资产管理
+
+[English](../en-US/asset-management.md)
+
+资产管理用于将手工录入、FOFA、HTTP API 和 Agent 任务中发现的域名、IP、端口与服务统一归档，形成可持续维护的资产基线。它关注三个问题：当前拥有哪些资产、哪些资产已经检查、风险集中在哪里。
+
+> 资产管理面向安全测试和攻击面治理，不替代完整的企业 CMDB。仅可录入和扫描自有系统或已获得明确授权的目标。
+
+## 功能概览
+
+资产管理包含三个主要入口：
+
+- **资产概览**：统计资产总量、IP、域名、端口、近期变化、扫描覆盖率和协议分布。
+- **资产库**：维护资产身份、服务信息、来源、标签、项目归属、扫描记录和风险状态。
+- **信息收集**：查询 FOFA，并将确认归属的结果单条或批量写入资产库。
+
+资产可以进一步发起单目标分析或批量扫描。Agent 保存漏洞并完成扫描回写后，资产列表会同步展示相关漏洞数量、风险等级和最近扫描时间。
+
+## 资产字段
+
+每条资产可记录：
+
+- Host、IP、域名、端口和协议；
+- 页面标题、服务或产品指纹；
+- 国家/地区、省份/州和城市；
+- 来源、来源查询条件和标签；
+- 活跃或停用状态；
+- 所属项目和所有者；
+- 首次发现、最近发现、创建和更新时间；
+- 最近扫描时间及关联的对话、任务队列和子任务；
+- 相关漏洞数量和当前风险等级。
+
+至少需要提供 `host`、`ip` 或 `domain` 中的一项。
+
+## 建立资产基线
+
+### 手工新增
+
+进入 **资产管理 → 资产库**，点击 **新增资产**。常见目标格式包括：
+
+```text
+https://example.com:8443
+example.com
+192.0.2.10:443
+[2001:db8::1]:443
+```
+
+系统会尽量识别 URL、域名、IP、端口和协议。保存前可继续补充项目、标签、标题、服务指纹、地理位置和状态。
+
+### 从 FOFA 导入
+
+1. 在配置文件或系统设置中填写 FOFA 邮箱和 API Key，也可使用 `FOFA_EMAIL`、`FOFA_API_KEY` 环境变量。
+2. 进入 **资产管理 → 信息收集**。
+3. 输入或生成 FOFA 查询语句，并确认查询范围。
+4. 执行查询，选择确认归属的结果后点击 **入库所选**。
+5. 根据返回的新增、更新和跳过数量检查导入结果。
+
+外部搜索结果不等同于自有资产。建议先通过组织域名、证书、网段或产品指纹缩小范围，确认授权后再入库。
+
+## 规范化与去重
+
+不同入口可能使用不同形式描述同一目标。系统会执行以下处理：
+
+- 去除字段首尾空白；
+- IP、域名和协议转为小写；
+- 从 URL 型 Host 提取 hostname、协议和端口；
+- 为未显式指定端口的 HTTP/HTTPS 补充默认端口；
+- 将国际化域名转换为 ASCII/Punycode；
+- 清理并去重标签；
+- 为缺失的状态和来源补充默认值。
+
+资产以“目标 + 端口 + 协议”作为服务级去重依据。目标优先采用域名，其次为 IP，最后为 Host。因此，同一主机的 `80/http` 和 `443/https` 会被视为不同资产。
+
+重复资产再次入库时，系统会更新本次提供的非空字段和最近发现时间，保留未提供的原有信息，不会重置首次发现时间。
+
+## 查询与筛选
+
+Web 端支持搜索 Host、IP、域名、标题、服务和标签，并按状态或项目筛选。后端和 Agent 工具还支持：
+
+- 来源、标签、端口和协议；
+- 已扫描、从未扫描等扫描状态；
+- 首次发现、最近发现和最近扫描时间范围；
+- 按最近扫描时间等白名单字段排序；
+- 分页查询。
+
+按最近扫描时间升序排列时，从未扫描的资产优先显示，便于识别覆盖盲区。
+
+## 扫描与风险回写
+
+### 单资产扫描
+
+在资产列表中点击 **扫描**。系统会：
+
+1. 创建新对话并注入资产目标和资产 ID；
+2. 将对话与资产关联；
+3. 引导 Agent 检查暴露服务和授权范围内的安全风险；
+4. 使用 `record_vulnerability` 保存确认的问题；
+5. 使用 `complete_asset_scan` 回写扫描状态。
+
+扫描提示词支持 `{{asset_id}}`、`{{target}}`、`{{host}}`、`{{ip}}`、`{{domain}}` 和 `{{port}}` 变量。发起前应按授权范围调整测试强度、端口和验证方式。
+
+### 批量扫描
+
+在资产库中选择多个目标后，点击 **创建扫描任务**。系统会为每个资产创建独立子任务，并建立资产、队列和子任务之间的关联。
+
+当前默认使用手动调度、单并发和 Eino 单 Agent 模式，以减少对目标和本机资源的瞬时压力。执行前仍需确认测试窗口、请求频率、允许的验证方式和审批要求。
+
+### 风险计算
+
+资产风险根据最近一次关联扫描中的未关闭漏洞动态计算：
+
+- `critical`、`high`、`medium`、`low`、`info`：存在对应等级的未关闭漏洞；
+- `normal`：已扫描且没有开放风险；
+- `unassessed`：尚未完成扫描。
+
+已修复、误报或忽略的漏洞仍保留在历史数量中，但不会继续提高当前风险等级。
+
+## Agent 工具
+
+系统向 Agent 提供六个内置资产工具：
+
+- `create_asset`：新增资产或去重更新；
+- `get_asset`：按 ID 获取完整详情；
+- `query_assets`：分页、筛选和排序；
+- `update_asset`：局部更新；
+- `delete_asset`：删除资产；
+- `complete_asset_scan`：扫描完成后回写状态。
+
+`query_assets` 默认每页返回 20 条、最多 50 条摘要。需要完整信息时使用 `get_asset`，避免大量资产数据占用模型上下文。
+
+## 权限控制
+
+资产权限分为：
+
+- `asset:read`：查看资产和统计数据；
+- `asset:write`：创建、导入、修改和回写扫描；
+- `asset:delete`：删除资产。
+
+服务端会同时检查资产所有者、显式资源授权、所属项目及权限 Scope（`all`、`assigned`、`own`）。当对话绑定项目后，Agent 的资产查询会被限制在该项目内，工具参数不能扩大访问范围。
+
+## 推荐使用流程
+
+1. 划定一组明确授权的域名、IP 或网段。
+2. 手工加入少量核心目标，验证识别和去重结果。
+3. 使用标签区分生产、测试、核心业务和外网范围。
+4. 配置 FOFA，从窄查询开始并确认资产归属。
+5. 对单个低风险目标测试扫描和漏洞回写流程。
+6. 使用“从未扫描”和“超过 30 天未扫描”筛选覆盖盲区。
+7. 确认流程稳定后，再逐步创建小规模批量任务。
+
+经过确认的小规模资产基线通常比来源混乱的全量清单更有价值。