pragmaconflux/titan1

# Titan Decoder Engine **面向网络安全专业人员、恶意软件分析师和执法机构的高级 payload 解码与取证分析框架。** [](https://github.com/pragmaconflux/titan1/actions/workflows/tests.yml) []() ## 安全 / 隐私 - 不要将真实的事件数据（日志、浏览器历史数据库、报告）上传到公开的 issues 中。 - 本工具可以处理不受信任的输入；请尽可能在沙盒环境中运行。 - 输出可能包含从样本中提取的敏感特征（IOC、电子邮件、主机名）。请妥善处理。 - 无担保：详见 [许可证](LICENSE)。 ## 🚀 快速开始 (5 分钟) 初次使用感到困惑？请从 [docs/USAGE.md](docs/USAGE.md) 中的实战演练开始。 维护者： - 发布清单：[docs/RELEASING.md](docs/RELEASING.md) - 社区发帖模板：[docs/ANNOUNCEMENT.md](docs/ANNOUNCEMENT.md) ### 1. 安装 ``` # 克隆仓库 git clone https://github.com/pragmaconflux/titan1.git cd titan1 # 安装核心 (无外部依赖) pip install -e . # 可选：安装扩展/高级功能依赖 pip install -e '.[enrichment]' ``` ### 2. 分析你的第一个文件 ``` # 快速分析 titan-decoder --file suspicious.bin --out report.json # 带进度和检测结果 titan-decoder --file payload.dat --progress --enable-detections --out report.json # 完整执法包 titan-decoder --file evidence.bin --profile full --enable-detections \\ --forensics-out forensics.json --ioc-out iocs.json --ioc-format misp \\ --report-out case_report.md --timeline-out timeline.csv # 添加 IR 证据日志 (DNS/Proxy/Firewall/VPN/Auth/DHCP) 用于关联 + pivots titan-decoder --file suspicious.bin --out report.json \\ --evidence dns:/path/dns.csv \\ --evidence proxy:/path/proxy.csv \\ --evidence firewall:/path/flows.csv ``` ### 3. 查看结果 ``` # 检查报告 (无需 jq) python -c 'import json; r=json.load(open("report.json")); print(r["node_count"]); print(r.get("iocs", {}))' # 查看风险评估 python -c 'import json; r=json.load(open("report.json")); print((r.get("risk_assessment") or {}).get("risk_score")); print(r.get("detections", []))' ``` **就是这样！** 你已经开始进行恶意软件分析了。 ## 📋 功能特性 ### 核心功能 - **18 种内置解码器（+ 插件）**：Base64（及递归）、Base32、Gzip、Bz2、LZMA、Zlib、Hex、XOR、ROT13、URL 解码、HTML 实体、Unicode 转义、UUEncode、ASN.1、QuotedPrintable、PDF、OLE - **智能检测**：自动启用特定格式的解码器 - **递归分析**：处理嵌套编码（可配置深度） - **归档支持**：支持带有防 ZIP 炸弹保护的 ZIP、TAR 格式 - **二进制分析**：PE、ELF 元数据提取 - **IOC 提取**：IP、URL、域名、电子邮件、哈希值及标准化 ### 取证与情报 - **设备取证**：VM 检测、移动设备 ID (IMEI/IMSI/ICCID)、一次性手机模式检测 - **标准化 IR 证据**：将常见的日志导出（DNS/Proxy/Firewall/VPN/Auth/DHCP）摄入到规范的 Event/Indicator 模型中 - **Top Pivots + Last Seen**：带有来源证明且基于证据的 pivots（多源指标会向上冒泡汇总） - **证据关联**：为关键关联提供原因代码 + 置信度 - **7 条检测规则**：深层 Base64 嵌套、Office 宏+网络 IOC、LOLBin 模式、加壳/加密 payload 启发式扫描、多阶段基础设施、XOR+C2、恶意 PDF - **风险评分**：0-100 启发式威胁评估 (CLEAN/LOW/MEDIUM/HIGH/CRITICAL) - **富化 enrichment**：Geo/WHOIS/YARA（可选，需配置）带有确定性本地缓存 + 刷新控制 - **AV 情报**：VirusTotal 查询（可选 API 密钥） ### 导出与报告 - **IOC 格式**：JSON、CSV、STIX 2.1、MISP - **案件报告**：为调查人员提供 Markdown/HTML 格式的摘要 - **时间线导出**：用于 Timesketch、Excel 的 CSV/JSON - **证据时间线导出**：基于标准化 `--evidence` 输入的 CSV/JSON - **图表导出**：JSON、DOT、Mermaid ### 工作流 / 信任 (CLI 优先) - **Doctor 自检**：`--doctor` 打印 JSON 诊断报告 - **安静模式**：`--quiet` 抑制非错误状态输出（干净管道输出） - **JSONL 导出**：`--jsonl-out events.jsonl` 方便数据摄入 - **本地 Vault**：`--vault-store` + `--vault-search ` 用于历史记录/搜索 ### 生产级特性 - **批处理**：分析整个目录 - **PII 脱敏**：安全的日志共享 - **资源限制**：内存上限、超时设置 - **信号处理**：优雅关闭 (Ctrl+C) - **错误恢复**：妥善处理损坏的文件 ## 📖 使用示例 ### 命令行 **基本分析** ``` titan-decoder --file payload.dat --out report.json --verbose ``` **快速分类** (depth=3, 最大 50 个 artifacts) ``` titan-decoder --file suspicious.bin --profile fast --progress --enable-detections ``` **深度分析** (depth=8, 最大 200 个 artifacts) ``` titan-decoder --file malware.bin --profile full --enable-detections --enable-enrichment ``` **执法机构专用包** ``` titan-decoder --file evidence.bin --enable-detections \\ --forensics-out forensics.json \\ --ioc-out iocs.json --ioc-format misp \\ --report-out case_report.md \\ --timeline-out timeline.csv ``` **批处理** ``` titan-decoder --batch ./input_dir --batch-pattern "*.bin" --out ./reports ``` ### Python API ``` from titan_decoder.core.engine import TitanEngine from titan_decoder.core.detection_rules import CorrelationRulesEngine from titan_decoder.core.risk_scoring import RiskScoringEngine from titan_decoder.config import Config # 基本分析 engine = TitanEngine() report = engine.run_analysis(data_bytes) # 带检测和风险评分 rules = CorrelationRulesEngine() detections = rules.evaluate_all(report, report['iocs']) risk_engine = RiskScoringEngine() risk = risk_engine.compute_risk_score(report, report['iocs'], detections) print(f"Risk Level: {risk['risk_level']} ({risk['risk_score']}/100)") print(f"Detections: {len(detections)}") print(f"IOCs: {sum(len(v) for v in report['iocs'].values())}") ``` ## ⚙️ 配置 ### 快速配置 创建 `~/.titan_decoder/config.json`： ``` { "max_recursion_depth": 5, "max_node_count": 100, "enable_logging": true, "log_level": "INFO" } ``` ### 完整配置 ``` { "max_recursion_depth": 5, "max_node_count": 100, "max_data_size": 52428800, "analysis_timeout_seconds": 300, "max_memory_mb": 1024, "decoders": { "base64": true, "gzip": true, "hex": true, "xor": true, "pdf": true }, "analyzers": { --- ## 💬 Feedback & Contributing - Bugs / questions: open a GitHub Issue (please avoid sensitive incident data) - Feature ideas: open a Feature Request Issue - Security issues: use GitHub Security Advisories (private report) See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup and PR guidelines. ## 🆘 支持 - Issues (bugs/questions): https://github.com/pragmaconflux/titan1/issues - Discussions (Q&A/ideas, enable in repo settings): https://github.com/pragmaconflux/titan1/discussions - Security reports (private): https://github.com/pragmaconflux/titan1/security/advisories/new ### 快速配置 "zip": true, "tar": true, "pe": true, "elf": true }, "enable_geo_enrichment": false, "enable_whois": false, "enable_yara": false, "yara_rules_path": "/path/to/rules.yar", "virustotal_api_key": "YOUR_API_KEY", "virustotal_rate_limit": 4, "enable_pii_redaction": true, "enable_logging": true, "log_level": "INFO" } ``` 运行 `titan-decoder --help` 获取完整的选项列表。 ## 🧪 测试 ``` # 开发设置 (安装 pytest + ruff) pip install -e ".[dev]" # 运行所有测试 pytest tests/ -v # Lint/格式化 python -m ruff check . python -m ruff format --check . # 带覆盖率 pytest tests/ --cov=titan_decoder --cov-report=html # 快速冒烟测试 tmpfile="$(mktemp)" && printf 'ZGF0YTogdGVzdA==' > "$tmpfile" && titan-decoder --file "$tmpfile" --out /tmp/titan_report.json && python -c 'import json; print(json.load(open("/tmp/titan_report.json"))["node_count"])' ``` ## 📚 文档 - **本 README** - 安装、使用、配置示例 - **CLI 帮助** - 运行 `titan-decoder --help` 获取完整的选项列表 ### 报告 schema - 报告格式的 JSON Schema：[docs/report.schema.json](docs/report.schema.json) ## 🔒 安全建议 **安全地分析不受信任的文件：** 1. **专用虚拟机**：在一次性虚拟机中运行 2. **快照**：使用快照并在分析后恢复 3. **网络隔离**：在分析前断开网络 4. **非 root 用户**：切勿以 root 用户身份运行 5. **资源限制**：设置 max_memory_mb 和 analysis_timeout_seconds ## 🏗️ 架构 ``` titan_decoder/ ├── cli.py # Command-line interface ├── config.py # Configuration management ├── core/ │ ├── engine.py # Main analysis engine │ ├── detection_rules.py # 7 starter detection rules │ ├── risk_scoring.py # Heuristic threat assessment │ ├── enrichment.py # Geo/WHOIS/YARA │ ├── device_forensics.py # VM/mobile/burner detection │ ├── vault.py # Local history/search store │ ├── ioc_export.py # JSON/CSV/STIX/MISP export │ ├── case_report.py # Markdown reports │ ├── timeline.py # Event timeline export │ ├── file_hashing.py # MD5/SHA1/SHA256 + VT │ ├── correlation.py # IOC correlation cache │ ├── resource_manager.py # Timeouts and limits │ ├── secure_logging.py # PII redaction │ ├── smart_detection.py # Format auto-detection │ ├── scoring.py # Decode scoring │ ├── profiling.py # Performance metrics │ ├── graph_export.py # Graph visualization │ └── analyzers/ │ └── base.py # ZIP, TAR, PE, ELF ├── decoders/ │ └── base.py # 18 built-in decoders (+ plugins) ├── plugins/ # Plugin system └── utils/ └── helpers.py # IOC extraction, entropy ``` ## 🤝 贡献 欢迎贡献！请开一个 PR 或 issue 来讨论变更。 **添加自定义解码器：** ``` from typing import Tuple from titan_decoder.plugins import PluginDecoder class MyDecoder(PluginDecoder): @property def name(self) -> str: return "MyFormat" def can_decode(self, data: bytes) -> bool: return data.startswith(b"MYMAGIC") def decode(self, data: bytes) -> Tuple[bytes, bool]: decoded = my_decode_logic(data) return decoded, True ``` 放置在 `~/.titan_decoder/plugins/my_decoder.py` 中即可自动加载！ ## 📄 许可证 许可证：MIT (详见 LICENSE)。 ## 🆘 支持 - **Issues**：[GitHub Issues](https://github.com/pragmaconflux/titan1/issues) ## 🎯 路线图 - [ ] 用于集成的 REST API - [ ] 用于目录监控的 Watch 模式 - [ ] Artifact 解析器 (prefetch, shimcache) - [ ] PyPI 包 - [ ] 单文件可执行文件 - [ ] Web UI ## 🙏 致谢 为网络安全社区而建。 **核心技术：** - Python 3.10+ (核心仅使用标准库) - 可选：psutil、geoip2、python-whois、yara-python、requests **准备好进行分析了吗？开始使用：** `titan-decoder --file your_sample.bin --progress --enable-detections`

标签：DAST, DNS 反向解析, IOC提取, IP 地址批量处理, Python, 威胁情报, 安全分析引擎, 库, 应急响应, 开发者工具, 恶意软件分析, 数字取证, 无后门, 沙箱, 法证分析, 网络信息收集, 网络安全, 自动化脚本, 调试插件, 载荷解码, 隐私保护