bluespam-cyber/exchange-mailbox-reporting-tool

# Exchange Online 邮箱报告工具 [](https://github.com/bluespam-cyber/exchange-mailbox-reporting-tool/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT) [](https://microsoft.com/PowerShell) [](https://python.org) 一个专业且具备审计就绪能力的工具包，用于提取和可视化 Exchange Online 邮箱统计信息、日历处理设置、配额使用情况以及合规性指标。该工具由企业安全工程师构建，旨在为管理层生成自动化的周报告，并为合规框架提供审计就绪的文档。 ## 📖 目录 - [概述](#overview) - [核心功能](#key-features) - [合规性与审计映射](#compliance--audit-mappings) - [架构与数据流](#architecture--data-flow) - [安装与前置条件](#installation--prerequisites) - [使用指南](#usage-guide) - [1. 数据提取 (PowerShell)](#1-data-extraction-powershell) - [2. 仪表板生成 (Python)](#2-dashboard-generation-python) - [安全与隐私](#security--privacy) - [许可证](#license) - [联系](#contact) ## 🎯 概述 **Exchange Online 邮箱报告工具** 填补了原始 PowerShell 提取与高管级可视化之间的空白。它由模块化的 PowerShell 提取脚本和基于 Python 的生成器组成，前者从 Microsoft 365 中提取关键的安全配置数据，后者将这些数据呈现为高级、交互式且离线可用的 HTML 仪表板。 ## ✨ 核心功能 * **深度邮箱洞察：** 提取准确的存储大小、项目数量和不活动时间线（检测超过 90 天未活动的邮箱）。 * **配额监控：** 通过基于百分比的统计分析，识别接近 `IssueWarningQuota`、`ProhibitSendQuota` 和 `ProhibitSendReceiveQuota` 阈值的邮箱。 * **合规性与保留追踪：** 审计整个租户内的 `ArchiveStatus`、`LitigationHoldEnabled`、`LitigationHoldDuration`、`RetentionPolicy` 和 `SingleItemRecoveryEnabled`。 * **日历与代理人安全：** 发现日历共享权限、自动处理设置以及拥有 `GrantSendOnBehalfTo` 访问权限的代理人，防止未经授权的日历窥探。 * **高级交互式仪表板：** * **100% 离线：** 零外部 CDN 或 API 调用。所有 CSS、JS 和 SVG 图表均直接嵌入在 HTML 中，确保安全的离线存档。 * **玻璃拟态 UI：** 具有平滑的深色/浅色模式切换、动态 SVG 指标环和滑出式详情抽屉。 * **本地导出：** 在浏览器中过滤您的数据，一键即时导出为 CSV 或 JSON。 ## 🛡️ 合规性与审计映射 此工具专为满足外部审计要求而设计。通过每周运行此报告，组织可以为以下框架提供特定时间点的证据： | 框架 | 控制 / 条款 | 监控指标 | 目的 | | :--- | :--- | :--- | :--- | | **GDPR** | Art. 32 (处理安全) | `LitigationHold`, `RetentionPolicy` | 确保数据不会被过早销毁或篡改。 | | **GDPR** | Art. 5 (数据最小化) | `IsInactive`, `TotalItemSizeInGB` | 识别并清除长期不活动账户中的数据。 | | **HIPAA** | § 164.312(b) (审计控制) | `Delegates`, `CalendarPermissions` | 限制并监控通过代理日历对 PHI 的访问。 | | **SOC 2 Type II** | CC6.1 (逻辑访问) | `Delegates`, `IsInactive` | 确保撤销不活动用户的访问权限；审计代理人权限。 | | **SOC 2 Type II** | CC7.3 (事件恢复) | `SingleItemRecoveryEnabled` | 确保在发生事件时能够恢复取证数据。 | | **ISO 27001** | A.8.20 (网络安全) | `AutomateProcessing` | 监控自动转发以防止数据泄露。 | *更多详细信息，请参阅 [docs/compliance_mapping.md](docs/compliance_mapping.md).* ## 🏗️ 架构与数据流 1. **提取 (`/powershell/`)：** 编排脚本 (`Invoke-MailboxReport.ps1`) 向 Exchange Online 进行身份验证，通过点源方式加载模块化提取脚本 (`Get-MailboxStats.ps1`, `Get-CalendarSettings.ps1`, `Get-QuotaUsage.ps1`, `Get-ComplianceMetrics.ps1`)，并按 `UserPrincipalName` 聚合数据。 2. **标准化：** 数据将作为 `JSON` 和 `CSV` 文件在本地导出至 `./reports/` 目录。 3. **渲染 (`/dashboard/`)：** Python CLI (`generator.py`) 摄取 JSON/CSV 数据并将其注入 Jinja 风格的 HTML 模板 (`template.html`) 中，输出一个自包含的仪表板。 *在 [docs/architecture.md](docs/architecture.md) 中查看完整的 Mermaid 时序图。* ## ⚙️ 安装与前置条件 ### PowerShell 要求 * Windows PowerShell 5.1+ 或 PowerShell Core 7.0+ * **ExchangeOnlineManagement V3 模块：** Install-Module -Name ExchangeOnlineManagement -Scope CurrentUser -Force ### Python 要求（用于仪表板生成器） * Python 3.8 或更高版本。 * 核心生成器不需要外部 pip 依赖！（仅使用标准库）。 * *（可选）* 如需运行单元测试：`pip install -r requirements.txt` ## 🚀 使用指南 ### 1. 数据提取 (PowerShell) 打开具有管理员权限的 PowerShell 提示符。您可以使用标准的交互式 MFA 或 App-Only 客户端证书（推荐用于 CI/CD 或 Cron 作业）进行身份验证。 **选项 A：交互式 MFA 登录** ``` .\powershell\Invoke-MailboxReport.ps1 -Interactive -OutputDirectory .\reports -InactiveThresholdDays 90 ``` **选项 B：App-Only 证书身份验证（自动化）** 确保您的 Azure AD App Registration 拥有 `Exchange.ManageAsApp` API 权限。 ``` .\powershell\Invoke-MailboxReport.ps1 -AppId "YOUR_APP_ID" -CertificateThumbprint "YOUR_CERT_THUMBPRINT" -Organization "yourtenant.onmicrosoft.com" -OutputDirectory .\reports ``` *这将在 `./reports/` 目录中生成 `mailbox_report_YYYYMMDD_HHMMSS.json` 和 `.csv`。* ### 2. 仪表板生成 (Python) 生成 JSON 或 CSV 报告后，将其传递给 Python 生成器以创建交互式仪表板。 ``` python dashboard/generator.py --input ./reports/mailbox_report_20260801_120000.json --output ./reports/dashboard.html ``` *最后，双击 `./reports/dashboard.html` 在您的默认 Web 浏览器中将其打开。* ## 🔒 安全与隐私 * **净化处理：** 此代码库不包含硬编码的租户 ID、客户端密钥或个人电子邮件地址。提供了一个 `.env.example` 文件供您安全地配置本地环境。 * **数据主权：** 由于 Python 生成器构建的是完全离线的 HTML 文件，您敏感的邮箱元数据永远不会离开您的本地机器或网络。 ## 📝 许可证 该项目基于 [MIT 许可证](LICENSE) 授权。

标签：AI合规, Exchange Online, IPv6, PowerShell, 后端开发, 多模态安全, 报表工具, 自动化运维, 逆向工具