Skip to content

Extract Exchange Online information

Jump to bottom
directorcia edited this page Feb 1, 2026 · 3 revisions

Purpose

exo-extract.ps1 extracts Exchange Online configuration, security, and compliance settings and writes them to JSON files for analysis or archiving. It produces a full configuration snapshot, plus AI-optimized summaries.

High-Level Execution Flow

  1. Parameter parsing and defaults

    • Requires -TenantDomain.
    • Optional parameters: -OutputFolder, -Compact, -Credential, -SkipConnection, -ConnectionRetries, -MaxRetries, -JsonDepth.
    • Initializes global counters and tracking collections for errors, warnings, timings, and export metadata.

  2. Output directory setup

    • If -OutputFolder is provided, it is used directly.
    • Otherwise, the output directory defaults to the parent of the script folder.
    • Creates the output directory if it does not exist.
    • Builds a timestamp and a sanitized tenant identifier for filenames.

  3. Module validation

    • Requires the ExchangeOnlineManagement module; if missing, the script stops.

  4. Connection logic

    • Tests for an active Exchange Online session using Get-ConnectionInformation and a validation call to Get-OrganizationConfig.
    • If -SkipConnection is provided and there is no active session, the script exits.
    • Otherwise, attempts connection with retry logic:
      • Interactive login if -Credential is not provided.
      • Uses retry delays and reports failures.

  5. Pre-collection summary

    • Prints a banner with tenant, user, PowerShell version, module version, output directory, and retry settings.
    • Lists all categories that will be collected.

  6. Category collection loop

    • Iterates through a predefined list of categories.
    • Each category has:
      • Name
      • Command (script block)
      • Description
      • Critical flag
    • For each category:
      • Displays progress
      • Executes the command via retry logic
      • Tracks count, duration, and success
      • Records timings and per-category statistics
      • Logs success or failure (critical vs non-critical)

  7. Summary assembly and export

    • Aggregates all raw results into a single full summary object.
    • Writes JSON using ConvertTo-Json with configurable depth.

  8. Compact summary export

    • Builds a compact, AI-optimized summary with key fields and samples.
    • Includes counts, samples, and selected properties to reduce size.

  9. Ultra-compact summary (optional)

    • If -Compact is set, produces an ultra-compact summary for instant analysis.
    • Includes minimal metadata, quick stats, and critical indicators.

  10. Final report

    • Displays generated file names.
    • Summarizes total categories collected and total time.
    • Prints actionable errors and warnings separately from generic retry failures.

Parameters

  • TenantDomain (required): Tenant domain (e.g., contoso.onmicrosoft.com).
  • OutputFolder (optional): Output directory for JSON files.
  • Compact (optional switch): Generate ultra-compact summary in addition to full and compact summaries.
  • MaxRetries (optional, default 3): Retry attempts for data collection commands.
  • SkipConnection (optional switch): Skip connection attempt if already connected.
  • Credential (optional): PSCredential object for non-interactive login.
  • ConnectionRetries (optional, default 3): Retry attempts for connection.
  • JsonDepth (optional, default 64): JSON serialization depth.

Helper Functions (Behavior)

  • Invoke-WithRetry

    • Executes a script block with retry logic.
    • Retries on transient errors (timeout, throttling, network issues).
    • Logs critical vs non-critical failures.

  • Write-Warn / Write-Err / Write-Info / Write-Stat

    • Output helpers that also track global warning/error counts.

  • Format-TimeSpan

    • Formats durations into human-readable seconds, minutes, or hours.

  • Get-SafeCount

    • Counts items safely across nulls and enumerables.

  • Save-Json

    • Ensures .json extension.
    • Skips empty data.
    • Writes UTF-8 JSON and records file size metadata.

Collected Categories

Each category is collected using the listed cmdlet(s), with retries and timing:

  • Organization config (Get-OrganizationConfig) — Critical
  • Mailboxes (Get-Mailbox -ResultSize Unlimited | Select-Object *) — Critical
  • Mailbox permissions (Get-MailboxPermission per mailbox) — Critical
  • Transport rules (Get-TransportRule) — Critical
  • Retention policies (Get-RetentionPolicy) — Non-critical
  • Retention policy tags (Get-RetentionPolicyTag) — Non-critical
  • Mobile device policies (Get-MobileDeviceMailboxPolicy) — Non-critical
  • Inbound connectors (Get-InboundConnector) — Non-critical
  • Outbound connectors (Get-OutboundConnector) — Non-critical
  • Accepted domains (Get-AcceptedDomain) — Critical
  • Remote domains (Get-RemoteDomain) — Non-critical
  • Journaling rules (Get-JournalRule) — Non-critical
  • Anti-spam policies (Get-HostedContentFilterPolicy) — Critical
  • Anti-malware policies (Get-MalwareFilterPolicy) — Critical
  • Safe Links policies (Get-SafeLinksPolicy) — Non-critical
  • Safe Attachments policies (Get-SafeAttachmentPolicy) — Non-critical
  • Sharing policies (Get-SharingPolicy) — Non-critical
  • Email address policies (Get-EmailAddressPolicy) — Non-critical
  • OWA policies (Get-OwaMailboxPolicy) — Non-critical
  • Anti-phishing policies (Get-AntiPhishPolicy) — Critical
  • ATP policies (Get-AtpPolicyForO365) — Critical
  • Distribution groups + members (Get-DistributionGroup + Get-DistributionGroupMember) — Non-critical
  • Unified groups + members (Get-UnifiedGroup + Get-UnifiedGroupLinks) — Non-critical

Output Files (JSON Only)

The script creates files in the output directory. Filenames include a sanitized tenant domain and timestamp.

  1. Full summary

    • Filename pattern: exo_summary_<tenant>_<timestamp>.json
    • Contains complete, unfiltered data for all categories, plus metadata:
      • Error/warning counts
      • Per-category timings
      • Export metadata (file sizes)
      • Collection date

  2. Compact summary

    • Filename pattern: exo_summary_<tenant>_<timestamp>_compact.json
    • AI-optimized selection of fields and samples:
      • Mailboxes: first 200
      • Mailbox permissions: first 400
      • Transport rules: first 100
      • Retention policy/tag samples: first 50
      • Most other policies: first 25
      • Distribution/Unified groups: first 75 groups with limited member samples

  3. Ultra-compact summary (only if -Compact is specified)

    • Filename pattern: exo_summary_<tenant>_<timestamp>_ultra-compact.json
    • Minimal snapshot with counts and health indicators:
      • Total counts for mailboxes, rules, domains, groups
      • Security policy counts
      • Critical category presence
      • Error and warning counts

Error and Warning Handling

  • Errors and warnings are tracked globally.
  • At the end, the script separates:
    • Actionable errors/warnings (specific failures)
    • Generic retry failures (non-specific collection failures)
  • Final output summarizes counts and actionable items.

Operational Notes

  • JSON depth defaults to 64 to avoid truncation of deeply nested objects.
  • For empty collections, files are skipped rather than creating empty JSON.
  • Transport rules are treated as informational when empty.
  • The script reports timing per category and total execution time.

Intended Use Cases

  • Compliance review and archiving
  • Configuration drift analysis
  • Security posture and policy review
  • AI-assisted analysis of EXO configuration

Clone this wiki locally