第十二节 安全分析工具
[!ref] 详解见用户手册「安全分析工具」节。
12.1 适用约束
- 全部工具仅在当前工作区下名为
samples/的子目录中可用。 - 该子目录下
exec类工具被强制禁用，且不可解除。 - 分析工具不修改样本本体；
samples/目录本身可写入（样本投放、sec.pcap_stream_extract的提取产物都会落盘）。
12.1.1 样本投放入口
| 入口 | 行为 |
|---|---|
| 输入框左下角「+」按钮 | 系统多文件对话框 → 落到 <workspace>/samples/ |
| 用户取消选择 | 静默忽略，不报错 |
| 重名 | 自动附加时间戳后缀，不覆盖 |
| 无活动工作区 | 按钮置灰；点击提示「没有活动工作区」 |
后端透明支持本地与远程工作区。
12.2 工具一览（共 16 个）
| 工具 | 用途 |
|---|---|
sec.hash |
多算法哈希（md5 / sha1 / sha256 / sha512 等） |
sec.entropy |
Shannon 熵（总 + 分块） |
sec.hexdump |
xxd 风格十六进制 + ASCII 视图 |
sec.strings |
提取 ASCII + UTF-16LE 字符串 |
sec.ioc_extract |
提取 IOC（IP / URL / 域名 / 邮箱 / 哈希含 SHA-512 / BTC·ETH·XMR / CVE / MAC / 注册表 / 路径）；先还原 defang，分页返回（见 §12.6） |
sec.pe_parse |
PE / PE+ 结构（节、导入、导出、入口、子系统） |
sec.elf_parse |
ELF 结构（节、动态依赖、符号、build-id） |
sec.macho_parse |
Mach-O 结构（含 FAT / universal） |
sec.imphash |
Mandiant-style PE 导入哈希 |
sec.disasm |
线性反汇编（架构自动嗅探） |
sec.decompile |
LLM 辅助反编译为 C / Java 伪代码 |
sec.pcap_info |
pcap 元信息 + Top-N 流聚合 |
sec.pcap_stream_list |
列出 pcap 中所有 TCP/UDP/ICMP 流并赋稳定 id |
sec.pcap_stream_extract |
把指定流的 L7 载荷 dump 到工作区路径 |
sec.pcap_extract |
DNS / HTTP / TLS ClientHello SNI 字段抽取 |
sec.yara_scan |
YARA 规则扫描（默认 build 为 stub） |
12.3 sec.hash
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
path |
string | — | 必填 |
algorithms |
array | [md5, sha1, sha256] |
可选：md5, sha1, sha256, sha384, sha512, sm3 |
12.4 sec.entropy
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
path |
string | — | 必填 |
block_size |
int | 4096 | 0 表示不分块 |
12.5 sec.strings
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
path |
string | — | 必填 |
min_len |
int | 6 | 最小长度 |
encodings |
array | [ascii, utf16le] |
|
limit |
int | 软 4096 / 硬 256 KiB |
12.6 sec.ioc_extract
先自动还原 defang（hxxp://、1.2.3[.]4、evil[.]com、foo(dot)bar）再在可打印字符串上匹配（减二进制噪声）。IP 走 net.ParseIP 校验并打标（private/loopback/link_local/multicast/cgnat/unspecified），MAC 不再误判为 IPv6，域名按公共后缀校验（丢弃 kernel32.dll 之类）。按值去重、附 count 与 tags（含 defanged）。分页同 sec.strings（limit 与 byte_limit 取更紧者；truncated=true 时读 next_offset / per_kind_capped / hint 续取）。
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
path |
string | — | 必填 |
kinds |
array | 全部 | 见下表；空 = 全部 |
max_per_kind |
int | 200（上限 5000） | 每类唯一命中上限；打满的类列入 per_kind_capped |
max_bytes |
int | 128 MiB | 扫描字节上限 |
offset |
int | 0 | 全集 0-based 续读起点（填上次 next_offset） |
limit |
int | 500（上限 5000） | 单次返回条数上限 |
byte_limit |
int | 4096（硬上限 262144） | 单次返回字节上限，整条粒度 |
defang_output |
bool | false | 以 defang 形式渲染值（evil[.]com / hxxp://…）便于安全展示 |
exclude_private |
bool | false | 丢弃非公网 IP（默认保留并打标） |
context |
bool | false | 每条附一小段命中上下文 |
可选 kinds：
| 类别 | 含义 |
|---|---|
ipv4 / ipv6 |
IP 地址（带分类标签） |
url / domain / email |
链接 / 域名（公共后缀校验）/ 邮箱 |
md5 / sha1 / sha256 / sha512 |
哈希 |
btc / eth / xmr |
比特币 / 以太坊 / 门罗币等加密货币地址 |
cve |
CVE 编号 |
mac |
MAC 地址 |
registry |
Windows 注册表路径 |
path_win / path_unix |
路径式字符串 |
提取是候选指标、非判黑结论，用前请二次核实。
12.7 sec.pe_parse / sec.elf_parse / sec.macho_parse
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
path |
string | — | 必填 |
sections |
bool | true | 节列表 |
imports |
bool | true | 导入表（PE）/ 动态依赖（ELF） |
exports |
bool | true | 导出表 |
signatures |
bool | false | 签名 / 证书链 |
12.8 sec.disasm
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
path |
string | — | 必填 |
arch |
enum | auto |
auto / x86 / x86_64 / arm / arm64 / ppc64 |
start |
int / hex | 文件入口 | 起始虚拟地址 / 偏移 |
length |
int | 4096 | 反汇编字节长度 |
12.9 sec.decompile
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
path |
string | — | 必填 |
target |
enum | c |
c / java |
function |
string | 入口 | 函数名或起始地址 |
隐私提示：
sec.decompile会把反汇编片段送往反编译模型；只在样本可外送的前提下使用。
12.10 sec.pcap_info / sec.pcap_stream_list / sec.pcap_stream_extract / sec.pcap_extract
| 工具 | 参数 | 说明 |
|---|---|---|
sec.pcap_info |
path |
总包数 / 起止时间 / 协议占比 / TopN 流 |
sec.pcap_stream_list |
path, limit（默认 200，最多 2000）, offset, sort_by（first_ts（默认） / packets / bytes） |
分页列出全部 TCP/UDP/ICMP 流；id 始终是全局时间序编号，跨页跨排序都不变，可直接传给 sec.pcap_stream_extract |
sec.pcap_stream_extract |
path, stream_id, out_path（相对工作区根，可写到 samples/ 之外） |
dump 该流 L7 载荷为文件 |
sec.pcap_extract |
path, protocol(dns/http/tls_sni), limit |
协议感知字段抽取，返回 IOC（IP 等） |
v1 仅做单包检视，不做 TCP 重组。
12.11 sec.yara_scan
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
path |
string | — | 必填 |
rules |
string | 内置规则集 | 规则文件相对路径或内置集合名 |
timeout_ms |
int | 60_000 | 超时即终止 |
12.12 sec.ontology.* — 安全领域事实层（v1 本地工作区）
| 工具 | 参数 | 说明 |
|---|---|---|
sec.ontology.record |
facts: [{s, p, o, source?}] |
写入 SPO 三元组；单值谓词（version / license / severity / auth）取代写入，多值谓词（depends_on / has_cve / exposes / listens / affects）累加写入 |
sec.ontology.query |
s?, p?, o?（空字段 = 通配） |
按模式查询；如 {p:"has_cve"} 列所有 CVE，{s:"pkg:lodash"} 列关于 lodash 的全部 |
sec.ontology.reachable |
start, predicate |
沿可传递谓词从 start 多跳遍历，得可达实体集；用于传递依赖 / 攻击面爆炸半径 |
实体命名约定：建议带类型前缀（pkg:lodash / svc:api / cve:CVE-2021-23337），便于跨类查询。SSOT 持久化：事实落到工作区，对话折叠不影响。
12.13 软件物料清单（SBOM）工具 — 供应链漏洞排查
sbom.* 是工作区工具（作用于项目的依赖清单，不限于 samples/），共 5 个。结果文件默认落到工作区 .avlcode/ 目录。配套设置见 §6.16。
| 工具 | 用途 |
|---|---|
sbom.generate |
扫描依赖清单生成 SBOM（默认 CycloneDX 1.5 JSON） |
sbom.convert |
在 CycloneDX / SPDX / DSDX / SWID 之间任意互转 |
sbom.audit |
对照 OSV 排查已知漏洞，标注 CVE / KEV / CVSS 严重度 |
sbom.vex |
符号级可达性收敛漏洞，输出 OpenVEX |
sbom.dbsync |
维护本地离线 OSV 漏洞库（air-gap） |
12.13.1 sbom.generate
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
path |
string | 工作区根 | 扫描根（相对工作区） |
format |
string | cyclonedx |
cyclonedx / spdx / dsdx / swid；加 -xml 出 XML（如 cyclonedx-xml），dsdx-tag 出 DSDX 原生 tag-value |
output |
string | .avlcode/sbom.<format>.<ext> |
输出路径（相对扫描根） |
- 识别生态（
Ecosystem常量）：go · npm（含 yarn Berry / pnpm v5）· cargo · pypi · maven · gem · composer · nuget · swift · pub · conan · conda · hex · cocoapods · cran · hackage · julia；另支持 Deno 清单。 - 清单扫描递归子目录，缺锁回退清单文件解析；npm/pypi/conan 多锁首个命中为准，maven 三种全读；剔除首方误报、正确处理 Go
replace/exclude、版本比对保真。 - 缺清单跳过该生态，全缺得 0 组件空清单（非错误）；输出确定性可复现（无时间戳 / 随机序列号、组件定序）。
- 审计逐生态回退，Maven/Gradle/pip/Conda/Conan/npm 附精度提示，未审生态明示，附可利用性描述。
- 返回字段：
format/encoding/component_count/ecosystems/bom_path/components（预览，最多 50）/truncated。
12.13.2 sbom.convert
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
input |
string | — | 必填，待转 SBOM 文件（相对工作区） |
to |
string | — | 必填，目标格式（同 format 取值语法） |
from |
string | 自动嗅探 | 源格式覆盖 |
output |
string | <input>.<to>.json |
输出路径 |
经规范化中间模型转换（N 读 + N 写）；保留组件 / purl / 许可 / 哈希 / 依赖关系，目标不支持的字段按规则丢弃（DSDX 无哈希、SWID 哈希不映射）。格式与编码矩阵：CycloneDX(1.5) JSON+XML、SPDX(2.3) JSON+RDF/XML、DSDX JSON+XML+native、SWID JSON+XML，均可读可写。
12.13.3 sbom.audit
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
path |
string | 工作区根 | 扫描根 |
mode |
enum | auto |
auto（本地有库则离线、否则在线）/ online(api.osv.dev) / offline（本地快照） |
output |
string | .avlcode/sbom.audit.json |
报告路径 |
对照 OSV 匹配；CVE 取首个 CVE-… 别名；KEV 取自 <config>/kev.json。严重度按 CVSS 向量计算：v2(AV:/AC:/Au:) / v3(CVSS:3) / v4(CVSS:4.0，官方 MacroVector 查表)；定级 critical ≥9 / high ≥7 / medium ≥4 / low >0；记录自带 GHSA 定性等级时以其为准。结果最严重优先、KEV 置顶。返回字段：source / components_scanned / vulnerable / total_vulns / by_severity / kev_count / report_path / findings（预览，最多 30）/ truncated。
12.13.4 sbom.vex
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
path |
string | 工作区根 | 扫描根 |
mode |
enum | auto |
同 audit 来源 |
output |
string | .avlcode/sbom.vex.json |
OpenVEX 输出 |
lsp_confirm |
bool | false | 用语言服务器确认每包至少一处真实引用（需装对应 server，会拉起进程）；默认纯离线导入扫描，air-gap 友好 |
detail |
bool | false | 附 findings_detail（供 App 端 LLM 收敛用） |
先跑 audit，再做确定性符号级可达性分析。状态：affected / not_affected / under_investigation / fixed；not_affected 带机读理由（vulnerable_code_not_present / vulnerable_code_not_in_execute_path / component_not_present / inline_mitigations_already_exist）。可达性扫描上限：≤4000 文件、≤256 KiB/文件，跳过 .git/node_modules/vendor/target/dist/build 等目录。Go 凭 OSV 受影响符号可直接收敛 not_affected；其它生态默认「用到即 affected、没用到即 under_investigation」（不擅自判 not_affected），可经 lsp_confirm 或 App 端符号比对进一步收敛。结论按 affected > under_investigation > fixed > not_affected 排序。
12.13.5 sbom.dbsync
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
action |
enum | status |
status（纯本地，看记录数 / 新鲜度）/ sync（联网拉 OSV dump）/ import（离线导入）/ kev（刷新 KEV） |
ecosystems |
string[] | 自动检测 | sync 指定生态；空则按工作区清单自动检测 |
path |
string | 工作区根 | sync 自动检测的扫描根 |
zip_path |
string | — | import 必填：本地 OSV 生态 zip（相对工作区） |
osv_eco |
string | — | import 必填：该 zip 对应的 OSV 生态名（如 npm / PyPI / Go） |
13 个生态有 OSV 离线 dump 覆盖（SyncableEcosystems）；conan / conda / CocoaPods 暂无离线库（可在线审计）。import 缺 zip_path 或 osv_eco 报错。
12.14 云端威胁情报工具（VirusTotal / GTI）
两组工具、独立门控，均在 设置 → 安全 配置（见 §6.17）。
哨兵哈希扫描 sec.vtai_*（绑定「自动扫描拦截·哨兵」配置，用 vtGuard）：
| 工具 | 参数 | 说明 |
|---|---|---|
sec.vtai_check_hash |
hash（必填，MD5/SHA1/SHA256） |
哈希查情报、不上传；返回 verdict/malicious/total/label/source/link；未配后端报错 |
sec.vtai_scan |
path（必填）, force（bool） |
上传高危文件全量扫描；RegisterUploadRequired——仅开「上传扫描」或本地 YARA 时对 LLM 可见，否则退化为哈希查询 |
sec.vtai_register |
display_name? / human_alias? / bio? / contact_email? |
触发 VirusTotal AI 注册；实际在设置面板同意流程完成（RegisterVTAI） |
sec.vtai_status |
— | 返回 enabled/monitor/auto_scan/mode/source/public_handle/cache_size 等 |
全量情报 vt.*（full_tools 策略门控，与哨兵并存）：
| 工具 | 关键参数 | 门控 |
|---|---|---|
vt.lookup |
indicators[] / indicator, type?(file/url/domain/ip), relationship? |
免费只读（仅主开关） |
vt.api |
resource? / id? / relationship? / action? / path? / method(默认 GET) / query{} / body{} / raw? |
读默认可用；写受 query_only、Premium/GTI 端点受 enable_paid_features |
vt.submit |
url? / file? / rescan? / wait? / confirm? |
写；query_only 拦；file 上传 ≤ 32 MB、confirm_sample_upload 开时需 confirm=true；wait 轮询上限 180s |
vt.download |
hash（必填）, save_to（必填） |
Premium（enable_paid_features） |
vt.feeds |
type, time（YYYYMMDDhhmm/hh,UTC）, save_to（均必填） |
Premium；T-60 分钟延迟 |
vt.hunt |
op(retrohunt_*/notifications/rulesets), id? / rules? / corpus? / limit? / cursor? |
Premium；异步 |
full_tools 策略：
- 字段：
enabled/query_only（默认开）/enable_paid_features（默认关）/confirm_sample_upload（默认开）/api_base。 Check()顺序：未启用 →ErrDisabled；写 + 仅查询 →ErrQueryOnly；非 public 档 + 未开收费 →ErrPaidDisabled；档位（public/premium/gti）由 VT 远端 403 兜底。- 启用需
KeyUsable（密文可解密且非空），否则启用环节即报错。 - 响应默认经
Summarize()紧凑摘要（namescap 8、tagscap 12），raw=true取原始；超时：api/lookup/hunt/submit 30s，download/feeds 5 分钟。