tlsh-rs

纯 Rust 实现的 TLSH，适用于 crates、服务、恶意软件流水线及相似性分析

## 概述 **tlsh-rs** 是 **TLSH** (Trend Locality Sensitive Hash) 的纯 Rust 实现，专为需要将模糊哈希作为原生 crate 使用，而非绑定到 C 或 C++ 实现的项目而构建。 此移植版本紧密遵循上游 TLSH 算法，保持实现为安全且可移植的 Rust 代码，并同时暴露了库 API 和 CLI。 ### 核心功能 | 功能 | 描述 | |---------|-------------| | **纯 Rust** | 哈希核心无需外部 crates | | **Edition 2024** | 现代 Rust crate 布局与工具链 | | **多 TLSH 配置** | 支持 `128/1`、`128/3`、`256/1` 和 `256/3` | | **流式构建器** | 通过 `TlshBuilder` 进行增量哈希计算 | | **摘要解析** | 处理原始摘要及带 `T1` 前缀的摘要 | | **距离计算** | 支持带或不带长度惩罚的哈希比较 | | **内置 CLI** | 包含 `hash`、`hash-many`、`diff` 和 `xref` 命令 | | **JSON + SARIF** | 适用于自动化流水线的机器可读输出 | | **真实测试向量** | 已针对上游兼容的参考向量和本地固件进行验证 | ### CI/CD 支持的目标 ``` Windows x64, ARM64 Linux x64, ARM64 macOS Intel, ARM64 ``` ## 安装说明 ### 从 crates.io 安装 ``` cargo install tlsh-rs --bin tlsh ``` ### 从源码安装 ``` git clone https://github.com/seifreed/tlsh-rs.git cd tlsh-rs cargo build --release ``` ### 构建 CLI ``` cargo build --release --bin tlsh ``` ## 快速开始 ``` # 哈希文件 cargo run --bin tlsh -- hash ./fixtures/small.txt # 比较两个文件 cargo run --bin tlsh -- diff ./fixtures/small.txt ./fixtures/small2.txt # 生成 SARIF cargo run --bin tlsh -- diff --format sarif ./a.bin ./b.bin ``` ## 使用指南 ### 命令行接口 ``` # 标准 TLSH 哈希 tlsh hash sample.bin # 原始摘要输出 tlsh hash --raw sample.bin # JSON 输出 tlsh hash --format json sample.bin # 哈希多个文件 tlsh hash-many file1.bin file2.bin file3.bin # 比较文件或摘要 tlsh diff left.bin right.bin tlsh diff T1... T1... # 交叉引用多个输入 tlsh xref a.bin b.bin c.bin # 从 stdin 读取一个输入 cat sample.bin | tlsh hash - ``` ### 可用命令 | 命令 | 描述 | |--------|-------------| | `hash` | 对单个文件或 `stdin` 进行哈希 | | `hash-many` | 对多个文件进行哈希 | | `diff` | 比较两个输入并返回 TLSH 距离 | | `xref` | 比较输入集合中的每一对 | ### 可用选项 | 选项 | 描述 | |--------|-------------| | `--profile` | 选择 `128-1`、`128-3`、`256-1` 或 `256-3` | | `--raw` | 返回原始十六进制摘要，而非带 `T1` 前缀的输出 | | `--format` | 输出格式为 `text`、`json` 或 `sarif` | | `--no-length` | 从 TLSH 距离计算中排除长度惩罚 | | `--threshold N` | 过滤 `xref` 结果，仅显示大于 `N` 的值 | | `-` | 从 `stdin` 读取单个二进制输入 | ## Rust 库 ### 基本用法 ``` use tlsh_rs::{hash_bytes, TlshBuilder}; let digest = hash_bytes(b"example payload")?; let mut builder = TlshBuilder::new(); builder.update(b"example ")?; builder.update(b"payload")?; let streamed = builder.finalize()?; assert_eq!(digest, streamed); ``` ### 特定配置哈希 ``` use tlsh_rs::{hash_bytes_with_profile, TlshProfile}; let digest = hash_bytes_with_profile( b"example payload", TlshProfile::full_256_3(), )?; println!("{}", digest.raw_hex()); ``` ### 解析与比较摘要 ``` use tlsh_rs::TlshDigest; let left: TlshDigest = "T1F8A0220C0F8C0023CB880800CA33E88B8F0C022AB302C2008A030300300E8A00C83AAC".parse()?; let right: TlshDigest = "T1C6A022A2E0008CC320C083A3E20AA888022A00000A0AB0088828022A0008A00022F22A".parse()?; let diff = left.diff(&right); let diff_no_length = left.diff_no_length(&right); ``` ## 示例 ### 使用特定配置进行哈希 ``` tlsh hash --profile 256-3 sample.bin ``` ### 将 `xref` 导出为 JSON ``` tlsh xref --format json a.bin b.bin c.bin ``` ### 将 `diff` 导出为 SARIF ``` tlsh diff --format sarif a.bin b.bin ``` ### 直接使用摘要字符串 ``` tlsh diff T1F8A0220C0F8C0023CB880800CA33E88B8F0C022AB302C2008A030300300E8A00C83AAC \ T1C6A022A2E0008CC320C083A3E20AA888022A00000A0AB0088828022A0008A00022F22A ``` ## 上游致谢 本项目的存在归功于 **Trend Micro** 最初推出的原 **TLSH** 项目： - 上游仓库：https://github.com/trendmicro/tlsh 衷心感谢 Trend Micro 团队发布并维护 TLSH。原项目使该算法得以面向社区开放，并为我们提供了坚实的参考标准以供验证。 构建此 Rust 移植版的初衷，是为了能在我们自己的项目中自然地作为 Rust crate 使用 TLSH，简化部署，并将模糊哈希集成到恶意软件分析和相似性流水线中，无需依赖 C/C++ 运行时。 致上游维护者：你们的工作确实实用，技术上优雅，并且仍在以最积极的方式对枯燥的恶意软件工作流造成有效打击。感谢你们的构建与分享。 ## 环境要求 - Rust stable - Cargo - Rust edition `2024` ## 许可证 本项目特意采用**宽松**的许可方式，以便可用于内部工具、商业产品、研究流水线及开源项目中。 ``` Apache-2.0 OR BSD-3-Clause ``` 为什么不用 MIT？ 本仓库是基于上游 TLSH 工作构建的 Rust 移植版，并保持了与 Trend Micro 发布的原项目一致的许可模式： - 上游仓库：https://github.com/trendmicro/tlsh - 上游许可模式：`Apache-2.0 OR BSD-3-Clause` 因此，安全且诚实的选择是保留该宽松许可模式，而不是将移植版重新标记为仅限 MIT。 在实际使用中，您可以自由使用此 crate，包括用于商业软件，但在重新分发时，应保留本项目及其上游来源适用的许可证和归属声明。

_{为 Rust 中实用的模糊哈希工作流而生}

标签：Crates.io, DAST, DNS 反向解析, EDR, IP 地址批量处理, Rust, TLSH, 可视化界面, 威胁情报, 库, 应急响应, 开发者工具, 恶意软件分析, 数字化指纹, 数据防泄露, 文件指纹, 文档结构分析, 无绑定, 模糊哈希, 沙箱, 相似性分析, 纯 Rust, 网络信息收集, 网络安全, 网络流量审计, 聚类分析, 脆弱性评估, 自定义DNS解析器, 距离计算, 通知系统, 隐私保护