mtayeb89/IOC-Scanner

# IOC Scanner 一款用于 **DFIR（数字取证与事件响应）** 和 **威胁狩猎** 的 Python 命令行工具，可递归扫描文件夹以查找 **危害指标**。 ## **版权所有 (c) Mahmoud Eltayeb** ## 检测内容 | IOC 类型 | 描述 | |---|---| | **可疑哈希** | 将 MD5 / SHA1 / SHA256 文件哈希与已知的恶意哈希列表进行比对 | | **已知恶意域名** | 将文本中发现的域名与域名黑名单进行比对 | | **IP 地址** | 在日志、配置文件或脚本中发现的 IPv4 地址 | | **电子邮件地址** | 标准的电子邮件地址模式 | | **比特币钱包** | 旧版 (`1...`)、P2SH (`3...`) 和 Bech32 (`bc1...`) BTC 地址 | | **API keys** | 通用样式的 `api_key=`、`secret_key=`、`access_token=`、`auth_token=` 赋值 | | **AWS keys** | AWS Access Key IDs (`AKIA…` / `ASIA…`) 以及 40 个字符的 AWS Secret Access Keys | | **JWT tokens** | JSON Web Tokens (`eyJ...`.`eyJ...`.`signature` 格式) | 扫描器会**递归**遍历目标目录，对每一个可读文件进行哈希处理，并根据上述 regex 模式扫描基于文本的文件。任何与用户提供的“已知恶意”哈希或域名列表匹配的内容都将被标记为**已确认的匹配**。 ## 环境要求 - Python 3.8 或更高版本 - 无第三方依赖 — 仅使用 Python 标准库 (`hashlib`, `re`, `os`, `json`, `csv`, `argparse`, `dataclasses`, `pathlib`, `datetime`) ## 项目结构 ``` ioc-scanner/ ├── ioc_scanner.py # Main program (entry point) ├── README.md # This file ├── LICENSE # MIT license, copyright Mahmoud Eltayeb └── sample_data/ ├── bad_hashes.txt # Example known-bad hash list ├── bad_domains.txt # Example known-bad domain list └── test_folder/ └── connection.log # Example log file containing sample IOCs ``` ## 安装说明 除了需要安装 Python 3.8+ 外，无需进行其他安装。 ``` git clone cd ioc-scanner python3 ioc_scanner.py --help ``` ## 用法 ### 基础扫描 ``` python3 ioc_scanner.py /path/to/folder ``` 这将递归扫描文件夹，打印控制台摘要，并生成一个名为 `ioc_report_.json` 的 JSON 报告到当前目录。 ### 使用已知的恶意哈希和域名列表进行扫描 ``` python3 ioc_scanner.py /path/to/folder \ --bad-hashes sample_data/bad_hashes.txt \ --bad-domains sample_data/bad_domains.txt ``` 哈希和域名列表文件为纯文本，**每行一条记录**。以 `#` 开头的行将被视为注释并忽略。 ### 自定义输出路径 ``` python3 ioc_scanner.py /path/to/folder \ --output results/report.json \ --csv results/report.csv ``` ### 静默模式（无控制台摘要，仅写入文件） ``` python3 ioc_scanner.py /path/to/folder --quiet ``` ### 完整 CLI 参考 ``` python3 ioc_scanner.py --help ``` ``` positional arguments: target Path to the folder to scan (scanned recursively). options: -h, --help show this help message and exit --bad-hashes BAD_HASHES Path to a text file with known-malicious hashes (one per line) --bad-domains BAD_DOMAINS Path to a text file with known-malicious domains (one per line) --output OUTPUT, -o OUTPUT Path to write a JSON report --csv CSV Optional path to also write a CSV report --quiet, -q Suppress the console summary --version Show program's version number and exit ``` ## 示例 使用内置的示例数据： ``` python3 ioc_scanner.py sample_data/test_folder \ --bad-hashes sample_data/bad_hashes.txt \ --bad-domains sample_data/bad_domains.txt ``` 示例控制台输出： ``` ====================================================================== IOC SCANNER REPORT Copyright (c) Mahmoud Eltayeb ====================================================================== Target directory : sample_data/test_folder Started at : 2026-06-30T09:44:11+00:00 Finished at : 2026-06-30T09:44:11+00:00 Files scanned : 1 Files skipped : 0 Total findings : 9 ---------------------------------------------------------------------- Findings by type: ipv4 : 2 domain : 2 email : 1 btc_wallet : 1 aws_access_key : 1 generic_api_key : 1 jwt_token : 1 ---------------------------------------------------------------------- !!! 1 CONFIRMED MATCHES against known-bad lists !!! [domain] malicious-c2-server.example <- sample_data/test_folder/connection.log ====================================================================== [+] JSON report written to: ioc_report_20260630T094411Z.json ``` ## 输出格式 ### JSON 报告 ``` { "scan_target": "sample_data/test_folder", "started_at": "2026-06-30T09:44:11+00:00", "finished_at": "2026-06-30T09:44:11+00:00", "files_scanned": 1, "files_skipped": 0, "findings": [ { "ioc_type": "domain", "value": "malicious-c2-server.example", "file_path": "sample_data/test_folder/connection.log", "matched_blocklist": true } ] } ``` ### CSV 报告 | ioc_type | value | file_path | matched_blocklist | |---|---|---|---| | domain | malicious-c2-server.example | sample_data/test_folder/connection.log | True | ## 工作原理 1. **目录遍历** — `os.walk()` 递归访问目标文件夹下的每一个文件。 2. **哈希处理** — 每一个可读文件都会以 64 KB 为数据块同时流式传输通过 MD5、SHA1 和 SHA256 进行处理（无需将整个文件加载到内存中）。如果提供了 `--bad-hashes`，每个计算出的哈希值都会与黑名单集合进行比对。 3. **文本扫描** — 如果文件具有已知的二进制扩展名（`.exe`、`.zip`、`.png` 等）或超过 25 MB，则会在文本扫描时跳过；否则，其内容将被解码为 UTF-8（忽略错误），并与 `PATTERNS` 中的每个 IOC regex 模式进行匹配。 4. **黑名单关联** — 在文本中发现的域名会与 `--bad-domains` 进行比对；哈希值会与 `--bad-hashes` 进行比对。匹配项将被标记为 `matched_blocklist: true`。 5. **报告生成** — 结果会被汇总到 `ScanReport` 中，作为控制台摘要打印，并导出为 JSON（始终）以及可选的 CSV。 ## 限制与说明 - 这是一个**静态的、基于签名/regex 的**扫描器 — 它不执行沙箱处理、行为分析或 YARA 规则匹配。 - 基于 regex 的检测（尤其是通用的 API keys 和 AWS secret keys）可能会产生**误报**；在采取行动之前，请务必手动筛选排查结果。 - AWS Secret Access Key 模式会匹配任何 40 个字符的类 base64 字符串，这是刻意为之的宽泛设计 — 请结合上下文审查命中结果。 - 对于大型环境，请提供精选的、最新的威胁情报源（例如来自 MISP、AlienVault OTX 或 VirusTotal）作为 `--bad-hashes` / `--bad-domains` 的输入文件。 - 此工具仅读取文件；它不会修改、隔离或删除磁盘上的任何内容。 ## 扩展扫描器 该工具具有刻意的模块化设计： - 通过在 `ioc_scanner.py` 中的 `PATTERNS` 字典中添加条目来增加新的 IOC 类型。 - 通过扩展 `load_lines_as_set()` 并将其接入 `IOCScanner.__init__` 来添加新的黑名单来源。 - 通过编写新的 `write_*_report()` 函数来添加新的输出格式。 ## 许可证 该项目基于 MIT 许可证授权 — 详情请参阅 [LICENSE](LICENSE)。 **Copyright (c) Mahmoud Eltayeb**

标签：Python, Ubuntu, 库, 应急响应, 数字取证, 无后门, 自动化脚本, 逆向工具