AmaimaKhalidSethi/forenscan_ai

# ForenScan_ai **数字取证文件分析系统** ForenScan 是一个自托管的 Web 应用，用于进行取证级别的文件分析。它通过魔数匹配检测文件类型，计算加密哈希值，可视化原始 hex 数据，标记异常，并且现在包含一个 AI 助手（由 Groq / LLaMA 3.3 提供支持），可以通过内置的聊天机器人用通俗易懂的英语解释分析结果并回答分析师的问题。 ## 目录 - [功能](#features) - [架构](#architecture) - [环境要求](#requirements) - [安装](#installation) - [配置](#configuration) - [运行应用](#running-the-app) - [AI 功能设置](#ai-features-setup) - [分析流水线](#analysis-pipeline) - [签名数据库](#signature-database) - [导出与监管链](#export--chain-of-custody) - [安全说明](#security-notes) - [项目结构](#project-structure) - [术语表](#glossary) ## 功能 | 功能 | 详情 | |---|---| | **魔数检测** | 针对涵盖 19 个类别的 185+ 个签名的最长匹配算法 | | **加密哈希** | 以 64 KB 数据块流式计算 MD5 + SHA-256 — 对于大文件具有内存安全性 | | **Hex 可视化** | 与 xxd 兼容的地址 / hex / ASCII 显示前 64 字节 | | **异常检测** | 扩展名不匹配、文档中包含可执行文件、高熵值、YARA-lite 字符串模式 | | **尾部验证** | 根据已知格式文件尾部（JPEG、ZIP、PDF、GIF 等）验证文件末尾字节 | | **熵分析** | 每个文件的香农熵 — 高于 7.2 bits/byte 的值将被标记为可能已加密或已加壳 | | **目录扫描** | 递归扫描最多 500 个文件，支持跳过 symlink 并设置大小上限 | | **扫描历史** | 完整的会话历史，包含每个会话的风险摘要 | | **签名管理** | 通过 Web UI 添加、编辑、删除自定义签名，并提供全面验证 | | **导出** | JSON（监管链信封）和 CSV（兼容 Autopsy/FTK） | | **AI 解释** | 通过 Groq LLaMA 3.3 一键对任何扫描进行通俗易懂的详细解析 | | **AI 聊天机器人** | 具备上下文感知能力的取证助手 — 可针对任何扫描结果提问 | ## # ForenScan ## 架构 ``` forenscan/ ├── app.py # Flask application, all routes ├── analyzer.py # Core analysis engine ├── ai_utils.py # Groq AI explanation + chatbot ├── config.py # Paths, limits, constants ├── forensic_signatures.db # SQLite — signatures + scan results │ ├── utils/ │ ├── hash_utils.py # Streaming MD5 + SHA-256 │ ├── hex_utils.py # xxd-style hex formatter │ └── export_utils.py # JSON + CSV serialisation │ ├── templates/ │ ├── base.html │ ├── index.html # Dashboard + upload forms │ ├── results.html # Scan results + AI panel + chatbot │ ├── history.html # Scan session history │ ├── signatures.html # Signature database browser │ └── add_signature.html # Add / edit signature form │ └── static/ ├── css/theme.css # Full design system (dark terminal theme) └── js/app.js # Drag-drop, spinners, hash copy, collapse ``` **单个文件扫描的数据流：** ``` Upload → Extension check → Save with UUID prefix → Magic number match (SQLite signatures) → Footer validation → MD5 + SHA-256 (streaming) → Hex preview (first 64 bytes) → Entropy calculation (first 64 KB) → YARA-lite string scan → Anomaly scoring → Persist to scan_results table → Redirect to results page ``` ## 环境要求 - Python 3.11+ - 下面列出的 pip 包 - 用于 AI 功能的免费 [Groq API key](https://console.groq.com)（可选 — 没有它应用也能完全正常运行） ## 安装 ### 1. 克隆仓库 ``` git clone https://github.com/your-org/forenscan.git cd forenscan ``` ### 2. 创建虚拟环境 ``` python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate ``` ### 3. 安装依赖项 ``` pip install flask flask-limiter werkzeug groq ``` 固定安装的完整要求： ``` flask>=3.0 flask-limiter>=3.5 werkzeug>=3.0 groq>=0.9 ``` ### 4. 创建所需目录 ``` mkdir -p uploads reports evidence ``` ## 配置 所有配置都位于 `config.py` 中： ``` DB_PATH = "forensic_signatures.db" # SQLite database path UPLOAD_DIR = "uploads" # Temp storage for uploaded files REPORTS_DIR = "reports" # Export output directory MAX_UPLOAD_SIZE = 50 * 1024 * 1024 # 50 MB upload cap MAX_FILE_SIZE_SCAN = 500 * 1024 * 1024 # 500 MB — skip larger files in dir scan MAX_DIR_FILES = 500 # Max files per directory scan ALLOWED_SCAN_ROOTS = [ # Whitelist for directory scan paths "evidence", "/tmp/forensic_evidence", ] BLOCKED_UPLOAD_EXTENSIONS = { # Extensions rejected on upload '.php', '.py', '.rb', '.sh', '.exe', ... } ``` **要添加允许的扫描目录**，请将其绝对路径追加到 `ALLOWED_SCAN_ROOTS`。白名单之外的目录扫描将被阻止。 ## 运行应用 ### 开发环境 ``` export FORENSCAN_SECRET_KEY="change-me-to-a-long-random-string" export GROQ_API_KEY="gsk_xxxxxxxxxxxxxxxxxxxx" # optional — for AI features python app.py ``` 应用启动地址为 **http://localhost:5050** ### 生产环境 (Gunicorn) ``` pip install gunicorn gunicorn -w 4 -b 0.0.0.0:5050 app:app ``` ### 环境变量 | 变量 | 必需 | 描述 | |---|---|---| | `FORENSCAN_SECRET_KEY` | 推荐 | Flask session 密钥。如果未设置，则会生成一个临时密钥（重启后会重置 session）。 | | `GROQ_API_KEY` | 可选 | 启用 AI 解释和聊天机器人。在 [console.groq.com](https://console.groq.com) 免费获取。 | ## AI 功能设置 ForenScan 使用带有 `llama-3.3-70b-versatile` 的 **Groq 免费套餐**。无需信用卡。 ### 步骤 1. 在 [console.groq.com](https://console.groq.com) 注册 2. 前往 **API Keys → Create API Key** 3. 在你的环境中设置该密钥： ``` export GROQ_API_KEY="gsk_xxxxxxxxxxxxxxxxxxxx" ``` 4. 安装 Groq 库： ``` pip install groq ``` ### AI 的作用 **AI 解释**（每个结果页面上的按钮） - 将扫描元数据（不包含原始文件字节）发送给 LLM - 返回结构化的解析：概述、风险判定、包含关键指标的逐文件解释，以及建议的后续步骤 - 懒加载 — 仅在你点击按钮时调用 **ForenScan AI 聊天机器人**（位于结果页面右下角的浮动小部件） - 上下文感知：每次对话都会将完整的扫描数据作为 system context 注入 - 可以询问任何问题：*“为什么这个文件被标记为 HIGH？”*，*“熵值 7.8 是什么意思？”*，*“我应该隔离这个文件吗？”* - 对话历史在客户端为当前会话保留（最后 10 轮对话） ### Groq 免费套餐限制 | 限制 | 数值 | |---|---| | 每日请求数 | 14,400 | | 每分钟 token 数 | 6,000 | | 每日 token 数 | 500,000 | 这足以满足单分析师取证工作流中的持续使用需求。 ## 分析流水线 ### 1. 魔数检测 文件签名使用**最长匹配优先**策略与 SQLite 的 `signatures` 表进行匹配 — 即匹配文件头字节最多的签名胜出。对于有歧义的魔数（例如由 ZIP、DOCX、XLSX、JAR、APK 共享的 `50 4B 03 04`），将使用声明的文件扩展名进行消歧。 支持的类别：`IMAGE`, `DOCUMENT`, `ARCHIVE`, `EXECUTABLE`, `SCRIPT`, `MEDIA`, `SYSTEM`, `CRYPTO`, `FORENSIC`, `FONT`, `DATABASE`, `CAD`, `GIS`, `GAME`, `CONTAINER`, `MOBILE`, `WEB`, `EMAIL`, `DISK` ### 2. 哈希计算 MD5 和 SHA-256 使用 64 KB 数据块在单次流式传递中同时计算。这对于高达 500 MB 扫描限制的文件具有内存安全性，并且符合基于哈希的证据完整性的 NIST 取证标准。 ### 3. Hex 可视化 前 64 字节以兼容 xxd 的格式渲染： ``` 0x0000 FF D8 FF E0 00 10 4A 46 49 46 00 01 01 00 00 01 ......JFIF...... 0x0010 00 01 00 00 FF E1 00 16 45 78 69 66 00 00 49 49 ........Exif..II ``` 点击结果中的任何哈希值即可将其复制到剪贴板。 ### 4. 异常检测 每个文件都会运行四个异常检查： | 检查项 | 触发条件 | 风险升级 | |---|---|---| | **扩展名不匹配** | 检测到的类型类别与声明的扩展名不匹配（例如伪装成 JPG 的 EXE） | CRITICAL | | **非脚本文件中的脚本** | 带有图像/压缩包扩展名的脚本文件 | HIGH | | **高熵值** | 非压缩包文件的香农熵 > 7.2 bits/byte | HIGH | | **YARA-lite 字符串** | 可疑的 Win32 API 字符串：`CreateRemoteThread`、`VirtualAlloc`、`WScript.Shell`、`cmd.exe /c` | HIGH | ### 5. 尾部验证 对于具有已知文件尾部的文件类型（JPEG 以 `FF D9` 结尾，ZIP 以 `50 4B 05 06` 结尾等），会将文件的最后 N 个字节与预期的尾部进行比较。`footer_valid = False` 加上异常标记是文件伪装的强烈指标。 | 数值 | 含义 | |---|---| | `Yes` | 文件以预期的尾部字节结束 — 结构完整 | | `No` | 尾部字节不匹配 — 文件可能被截断、损坏或伪装 | | `N/A` | 签名中未定义此文件类型的尾部 | ## 签名数据库 SQLite 的 `signatures` 表内置了 185+ 个条目。你可以通过 UI 中的 **Signatures** 页面管理它们。 ### Schema ``` CREATE TABLE signatures ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, -- e.g. "JPEG Image" category TEXT NOT NULL, -- e.g. "IMAGE" mime_type TEXT NOT NULL, -- e.g. "image/jpeg" header_hex TEXT NOT NULL, -- e.g. "FF D8 FF" footer_hex TEXT, -- e.g. "FF D9" (nullable) extensions TEXT NOT NULL, -- JSON array e.g. '["jpg","jpeg"]' risk_level TEXT NOT NULL -- CRITICAL | HIGH | MEDIUM | LOW ); ``` ### 添加自定义签名 前往 **Signatures → Add Signature** 并填写： - **Header Hex** — 以空格分隔的 hex 格式魔数（例如 `89 50 4E 47`） - **Footer Hex** — 可选的文件末尾字节 - **Extensions** — 以逗号分隔，不带点号（例如 `png, apng`） - **Risk Level** — `CRITICAL` 保留给 `EXECUTABLE` 和 `SCRIPT` 类别 UI 会实时验证你的 hex 数据，并在保存前检查是否有重复签名。 ## 导出与监管链 每次扫描都可以从结果页面或扫描历史记录中导出。 ### JSON 导出 将结果包装在监管链信封中： ``` { "forenscan_version": "1.0", "export_timestamp": "2025-04-27T10:30:00Z", "scan_id": "uuid-v4", "chain_of_custody": { "analyst": "automated", "tool": "ForenScan", "hash_algorithm": "MD5+SHA256" }, "results": [ ... ] } ``` ### CSV 导出 兼容 **Autopsy**、**FTK** 和其他取证平台的平面文件导出。列名包括：`scan_id`, `filename`, `filepath`, `detected_type`, `mime_type`, `declared_ext`, `risk_level`, `anomaly_flag`, `anomaly_reason`, `md5_hash`, `sha256_hash`, `file_size`, `scan_timestamp`, `footer_valid`。 ## 安全说明 - **路径遍历保护** — 使用 `os.path.realpath` 根据 `ALLOWED_SCAN_ROOTS` 验证目录扫描。白名单之外的路径将被拒绝。 - **上传过滤** — 上传时会阻止服务器可执行扩展名（`.php`、`.py`、`.sh`、`.exe` 等）。 - **文件名净化** — 上传的文件保存为 `{uuid}_{secure_filename}`，绝不使用原始文件名作为路径组件。 - **速率限制** — 扫描端点有速率限制（文件扫描 10次/分钟，目录扫描 5次/分钟，聊天 60次/小时）。 - **临时文件清理** — 上传的文件在分析后 5 分钟自动删除。 - **UUID 验证** — 所有 `scan_id` 值在用于 SQL 查询或文件名之前，都会通过严格的 UUID v4 正则表达式进行验证。 - **AI 隐私** — 仅将文件元数据（名称、类型、哈希值、标记）发送给 AI。原始文件字节绝不会离开服务器。 ## 项目结构 ``` forenscan/ ├── app.py # Flask app + all routes ├── analyzer.py # ForensicAnalyzer engine ├── ai_utils.py # Groq AI — explain_scan() + chat() ├── config.py # Central configuration ├── forensic_signatures.db # SQLite database (signatures + results) │ ├── utils/ │ ├── hash_utils.py │ ├── hex_utils.py │ └── export_utils.py │ ├── templates/ │ ├── base.html │ ├── index.html │ ├── results.html │ ├── history.html │ ├── signatures.html │ └── add_signature.html │ ├── static/ │ ├── css/theme.css │ └── js/app.js │ ├── uploads/ # Temp upload storage (auto-cleaned) ├── reports/ # JSON/CSV export output └── evidence/ # Default allowed scan root ``` ## 术语表 **Magic number** — 标识文件格式的文件开头几个字节，与文件扩展名无关。例如，所有 JPEG 文件都以 `FF D8 FF` 开头。 **Entropy** — 衡量文件字节分布随机性的指标（香农熵，0–8 bits/byte）。普通文件的得分为 4–7。加密或压缩的数据得分接近 8。高熵值的非压缩包文件是可疑的。 **Footer / magic tail** — 某些格式同时定义了文件头和结尾字节序列。验证两端可确认文件在结构上是完整的。 **YARA-lite** — 受 YARA 规则启发的简化字符串模式扫描。ForenScan 会扫描已知的恶意 Win32 API 字符串，而无需完整的 YARA 引擎。 **Chain of custody** — 证明数字证据未被篡改的文档记录。JSON 导出包含时间戳、工具版本和所使用的哈希算法。 **Anomaly flag** — 当四个异常检查中的任何一个触发时设置。异常文件在结果 UI 中以红色高亮显示。 **Scan ID** — 每个扫描会话生成的 UUID v4，用于对结果进行分组、链接导出，并作为结果页面的 URL 键。

标签：AI助手, 哈希计算, 异常检测, 数字取证, 文件分析, 自动化脚本, 逆向工具, 魔法数字检测