第十二節 安全分析工具
[!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 分鐘。