auditex

Overview

Auditex is a Python CLI and MCP toolkit for read-only Microsoft 365 and Google Workspace tenant audits. It collects local evidence, normalizes results, and produces report, export, comparison, and customer handoff artifacts.

The public audit surface does not write to production tenants. It also does not read message bodies or file contents in audit mode. The separate tenant-bootstrap/ kit is for lab setup and rehearsal; treat it as a writable lab tool with its own credentials, outputs, and safeguards.

What is included

• Microsoft 365 collection through the auditex and azure-tenant-audit CLIs.
• Google Workspace collection through the optional google dependencies.
• Guided setup and audit flows, capability probes, local auth-context management, and diagnostics.
• Offline fixtures for contract checks and demonstrations.
• Report rendering, CSV/JSON and other exporters, comparison and drift gates, customer handoff packs, and a local MCP server.
• Offline imports and control-by-control review of Maester, ScubaGear and Monkey365 JSON assessments, with source hashes and strict tenant identity checks.
• Offline model-development tools for staging public conversations, checking recorded structured answers, and preparing a reviewed single-base LoRA training pack.
• Read-only privilege graph: potential routes from users, groups and applications to tier-0 control, with evidence per hop, explicit unverified prerequisites and candidate breakpoints.
• Detection coverage ("could this tenant see an attack?") and the tenant's public footprint, including MTA-STS and TLS-RPT.
• Baseline alignment with CIS Microsoft 365 Foundations v7, CISA SCuBA, Microsoft Secure Score, Zero Trust, the Microsoft cloud security benchmark, and the NCSC Cyber Essentials requirements (v3.3), where device-side requirements show as manual or assessor-tested, the ones Intune and Exchange Online evidence in part (updates, anti-malware) show as partial, and tenant-backed ones never read pass. See framework mappings.
• auditex demo, a guided walkthrough on a fictional company, and auditex report explorer, a self-contained interactive HTML view of any run.

The package is Python 3.11 or newer. Its required runtime dependencies are requests and msal. Google Workspace and MCP support are optional extras.

Install and check locally

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[test]'
auditex doctor --json

Optional dependencies:

python -m pip install -e '.[google]'
python -m pip install -e '.[mcp]'

Useful repository checks are:

make lint
make test
make contract-smoke
./scripts/oss-taint-scan.sh

make contract-smoke runs an offline sample and checks the finalized bundle contract. See the runbook for the complete local and release check matrix.

Main commands

Try the whole flow on a fictional company without touching any tenant:

auditex demo

auditex demo replays a synthetic tenant offline, then walks through access planning, findings, evidence, attack paths, and a checksum-verified customer pack, and writes an interactive HTML explorer. Use --no-pause for an unattended run.

Generate a provider-specific permission and scope plan before requesting access:

auditex setup-guide m365 --collector-preset full --format md
auditex setup-guide google --collector-preset everything --format md

Guided operator flow:

auditex guided-run
auditex guided-run --flow gr-audit --include-exchange
auditex guided-run --flow app-audit

The ga-setup-app flow is a separate setup operation. Run it only when you are authorized to create or configure the app registration and its permissions:

auditex guided-run --flow ga-setup-app

Offline runs are safe for local checking:

auditex run --offline --tenant-name demo --out outputs/offline
auditex google run --offline --sample examples/google_workspace_sample.json \
  --domain example.com --tenant-name demo --out outputs/google

For an authorized live Microsoft 365 audit with an existing Azure CLI sign-in, authenticate first and use the resulting delegated read-only context:

make login TENANT=contoso.onmicrosoft.com
auditex run --tenant-name CONTOSO --tenant-id contoso.onmicrosoft.com \
  --use-azure-cli-token \
  --auditor-profile global-reader --out outputs/live

Use auditex probe live after auth or scope changes to identify capability blockers before a full run. For app-based runs, use an already authorized read-only app context and follow the generated setup guide.

Google Workspace supports domain-wide delegation and OAuth. The full Google path requires the optional dependencies and provider credentials kept outside the repository:

auditex google doctor --json
auditex google probe --auth domain-delegation --domain example.com \
  --service-account-key /path/to/service-account.json --subject admin@example.com

Read a run and prepare a handoff

External Microsoft assessment reports can also be reviewed locally with auditex assessment import and auditex assessment compare. See external assessment comparison for supported formats, evidence references and comparison limits.

Each finalized run contains a manifest, summary, report pack, evidence index, AI context, and validation result. The current contract version is recorded in run-manifest.json; required files and evidence rules are documented in the output contract.

For the proposed specialist reasoning model, use auditex model sources, stage, evaluate, combine, and prepare. These commands operate on local files. See model development for reference availability, review gates, and the separate training recipe. The supplied examples are unreviewed proposals; no trained Auditex model or measured model quality is claimed.

auditex report render <run-dir> --format md
auditex report api-calls <run-dir> --format md
auditex report permissions <run-dir> --format md
auditex report proof-table <run-dir> --format md
auditex report customer-pack <run-dir> --output-dir customer-pack
auditex report verify-pack customer-pack
auditex report explorer <run-dir>
auditex report explorer <run-dir> --compare <previous-run-dir>
auditex compare --run-dir run-a --run-dir run-b
auditex export list

Start customer review with the handoff output, then inspect the API and permission ledgers, proof table, data-handling.json, and validation.json. Partial runs should be explained with their blocker and readiness artifacts rather than presented as complete coverage.

MCP

Run the local MCP server after installing the mcp extra:

auditex-mcp

The MCP registry exposes inventory and contract inspection, offline validation, Microsoft 365 and Google Workspace audit/probe operations, run summaries and comparisons, reports and proof tables, customer-pack verification, exports, notifications, rules, auth status, and setup guides. Audit operations retain the same read-only and no-content-read boundary as the CLI. No MCP tool takes a bearer token or client secret; app credentials come from the server's environment. Every path argument is confined to AUDITEX_MCP_ROOT (default: the server's working directory).

Documentation

Use docs/index.md as the documentation index.

• The runbook covers setup, operator flows, local checks, and the separate lab bootstrap kit.
• The product manual explains the product workflows.
• The setup guide and the administrator permission guide cover access planning.
• The security and privacy model describes data handling and audit boundaries.
• The customer handoff guide covers review packs.
• The troubleshooting guide covers common failures.
• AGENTS.md contains repository-specific development rules.
• .github/CONTRIBUTING.md covers development setup and review expectations.
• .github/SUPPORT.md explains how to request help and report product issues.

Keep .venv/, .secrets/, tenant evidence, and generated output directories local. Never commit tokens, OAuth caches, service-account keys, or tenant evidence. Do not add external telemetry.

Licence

Auditex is open source under the Apache License 2.0. See LICENSE and NOTICE; the fuller dependency inventory is in third-party notices. Security reporting instructions are in .github/SECURITY.md. Trademark information is in docs/legal/trademarks.md. Contributions: see CONTRIBUTING.

© 2026 MAGRATHEAN UK LTD · Legal