SVA-Cybersecurity/magic

# MAGIC – Microsoft Azure Graph Information Crawler MAGIC 是一个围绕 Microsoft Graph Python SDK 构建的封装工具，旨在从 Microsoft 365 环境中提取与事件响应相关的数据。 它帮助分析人员高效导出日志数据，并生成一个整合的 `.jsonl` 文件，以便导入 OpenSearch 或 Timesketch。 | :zap: 主要优势在于该工具完全使用 Python 编写，因此可以在几乎任何操作系统上运行。 | |-----------------------------------------------------------------------------------------------------------------------------| ## 60 秒快速入门 ``` # 1. 创建并激活虚拟环境 python3 -m venv .venv source .venv/bin/activate # 2. 安装 MAGIC pip install git+https://github.com/SVA-Cybersecurity/magic.git # 3. 初始化工作区（创建 config + 文件夹） magic-init # 4. 编辑 config.yaml： # - 添加您的 M365 应用程序凭证 # - 从 available_crawls.yaml 添加爬取模块（例如 m365_signin） # 5. 运行 MAGIC magic ``` 仅此而已 —— 现在你已经拥有了标准化的 M365 事件日志，准备进行分析。 ## 1. 需求 ### 1.1. Microsoft 365 应用程序（必需） MAGIC 需要一个 Entra ID **应用程序注册**，包含以下内容： - 应用程序（客户端）ID - 客户端密钥 - 租户 ID - 根据要运行的爬取模块所需的相应 **Microsoft Graph 权限** MAGIC 可以使用以下命令自动生成包含所需权限的应用程序清单： ``` magic --manifest ``` 完整的权限清单位于本文档末尾。 ### 1.2. Python - Python 3.11+ - 建议使用虚拟环境 ## 2. 安装 ### 2.1. 创建虚拟环境（推荐） ``` python3 -m venv .venv source .venv/bin/activate ``` ### 2.2. 安装 MAGIC ``` pip install git+https://github.com/magic-tool/magic/.git ``` ### 2.3. 初始化工作区 ``` magic-init ``` 这将创建以下目录结构： ``` . ├── logs # Log folder ├── output # Output folder ├── available_crawls.yaml # All crawl modules ├── config.yaml # Active configuration ``` ## 3. 配置 ### 3.1. 应用程序凭证 这是使用 Microsoft Graph API 下载任何信息所必需的。 ``` settings: auth: client_secret: "" client_id: "" tenant_id: "" ``` ### 3.2. （可选）默认参数 默认参数可用于配置所有爬取模块的设置。 默认值可以在各个爬取模块中被覆盖。 参数优先级： 1. 爬取级数值 2. 默认值 3. 内部回退值 ``` settings: defaults: user_principal_names: - jdoe@tenant.com date_start: 2026-01-01 12:00:00 date_end: 2026-01-12 ``` ### 3.3. （可选）权限预检 在下载日志之前，将验证所配置应用程序的权限。 通过以下配置启用或禁用： ``` settings: permission_preflight_check: True ``` ### 3.4. （可选）IpAPI enrichment 若要使用 IpAPI 增强模块丰富事件，请配置凭证： ``` settings: ipapi: key: ExampleKey endpoint: "https://your-ipapi-endpoint" cert: False ``` ## 4. 爬取配置 要下载日志，可以配置多个爬取模块。 一个模块可以使用不同的参数多次出现。 示例： ``` crawl: - type: m365_signin sign_in_type: user - type: m365_message_traces recipient_addresses: - john@tenant.com ``` 所有模块及其参数均在 `available_crawls.yaml` 中有文档说明。 ## 5. CLI 使用 ``` magic [-h] [-c CONFIG] [-o OUTPUT_DIR] [--reports-dir REPORTS_DIR] [--debug] [--manifest] MAGIC - Microsoft Azure Graph Informations Crawler options: -h, --help show this help message and exit -c CONFIG, --config CONFIG Path to configuration file (default: config.yaml in working directory or module directory) -o OUTPUT_DIR, --output-dir OUTPUT_DIR Directory for results (default: output in working directory or module directory) --reports-dir REPORTS_DIR Directory for logs (default: logs in working directory or module directory) --debug Enable debug logging --manifest Generate permissions manifest ``` ## 6. 输出与增强 每个爬取模块都会在其基础输出文件夹下创建独立的输出目录。每个爬取配置会基于配置的过滤器和参数生成一个计算的文件标识符。 基础输出会被整合到一个单一的 `base.jsonl` 文件中。 为确保一致性： - 输出 JSON 仅包含**一层** - 嵌套的 JSON 对象以 JSON 字符串形式存储 可用的增强模块可以转换或丰富输出内容，当前包括： - Timesketch 转换器 - IPAPI 增强 - 用于完整性验证的哈希生成器 示例： ``` enrich: timesketch: enabled: True output_filename: timesketch.jsonl ipapi: enabled: True input_filename: timesketch.jsonl output_filename: ipapi.jsonl hash: enabled: True output_filename: hash.jsonl output_filename_csv: hash.csv ``` ## 7. 完整工作流程示例 为了说明该工具的工作流程，以下是一个常见的 M365 取证场景。 ### 7.1. 目标 收集 `user1@contoso.com` 在 **2025‑12‑01** 到 **2025‑12‑10** 之间的所有登录记录，并将结果转换为 Timesketch 兼容格式。 ### 7.2. 示例 config.yaml ``` settings: auth: client_id: "" client_secret: "" tenant_id: "" defaults: date_start: 2025-12-01 date_end: 2025-12-10 user_principal_names: - user1@contoso.com crawl: - type: m365_signin sign_in_type: user enrich: timesketch: enabled: True output_filename: timesketch.jsonl ``` ### 7.3. 运行 MAGIC ``` magic ``` ### 7.4. 内部执行流程 1. MAGIC 加载并合并配置值 2. OAuth2 客户端凭证流程获取 Microsoft Graph API 令牌 3. 每个爬取模块调用其对应的 Graph API 端点 4. 所有数据合并到 `base.jsonl` 5. 运行增强模块（Timesketch） 6. 生成最终的 `timesketch.jsonl` 文件，准备导入 ## 8. 限制 某些模块受 Microsoft Graph API 限制。 如果未指定日期范围，将应用默认保留策略。 可用数据可能取决于租户的许可证。 ## 9. 权限 所有爬取模块都会声明其所需的 Microsoft Graph 权限。 你可以使用以下命令验证应用程序权限： ``` permission_preflight_check: True ``` 要为你的配置生成包含所需权限的权限清单，请使用： ``` magic --manifest ``` ## 10. 贡献 非常欢迎贡献！ ### 如何贡献 1. **报告错误** 通过 GitHub Issues 2. **提出新功能** 通过 Issues 3. **提交 Pull Request**： - 使用特性分支 - 提交清晰的提交信息 - 必要时更新文档

标签：Azure AD, crawl modules, Entra ID, Incident Response, JSONL, M365, m365_signin, Microsoft 365, Microsoft Graph, pip 安装, Python, Python SDK, SEO: Python Graph SDK 包装器, SEO: 事件响应数据提取, SEO: 微软365日志工具, Timesketch, 客户端密钥, 应用注册, 数据导出, 无后门, 日志采集, 时序数据库, 权限管理, 模型越狱, 租户ID, 虚拟环境, 逆向工具