Zeek 文件分析器（File Analyzers）权威指南：Files::Tag 枚举、内置插件与实战配置-平芜编程栈

网络安全
网络
IDS

【免费下载链接】zeek

Zeek is a powerful network analysis framework that is much different from the typical IDS you may know.

项目地址：https://gitcode.com/gh_mirrors/ze/zeek

本文以 Zeek 官方脚本参考文档 doc/reference/zeekscript/autogenerated-file-analyzer-index.rst 为主线，系统梳理 Files 框架中全部内置文件分析器（File Analyzers）的类型标签、事件与函数 API，并结合 scripts/base/files/ 下的真实脚本实现，给出可复制、可运行的 Zeek 脚本示例。读完本文，你将掌握Files::add_analyzer、register_for_mime_type等核心 API 的用法，能够为文件启用哈希、熵值、提取、PE 与 X.509/OCSP 分析，并理解各分析器底层的工作原理。

一、文件分析器与 Files::Tag 枚举总览

在 Zeek 中，文件分析器（File Analyzer）是附着在fa_file（文件句柄）上、对文件内容进行专项处理的分析单元。它与协议分析器不同：文件分析器不关心数据如何传输，只关心被还原出的完整文件本身（如通过 HTTP 下载的二进制、TLS 会话中的证书）。

Files::Tag是 Zeek 脚本层用来标识文件分析器类型的枚举类型，其全部取值如下：

Files::Tag 枚举值	对应分析器	用途
`Files::ANALYZER_DATA_EVENT`	`Zeek::FileDataEvent`	将文件内容以数据事件形式交付给脚本层
`Files::ANALYZER_ENTROPY`	`Zeek::FileEntropy`	对文件内容做熵测试（信息密度）
`Files::ANALYZER_EXTRACT`	`Zeek::FileExtract`	将文件内容提取写入磁盘
`Files::ANALYZER_MD5`	`Zeek::FileHash`	计算 MD5 摘要
`Files::ANALYZER_SHA1`	`Zeek::FileHash`	计算 SHA1 摘要
`Files::ANALYZER_SHA224`	`Zeek::FileHash`	计算 SHA224 摘要
`Files::ANALYZER_SHA256`	`Zeek::FileHash`	计算 SHA256 摘要
`Files::ANALYZER_SHA384`	`Zeek::FileHash`	计算 SHA384 摘要
`Files::ANALYZER_SHA512`	`Zeek::FileHash`	计算 SHA512 摘要
`Files::ANALYZER_PE`	`Zeek::PE`	解析 Windows PE（可移植可执行）文件
`Files::ANALYZER_ZIP`	`Zeek::ZIP`	解析 ZIP 压缩包结构
`Files::ANALYZER_OCSP_REPLY`	`Zeek::X509`	解析 OCSP 应答
`Files::ANALYZER_OCSP_REQUEST`	`Zeek::X509`	解析 OCSP 请求
`Files::ANALYZER_X509`	`Zeek::X509`	解析 X.509 证书

这些枚举值的定义与说明完整保留在 doc/reference/zeekscript/autogenerated-file-analyzer-index.rst 中，是本文后续所有内容的索引骨架。

二、分析器的挂载方式：显式添加与 MIME 自动注册

在深入各分析器之前，先掌握两种挂载文件分析器的方式。它们定义于 scripts/base/frameworks/files/main.zeek。

2.1 显式添加：Files::add_analyzer

对一个已知文件句柄f直接挂载分析器：

# 为文件 f 添加 SHA256 哈希分析器 Files::add_analyzer(f, Files::ANALYZER_SHA256); # 添加提取分析器并指定提取文件名与大小上限（单位：字节） Files::add_analyzer(f, Files::ANALYZER_EXTRACT, Files::AnalyzerArgs($extract_filename="sample.bin", $extract_limit=10485760));

Files::add_analyzer签名（见 scripts/base/frameworks/files/main.zeek）：

global add_analyzer: function(f: fa_file, tag: Files::Tag, args: AnalyzerArgs &default=AnalyzerArgs()): bool;

返回T表示分析器成功挂载；返回F表示该文件当前未处于分析状态（例如已经结束），或传入的args对该分析器类型无效。对应地，Files::remove_analyzer用于移除分析器，Files::stop则彻底停止对该文件的后续分析。

2.2 MIME 类型自动注册：register_for_mime_type

更常见的做法是让分析器按文件 MIME 类型自动挂载。核心函数为Files::register_for_mime_type(tag, mt)（批量版本是Files::register_for_mime_types），其含义是：一旦某个文件的 MIME 类型被识别为mt，就自动把tag指定的分析器挂到该文件上。MIME 类型匹配不区分大小写。

典型的真实用法来自 scripts/base/files/x509/main.zeek：

# 只要识别出 X.509 证书相关 MIME，就自动挂载 X509 与哈希分析器 Files::register_for_mime_type(Files::ANALYZER_X509, "application/x-x509-user-cert"); Files::register_for_mime_type(Files::ANALYZER_X509, "application/x-x509-ca-cert"); Files::register_for_mime_type(Files::ANALYZER_X509, "application/pkix-cert"); Files::register_for_mime_type(Files::ANALYZER_MD5, "application/x-x509-user-cert"); Files::register_for_mime_type(Files::ANALYZER_SHA1, "application/x-x509-user-cert"); Files::register_for_mime_type(Files::ANALYZER_SHA256, "application/x-x509-user-cert");

在这段代码中，前三条调用把X509分析器注册到三类证书 MIME 上；后三条调用确保对证书始终计算 MD5/SHA1/SHA256 摘要（SHA256 是证书事件缓存所必需，见下文第四节）。

三、六大内置分析器逐个解析

3.1 Zeek::FileDataEvent —— 数据交付

组件：Files::ANALYZER_DATA_EVENT

该分析器的职责是"交付文件内容"，即把还原出的文件数据以事件形式交给脚本层，供自定义逻辑（如病毒特征匹配、内容关键字检测）消费。它是内置插件Zeek::FileDataEvent的核心。

3.2 Zeek::FileEntropy —— 熵测试

组件：Files::ANALYZER_ENTROPY

事件：file_entropy(f: fa_file, ent: entropy_test_result)

file_entropy在文件分析器对文件完成一次熵测试后触发。参数含义：

f：被测文件；
ent：熵测试结果，其中ent$entropy是以"每字符比特数"表示的信息密度。

熵值用于衡量文件内容的随机/压缩程度：高熵通常意味着加密、压缩或混淆数据；低熵常见于明文文本或未压缩的简单格式。策略脚本 scripts/policy/frameworks/files/entropy-test-all-files.zeek 演示了完整用法——它向Files::Info记录追加entropy字段，并在file_new事件中对每个新文件挂载熵分析器：

redef record Files::Info += { entropy: double &log &optional; }; event file_new(f: fa_file) { Files::add_analyzer(f, Files::ANALYZER_ENTROPY); } event file_entropy(f: fa_file, ent: entropy_test_result) { f$info$entropy = ent$entropy; }

这样，files.log中每个文件都会带上一列entropy值，便于后续统计与告警。

3.3 Zeek::FileExtract —— 文件提取

组件：Files::ANALYZER_EXTRACT

文件提取是把网络流量中还原出的文件内容写入本地磁盘的过程，常用于恶意软件样本收集。相关实现位于 scripts/base/files/extract/main.zeek。

事件：file_extraction_limit(f: fa_file, args: Files::AnalyzerArgs, limit: count, len: count)

当提取分析器即将突破Files::AnalyzerArgs的extract_limit字段所允许的最大文件大小时触发，随后分析器会被自动从文件f上移除，除非脚本调用FileExtract::set_limit调高限额。参数含义：

f：被提取的文件；
args：标识某个特定提取分析器的参数，通常仅用于转交给FileExtract::set_limit；
limit：即将被突破的限额（字节）；
len：即将写入的文件块长度（字节）。

函数：FileExtract::__set_limit(file_id: string, args: any, n: count): bool

这是FileExtract::set_limit的底层实现，由脚本层包装函数调用，见 scripts/base/files/extract/main.zeek：

global set_limit: function(f: fa_file, args: Files::AnalyzerArgs, n: count): bool; function set_limit(f: fa_file, args: Files::AnalyzerArgs, n: count): bool { return __set_limit(f$id, args, n); }

关键配置选项（均可在local.zeek中redef覆盖）：

FileExtract::prefix：提取文件写入的前缀目录，默认"./extract_files/"。实际路径由build_path_compressed(prefix, extract_filename)拼接生成（见 scripts/base/files/extract/main.zeek）；
FileExtract::default_limit：默认提取大小上限，默认104857600（100 MB），0表示不限制；
FileExtract::default_limit_includes_missing：缺失字节（如因丢包或 Range 下载产生的空洞）是否计入限额，默认T。设为F时，带空洞的文件会以稀疏文件（sparse file）形式落盘，其表观大小可能超过限额。

Files::AnalyzerArgs中与提取相关的字段（scripts/base/files/extract/main.zeek）：

字段	类型	默认值	说明
`extract_filename`	`string`	自动生成	本地文件名；未指定时自动生成为`extract-<last_active>-<source>-<id>`格式
`extract_limit`	`count`	`FileExtract::default_limit`	允许的最大字节数，`0`表示不限
`extract_limit_includes_missing`	`bool`	`FileExtract::default_limit_includes_missing`	缺失字节是否计入限额

提取分析器被挂载时，on_add回调（scripts/base/files/extract/main.zeek）会自动在Files::Info中记录：

extracted：本地提取文件名（&log）；
extracted_cutoff：文件是否因达到限额被截断（&log）；
extracted_size：实际写入磁盘的字节数（&log）。

file_extraction_limit事件以&priority=10处理时会把extracted_cutoff置为T（scripts/base/files/extract/main.zeek），因此运维人员可以从files.log直接发现被截断的样本。

3.4 Zeek::FileHash —— 内容哈希

组件：Files::ANALYZER_MD5、Files::ANALYZER_SHA1、Files::ANALYZER_SHA224、Files::ANALYZER_SHA256、Files::ANALYZER_SHA384、Files::ANALYZER_SHA512

事件：file_hash(f: fa_file, kind: string, hash: string)

每当文件分析生成一次内容摘要时触发。参数含义：

f：文件；
kind：摘要算法名称字符串（如"md5"、"sha1"、"sha256"）；
hash：哈希计算结果。

基础脚本 scripts/base/files/hash/main.zeek 会把 MD5/SHA1/SHA256 摘要写回Files::Info并记录到日志：

redef record Files::Info += { md5: string &log &optional; sha1: string &log &optional; sha256: string &log &optional; }; event file_hash(f: fa_file, kind: string, hash: string) &priority=5 { switch ( kind ) { case "md5": f$info$md5 = hash; break; case "sha1": f$info$sha1 = hash; break; case "sha256": f$info$sha256 = hash; break; default: break; } }

这解释了为何默认情况下files.log中每个文件都有md5、sha1、sha256三列：六个哈希标签共用同一个Zeek::FileHash插件，而基础脚本只把最常见的三种写入日志。想要 SHA224/SHA384/SHA512 结果，可在自己的脚本中监听file_hash事件并按kind分支处理。

3.5 Zeek::PE —— Windows 可执行文件解析

组件：Files::ANALYZER_PE

PE 分析器解析 Windows Portable Executable 文件，把 DOS 头、DOS 存根、文件头、可选头、节表等结构逐层解析并触发事件。其日志记录实现位于 scripts/base/files/pe/main.zeek。

PE 文件通过 MIME 类型"application/x-dosexec"自动识别（scripts/base/files/pe/main.zeek）。pe.log的Info记录包含machine（编译目标机器）、compile_ts（编译时间）、os（所需操作系统）、subsystem、is_exe、is_64bit、uses_aslr、uses_dep、uses_code_integrity、uses_seh、has_import_table、has_export_table、has_cert_table、has_debug_data、section_names等字段（scripts/base/files/pe/main.zeek）。

PE 分析器触发的事件族（f均为文件）：

事件	参数	含义
`pe_dos_header`	`h: PE::DOSHeader`	解析出顶层 DOS 头，含文件大小、寄存器初值等信息
`pe_dos_code`	`code: string`	解析出 DOS 存根（一段在 DOS 下运行的兼容程序，通常用于提示用户无法在 DOS 模式运行）
`pe_file_header`	`h: PE::FileHeader`	解析出文件头，含目标机器、创建时间戳、节数量及指向文件其他部分的指针
`pe_optional_header`	`h: PE::OptionalHeader`	解析出可选头（可执行文件必需、目标文件可选），含 OS 需求、原始入口点地址及装载信息
`pe_section_header`	`h: PE::SectionHeader`	解析出节表头，含节名称、大小、地址与特征

各事件在脚本层的挂载与日志写入对应 scripts/base/files/pe/main.zeek 的source-code引用区域，可用于自定义检测（例如检查is_64bit与section_names判断可疑加载方式）。

3.6 Zeek::X509 —— X.509 证书与 OCSP

组件：Files::ANALYZER_X509、Files::ANALYZER_OCSP_REQUEST、Files::ANALYZER_OCSP_REPLY

X509 插件是文件分析器中结构最复杂、功能最丰富的内置插件，同时覆盖 X.509 证书解析、OCSP 请求/应答解析与证书链验证。基础脚本位于 scripts/base/files/x509/main.zeek，OCSP 日志实现在 scripts/base/files/x509/log-ocsp.zeek。

3.6.1 核心记录类型

X509::Certificate（定义于 scripts/base/init-bare.zeek）——证书基础信息，大多数字段&log记录：

字段	类型	说明
`version`	`count`	版本号
`serial`	`string`	序列号
`subject`	`string`	主体（Subject）
`issuer`	`string`	颁发者（Issuer）
`cn`	`string &optional`	最后一个（最具体的）通用名
`not_valid_before`	`time`	有效期起始时间
`not_valid_after`	`time`	有效期截止时间
`key_alg`	`string`	密钥算法名称
`sig_alg`	`string`	签名算法名称
`key_type`	`string &optional`	密钥类型（rsa/dsa/ec，可由 OpenSSL 解析时）
`key_length`	`count &optional`	密钥长度（位）
`exponent`	`string &optional`	RSA 证书的指数
`curve`	`string &optional`	EC 证书的曲线
`tbs_sig_alg`	`string`	tbsCertificate 内给出的签名算法名，应与`sig_alg`一致

X509::Extension——通用扩展（scripts/base/init-bare.zeek）：name（扩展长名，未知时为 OID）、short_name（已知时的短名，可选）、oid、critical（是否关键扩展）、value（已知扩展解析为字符串，否则为原始数据）。

X509::BasicConstraints（scripts/base/init-bare.zeek）：ca（是否 CA 标志）与path_len（最大路径长度，可选），整条记录&log。

X509::SubjectAlternativeName（scripts/base/init-bare.zeek）：dns、uri、email、ip四个向量字段（均&log &optional），以及other_fields（证书是否包含其他未识别/未解析的名称字段）。

X509::Result（scripts/base/init-bare.zeek）：证书链验证结果，含result（OpenSSL 结果码）、result_string、以及验证成功时按"终端证书在前"顺序排列的chain_certs（vector of opaque of x509，可选）。

3.6.2 证书相关事件

x509_certificate(f, cert_ref: opaque of x509, cert: X509::Certificate)：遇到 X.509 证书时触发（例如 TLS 明文握手）。cert_ref是指向底层 OpenSSL 证书结构的 opaque 句柄。
x509_extension(f, ext: X509::Extension)：证书中出现扩展时触发。
x509_ext_basic_constraints(f, ext: X509::BasicConstraints)：解析到 basic constraints 扩展时触发，可用于识别证书主体是否为 CA。
x509_ext_subject_alternative_name(f, ext: X509::SubjectAlternativeName)：解析到 SAN 扩展时触发；SAN 通常用于绑定一个或多个 DNS 名，指明证书对哪些域名有效。
x509_ocsp_ext_signed_certificate_timestamp(f, version, logid, timestamp, hash_algorithm, signature_algorithm, signature)：遇到 RFC 6962 定义的signed_certificate_timestamp（SCT）扩展时触发，该扩展用于传输证书透明度（Certificate Transparency）的签名证明，可在 X.509 证书或 OCSP 应答中出现。其中version恒为 0（v1）、logid为 32 位密钥 ID、timestamp为自 epoch 起忽略闰秒的 NTP 毫秒时间戳。

基础脚本对以上事件的优先级为&priority=5（scripts/base/files/x509/main.zeek），逐一把扩展填入f$info$x509$extensions、san、basic_constraints与extensions_cache，并在文件结束（file_state_remove）时按去重索引写入x509.log。

3.6.3 OCSP 事件族

OCSP（在线证书状态协议，RFC 6960）相关事件共六个，覆盖请求与应答的完整生命周期：

事件	触发时机	关键参数
`ocsp_request(f, version)`	每个 OCSP 请求恰好触发一次（如 HTTP 连接中）	`version`通常为 0（v1）
`ocsp_request_certificate(f, hashAlgorithm, issuerNameHash, issuerKeyHash, serialNumber)`	OCSP 请求针对的每一张证书触发一次（单个请求可含多张证书）	颁发者名称哈希、颁发者公钥哈希、证书序列号
`ocsp_response_status(f, status)`	每个 OCSP 应答恰好触发一次	`status`如 successful/malformedRequest/tryLater
`ocsp_response_bytes(f, status, version, responderId, producedAt, signatureAlgorithm, certs)`	遇到含响应信息的 OCSP 应答时触发	`certs`为随应答发送的验证用证书列表（`x509_opaque_vector`）
`ocsp_response_certificate(f, hashAlgorithm, issuerNameHash, issuerKeyHash, serialNumber, certStatus, revokeTime, revokeReason, thisUpdate, nextUpdate)`	OCSP 应答中每个 SingleResponse 触发一次	吊销时间/原因，未吊销时`revokeTime`为 0、`revokeReason`为空串
`ocsp_extension(f, ext: X509::Extension, global_resp: bool)`	应答中出现 OCSP 扩展时触发	`global_resp`为`T`表示扩展位于全局 ResponseData，`F`表示位于 SingleResponse

其中ocsp_response_certificate的日志落地实现在 scripts/base/files/x509/log-ocsp.zeek，输出到ocsp.log，可用于监测证书吊销状态的变化。

3.6.4 X.509 实用函数 API

X509 插件还提供一组可在脚本中直接调用的函数（定义于 scripts/base/bif/plugins/Zeek_X509.functions.bif.zeek）：

函数	签名（要点）	用途
`x509_parse`	`(cert: opaque of x509) : X509::Certificate`	把证书 opaque 句柄解析为`X509::Certificate`
`x509_from_der`	`(der: string) : opaque of x509`	从 DER 字符串构造 opaque 证书句柄（主要用于测试）
`x509_get_certificate_string`	`(cert, pem: bool &default=F) : string`	返回证书字符串，`pem=T`返回 PEM 形式，否则返回原始 ASN.1 二进制
`x509_ocsp_verify`	`(certs: x509_opaque_vector, ocsp_reply: string, root_certs: table_string_of_string, verify_time: time &default=0.0) : X509::Result`	校验 OCSP 应答，`certs`中服务器证书在前
`x509_verify`	`(certs: x509_opaque_vector, root_certs: table_string_of_string, verify_time: time &default=0.0) : X509::Result`	校验证书链；宿主证书必须在索引 0，成功后返回完整证书链
`sct_verify`	`(cert, logid, log_key, signature, timestamp, hash_algorithm, issuer_key_hash: string &default="") : bool`	验证证书透明度 SCT（RFC 6962）；SCT 出现在 X.509 扩展中时须提供`issuer_key_hash`
`x509_subject_name_hash`/`x509_issuer_name_hash`/`x509_spki_hash`	`(cert, hash_alg: count) : string`	分别计算主体 DN、颁发者 DN、Subject Public Key Info 的哈希；`hash_alg`按 IANA TLS 参数映射取值
`x509_check_hostname`	`(hostname: string, certname: string) : bool`	按 RFC 6125 通配规则检查主机名与证书名是否匹配
`x509_check_cert_hostname`	`(cert_opaque: opaque of x509, hostname: string) : string`	检查主机名是否匹配证书中的任一名称：存在 SAN 时仅校验 SAN 并忽略 Subject CN（RFC 2818）；无 SAN 时使用 Subject 中最后一个 CN。匹配返回匹配名（可能含通配符），不匹配返回空串
`x509_set_certificate_cache`	`(tbl: string_any_table) : bool`	建立证书缓存：遇到证书时若`tbl[sha256 of certificate]`已设置，则跳过后续处理，仅调用回调
`x509_set_certificate_cache_hit_callback`	`(f: string_any_file_hook) : bool`	设置命中缓存时调用的回调函数

注意：基础脚本已用x509_set_certificate_cache建立证书缓存（见 scripts/base/files/x509/certificate-event-cache.zeek），只有确定不会与基础脚本冲突时才应修改缓存表或回调函数。

3.6.5 X509 分析器的行为配置

来自 scripts/base/files/x509/main.zeek 的常用选项：

X509::hash_function：证书指纹哈希函数，默认sha256_hash；改动会影响ssl.log与x509.log中的指纹；
X509::log_x509_in_files_log：是否把 X.509 证书条目也写入files.log，默认F；
X509::relog_known_certificates_after：证书去重后重新记录的最大时间间隔，默认1day；设为0secs完全关闭去重。注意整机重启会重置去重状态；
X509::known_log_certs_maximum_size：known_log_certs集合上限，默认1000000；
X509::known_log_certs_enable_publish/known_log_certs_enable_node_up_publish：是否把已记录证书哈希发布到集群其他节点、以及新 worker 上线时是否由 manager 下发全量集合，默认均T。对应实现是X509::log_cert_hashes_internal事件与Cluster::node_up处理（scripts/base/files/x509/main.zeek）；
X509::default_max_field_string_bytes/default_max_field_container_elements/default_max_total_container_elements：日志中单字符串字段、单容器字段、记录总容器元素的上限，分别默认继承Log::全局默认值、500、1500，用于防止超大证书撑爆日志。

四、端到端实战：给某个文件同时挂多个分析器

下面把以上知识整合为一个可直接运行的 Zeek 脚本，演示file_new中批量挂载、事件中处理结果：

# my-file-analyzers.zeek @load base/frameworks/files @load base/files/hash @load base/files/extract @load base/files/x509 @load base/files/pe module MyFileAnalysis; export { redef record Files::Info += { sha512: string &log &optional; }; } event file_new(f: fa_file) { # 显式挂载：SHA512 哈希 + 熵测试 Files::add_analyzer(f, Files::ANALYZER_SHA512); Files::add_analyzer(f, Files::ANALYZER_ENTROPY); # 提取：限定 50 MB，文件名自动生成 Files::add_analyzer(f, Files::ANALYZER_EXTRACT, Files::AnalyzerArgs($extract_limit=52428800)); } event file_hash(f: fa_file, kind: string, hash: string) { if ( kind == "sha512" ) f$info$sha512 = hash; } event file_extraction_limit(f: fa_file, args: Files::AnalyzerArgs, limit: count, len: count) { # 达到限额时把上限翻倍，继续提取 if ( FileExtract::set_limit(f, args, limit * 2) ) print fmt("extended extraction limit for %s", f$id); }

运行时使用zeek -C -r trace.pcap my-file-analyzers.zeek即可观察files.log中出现sha512列、pe.log、x509.log按 MIME 自动记录，以及./extract_files/目录下的提取产物。若不想每次手动加载，可把上述逻辑放进local.zeek或包（package）中。

五、验证与进一步探索

以上所有结论均可在当前仓库中直接核实：

分析器枚举与全部事件/函数参考：doc/reference/zeekscript/autogenerated-file-analyzer-index.rst（即本文主文档，由 doc/reference/zeekscript/file-analyzers.rst 引入）；
Files 框架核心 API：scripts/base/frameworks/files/main.zeek；
提取：FileExtract::prefix/default_limit及file_extraction_limit处理见 scripts/base/files/extract/main.zeek；
哈希：file_hash落日志见 scripts/base/files/hash/main.zeek；
熵：策略级全文件熵测试见 scripts/policy/frameworks/files/entropy-test-all-files.zeek；
PE：pe.log字段与事件挂载见 scripts/base/files/pe/main.zeek；
X.509：证书去重、MIME 注册、日志策略见 scripts/base/files/x509/main.zeek，OCSP 日志见 scripts/base/files/x509/log-ocsp.zeek，证书缓存见 scripts/base/files/x509/certificate-event-cache.zeek；
ZIP 分析器脚本：scripts/base/files/zip/main.zeek。

如需深入事件触发时序与数据流，可结合 doc/frameworks/file-analysis.rst 中关于 Files 框架的整体介绍阅读。