slavicbob/M365-License-Auditor-Tool-MCP

# M365 License Auditor Tool MCP A full-stack Microsoft 365 governance intelligence dashboard that combines identity risk detection, license cost optimization, sign-in threat analytics, and a natural-language analyst assistant. This project is designed as a portfolio-grade demonstration of: - Secure data retrieval from Microsoft Graph - Actionable analytics over identity, licensing, and access telemetry - API-first backend architecture with caching and composable insights - A clean React dashboard for operational decision support - LLM-assisted query experience over governance and cost data ## Table of Contents - Overview - Core Functionalities - Architecture - API Endpoints - Frontend Experience - Data Sources and Detection Logic - Real-World Use Cases - Business Applications - Technology Stack - Local Setup - Environment Variables - Caveats and Limitations - Roadmap Suggestions - Portfolio Positioning ## Overview M365 License Auditor Tool MCP helps IT, SecOps, and FinOps teams answer critical questions such as: - Which users are high risk from an identity governance perspective? - Where are we overspending on Microsoft 365 licenses? - Which sign-in patterns indicate suspicious activity? - What actions should we prioritize this week for risk and cost reduction? The system aggregates Microsoft Graph data, computes scores and insights, and presents both tabular detail and executive summaries. ## Core Functionalities ### 1. Governance Risk Scan Implemented in app/scanner.py. Detects and classifies governance findings into high and medium risk buckets. Key detections: - Premium-licensed users without MFA - Privileged users with basic licenses (under-licensed admin risk) - Privileged users without MFA - Inactive licensed users (90+ day threshold) - Contractors assigned premium licenses - Disabled accounts that still retain licenses - Maternity leave exclusion logic using custom security attributes Outputs: - Risk score out of 100 - User-level findings with recommendations - Summary counts for high risk, medium risk, excluded users, and disabled licensed users ### 2. License Cost Optimization Implemented in app/cost.py. Computes tenant licensing spend and optimization opportunities. Key analytics: - Total monthly license cost - Wasted monthly cost from inactive licensed users - Premium user population - Contractor premium over-assignment - Under-utilized premium users based on 30-day M365 activity signals: - Email - Teams - OneDrive - SharePoint - Potential downgrade savings based on configurable SKU downgrade map - Top cost drivers and license distribution Outputs: - Cost score out of 100 - Monthly and annualized waste/savings indicators - Actionable per-user downgrade or reclaim suggestions ### 3. Threat Activity Analysis Implemented in app/threats.py. Analyzes Entra sign-in telemetry for suspicious behavior over a 7-day lookback. Key detections: - Failed login bursts (possible brute force) - Risky sign-ins from Entra ID protection signals - Atypical-country successful sign-ins - Impossible travel events (cross-country sign-ins in short time windows) Outputs: - Threat summary metrics - Detailed event tables by threat category - Recommendations for investigation and policy hardening ### 4. Executive Overview Aggregation Implemented in app/main.py at /overview. Combines governance, cost, and threat summaries into an executive snapshot with: - Risk and cost scores - Threat volume - Annualized waste and savings potential - Top recommended actions with category-based navigation ### 5. AI Governance Assistant Implemented in app/agent.py and exposed at /agent. Provides natural-language querying over governance and cost datasets. Design characteristics: - Dataset compaction to control token footprint - Insight truncation with summary totals preserved - Query-keyword routing (cost-only, scan-only, or combined) - Structured JSON response contract for frontend rendering ## Architecture ### Backend (FastAPI) - Entry point: app/main.py - CORS enabled for local Vite frontend (localhost:5173) - In-memory response caching with per-key locking - Cache TTL: 30 minutes - Endpoints: scan, cost, threats, overview, agent ### Graph Access Layer - Implemented in app/graph.py - MSAL confidential client credential flow - Token reuse with expiration handling - Retry and throttle-aware handling for Graph 429/5xx responses - Pagination handling with optional page limits - CSV report ingestion for activity analytics ### Frontend (React + Vite) - Tabbed app shell in frontend/src/App.jsx - Page modules: - Overview - Governance - Cost - Threats - AI Agent - Reusable components: - Summary cards - Searchable, sortable user table ## API Endpoints All endpoints are served by FastAPI (default local base URL: http://127.0.0.1:8000). - GET / - Health/status - GET /scan?refresh=true|false - Governance scan summary and findings - GET /cost?refresh=true|false - Cost analysis summary and optimization insights - GET /threats?refresh=true|false - Sign-in threat analysis summary and event insights - GET /overview?refresh=true|false - Aggregated executive dashboard payload - POST /agent - Request body: { "query": "..." } - Returns typed JSON payload for UI rendering ## Frontend Experience The dashboard supports: - Executive KPI summaries for leadership reporting - Drill-down finding tables for analyst workflows - Global table search and sortable columns - One-click refresh for latest overview data - AI-assisted Q&A for exploratory analysis ## Data Sources and Detection Logic Primary data comes from Microsoft Graph APIs: Scoring model highlights: - Governance risk score penalizes high-risk and medium-risk prevalence - Cost score penalizes inactive-licensed and contractor-premium ratios ## Real-World Use Cases - Quarterly M365 license right-sizing program - Security posture review for privileged identities - Detection of stale, risky, or over-provisioned accounts - Tenant-wide operational readiness dashboard for IT leadership - Evidence-driven recommendations for identity governance committees ## Business Applications - Reduce recurring Microsoft 365 licensing waste - Improve compliance outcomes for privileged access controls - Surface suspicious sign-in behavior earlier - Build a shared operating picture between SecOps, IAM, and FinOps ## Technology Stack Backend: - Python - FastAPI - MSAL - Requests - Azure OpenAI SDK Frontend: - React - Vite - Axios Supporting: - Microsoft Graph API - Entra ID app registration with application permissions ## Local Setup ### 1. Clone and enter project - Clone this repository - Open the project root folder ### 2. Backend setup From the project root: python -m venv .venv .venv\Scripts\activate pip install -r requirements.txt Run API server: uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 ### 3. Frontend setup From frontend directory: npm install npm run dev Default frontend URL: - http://127.0.0.1:5173 If needed, set frontend API target with VITE_API_BASE_URL. ## Environment Variables Create a .env file at project root for backend settings: Required for Microsoft Graph: - CLIENT_ID - CLIENT_SECRET - TENANT_ID Required for AI assistant: - AZURE_OPENAI_KEY - AZURE_OPENAI_ENDPOINT - AZURE_OPENAI_DEPLOYMENT Optional: - AZURE_OPENAI_API_VERSION (default in code: 2024-12-01-preview) - AGENT_MAX_RECORDS_PER_INSIGHT (default: 100) - SIGNIN_PAGE_LIMIT (default: 50) Optional for frontend (frontend/.env): - VITE_API_BASE_URL ## Caveats and Limitations This section is important for production honesty and portfolio credibility. ### 1. Pricing placeholders must be replaced In app/cost.py, license pricing and downgrade savings currently contain placeholder symbols (for example, XYZ and ABC). This is not executable Python and must be replaced with real numeric values before running cost analytics. ### 2. Permission scope requirements Graph endpoints used by this project require elevated application permissions (for example: audit logs, reports, directory data). Missing permissions will produce partial insights or endpoint failures. ### 3. In-memory cache only Caching is process-local and non-distributed. It is suitable for local use and demos but not sufficient for horizontally scaled production deployments. ### 4. Heuristic detection model Threat and governance logic uses deterministic heuristics (thresholds and rules) and is not a replacement for full SIEM/SOAR or incident response pipelines. ### 5. AI response dependency The AI assistant requires a configured Azure OpenAI deployment and may return different outputs depending on model behavior and prompt routing. ### 6. Data freshness and API limits Graph report endpoints can be delayed, and high-volume tenants may experience throttling despite retry/backoff handling. ## Roadmap Suggestions Potential upgrades for production-readiness: - External persistent cache (Redis) - Background scheduled scans with snapshot history - Multi-tenant RBAC and auth for the dashboard itself - Export capabilities (CSV/PDF executive reports) - Policy-as-code integration for remediation workflows - Unit and integration test expansion, including mocked Graph fixtures - SIEM connector support (Sentinel/Splunk) ## Portfolio Positioning This project demonstrates practical cloud engineering and product thinking across: - API engineering and integration resilience - Security and governance analytics design - Cost optimization intelligence - LLM feature integration with payload shaping and structured output contracts - Frontend delivery focused on operator workflows ## Architectural Diagram (ASCII) +--------------------------------------+ | React Frontend | | Vite app with tabs and data tables | | (Overview, Scan, Cost, Threats, AI) | +------------------+-------------------+ | | HTTP/JSON v +--------------------------------------+ | FastAPI Backend | | app/main.py | | - /scan /cost /threats /overview | | - /agent | | - In-memory cache (30 min TTL) | +-----------+--------------+-----------+ | | calls modules | | calls LLM | | +-----------------------+--+ +---+----------------------+ | Analytics Modules | | Azure OpenAI Service | | scanner.py | | (structured JSON output) | | cost.py | +--------------------------+ | threats.py | | agent.py | +------------+-------------+ | | via graph.py (MSAL + retry + paging) v +--------------------------------------+ | Microsoft Graph APIs | | Users, Roles, SKUs, Reports, SignIns | +--------------------------------------+ ## Disclaimer This project is a generalized and sanitized portfolio implementation inspired by enterprise automation scenarios. No proprietary company information, credentials, production configurations, or internal business logic are included.