magic-tool/magic

# MAGIC – Microsoft Azure Graph 信息爬虫 MAGIC 是 Microsoft Graph Python SDK 的封装工具，旨在从 Microsoft 365 环境中提取与事件响应相关的数据。 它协助分析人员高效导出日志数据，并生成一个统一的 `.jsonl` 文件，以便导入到 OpenSearch 或 Timesketch 中。 | :zap: 主要优势在于该工具完全使用 Python 编写，因此几乎可以在任何操作系统上运行。 | |-----------------------------------------------------------------------------------------------------------------------------| ## 60 秒快速入门 ``` # 1. 创建并激活 virtual environment python3 -m venv .venv source .venv/bin/activate # 2. 安装 MAGIC pip install git+https://github.com/magic-tool/magic.git # 3. 初始化 workspace (创建 config + folders) magic-init # 4. 编辑 config.yaml: # - 添加你的 M365 App credentials # - 从 available_crawls.yaml 添加 crawl modules (例如 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 丰富化 要使用 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 token 3. 每个爬取模块调用其 Graph API endpoint 4. 所有数据合并到 `base.jsonl` 中 5. 运行丰富化模块 6. 最终的 `timesketch.jsonl` 文件已准备好被导入 ## 8. 限制 某些模块受限于 Microsoft Graph API 的限制。 如果未指定日期范围，将应用默认的保留期限。 可用数据可能取决于租户的许可证。 ## 9. 权限 所有爬取模块都会声明它们所需的 Microsoft Graph 权限。 您可以使用以下命令验证您的应用程序权限： ``` permission_preflight_check: True ``` 要生成包含您配置所需权限的权限清单，请使用： ``` magic --manifest ``` ## 10. 贡献 非常欢迎贡献！ ### 如何贡献 1. 通过 GitHub Issues **报告 bug** 2. 通过 Issues **提议新功能** 3. **提交 Pull Requests**： - 使用 feature 分支 - 编写清晰的 commit message - 在需要时更新文档

标签：Azure, Entra ID, JSONL, M365, Microsoft 365, Microsoft Graph, Python, SDK封装, Timesketch, 代码示例, 取证工具, 库, 应急响应, 数据分析, 数据泄露, 数据爬取, 无后门, 日志导出, 网络调试, 自动化, 逆向工具