CyberStrikeAI 资产管理实战：从资产基线建立到 Agent 扫描风险回写的完整指南-平芜编程栈

CyberStrikeAI 资产管理实战：从资产基线建立到 Agent 扫描风险回写的完整指南

【免费下载链接】CyberStrikeAIThe system of action for AI-native cybersecurity—where intent becomes governed execution, evidence becomes operational memory, and every operation improves the next.项目地址: https://gitcode.com/GitHub_Trending/cy/CyberStrikeAI

资产是安全测试与攻击面治理的起点。CyberStrikeAI 的资产管理模块将手工录入、网络空间测绘搜索、HTTP API 与 Agent 任务中发现的域名、IP、端口和服务统一归档，形成可持续维护的资产基线，并持续回答三个核心问题：当前拥有哪些资产、哪些资产已经检查、风险集中在哪里。读完本文，你将掌握从手工建档、表格批量导入、FOFA/ZoomEye/Quake/Shodan 测绘回填，到单资产扫描、批量扫描与漏洞风险回写的全链路操作，并理解服务端规范化、去重、权限与风险计算的底层实现。

资产管理面向安全测试和攻击面治理，不替代完整的企业 CMDB。仅可录入和扫描自有系统或已获得明确授权的目标。英文版请参阅 docs/en-US/asset-management.md。

功能概览

资产管理在 Web 端包含三个主要入口：

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

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

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

资产字段

每条资产可以记录以下信息，对应服务端Asset结构的 JSON 字段（见 internal/database/asset.go）：

host、ip、domain、port和protocol：目标身份字段；
title、server：页面标题、服务或产品指纹；
country、province、city：地理归属信息；
responsible_person、department、business_system、environment、criticality：责任与业务属性；
source、source_query、tags：来源、来源查询条件和标签；
status：活跃（active）或停用（inactive）状态；
project_id、owner_user_id：所属项目和所有者；
first_seen_at、last_seen_at、created_at、updated_at：首次发现、最近发现、创建和更新时间；
last_scan_at、last_scan_conversation_id、last_scan_queue_id、last_scan_task_id：最近扫描时间及关联的对话、任务队列和子任务；
vulnerability_count、risk_level、risk_score：相关漏洞数量和当前风险等级。

至少需要提供host、ip或domain中的一项，否则服务端会拒绝写入（校验逻辑位于 validateAsset）。

建立资产基线

手工新增

进入资产管理 → 资产库，点击新增资产。系统会尽量识别 URL、域名、IP、端口和协议，常见目标格式包括：

https://example.com:8443 example.com 192.0.2.10:443 [2001:db8::1]:443

保存前可继续补充项目、标签、标题、服务指纹、地理位置、负责人、部门、业务系统、环境、重要性和状态。

从表格批量导入

进入资产管理 → 资产库，点击批量导入：

下载 XLSX（推荐）或 CSV 模板。
在Assets工作表中填写资产；不要修改表头。
上传文件，或将文件拖入上传区域。
查看逐行校验结果。文件内重复、格式错误和无权访问的项目会标为错误。
点击导入有效数据。错误行不会提交，预览超过 100 行时只展示前 100 行，但提交会处理全部有效行。
根据提示核对新增、更新和跳过数量。

模板字段如下：

字段	必填	说明
`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。
POST /api/assets/import单次请求最多 100000 条资产，服务端在 Import 中校验数量并拒绝超限请求。
文件内相同“目标 + 端口 + 协议”的后续行会标记为重复，不会提交。
Web 端负责文件解析、预览和即时格式提示；服务端仍会执行权限检查、字段校验、规范化、去重和事务写入。
已存在的资产会合并本次提供的非空字段并更新最近发现时间；不会创建重复记录。
批量导入需要asset:write权限。填写项目时，当前用户还必须有权访问该项目。
不建议取消服务端条数上限。更大规模的数据应拆分文件并在低峰期导入。

从网络空间测绘搜索导入

在配置文件或系统设置 → 资产管理中填写对应 API Key，也可使用环境变量：FOFA_API_KEY、ZOOMEYE_API_KEY、QUAKE_API_KEY、SHODAN_API_KEY（服务端按 Provider 解析对应环境变量，见 internal/handler/fofa.go）。
进入资产管理 → 信息收集。
选择数据源：FOFA、ZoomEye、Quake 或 Shodan。
输入或生成该数据源的查询语句，并确认查询范围。
执行查询，选择确认归属的结果后点击入库所选。
根据返回的新增、更新和跳过数量检查导入结果。

外部搜索结果不等同于自有资产。建议先通过组织域名、证书、网段或产品指纹缩小范围，确认授权后再入库。从源码看，测绘数据源还支持按 Provider 选择默认查询字段（defaultFieldsForProvider），不同搜索引擎返回字段存在差异，入库前系统会对测绘来源的数据做更宽松的清洗：例如 FOFA 来源的脏 IP、域名或协议字段会被置空而不是导致整批失败（见 normalizeAsset）。

规范化与去重

不同入口可能使用不同形式描述同一目标。服务端在写入前统一执行以下规范化（normalizeAsset，见 internal/database/asset.go）：

去除字段首尾空白；
IP、域名和协议转为小写；
从 URL 型 Host 提取 hostname、协议和端口（使用标准库net/url解析）；
为未显式指定端口的 HTTP/HTTPS 补充默认端口（80/443）；
将国际化域名通过 IDNA 转换为 ASCII/Punycode；
清理并去重标签；
为缺失的状态补充active、为缺失的来源补充manual。

资产以“目标 + 端口 + 协议”作为服务级去重依据（assetDedupKey，见 internal/database/asset.go）。目标优先采用域名，其次为 IP，最后为 Host。因此，同一主机的80/http和443/https会被视为不同资产。

写入通过UpsertAssets在单事务内完成（见 internal/database/asset.go）：按去重键查询已存在记录，不存在则插入并登记资源授权；存在则用CASE WHEN ?<>'' THEN ? ELSE ...逐字段合并，即重复资产再次入库时只更新本次提供的非空字段和最近发现时间，保留未提供的原有信息，不会重置首次发现时间。整个批量操作在同一事务中提交，任一资产校验失败都会回滚并报告具体行号错误。

查询、筛选与视图

Web 端的关键字搜索覆盖 Host、IP、域名、标题、服务、标签、负责人、部门和业务系统（SQL 层面使用带转义的LIKE模糊匹配，见 assetWhere）。常用筛选包括状态和项目；展开高级筛选后还可以组合：

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

按最近扫描时间升序排列时，从未扫描的资产优先显示，便于识别覆盖盲区——sort_by=last_scan_at, sort_order=asc是定位扫描盲区最常用的组合。

常用筛选组合可以保存为筛选视图。筛选视图保存在当前浏览器的localStorage中，不会同步到服务端、其他浏览器或其他用户。

HTTP API 和query_assets还支持max_vulnerabilities、最近扫描时间范围，以及创建/更新时间等白名单排序字段。白名单外的排序字段会被服务端拒绝（见 assetFilterFromToolArgs 中的sort_by枚举校验）。HTTP 列表每页最多 100 条，Agent 查询每页最多 50 条。

批量维护与导出

选择资产后，可以对当前页执行操作，也可以选择当前筛选条件命中的全部结果。跨页选择由服务端重新解析当前筛选条件（GET /api/assets/selection），最多返回 10000 条；超过上限时需要进一步缩小范围。

可用操作：

绑定项目：为所选资产统一替换项目归属；
批量编辑：修改状态、负责人、部门、业务系统、环境和重要性，并增删标签；
创建扫描任务 / 发送到对话：复用同一提示词模板处理所选资产；
导出 CSV / XLSX：在浏览器中导出当前已选择的资产，包含责任属性、风险、漏洞数量和时间字段；
合并重复资产：保留第一个所选资产为主资产，以其他记录的非空字段补齐主资产并合并标签；
批量删除：永久删除所选资产。

批量编辑、项目绑定和批量删除采用全有或全无的事务：只要其中一个资产不存在或超出调用者权限，整批操作就会失败，不会留下部分更新。

合并仅适用于具有共同域名、IP 或 Host 的记录，每次可选择 2-100 条。主资产已有值优先，标签取并集且仍受 30 个标签限制，其余记录会被删除。该操作同时需要asset:write和asset:delete；合并前应确认主资产选择以及需要保留的扫描历史。

扫描与风险回写

单资产扫描

在资产列表中点击扫描。系统会：

创建新对话并注入资产目标和资产 ID；
将对话与资产关联；
引导 Agent 检查暴露服务和授权范围内的安全风险；
使用record_vulnerability保存确认的问题；
使用complete_asset_scan回写扫描状态。

扫描提示词支持{{asset_id}}、{{target}}、{{host}}、{{ip}}、{{domain}}和{{port}}变量。发起前应按授权范围调整测试强度、端口和验证方式。

批量扫描

在资产库中选择多个目标后，点击创建扫描任务。系统会为每个资产创建独立子任务，并建立资产、队列和子任务之间的关联。

当前默认使用手动调度、单并发和 Eino 单 Agent 模式，以减少对目标和本机资源的瞬时压力。执行前仍需确认测试窗口、请求频率、允许的验证方式和审批要求。

风险计算

资产风险根据最近一次关联扫描中的未关闭漏洞动态计算：

critical、high、medium、low、info：存在对应等级的未关闭漏洞；
normal：已扫描且没有开放风险；
unassessed：尚未完成扫描（对应 SQL 表达式中的COALESCE(NULLIF(assets.risk_level,''),'unassessed')，见 internal/database/asset.go）。

已修复、误报或忽略的漏洞仍保留在历史数量中，但不会继续提高当前风险等级。complete_asset_scan回写时，相关漏洞数量不手填，而是自动统计当前扫描对话中通过record_vulnerability保存的漏洞（见 internal/app/asset_tools.go）。

Agent 工具

系统向 Agent 提供六个内置资产工具（注册逻辑见 internal/app/asset_tools.go）：

create_asset：新增资产或去重更新；至少提供host、ip、domain之一，返回created或updated动作；
get_asset：按 ID 获取完整详情；
query_assets：分页、筛选和排序；
update_asset：按 ID 局部更新，只修改显式传入的字段；可传空project_id清除项目绑定，可传空tags清空标签；
delete_asset：删除资产（仅在用户明确要求删除时调用）；
complete_asset_scan：扫描完成后回写状态，并把上次扫描时间更新为当前时间、关联当前对话。

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

create_asset和update_asset均支持责任与业务属性；query_assets也可以按这些字段筛选（environment、criticality、responsible_person、department、business_system等均有对应参数）。Agent 写入仍经过与 HTTP API 相同的规范化、字段校验、去重和权限检查，例如port参数在工具参数层即受0-65535约束（见 assetMutationProperties）。

权限控制

资产权限分为：

asset:read：查看资产和统计数据；
asset:write：创建、导入、修改和回写扫描；
asset:delete：删除资产。

服务端会同时检查资产所有者、显式资源授权、所属项目及权限 Scope（all、assigned、own）。SQL 层通过appendAssetAccess拼接访问约束（见 internal/database/asset.go）：命中allScope 时直接放行，否则要求满足“资产所有者、显式授权、所属项目所有者或项目授权”之一。当对话绑定项目后，Agent 的资产查询会被强制限制在该项目内，工具参数不能扩大访问范围（见 internal/app/asset_tools.go）。

资产批量接口限制：