supunhg/filo
GitHub: supunhg/filo
Filo 是一个基于机器学习的文件取证与修复工具，旨在帮助安全专业人士识别和修复未知或损坏的文件。
Stars: 2 | Forks: 0
# Filo - 取证智能与学习操作器
**面向安全专业人士的久经考验的文件取证平台**
Filo 能将未知的二进制数据块转化为已分类、可修复且可解释的文件工件，并具备离线的机器学习能力。
## 功能
- 🔍 **深度文件分析**：多层签名、结构及 ZIP 容器分析
- 🎯 **智能格式检测**：区分 DOCX/XLSX/PPTX、ODT/ODP/ODS、ZIP、JAR、APK、EPUB
- 🧠 **增强型机器学习**：判别性模式提取、丰富的统计特征、N-gram 分析
- 🔧 **智能修复**：通过 21 种修复策略自动重建损坏的文件头
- 📊 **灵活输出**：简洁的证据显示（默认显示前 3 项），使用 -a/--all-evidence 查看完整详情
- 😎 **置信度分解**：使用 --explain 标志进行可审计的检测（符合法庭证据要求的透明度）
- 🛡️ **矛盾检测**：识别恶意软件、多义性文件、结构异常（用于恶意软件分类）
- 🕵️ **嵌入文件检测**：查找隐藏在文件内部的文件 - EXE 中的 ZIP、EOF 后的 PNG（恶意软件猎手的利器）
- 🔧 **工具指纹识别**：识别文件的创建方式、时间及所用工具（用于取证溯源）
- 🔐 **加密检测** *(新版 v0.3.0)*：检测加密数据，识别加密算法类型（AES-ECB、OpenSSL、PGP），分析块对齐方式，解释熵值 - 非常适合 CTF 挑战
- 🔍 **YARA 扫描** *(新版 v0.3.0)*：使用自定义 YARA 规则扫描文件 - 规则编译、匹配解析、标签和元数据提取
- 📄 **Office 宏分析** *(新版 v0.3.0)*：检测 OLE2 文档中的 VBA 宏 - 自动执行宏、50+ 可疑关键字
- 🔤 **字符串提取** *(新版 v0.3.0)*：高级的 `filo strings` 命令，支持正则表达式、熵过滤、编码检测、JSON 输出
- 📊 **熵值可视化** *(新版 v0.3.0)*：使用 `--entropy-viz` 标志生成颜色编码的熵图
- ⚠️ **多义性文件检测** *(v0.2.5)*：检测双格式文件（GIFAR、PNG+ZIP、PDF+JS）并评估风险
- 🖥️ **CPU 架构检测** *(v0.2.8)*：自动检测可执行文件的 CPU 架构（支持 90+ 种架构：x86、ARM、RISC-V、XTensa、MIPS 等）
- 🎨 **zsteg 兼容隐写分析** *(v0.2.7)*：60+ 种位平面 LSB/MSB 提取（PNG/BMP），自动 base64 解码，文件类型检测，针对 CTF 优化
- 🌐 **PCAP 分析** *(v0.2.6)*：网络捕获文件分析，包含协议检测、字符串提取、base64 解码、旗标搜索
- 🚀 **批量处理**：并行目录分析，可配置工作线程数
- 🔗 **哈希溯源追踪**：为法庭证据提供加密的监管链
- 📦 **容器检测**：对 Office 和归档格式进行基于 ZIP 的深度格式检查
- ⚡ **性能分析**：识别大规模分析中的瓶颈
- 🎨 **增强型 CLI**：彩色输出、十六进制转储、修复建议
- 🧹 **易于维护**：通过简单命令重置机器学习模型和溯源数据库
## 快速开始
**选项 1：pip 安装（Linux / macOS / Windows）**
```
pip install filo-forensics
# file
pip install filo-forensics[yara]
# Identify CPU architecture (ELF/PE/Mach-O executables)
pip install filo-forensics[all]
```
**选项 2：Docker（任意平台）**
```
docker pull ghcr.io/supunhg/filo:latest
docker run --rm -v $(pwd):/data filo:latest analyze /data/target_file
```
**选项 3：从源码安装（开发用途）**
```
git clone https://github.com/supunhg/Filo
cd Filo
pip install -e .
```
**选项 4：.deb 包（仅限 Linux）**
```
git clone https://github.com/supunhg/Filo
cd Filo
./build-deb.sh
sudo dpkg -i filo-forensics_0.3.0_all.deb
```
**用法：**
```
# Detect encrypted data (CTF-optimized)
filo analyze suspicious.bin
# Example output: "Medium entropy - AES-aligned (3 blocks) - Possible AES-ECB"
filo analyze binary # Shows: x86-64, ARM64, Xtensa, etc.
# Detect steganography (zsteg-compatible with auto base64 decoding)
filo analyze cipher.bin # Shows entropy, block alignment, cipher hints
# Analyze PCAP network capture files
# Show detailed confidence breakdown (forensic-grade)
filo stego challenge.png # CTF flag hunting
filo stego image.png --all # Show all 60+ bit plane results
filo stego image.png --extract="b1,rgba,lsb,xy" -o flag.txt
# Show all detection evidence and embedded artifacts
filo pcap capture.pcap
# Analyze with JSON output
filo analyze --explain file.bin
# Teach ML about a file format
filo analyze -a -e file.bin
# Batch process directory
filo analyze --json file.bin > report.json
# Repair corrupted file
filo teach correct_file.zip -f zip
# Reset ML model or lineage database
filo batch ./directory
# Clone repository
filo repair --format=png broken_image.bin
# Build .deb package
filo reset-ml -y
filo reset-lineage -y
```
## 安装说明
### 📦 简易安装（推荐） - Debian/Ubuntu
安装 Filo 最简单的方式是构建并安装 `.deb` 包：
```
# Install
git clone https://github.com/supunhg/Filo
cd Filo
# Start using immediately
./build-deb.sh
# Clone and install with dev dependencies
sudo dpkg -i filo-forensics_0.2.8_all.deb
# Run tests
filo --version
filo analyze file.bin
```
**特点：**
- ✅ 隔离安装在 `/opt/filo/` 目录下（无系统冲突）
- ✅ 自动管理依赖项
- ✅ 全局 `filo` 命令（可在任何位置使用）
- ✅ 无需手动激活虚拟环境
- ✅ 干净卸载：`sudo dpkg -r filo-forensics`
**支持系统：** Ubuntu 20.04+、Debian 11+ 及兼容发行版
**注意：** 所有用户数据存储在 `/home/user/.filo/` 目录中：
- 机器学习模型：`/home/user/.filo/learned_patterns.pkl`
- 溯源数据库：`/home/user/.filo/lineage.db`
### 从源码安装（开发用途）
```
git clone https://github.com/supunhg/Filo
cd Filo
pip install -e .
```
### 开发环境设置
```
# Python API
git clone https://github.com/supunhg/Filo
cd Filo
pip install -e ".[dev]"
# Analyze file with ML enabled
pytest
```
## 使用示例
### View detection evidence
```
from filo import Analyzer, RepairEngine
from filo.batch import analyze_directory
from filo.export import export_to_file
from filo.container import analyze_archive
# Teach ML about correct format
analyzer = Analyzer(use_ml=True)
result = analyzer.analyze_file("unknown.bin")
print(f"Detected: {result.primary_format} ({result.confidence:.0%})")
print(f"Alternatives: {result.alternative_formats[:3]}")
# Batch process directory
for evidence in result.evidence_chain[:3]:
print(f" {evidence['module']}: {evidence['confidence']:.0%}")
# Export to JSON/SARIF
with open("sample.zip", "rb") as f:
analyzer.teach(f.read(), "zip")
# Analyze container (DOCX, ZIP, etc.)
batch_result = analyze_directory("./data", recursive=True)
print(f"Analyzed {batch_result.analyzed_count} files")
# Repair file
export_to_file(result, "report.json", format="json")
# CLI
container = analyze_archive("document.docx")
for entry in container.entries:
print(f"{entry.path}: {entry.format}")
# Analysis with limited evidence (default: top 3)
repair = RepairEngine()
repaired_data, report = repair.repair_file("corrupt.png")
```
### Show all evidence and embedded artifacts
```
# Show detailed confidence breakdown (auditable, court-ready)
filo analyze suspicious.bin
# Combine for full transparency
filo analyze -a -e suspicious.bin
# Disable ML for pure signature detection
filo analyze --explain file.bin
# Analysis with JSON output
filo analyze --explain -a -e file.bin
# Detect embedded files (ZIP in EXE, PNG after EOF)
filo analyze --no-ml file.bin
# Identify tool/creator fingerprints
filo analyze --json suspicious.bin
# Batch processing with export
filo analyze malware.exe -e
# Teach ML about file formats
filo analyze document.pdf # Automatically fingerprints
# Reset ML model or lineage database
filo batch ./directory --export=sarif --output=scan.sarif
# Export to JSON for scripting
filo teach correct_file.zip -f zip
filo teach image.png -f png
# Security: Detect embedded malware in documents
filo reset-ml -y
filo reset-lineage -y
# Automation: Filter files with critical contradictions
filo analyze --json file.bin | jq '.primary_format'
# Check for hidden files
filo analyze suspicious.docx # Automatically checks for contradictions
# Chain-of-custody: Query file transformation lineage
filo analyze *.docx --json | \
jq 'select(.contradictions[]? | .severity == "critical")'
# View lineage history
filo analyze *.png --json | \
jq 'select(.embedded_objects | length > 0)'
# Export lineage for court
filo lineage $(sha256sum repaired.png | cut -d' ' -f1)
# Concise output (default)
filo lineage-history --operation repair
# Full evidence when needed
filo lineage $FILE_HASH --format json --output chain-of-custody.json
```
## 关键改进
### 基于 ZIP 的格式检测
Filo 现在通过检查容器内容，能够准确区分基于 ZIP 的格式：
- **Office Open XML**：DOCX、PPTX、XLSX（通过 `[Content_Types].xml` 检测）
- **OpenDocument**：ODT、ODP、ODS（通过 `mimetype` 文件检测）
- **归档文件**：JAR、APK、EPUB、普通 ZIP
- **大文件**：高效处理 >10MB 的文件（通过文件路径访问）
### 增强的机器学习特性
机器学习检测的三大改进：
1. **判别性模式提取**：自动发现特定格式的字节序列
2. **丰富特征分析**：8 种统计特征，包括压缩率、熵值、字节分布
3. **N-gram 分析**：使用前 100 个字节三元组进行模糊匹配，用于相似度检测
### 更简洁的输出
证据显示现在默认只展示最相关的前 3 项：
```
# Output:
filo analyze file.zip
# 🔍 Steganography Analysis: image.png
filo analyze --all-evidence file.zip
```
## 文档
- [快速入门指南](QUICKSTART.md) - 5 分钟上手
- [隐写分析检测](docs/STEGANOGRAPHY_DETECTION.md) - 隐藏数据提取（LSB/MSB、元数据、尾随数据） *(新版)*
- [嵌入文件检测](docs/EMBEDDED_DETECTION.md) - 查找隐藏在文件内部的文件
- [工具指纹识别](docs/TOOL_FINGERPRINTING.md) - 取证溯源（谁/何时/如何）
- [置信度分解](docs/CONFIDENCE_BREAKDOWN.md) - 可审计的检测解释
- [哈希溯源](docs/HASH_LINEAGE.md) - 监管链追踪
- [多义性文件检测](docs/POLYGLOT_DETECTION.md) - 双格式文件检测
- [矛盾检测](docs/CONTRADICTION_DETECTION.md) - 恶意软件与异常检测
- [系统架构](ARCHITECTURE.md) - 详细的设计说明
- [示例](examples/README.md) - 代码示例与演示
## v0.2.6 更新内容
🎨 **隐写分析检测**
检测图像文件和文档中的隐藏数据：
```
filo stego image.png
# # ✓ Potential Hidden Data Found (3 methods)
# # Method: b1,rgb,lsb,xy
# Confidence: 95% (FLAG PATTERN DETECTED)
# Data: picoCTF{h1dd3n_1n_LSB}
# Output:
# 📊 Statistics
```
**功能：**
- ✅ **LSB/MSB 检测**：从最低/最高有效位提取数据（PNG、BMP）
- ✅ **多通道支持**：测试 RGB、RGBA、独立通道（r、g、b、a）、BGR
- ✅ **位序**：支持 LSB 和 MSB，行/列主序
- ✅ **PDF 元数据**：从作者、标题、主题、关键字中提取隐藏的旗标
- ✅ **尾随数据**：检测 JPEG EOI、PNG IEND、PDF EOF 标记之后的数据
- ✅ **旗标识别**：自动检测 CTF 旗标模式（picoCTF{}、flag{}、HTB{}）
- ✅ **自动解码**：自动 base64 和 zlib 解压
- ✅ **提取功能**：将特定通道/方法的数据保存到文件
**完整指南：** [隐写分析检测文档](docs/STEGANOGRAPHY_DETECTION.md)
🌐 **PCAP 网络分析**
快速分类网络捕获文件：
```
filo pcap dump.pcap
# Packets: 1,234
# Protocols: TCP (800), UDP (400), ICMP (34)
# # 🚩 FLAGS FOUND (2)
# picoCTF{n3tw0rk_f0r3n51c5}
# flag{hidden_in_packets}
# # 📝 Base64 Data
# cGljb0NURnsuLi59 → picoCTF{...}
# Output:
# Entropy: 5.49 bits/byte
```
**功能：**
- ✅ **协议检测**：IPv4、IPv6、TCP、UDP、ICMP、ARP
- ✅ **字符串提取**：从数据包负载中提取 ASCII 字符串
- ✅ **Base64 解码**：自动检测并解码
- ✅ **旗标搜索**：在所有数据包中搜索 CTF 旗标模式
- ✅ **HTTP 提取**：GET/POST 请求及头部信息
- ✅ **轻量级**：无需 Wireshark/tshark 依赖即可快速分类
**新增格式支持：**
- 📦 **PCAP/PCAPNG**：网络捕获文件（小端/大端）
- 📜 **Shell 归档 (shar)**：自解压 Shell 脚本归档
## 历史版本
## 参与贡献
我们欢迎贡献！优先领域包括：
- 格式规范（YAML）
- 分析插件
- 测试语料样本
- 性能优化
## 安全与稳定性
Filo 在设计时充分考虑了安全性：
- 非破坏性分析（除非明确使用修复命令）
- 资源限制处理
- 所有层级的输入验证
- 无外部网络调用（完全离线的机器学习）
## 作者
Supun Hewagamage ([@supunhg](https://github.com/supunhg))
**当你需要知道的不仅仅是某物*是*什么，还有它*为何*如此，以及*如何*修复它。**
v0.3.0 - 加密检测（最新）
🔐 **重大增强：密码学分析与加密检测** Filo 现在能够自动检测加密数据，识别加密算法类型，并为 CTF 挑战和恶意软件调查提供取证级别的密码学分析： ``` filo analyze cipher.bin # (Medium - compressed data, weak encryption, or obfuscation) # Crypto indicators: File size is AES-aligned (3 blocks) # # 🔐 Encryption Detected: 95% confidence # • OpenSSL command-line encryption format # • File size is AES-aligned (3 blocks) # # Possible Cipher Types: # • AES (block size: 16 bytes) # • OpenSSL enc (likely AES-256-CBC) # Output: # 🖥️ CPU Architecture: ``` **关键特性：** - ✅ **熵值解释**：人类可读的香农熵解释（极低 → 极高） - ✅ **分组密码分析**：检测 AES/DES/Blowfish 块对齐、PKCS#7 填充、块数量 - ✅ **ECB 模式检测**：通过发现重复的密文块识别不安全的 ECB 模式（安全漏洞指标） - ✅ **格式识别**：OpenSSL enc（`Salted__`）、PGP/GPG 加密文件、二进制加密格式 - ✅ **CTF 优化**：通过熵值和块对齐提示完美识别加密的 CTF 挑战 - ✅ **JSON 导出**：完整的加密分析以 JSON 格式输出，便于自动化工作流 - ✅ **全面测试**：26 项测试覆盖所有加密检测场景 **可检测模式：** - **高熵值**：强加密或加密随机数据（>7.9 比特/字节） - **块对齐**：检测 AES（16字节）、DES/Blowfish（8字节）块 - **ECB 模式**：通过重复的密文块检测安全漏洞 - **填充**：检测分组密码的 PKCS#7 填充 - **格式**：OpenSSL、PGP/GPG、通用加密数据 **实际用例：** 非常适合像 "Old Habits" 这样的 CTF 挑战，您需要识别： - 加密算法（例如 AES-ECB） - 块大小和对齐方式 - 是尝试暴力破解还是寻找密码提示 **文档：** 详细用法和示例请参阅 [docs/CRYPTO_DETECTION.md](docs/CRYPTO_DETECTION.md)。 **发布日期**：2026年2月13日v0.2.8 - CPU 架构检测
🖥️ **重大增强：CPU 架构检测** Filo 现在能够自动检测并报告可执行文件的 CPU 架构： ``` filo analyze astronaut # • Tensilica Xtensa Architecture (32-bit, Little-endian) # Format: ELF | Machine Code: 0x005E # Output: # ⚠ Polyglot Detected: ``` **关键特性：** - ✅ **支持 90+ 种架构**：x86、x86-64、ARM、ARM64、RISC-V、MIPS、PowerPC、Xtensa、SPARC、AVR、Alpha、IA-64 等等 - ✅ **三种可执行文件格式**：ELF（Linux/Unix）、PE/COFF（Windows）、Mach-O（macOS/iOS） - ✅ **完整信息**：架构名称、地址宽度（32/64位）、字节序、机器代码 - ✅ **CTF 优化**：瞬间解决架构识别挑战 - ✅ **全面测试**：24 项测试覆盖所有主要架构 **支持的架构包括：** - 常见架构：x86、x86-64、ARM（32/64位）、RISC-V、MIPS、PowerPC - 嵌入式架构：Xtensa（物联网/WiFi）、AVR（Atmel）、SuperH、M68k - 专用架构：SPARC、Alpha AXP、IA-64（Itanium）、S390（大型机） - 特殊架构：VAX、PDP-10/11、TMS320C6000、Elbrus e2k、BPF **文档：** 完整指南请参阅 [docs/ARCHITECTURE_DETECTION.md](docs/ARCHITECTURE_DETECTION.md) 📊 **测试覆盖**：24 项新测试（100% 通过） 🎯 **CTF 就绪**：一条命令即可解决架构挑战v0.2.7 - zsteg 兼容隐写分析
✨ **重大增强：zsteg 算法兼容性** Filo 的隐写分析检测现在与行业标准 `zsteg` 工具完全一致： **关键特性：** - ✅ 每张图像测试 **60+ 种位平面配置** - ✅ 与 zsteg 相比，**逐字节完全一致**的提取结果 - ✅ **多位提取**（b1、b2、b4），具有正确的半字节/字节打包 - ✅ **自动 base64 解码** - 直接显示解码后的旗标（相比 zsteg 的改进！） - ✅ **文件类型检测** - OpenPGP 密钥、Targa、Applesoft BASIC、Alliant - ✅ **智能结果过滤** - 默认隐藏元数据噪声 - ✅ **zsteg 风格输出** - CTF 玩家熟悉的格式 **v0.2.7 中的其他改进：** - 降低了嵌入对象的误报率（置信度阈值从 0.70 提高到 0.80） - 添加了格式排除规则（跳过 ELF/PE 二进制文件中的 WASM/ICO 模式） - 嵌入检测中引入父格式感知 **测试：** - 在 CTF 挑战图像（picoCTF）上验证 - 与 zsteg 参考输出进行算法验证 - 测试多位提取（b2、b4 位平面） 📊 **测试覆盖**：85%+（所有测试通过） **完整详情：** [RELEASE_v0.2.7.md](docs/RELEASE_v0.2.7.md)v0.2.6 - 隐写分析与 PCAP 分析
✨ **新增功能：** - 隐写分析检测（LSB/MSB 分析、PDF 元数据、尾随数据） - PCAP 网络捕获分析，包含旗标搜索 - 增强的输出过滤v0.2.5 - 多义性文件与双格式检测
⚠️ **主要新功能：多义性文件与双格式检测** Filo 现在能够检测同时满足多种格式规范的文件： ``` filo analyze suspicious_image.gif # • GIF + JAR - GIF + JAR hybrid (GIFAR attack) (91%) # Risk: HIGH | Pattern: gifar" # Now, let's count the lines. I'll number each line starting from 1. # 1. With optional YARA support ``` **支持的多种性文件模式：** - **GIFAR**（GIF+JAR） - 高风险：绕过图像过滤器的经典攻击向量 - **PDF + JavaScript** - 高风险：包含嵌入式 JS 载荷的恶意 PDF - **PE + ZIP** - 高风险：同时也是 ZIP 归档的 Windows 可执行文件 - **PNG + ZIP** - 中等风险：包含隐藏 ZIP 归档的图像 - **JPEG + ZIP** - 中等风险：包含嵌入式归档的 JPEG 文件 **关键特性：** - ✅ 多格式验证（PNG、GIF、JPEG、ZIP、JAR、RAR、PDF、PE、ELF） - ✅ 安全风险评估（高、中、低） - ✅ 置信度评分（70-98%） - ✅ PDF 中的 JavaScript 载荷检测 - ✅ 用于测试的演示多种性文件 - ✅ 全面的测试套件（26 项新测试） **文档：** 完整指南请参阅 [docs/POLYGLOT_DETECTION.md](docs/POLYGLOT_DETECTION.md) 📊 **测试覆盖**：总体 67%（173/173 项测试通过，+26 项多种性文件测试） 🎯 **支持格式**：60+ 种文件格式 🔬 **检测精度**：干净文件 95%+，损坏文件 70%+v0.2.4 - 嵌入检测与工具指纹识别（上一版本）
✨ **增强功能：** 1. **嵌入对象检测** - 查找隐藏在文件内部的文件（EXE 中的 ZIP、EOF 后的 PNG、多种性文件） 2. **工具指纹识别** - 识别创建工具、版本、操作系统、时间戳（用于取证溯源） 3. **短标志** - `-a` 查看所有证据，`-e` 查看所有嵌入工件 4. **重置命令** - `filo reset-ml` 和 `filo reset-lineage` 方便维护 5. **演示文件** - `demo/` 目录中的复杂测试文件 6. **哈希溯源追踪** - 为所有转换提供加密的监管链 7. **格式矛盾检测** - 识别恶意软件、多种性文件、嵌入的可执行文件 8. **置信度分解** - 使用 --explain 标志进行可审计的检测 9. **ZIP 容器分析** - 准确检测 DOCX/XLSX/PPTX/ODT/ODP/ODS 10. **增强的机器学习** - 模式提取、丰富特征、N-gram 分析 📊 147/147 项测试通过标签：Apex, CTF竞赛工具, YARA规则扫描, 二进制分析, 云安全运维, 加密检测, 字符串提取, 宏分析, 嵌入文件检测, 工具指纹, 文件修复, 文件智能, 智能修复, 机器学习, 格式检测, 格式识别, 法庭就绪, 深度分析, 熵可视化, 矛盾检测, 离线学习, 结构分析, 证据展示, 请求拦截, 逆向工具