marky224/m365-guardian

# 🛡️ M365 Guardian **你的 Microsoft 365 用户与安全守护者 —— 由自然语言驱动。** M365 Guardian 是一个为 SMB IT 技术人员打造的 LLM 聊天机器人。它支持使用自然语言管理 Microsoft Entra ID 用户和 Exchange Online 邮箱，并提供自动化的每周安全洞察。 ## 架构 ``` ┌──────────────────────────────────────────────────────────────────┐ │ M365 GUARDIAN │ ├──────────────┬───────────────┬───────────────┬──────────────────┤ │ Teams Bot │ Web Chat │ Timer Func │ REST API │ │ (Bot Fwk) │ (aiohttp) │ (Az Func) │ /api/chat │ ├──────────────┴───────────────┴───────────────┴──────────────────┤ │ LLM Orchestration Layer │ │ LiteLLM (Anthropic / Azure OpenAI / OpenAI / xAI) │ │ Tool Calling + Structured Output │ ├─────────────────────────────────────────────────────────────────┤ │ Tool Executor │ │ Routes LLM tool calls → Graph API service methods │ │ Audit logging on every read/write operation │ ├──────────────┬──────────────────────────┬──────────────────────┤ │ Graph API │ Report Service │ Audit Service │ │ (msgraph) │ 10 security checks │ (Cosmos DB) │ │ Users/Mail │ Teams + Email delivery │ Full traceability │ ├──────────────┴──────────────────────────┴──────────────────────┤ │ Microsoft Graph API │ │ Entra ID · Exchange Online · Identity Protection │ └─────────────────────────────────────────────────────────────────┘ ``` ## 项目结构 ``` m365-guardian/ ├── backend/ │ ├── app.py # Main entry point (aiohttp server) │ ├── bot.py # Teams bot handler │ ├── config.py # Configuration from environment │ ├── services/ │ │ ├── graph_service.py # Microsoft Graph API wrapper │ │ ├── llm_service.py # LLM orchestration via LiteLLM │ │ ├── audit_service.py # Cosmos DB audit logging │ │ └── report_service.py # Weekly security report (10 checks) │ ├── tools/ │ │ └── executor.py # Routes tool calls to Graph methods │ ├── functions/ │ │ └── weekly_report.py # Azure Function timer trigger │ └── web-app/ │ └── templates/ │ └── index.html # Standalone web chat interface ├── deployment/ │ └── configure-ip-restrictions.ps1 # Azure IP restriction setup script ├── docs/ │ ├── 01_SYSTEM_PROMPT.md # Complete chatbot system prompt │ ├── 02_TOOL_SCHEMAS.json # All 18 tool/function definitions │ ├── 03_DEPLOYMENT_GUIDE.md # Step-by-step Azure deployment │ └── 04_SAMPLE_CONVERSATIONS.md # PoC scenario conversation flows ├── .env.template # Environment variable template ├── pyproject.toml # Python project configuration └── README.md # This file ``` ## 快速开始 ### 1. 克隆并配置 ``` cp .env.template .env # 使用您的租户、应用程序注册和 API 密钥编辑 .env ``` ### 2. 安装依赖 ``` pip install -e . ``` ### 3. 本地运行 ``` python -m backend.app # 服务器在 http://localhost:8080 启动 # Web 聊天： http://localhost:8080/ # 机器人端点：http://localhost:8080/api/messages # 健康检查：http://localhost:8080/health ``` ### 配置说明 - **LLM 提供商**：默认为 xAI（Grok）。在 `.env` 中设置 `LLM_PROVIDER` 和对应的 API 密钥。 - **机器人类型**：使用 `SingleTenant`（Azure 已弃用 MultiTenant）。 - **Azure 区域**：部署到 `centralus`（eastus 存在配额限制）。 - **IP 限制**：应用服务通过 Azure 平台级访问限制锁定到特定 IP。 ### 4. 部署到 Azure 请参考 `docs/03_DEPLOYMENT_GUIDE.md` 中的完整指南。 ## PoC 场景 | # | 场景 | 使用的工具 | |---|------|------------| | 1 | 创建用户 + 邮箱 | `create_user` → `assign_license` → `enforce_mfa` | | 2 | 密码重置 + MFA | `search_users` → `get_user_details` → `reset_password` → `enforce_mfa` | | 3 | 周度安全报告 | `generate_weekly_insights_report` → `send_report_to_teams` → `send_report_via_email` | 完整的对话记录请参见 `docs/04_SAMPLE_CONVERSATIONS.md`。 ## 周度安全报告 — 10 项检查 | # | 检查项 | 严重性逻辑 | |---|--------|------------| | 1 | 可疑登录 | 🔴 若 >3 次高风险，🟡 若 1–3 次，🟢 若 0 次 | | 2 | MFA 合规缺口 | 🔴 若 >5 个用户未启用 MFA | | 3 | 休眠账户 | 🔴 若 >10 个账户超过 90 天未活动 | | 4 | 许可证优化 | 🟡 若每个 SKU 超过 5 个未使用许可证 | | 5 | 特权访问卫生 | 🔴 若 >5 个永久特权管理员 | | 6 | 外部来宾用户与访问 | 🟡 若 >20 个来宾用户 | | 7 | 旧版身份验证 | 检查是否阻止旧版身份验证 | | 8 | Exchange 最佳实践 | 转发、委派、存储 | | 9 | 条件访问缺口 | 策略覆盖分析 | | 10 | 密码与身份验证卫生 | SSPR、禁止密码、验证方法 | ## 切换 LLM 提供商 M365 Guardian 支持通过 LiteLLM 一键切换 LLM： | 提供商 | `LLM_PROVIDER` | 所需环境变量 | |--------|----------------|--------------| | xAI / Grok（默认） | `xai` | `XAI_API_KEY` | | Anthropic | `anthropic` | `ANTHROPIC_API_KEY` | | Azure OpenAI | `azure_openai` | `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_DEPLOYMENT` | | OpenAI | `openai` | `OPENAI_API_KEY` | ## 安全原则 - **强制确认**：每个写入操作都需要明确的 `YES`。 - **最小权限**：Graph 权限严格限制在所需范围内。 - **完整审计追踪**：每个操作记录谁、什么、何时及完整会话。 - **IP 限制**：Azure 应用服务访问限制在平台层阻止未授权 IP。 - **无数据泄露**：密码被屏蔽，密钥永不输出。 - **提供者隔离**：客户数据不用于 LLM 训练。 ## IP 访问限制 M365 Guardian 使用 Azure 应用服务访问限制在应用到达前阻止未授权 IP。配置方式如下： ``` # 添加允许的 IP 地址 az webapp config access-restriction add --name m365guardian-app --resource-group rg-m365guardian --priority 100 --rule-name "MyIP" --action Allow --ip-address YOUR_IP/32 # 允许 Bot Framework（在 Teams 中必需） az webapp config access-restriction add --name m365guardian-app --resource-group rg-m365guardian --priority 500 --rule-name "BotFramework" --action Allow --service-tag AzureBotService # 拒绝所有其他请求 az webapp config access-restriction set --name m365guardian-app --resource-group rg-m365guardian --default-action Deny ``` ## 工具清单（18 个函数） | 工具 | 类型 | 描述 | |------|------|------| | `search_users` | 读取 | 搜索 Entra ID 用户 | | `get_user_details` | 读取 | 完整用户资料 + MFA + 登录记录 | | `create_user` | 写入 | 创建用户 + 可选许可证/邮箱 | | `update_user` | 写入 | 更新用户属性 | | `delete_user` | 写入 | 软删除用户（30 天可恢复） | | `reset_password` | 写入 | 重置密码并自动生成临时密码 | | `enforce_mfa` | 写入 | 启用/强制用户 MFA | | `list_available_licenses` | 读取 | 列出租户许可证 SKU | | `assign_license` | 写入 | 分配许可证给用户 | | `remove_license` | 写入 | 从用户移除许可证 | | `manage_group_membership` | 写入 | 添加/移除组成员 | | `manage_shared_mailbox` | 写入 | 创建/管理共享邮箱 | | `manage_distribution_group` | 写入 | 创建/管理分发组 | | `check_mailbox_status` | 读取 | 检查邮箱配置与健康状况 | | `generate_weekly_insights_report` | 读取 | 运行全部 10 项安全检查 | | `send_report_to_teams` | 写入 | 向 Teams 发送自适应卡片 | | `send_report_via_email` | 写入 | 通过邮件发送 HTML 报告 | | `get_audit_log` | 读取 | 查询 Guardian 操作历史 | | `bulk_operation` | 写入 | 批量执行密码/许可证/MFA 操作 | ## 许可证 专有 — 保留所有权利。

标签：aiohttp, Anthropic, Azure Functions, Azure OpenAI, Bot Framework, CIS基准, DLL 劫持, Entra ID, Exchange Online, IT 管理员, LiteLLM, LLM, M365, Microsoft 365, Microsoft Graph API, NLU, OpenAI, PB级数据处理, REST API, SMB IT, Teams, Timer Trigger, Unmanaged PE, Web Chat, xAI, 内存规避, 多模型支持, 大语言模型, 大语言模型蜜罐, 安全运维, 审计日志, 工具调用, 智能助手, 结构化输出, 自动化安全洞察, 读写审计, 逆向工具