MAES Platform

MAES is a Microsoft 365 extraction, analysis, reporting, and compliance platform with built-in security operations capabilities including UEBA, case management, automated playbooks, and threat intelligence enrichment.

• Current release: v1.5.0
• Upstream extractor reference: invictus-ir/Microsoft-Extractor-Suite (Tier 3 Exchange-only sidecar)
• Upstream analyzer reference: LETHAL-FORENSICS/Microsoft-Analyzer-Suite

Assessment release. MAES can now see a tenant from the outside as well as the inside.

A domain-seeded attack surface assessment that runs without credentials — the view an attacker has before they have anything. Eleven phases across three profiles: tenant fingerprinting, DNS and mail authentication, certificate transparency, dangling-DNS detection, AD FS endpoint exposure, anonymous Azure and Microsoft 365 access, and, at the aggressive tier, account-existence and third-party SaaS checks. Findings are chained into attack paths, compared scan over scan, and reported in HTML, PDF, JSON, or CSV.

Because scans send real traffic to systems outside MAES, they are governed rather than merely offered: a recorded scope authorization with a profile ceiling and mandatory expiry, re-checked every time a scan runs; a complete audit trail of every probe; and centralised rate limiting that scan phases cannot bypass. Read Authorized Scanning before running one.

Sixteen new authenticated controls covering identity exposure the CIS benchmark does not reach — federation and AD FS surface, legacy authentication and ROPC, MFA coverage including phishing-resistant methods for privileged roles, Conditional Access gaps, service principal privilege, and mail authentication. The compliance engine now runs 25 automated checks, up from 9.

New high and critical exposures raise alerts, deduplicated against the previous scan so that standing findings do not re-alert every run. Alerts now also push over websockets rather than waiting for a poll, and per-user read state finally exists.

Two confirmed critical vulnerabilities were fixed: unauthenticated cross-tenant access through Socket.IO, and a reflected XSS in the admin-consent callback that could be escalated to account takeover. See the changelog for the full list, which also covers a broken SIEM export and a UEBA alerting path that had never once persisted an alert.

Interface release implementing the MAES redesign. No API or extraction behavior changes.

A single source of truth for the interface: design tokens (frontend/src/theme/tokens.js), an MUI theme built from them (frontend/src/theme/maesTheme.js, registered as the default MAES Command theme), and shared primitives in frontend/src/components/ui/ — severity pills, status dots, KPI strips, filter chips, panels, and evidence/timeline rows. Because the theme overrides the shared MUI components, every screen inherits the new surfaces, density, and control geometry.

The dashboard is now organized around security posture rather than widgets: an unassigned-critical-first KPI strip, the triage queue as the primary column, collection pipeline and platform health alongside, and a detection trend over the selected time range. Panels degrade independently, so a permission-gated summary returning 403 no longer blanks the page.

The previous drag-and-drop widget board was removed along with the fabricated panels it hosted — randomly generated CPU/memory/disk/network figures and hardcoded "recent errors" and "container logs" lists. Real service health comes from /api/health; real logs remain at /system-logs.

Alerts is a filterable queue beside a detail pane carrying evidence, a lifecycle timeline derived from the alert's own timestamps, and recommended actions. Adds assign-to-self, bulk triage over the filtered queue, and escalation of an alert into a case.

Regrouped into Operate / Investigate / Govern in a 224px sidebar with live alert badges, platform health, and identity in the footer. The topbar is reduced to 52px with an organization switcher, global search (⌘K), the shared time range, notifications, and help. Role-based visibility is unchanged. Below 900px the layout collapses to a single column with an overlay navigation rail.

See CHANGELOG.md for full details.

Bug-fix release restoring clean boot and login on fresh deployments:

• API boots from a clean build. Fixed a crash under Express 5 / path-to-regexp v8 in the compliance module (the optional-param route /controls/:assessmentType? is no longer valid syntax), and added the previously-undeclared uuid runtime dependency.
• Cleaner startup logs. The optional API migration directory is now skipped gracefully when absent (the SQL schema is applied by the postgres init scripts).
• Frontend login no longer blocked by CSP. The auth store now uses the same-origin API base (proxied by nginx via /api/*) instead of a hardcoded cross-origin http://localhost:3000.

The extractor service now calls Microsoft Graph API directly via @azure/msal-node + @microsoft/microsoft-graph-client for 23 of 28 extraction types, eliminating the PowerShell runtime dependency and reducing the Docker image by ~300-500 MB. A lightweight PowerShell sidecar (extractor-sidecar) handles the 5 Exchange-only types that have no Graph API equivalent.

PFX/PKCS12 certificate validation in the API service now uses node-forge instead of spawning pwsh. Certificate thumbprint, expiry, and private key extraction are handled entirely in JavaScript.

Replaced stdout regex parsing with a ProgressTracker class that updates BullMQ job progress through phase-based events (authenticating, fetching, paginating, writing).

Native Graph extractors produce output in Graph API's native JSON format with a metadata envelope (format version, extraction type, timestamp, record count) for format detection by downstream services.

See CHANGELOG.md for full details.

Behavioral baselines built from 30-day audit history, with geographic, temporal, and operational anomaly detection. Risk scores (0–100) drive automated recommendations and high-risk alerting.

Full incident lifecycle — new → investigating → contained → resolved → closed — with timeline tracking, evidence management, and user assignment.

Three built-in playbooks (Compromised Account, Phishing Email, Privileged Access Abuse) with approval gates for destructive actions and database-backed execution tracking.

Multi-provider IOC enrichment (VirusTotal, AbuseIPDB, Shodan, IPQualityScore) for IPs, domains, and file hashes. Saved IOC tracking with risk-level classification and 1-hour caching.

• Eliminated duplicate require() calls and duplicate app declarations that would crash startup
• Fixed broken sidebar menu array, duplicate frontend routes, and duplicate imports
• Replaced insecure pool.query('BEGIN') transactions with proper client-based transactions
• Parameterized SQL query in getUserCountries() (was injectable)
• Fixed route ordering so /stats/summary and /meta/playbooks match before /:id
• Aligned RBAC permission names across all new routes to the actual system permissions

See CHANGELOG.md and docs/releases/v1.2.0.md for full details.

• api/: authentication, orchestration, uploads, reporting, UEBA, incidents, threat intel
• frontend/: React UI behind nginx (src/theme/ design tokens and themes, src/components/ui/ shared primitives)
• services/extractor/: Microsoft 365 extraction worker (native Graph API + PowerShell sidecar dispatcher)
• services/extractor-sidecar/: PowerShell sidecar for Exchange-only extractions (unified audit log, admin audit, mailbox audit, transport rules, message trace)
• services/analyzer/: analysis worker
• services/compliance/: compliance assessment worker, external exposure scanner (src/recon/), and report service
• database/: bootstrap schema and migrations
• shared/: capability metadata used across services

• Docker Engine with Compose support
• Microsoft 365 tenant credentials for extraction/compliance workflows
• A .env file with explicit secrets

Set these in .env before starting the stack:

POSTGRES_PASSWORD=
REDIS_PASSWORD=
JWT_SECRET=
SERVICE_AUTH_TOKEN=
ENCRYPTION_KEY=
CERT_PASSWORD=
GRAFANA_PASSWORD=

Recommended generation commands:

openssl rand -hex 24   # POSTGRES_PASSWORD / REDIS_PASSWORD
openssl rand -hex 32   # JWT_SECRET / SERVICE_AUTH_TOKEN / ENCRYPTION_KEY / CERT_PASSWORD / GRAFANA_PASSWORD

Notes:

• ENCRYPTION_KEY must be at least 32 characters.
• SERVICE_AUTH_TOKEN is required for internal API calls between services.
• CERT_PASSWORD protects the default extractor certificate bundle.
• There is no seeded admin@maes.local / admin123 account.

These enable external IOC enrichment; the platform runs without them (enrichment endpoints return empty results):

VIRUSTOTAL_API_KEY=        # VirusTotal file hash and domain reputation
ABUSEIPDB_API_KEY=         # AbuseIPDB IP reputation
SHODAN_API_KEY=            # Shodan IP exposure and vulnerability data
IPQUALITYSCORE_API_KEY=    # IPQualityScore fraud and abuse scoring

1. Clone the repository.
2. Create .env from .env.example.
3. Fill in all required secrets.
4. Start the stack:

docker compose up -d --build

5. Apply database migrations:

docker compose exec -T postgres psql -U maes_user -d maes_db \
  < database/migrations/007_add_ueba_incidents_playbooks.sql
docker compose exec -T postgres psql -U maes_user -d maes_db \
  < database/migrations/008_add_saved_iocs.sql

6. Open the platform at https://localhost for local deployment, or your configured domain for production.
7. Create the first administrator account through the registration flow.

• Register the first user through the MAES UI.
• Complete onboarding and create the first organization.
• Configure Microsoft Entra / Microsoft 365 application credentials.
• Upload a certificate or use the extractor-managed default certificate.
• Run a connection test before scheduling extractions.
• Optionally configure threat intelligence API keys in .env for IOC enrichment.

• Services fail fast when required secrets are missing.
• No seeded default admin account.
• No hardcoded fallback internal service tokens.
• Docker log collection is disabled unless explicitly enabled.
• CSP and CORS defaults are tight in production mode.
• Container image references are pinned.
• All SQL queries use parameterized inputs.
• All new API endpoints enforce RBAC permissions and rate limiting.
• Websocket connections are authenticated and organization room membership is decided server-side.
• External exposure scans require a recorded scope authorization, identify themselves honestly, are rate limited, and log every probe they issue.

System log collection from Docker containers is not enabled by default. To enable it:

1. Set ENABLE_DOCKER_LOGS=true in the API environment.
2. Restore a read-only Docker socket mount for the API service.
3. Accept that this increases the privilege level of that container.

If you do not enable it, /api/system/logs returns 503.

• Frontend: cd frontend && npm install && npm run dev
• API: cd api && npm install && npm run dev
• Services: run their respective npm install and npm start commands

For local development, you may set development-only origins with CORS_ORIGIN or run with NODE_ENV=development.

• Environment Variables
• Domain Setup
• Monitoring
• Monitoring Quick Reference
• API Documentation
• Authorized Scanning
• External Exposure Architecture
• Release Notes: v1.1.0
• Release Notes: v1.2.0

MIT