Exporting Purview DLP configuration for your tenant

Prev Next

This document describes two companion PowerShell scripts that export a customer’s Microsoft Purview Data Loss Prevention (DLP) configuration — custom Sensitive Information Types (SITs), SIT rule packages, keyword dictionaries, DLP policies, and DLP rules — directly from Security & Compliance PowerShell. It is intended for eShare to evaluate a prospective or existing customer’s Microsoft 365 tenant. The following topics are covered:

Prerequisites

REQUIREMENT:

These scripts are typically run with Global Administrator access in the customer’s tenant.

Note:

Both scripts are read-only — they call only Get-* cmdlets and make no changes to the tenant.

Why This Is Needed and What It’s Used For

Neither script is something to run casually against a customer’s tenant — it pulls their live DLP configuration, so it has to come with a clear reason and the customer’s sign-off. There are two reasons we ask for it:

  • CAS report enrichment. The exported SITs, policies, and rules show exactly what DLP controls the customer already has in place in Purview. That turns the CAS report from a generic assessment into one grounded in the customer’s actual configuration — what’s being inspected, where, and what happens when it matches.

  • Mimicking the customer’s tenant for POC or testing. The exported rule-package XML is re-importable directly with New-DlpSensitiveInformationTypeRulePackage, and the exported policy and rule data carries the full definitions needed to recreate matching DLP policies and rules elsewhere. That lets us stand up a test or POC tenant that mirrors the customer’s actual Purview setup — useful for reproducing an issue, validating a fix, or demoing eShare against the customer’s own SIT/DLP configuration without needing further access to their live tenant.

Export-PurviewDlp (Commercial )

This is the default script, used for Commercial tenants. It connects to Security & Compliance PowerShell and exports:

  • Custom SITs — anything not published by Microsoft Corporation

  • Keyword dictionaries referenced by custom SITs

  • DLP policies — mode, priority, workloads, included/excluded locations

  • DLP rules — parent policy, SITs used, actions, notifications, severity

  • A summary.txt with counts and the tenant/account the export came from

Key parameters: OutputPath (defaults to a timestamped folder in the current directory), UserPrincipalName (optional — prompts for sign-in if omitted), Environment (Commercial), and KeepSession (leaves the Security & Compliance session connected when the script finishes).

Example: ./Export-PurviewDlp_v1.1.ps1 -UserPrincipalName admin@eshare.com

Copy the below script or download the file

Export-PurviewDlp_v1.1
18.14 KB

Expand this section to copy the script

  <#
.SYNOPSIS
    Exports custom sensitive information types (SITs), DLP policies and DLP rules from Microsoft Purview.

.DESCRIPTION
    Read-only: calls only Get-* cmdlets from Security & Compliance PowerShell. Nothing in the tenant is changed.

    Writes to a timestamped folder:
      custom-sits.csv / .json            Custom SITs (anything not published by Microsoft Corporation)
      rule-packages\<n>.xml              Full XML of each non-built-in SIT rule package: the actual
                                         definitions (regexes, keyword lists, proximity, confidence levels).
                                         This is what you would re-import with New-DlpSensitiveInformationTypeRulePackage.
      keyword-dictionaries.csv / .json   Keyword dictionaries (custom SITs can reference these)
      dlp-policies.csv / .json           DLP policies: mode, priority, workloads, included/excluded locations
      dlp-rules.csv / .json              DLP rules: parent policy, SITs used, actions, notifications, severity
      summary.txt                        Counts and the tenant/account the export came from

    The CSVs are for reading in Excel; the JSON files hold every property, including the full
    rule conditions (ContentContainsSensitiveInformation, AdvancedRule) that a CSV cell cannot.

    Requirements:
      - PowerShell 7+ (or Windows PowerShell 5.1)
      - ExchangeOnlineManagement module 3.x:  Install-Module ExchangeOnlineManagement -Scope CurrentUser
      - A role that can read DLP configuration, e.g. Compliance Administrator,
        Compliance Data Administrator, or View-Only DLP Compliance Management

    Changes in v1.1:
      - Fixed JSON export failing with "The type 'System.Collections.Hashtable' is not supported for
        serialization or deserialization of a dictionary. Keys must be strings." (non-string dictionary
        keys such as CultureInfo are now converted before serialization).
      - Fixed empty CSV handling when a category has zero objects.
      - Rule package files no longer overwrite each other when two packages share a name.
      - summary.txt now records the signed-in account and tenant ID from the live session.
      - dlp-rules.csv gains EndpointDlpRestrictions and RestrictAccess columns (compact JSON).

.PARAMETER OutputPath
    Folder to write to. Defaults to .\purview-export-<yyyyMMdd-HHmmss>.

.PARAMETER UserPrincipalName
    Account to sign in with. Optional; you are prompted if omitted.

.PARAMETER Environment
    Commercial (default; also covers GCC), GCCHigh or DoD.

.PARAMETER KeepSession
    Leave the Security & Compliance session connected when the script finishes.

.EXAMPLE
    ./Export-PurviewDlp_v1.1.ps1 -UserPrincipalName admin@eshare.com

.EXAMPLE
    ./Export-PurviewDlp_v1.1.ps1 -Environment GCCHigh -OutputPath ./gov-purview-export
#>
[CmdletBinding()]
param(
    [string]$OutputPath = (Join-Path -Path (Get-Location) -ChildPath ('purview-export-' + (Get-Date -Format 'yyyyMMdd-HHmmss'))),
    [string]$UserPrincipalName,
    [ValidateSet('Commercial', 'GCCHigh', 'DoD')]
    [string]$Environment = 'Commercial',
    [switch]$KeepSession
)

$ErrorActionPreference = 'Stop'

# The built-in Microsoft SIT definitions live in this rule package. It is large and identical in every
# tenant, so it is skipped; every other rule package (where portal-created custom SITs, document
# fingerprints and imported XML packages live) is exported.
$BuiltInRulePackageName = 'Microsoft Rule Package'

function Join-Values {
    # Flattens a property (string, array of strings, or array of location objects) into one "; "-separated cell.
    param($Value)
    if ($null -eq $Value) { return '' }
    if ($Value -is [string]) { return $Value }
    $items = foreach ($v in $Value) {
        if ($null -eq $v) { continue }
        if ($v -is [string]) { $v }
        elseif ($v.PSObject.Properties['DisplayName'] -and $v.DisplayName) { $v.DisplayName }
        elseif ($v.PSObject.Properties['Name'] -and $v.Name) { $v.Name }
        else { "$v" }
    }
    (@($items) | Where-Object { $_ }) -join '; '
}

function ConvertTo-JsonSafe {
    # Recursively copies an object into plain ordered hashtables, arrays and scalars so ConvertTo-Json
    # cannot trip on non-string dictionary keys (e.g. CultureInfo) or odd .NET types.
    param($InputObject, [int]$Depth = 0)
    if ($null -eq $InputObject) { return $null }
    if ($InputObject -is [string]) { return $InputObject }
    if ($Depth -gt 10) { return "$InputObject" }                        # depth guard: stringify anything deeper
    if ($InputObject -is [enum]) { return "$InputObject" }
    if ($InputObject -is [ValueType]) { return $InputObject }           # numbers, bool, datetime, guid
    if ($InputObject -is [System.Collections.IDictionary]) {
        $out = [ordered]@{}
        foreach ($k in $InputObject.Keys) {
            $out["$k"] = ConvertTo-JsonSafe $InputObject[$k] ($Depth + 1)   # "$k" forces string keys
        }
        return $out
    }
    if ($InputObject -is [System.Collections.IEnumerable]) {
        $list = [System.Collections.Generic.List[object]]::new()
        foreach ($i in $InputObject) { $list.Add((ConvertTo-JsonSafe $i ($Depth + 1))) }
        return , $list.ToArray()                                        # leading comma stops PowerShell unrolling the array
    }
    $out = [ordered]@{}
    foreach ($p in $InputObject.PSObject.Properties) {
        try { $out[$p.Name] = ConvertTo-JsonSafe $p.Value ($Depth + 1) }
        catch { $out[$p.Name] = $null }                                 # skip properties whose getter throws
    }
    $out
}

function ConvertTo-CompactJson {
    # Single-cell JSON for properties that are too structured for a flat CSV column.
    param($Value)
    if ($null -eq $Value) { return '' }
    ConvertTo-Json -InputObject (ConvertTo-JsonSafe $Value) -Depth 12 -Compress -WarningAction SilentlyContinue
}

function Get-SitName {
    # Walks a rule's ContentContainsSensitiveInformation (hashtables, possibly nested in groups) or its
    # parsed AdvancedRule JSON, and returns the names of the SITs it references. A SIT entry is any node
    # that has a name plus an id or a min count; group nodes have a name but neither, so they are skipped.
    param($Node)
    if ($null -eq $Node -or $Node -is [string] -or $Node -is [ValueType]) { return }
    if ($Node -is [System.Collections.IDictionary]) {
        $map = @{}  # case-insensitive copy: the key casing differs between cmdlet output and AdvancedRule JSON
        foreach ($k in $Node.Keys) { $map["$k"] = $Node[$k] }
        if ($map.ContainsKey('name') -and ($map.ContainsKey('id') -or $map.ContainsKey('mincount'))) { $map['name'] }
        foreach ($v in $map.Values) { Get-SitName $v }
        return
    }
    if ($Node.GetType().FullName -eq 'System.Management.Automation.PSCustomObject') {
        $names = @($Node.PSObject.Properties.Name)
        if ($names -contains 'Name' -and ($names -contains 'Id' -or $names -contains 'MinCount')) { $Node.Name }
        foreach ($p in $Node.PSObject.Properties) { Get-SitName $p.Value }
        return
    }
    if ($Node -is [System.Collections.IEnumerable]) {
        foreach ($v in $Node) { Get-SitName $v }
    }
}

function Save-Export {
    # Writes the full objects as JSON (via ConvertTo-JsonSafe) and the given flattened rows as CSV.
    param($Objects, $Rows, [string]$BaseName)
    $safe = ConvertTo-JsonSafe @($Objects | Where-Object { $null -ne $_ })
    ConvertTo-Json -InputObject $safe -Depth 12 -WarningAction SilentlyContinue |
        Set-Content -Path (Join-Path $OutputPath "$BaseName.json") -Encoding UTF8
    $realRows = @($Rows | Where-Object { $null -ne $_ })                # avoids the @($null).Count -eq 1 quirk
    if ($realRows.Count -gt 0) {
        $realRows | Export-Csv -Path (Join-Path $OutputPath "$BaseName.csv") -NoTypeInformation -Encoding UTF8
    }
}

# --- Connect -------------------------------------------------------------------------------------------

if (-not (Get-Module -ListAvailable -Name ExchangeOnlineManagement)) {
    throw 'ExchangeOnlineManagement module not found. Install it with: Install-Module ExchangeOnlineManagement -Scope CurrentUser'
}
Import-Module ExchangeOnlineManagement

$connectParams = @{}
if ($UserPrincipalName) { $connectParams.UserPrincipalName = $UserPrincipalName }
switch ($Environment) {
    'GCCHigh' {
        $connectParams.ConnectionUri = 'https://ps.compliance.protection.office365.us/powershell-liveid/'
        $connectParams.AzureADAuthorizationEndpointUri = 'https://login.microsoftonline.us/common'
    }
    'DoD' {
        $connectParams.ConnectionUri = 'https://l5.ps.compliance.protection.office365.us/powershell-liveid/'
        $connectParams.AzureADAuthorizationEndpointUri = 'https://login.microsoftonline.us/common'
    }
}

Write-Host "Connecting to Security & Compliance PowerShell ($Environment)..."
Connect-IPPSSession @connectParams

# Record who/what we actually connected as, for summary.txt. Best-effort: older module builds may not
# expose Get-ConnectionInformation or these property names, in which case the summary falls back gracefully.
$connectedAccount = $null
$connectedTenantId = $null
try {
    $conn = Get-ConnectionInformation | Select-Object -First 1
    if ($conn) {
        $connectedAccount = $conn.UserPrincipalName
        $connectedTenantId = $conn.TenantID
    }
}
catch { Write-Verbose "Get-ConnectionInformation unavailable: $($_.Exception.Message)" }

try {
    New-Item -ItemType Directory -Path $OutputPath -Force | Out-Null
    $rulePackDir = Join-Path $OutputPath 'rule-packages'
    New-Item -ItemType Directory -Path $rulePackDir -Force | Out-Null

    # --- Custom sensitive information types ------------------------------------------------------------

    Write-Host 'Exporting custom sensitive information types...'
    $customSits = @(Get-DlpSensitiveInformationType | Where-Object { $_.Publisher -ne 'Microsoft Corporation' })
    $sitRows = foreach ($s in $customSits) {
        [pscustomobject]@{
            Name                  = $s.Name
            Id                    = $s.Id
            Publisher             = $s.Publisher
            Description           = $s.Description
            RecommendedConfidence = $s.RecommendedConfidence
            RulePackId            = $s.RulePackId
        }
    }
    Save-Export -Objects $customSits -Rows $sitRows -BaseName 'custom-sits'

    Write-Host 'Exporting SIT rule packages (XML definitions)...'
    $rulePacks = @(Get-DlpSensitiveInformationTypeRulePackage)
    $exportedPacks = @()
    $usedFileNames = @{}   # tracks filenames already written so duplicate package names don't overwrite each other
    foreach ($pack in $rulePacks) {
        $packName = if ($pack.Name) { "$($pack.Name)" } else { "$($pack.Identity)" }
        if ($packName -eq $BuiltInRulePackageName) {
            Write-Host "  skipping built-in rule package '$packName'"
            continue
        }
        $safeName = $packName -replace '[\\/:*?"<>|]', '_'
        if ($usedFileNames.ContainsKey($safeName.ToLowerInvariant())) {
            # Collision: disambiguate with the package identity (sanitized), or a counter as a last resort.
            $idPart = ("$($pack.Identity)" -replace '[\\/:*?"<>|]', '_')
            $safeName = if ($idPart -and $idPart -ne $safeName) { "${safeName}_$idPart" } else { "${safeName}_$($usedFileNames.Count)" }
        }
        $usedFileNames[$safeName.ToLowerInvariant()] = $true
        $file = Join-Path $rulePackDir "$safeName.xml"
        [System.IO.File]::WriteAllBytes($file, [byte[]]$pack.SerializedClassificationRuleCollection)
        Write-Host "  $packName -> $file"
        $exportedPacks += $packName
    }

    Write-Host 'Exporting keyword dictionaries...'
    $dictionaries = @(Get-DlpKeywordDictionary)
    $dictRows = foreach ($d in $dictionaries) {
        [pscustomobject]@{
            Name        = $d.Name
            Identity    = $d.Identity
            Description = $d.Description
        }
    }
    Save-Export -Objects $dictionaries -Rows $dictRows -BaseName 'keyword-dictionaries'

    # --- DLP policies ----------------------------------------------------------------------------------

    Write-Host 'Exporting DLP policies...'
    $policies = @(Get-DlpCompliancePolicy)
    $rules = @(Get-DlpComplianceRule)

    $policyRows = foreach ($p in $policies) {
        [pscustomobject]@{
            Name                                  = $p.Name
            Guid                                  = $p.Guid
            Mode                                  = $p.Mode
            Enabled                               = $p.Enabled
            Priority                              = $p.Priority
            Workload                              = Join-Values $p.Workload
            RuleCount                             = @($rules | Where-Object { "$($_.Policy)" -eq "$($p.Guid)" -or $_.ParentPolicyName -eq $p.Name }).Count
            ExchangeLocation                      = Join-Values $p.ExchangeLocation
            ExchangeSenderMemberOf                = Join-Values $p.ExchangeSenderMemberOf
            ExchangeSenderMemberOfException       = Join-Values $p.ExchangeSenderMemberOfException
            SharePointLocation                    = Join-Values $p.SharePointLocation
            SharePointLocationException           = Join-Values $p.SharePointLocationException
            OneDriveLocation                      = Join-Values $p.OneDriveLocation
            OneDriveLocationException             = Join-Values $p.OneDriveLocationException
            TeamsLocation                         = Join-Values $p.TeamsLocation
            TeamsLocationException                = Join-Values $p.TeamsLocationException
            EndpointDlpLocation                   = Join-Values $p.EndpointDlpLocation
            EndpointDlpLocationException          = Join-Values $p.EndpointDlpLocationException
            OnPremisesScannerDlpLocation          = Join-Values $p.OnPremisesScannerDlpLocation
            OnPremisesScannerDlpLocationException = Join-Values $p.OnPremisesScannerDlpLocationException
            ThirdPartyAppDlpLocation              = Join-Values $p.ThirdPartyAppDlpLocation
            ThirdPartyAppDlpLocationException     = Join-Values $p.ThirdPartyAppDlpLocationException
            PowerBIDlpLocation                    = Join-Values $p.PowerBIDlpLocation
            PowerBIDlpLocationException           = Join-Values $p.PowerBIDlpLocationException
            DistributionStatus                    = $p.DistributionStatus
            Comment                               = $p.Comment
            CreatedBy                             = $p.CreatedBy
            LastModifiedBy                        = $p.LastModifiedBy
            WhenCreatedUTC                        = $p.WhenCreatedUTC
            WhenChangedUTC                        = $p.WhenChangedUTC
        }
    }
    Save-Export -Objects $policies -Rows $policyRows -BaseName 'dlp-policies'

    # --- DLP rules -------------------------------------------------------------------------------------

    Write-Host 'Exporting DLP rules...'
    $ruleRows = foreach ($r in $rules) {
        $sitNames = @(
            Get-SitName $r.ContentContainsSensitiveInformation
            if ($r.AdvancedRule) {
                try { Get-SitName ($r.AdvancedRule | ConvertFrom-Json) }
                catch { Write-Warning "Could not parse AdvancedRule on rule '$($r.Name)'; see dlp-rules.json for the raw text." }
            }
        )
        $exceptSitNames = @(Get-SitName $r.ExceptIfContentContainsSensitiveInformation)

        [pscustomobject]@{
            Name                      = $r.Name
            Guid                      = $r.Guid
            Policy                    = $r.ParentPolicyName
            Priority                  = $r.Priority
            Disabled                  = $r.Disabled
            Mode                      = $r.Mode
            SensitiveInfoTypes        = (@($sitNames | Where-Object { $_ }) | Sort-Object -Unique) -join '; '
            ExceptSensitiveInfoTypes  = (@($exceptSitNames | Where-Object { $_ }) | Sort-Object -Unique) -join '; '
            UsesAdvancedRule          = [bool]$r.AdvancedRule
            AccessScope               = $r.AccessScope
            BlockAccess               = $r.BlockAccess
            BlockAccessScope          = $r.BlockAccessScope
            RestrictAccess            = ConvertTo-CompactJson $r.RestrictAccess
            EndpointDlpRestrictions   = ConvertTo-CompactJson $r.EndpointDlpRestrictions
            NotifyUser                = Join-Values $r.NotifyUser
            NotifyPolicyTipCustomText = $r.NotifyPolicyTipCustomText
            NotifyAllowOverride       = Join-Values $r.NotifyAllowOverride
            GenerateAlert             = Join-Values $r.GenerateAlert
            GenerateIncidentReport    = Join-Values $r.GenerateIncidentReport
            ReportSeverityLevel       = $r.ReportSeverityLevel
            Comment                   = $r.Comment
            LastModifiedBy            = $r.LastModifiedBy
            WhenChangedUTC            = $r.WhenChangedUTC
        }
    }
    Save-Export -Objects $rules -Rows $ruleRows -BaseName 'dlp-rules'

    # --- Summary ---------------------------------------------------------------------------------------

    $accountLine = if ($connectedAccount) { $connectedAccount }
                   elseif ($UserPrincipalName) { $UserPrincipalName }
                   else { '(interactive sign-in)' }
    $tenantLine = if ($connectedTenantId) { $connectedTenantId } else { '(unavailable)' }

    $summary = @(
        "Purview DLP export"
        "Exported:     $((Get-Date).ToUniversalTime().ToString('yyyy-MM-dd HH:mm:ss')) UTC"
        "Environment:  $Environment"
        "Account:      $accountLine"
        "Tenant ID:    $tenantLine"
        ''
        "Custom SITs:          $($customSits.Count)"
        "Rule packages (XML):  $($exportedPacks.Count)  [$($exportedPacks -join ', ')]"
        "Keyword dictionaries: $($dictionaries.Count)"
        "DLP policies:         $($policies.Count)"
        "DLP rules:            $($rules.Count)"
    )
    $summary | Set-Content -Path (Join-Path $OutputPath 'summary.txt') -Encoding UTF8
    ''
    $summary
    ''
    Write-Host "Done. Output: $OutputPath"
}
finally {
    if (-not $KeepSession) {
        Disconnect-ExchangeOnline -Confirm:$false -ErrorAction SilentlyContinue
    }
}

Export-PurviewDlp-GCCH (GCC High)

This is the hardened variant for GCC High tenants. It defaults to the US Government sovereign cloud endpoints and the login.microsoftonline.us authorization endpoint, and fails fast if the ExchangeOnlineManagement module is older than 3.2.0, since GCC High requires REST mode (the legacy RPS mode needs WinRM Basic auth, which isn’t available on macOS). Everything else — the exported files and parameters — is identical to the Commercial script above.

Example: ./Export-PurviewDlp-GCCH_v1.1.ps1 -UserPrincipalName admin@contoso.onmicrosoft.us

Copy the below script or download the file

Export-PurviewDlp-GCCH_v1.1
19.56 KB

Expand this section to copy the script

  <#
.SYNOPSIS
    Exports custom sensitive information types (SITs), DLP policies and DLP rules from Microsoft Purview
    in a GCC High (default) or DoD tenant.

.DESCRIPTION
    Read-only: calls only Get-* cmdlets from Security & Compliance PowerShell. Nothing in the tenant is changed.

    This is the GCC High variant of Export-PurviewDlp. It connects to the US Government sovereign cloud
    endpoints by default:
      GCCHigh  ConnectionUri  https://ps.compliance.protection.office365.us/powershell-liveid/
      DoD      ConnectionUri  https://l5.ps.compliance.protection.office365.us/powershell-liveid/
      Both     Entra authorization endpoint  https://login.microsoftonline.us/common
    Sign in with a GCC High account (the Entra sign-in page will be login.microsoftonline.us, not
    login.microsoftonline.com). Commercial and GCC tenants should use Export-PurviewDlp_v1.1.ps1 instead.

    Writes to a timestamped folder:
      custom-sits.csv / .json            Custom SITs (anything not published by Microsoft Corporation)
      rule-packages\<n>.xml              Full XML of each non-built-in SIT rule package: the actual
                                         definitions (regexes, keyword lists, proximity, confidence levels).
                                         This is what you would re-import with New-DlpSensitiveInformationTypeRulePackage.
      keyword-dictionaries.csv / .json   Keyword dictionaries (custom SITs can reference these)
      dlp-policies.csv / .json           DLP policies: mode, priority, workloads, included/excluded locations
      dlp-rules.csv / .json              DLP rules: parent policy, SITs used, actions, notifications, severity
      summary.txt                        Counts and the tenant/account the export came from

    The CSVs are for reading in Excel; the JSON files hold every property, including the full
    rule conditions (ContentContainsSensitiveInformation, AdvancedRule) that a CSV cell cannot.

    Requirements:
      - PowerShell 7+ (or Windows PowerShell 5.1)
      - ExchangeOnlineManagement module 3.x:  Install-Module ExchangeOnlineManagement -Scope CurrentUser
      - A role that can read DLP configuration, e.g. Compliance Administrator,
        Compliance Data Administrator, or View-Only DLP Compliance Management

    Changes in v1.2 (GCC High variant):
      - Environment now defaults to GCCHigh and only accepts GCCHigh or DoD.
      - Default output folder is purview-gcch-export-<timestamp>.
      - Fails fast with a clear message if the module is older than 3.2.0 (REST mode is required;
        the legacy RPS mode needs WinRM Basic auth, which is not available on macOS).
      - Everything else is unchanged from v1.1.

    Changes in v1.1:
      - Fixed JSON export failing with "The type 'System.Collections.Hashtable' is not supported for
        serialization or deserialization of a dictionary. Keys must be strings." (non-string dictionary
        keys such as CultureInfo are now converted before serialization).
      - Fixed empty CSV handling when a category has zero objects.
      - Rule package files no longer overwrite each other when two packages share a name.
      - summary.txt now records the signed-in account and tenant ID from the live session.
      - dlp-rules.csv gains EndpointDlpRestrictions and RestrictAccess columns (compact JSON).

.PARAMETER OutputPath
    Folder to write to. Defaults to .\purview-export-<yyyyMMdd-HHmmss>.

.PARAMETER UserPrincipalName
    Account to sign in with. Optional; you are prompted if omitted.

.PARAMETER Environment
    GCCHigh (default) or DoD.

.PARAMETER KeepSession
    Leave the Security & Compliance session connected when the script finishes.

.EXAMPLE
    ./Export-PurviewDlp-GCCH_v1.2.ps1 -UserPrincipalName admin@contoso.onmicrosoft.us

.EXAMPLE
    ./Export-PurviewDlp-GCCH_v1.2.ps1 -Environment DoD -OutputPath ./dod-purview-export
#>
[CmdletBinding()]
param(
    [string]$OutputPath = (Join-Path -Path (Get-Location) -ChildPath ('purview-gcch-export-' + (Get-Date -Format 'yyyyMMdd-HHmmss'))),
    [string]$UserPrincipalName,
    [ValidateSet('GCCHigh', 'DoD')]
    [string]$Environment = 'GCCHigh',
    [switch]$KeepSession
)

$ErrorActionPreference = 'Stop'

# The built-in Microsoft SIT definitions live in this rule package. It is large and identical in every
# tenant, so it is skipped; every other rule package (where portal-created custom SITs, document
# fingerprints and imported XML packages live) is exported.
$BuiltInRulePackageName = 'Microsoft Rule Package'

function Join-Values {
    # Flattens a property (string, array of strings, or array of location objects) into one "; "-separated cell.
    param($Value)
    if ($null -eq $Value) { return '' }
    if ($Value -is [string]) { return $Value }
    $items = foreach ($v in $Value) {
        if ($null -eq $v) { continue }
        if ($v -is [string]) { $v }
        elseif ($v.PSObject.Properties['DisplayName'] -and $v.DisplayName) { $v.DisplayName }
        elseif ($v.PSObject.Properties['Name'] -and $v.Name) { $v.Name }
        else { "$v" }
    }
    (@($items) | Where-Object { $_ }) -join '; '
}

function ConvertTo-JsonSafe {
    # Recursively copies an object into plain ordered hashtables, arrays and scalars so ConvertTo-Json
    # cannot trip on non-string dictionary keys (e.g. CultureInfo) or odd .NET types.
    param($InputObject, [int]$Depth = 0)
    if ($null -eq $InputObject) { return $null }
    if ($InputObject -is [string]) { return $InputObject }
    if ($Depth -gt 10) { return "$InputObject" }                        # depth guard: stringify anything deeper
    if ($InputObject -is [enum]) { return "$InputObject" }
    if ($InputObject -is [ValueType]) { return $InputObject }           # numbers, bool, datetime, guid
    if ($InputObject -is [System.Collections.IDictionary]) {
        $out = [ordered]@{}
        foreach ($k in $InputObject.Keys) {
            $out["$k"] = ConvertTo-JsonSafe $InputObject[$k] ($Depth + 1)   # "$k" forces string keys
        }
        return $out
    }
    if ($InputObject -is [System.Collections.IEnumerable]) {
        $list = [System.Collections.Generic.List[object]]::new()
        foreach ($i in $InputObject) { $list.Add((ConvertTo-JsonSafe $i ($Depth + 1))) }
        return , $list.ToArray()                                        # leading comma stops PowerShell unrolling the array
    }
    $out = [ordered]@{}
    foreach ($p in $InputObject.PSObject.Properties) {
        try { $out[$p.Name] = ConvertTo-JsonSafe $p.Value ($Depth + 1) }
        catch { $out[$p.Name] = $null }                                 # skip properties whose getter throws
    }
    $out
}

function ConvertTo-CompactJson {
    # Single-cell JSON for properties that are too structured for a flat CSV column.
    param($Value)
    if ($null -eq $Value) { return '' }
    ConvertTo-Json -InputObject (ConvertTo-JsonSafe $Value) -Depth 12 -Compress -WarningAction SilentlyContinue
}

function Get-SitName {
    # Walks a rule's ContentContainsSensitiveInformation (hashtables, possibly nested in groups) or its
    # parsed AdvancedRule JSON, and returns the names of the SITs it references. A SIT entry is any node
    # that has a name plus an id or a min count; group nodes have a name but neither, so they are skipped.
    param($Node)
    if ($null -eq $Node -or $Node -is [string] -or $Node -is [ValueType]) { return }
    if ($Node -is [System.Collections.IDictionary]) {
        $map = @{}  # case-insensitive copy: the key casing differs between cmdlet output and AdvancedRule JSON
        foreach ($k in $Node.Keys) { $map["$k"] = $Node[$k] }
        if ($map.ContainsKey('name') -and ($map.ContainsKey('id') -or $map.ContainsKey('mincount'))) { $map['name'] }
        foreach ($v in $map.Values) { Get-SitName $v }
        return
    }
    if ($Node.GetType().FullName -eq 'System.Management.Automation.PSCustomObject') {
        $names = @($Node.PSObject.Properties.Name)
        if ($names -contains 'Name' -and ($names -contains 'Id' -or $names -contains 'MinCount')) { $Node.Name }
        foreach ($p in $Node.PSObject.Properties) { Get-SitName $p.Value }
        return
    }
    if ($Node -is [System.Collections.IEnumerable]) {
        foreach ($v in $Node) { Get-SitName $v }
    }
}

function Save-Export {
    # Writes the full objects as JSON (via ConvertTo-JsonSafe) and the given flattened rows as CSV.
    param($Objects, $Rows, [string]$BaseName)
    $safe = ConvertTo-JsonSafe @($Objects | Where-Object { $null -ne $_ })
    ConvertTo-Json -InputObject $safe -Depth 12 -WarningAction SilentlyContinue |
        Set-Content -Path (Join-Path $OutputPath "$BaseName.json") -Encoding UTF8
    $realRows = @($Rows | Where-Object { $null -ne $_ })                # avoids the @($null).Count -eq 1 quirk
    if ($realRows.Count -gt 0) {
        $realRows | Export-Csv -Path (Join-Path $OutputPath "$BaseName.csv") -NoTypeInformation -Encoding UTF8
    }
}

# --- Connect -------------------------------------------------------------------------------------------

if (-not (Get-Module -ListAvailable -Name ExchangeOnlineManagement)) {
    throw 'ExchangeOnlineManagement module not found. Install it with: Install-Module ExchangeOnlineManagement -Scope CurrentUser'
}
Import-Module ExchangeOnlineManagement

# REST mode (no WinRM) needs module 3.2.0+. Fail early with a clear message rather than a confusing connect error.
$exoModule = Get-Module -Name ExchangeOnlineManagement | Select-Object -First 1
if ($exoModule -and $exoModule.Version -lt [version]'3.2.0') {
    throw "ExchangeOnlineManagement $($exoModule.Version) is too old. Update with: Update-Module ExchangeOnlineManagement (3.2.0 or later required)."
}

$connectParams = @{}
if ($UserPrincipalName) { $connectParams.UserPrincipalName = $UserPrincipalName }
switch ($Environment) {
    'GCCHigh' {
        $connectParams.ConnectionUri = 'https://ps.compliance.protection.office365.us/powershell-liveid/'
        $connectParams.AzureADAuthorizationEndpointUri = 'https://login.microsoftonline.us/common'
    }
    'DoD' {
        $connectParams.ConnectionUri = 'https://l5.ps.compliance.protection.office365.us/powershell-liveid/'
        $connectParams.AzureADAuthorizationEndpointUri = 'https://login.microsoftonline.us/common'
    }
}

Write-Host "Connecting to Security & Compliance PowerShell ($Environment)..."
Connect-IPPSSession @connectParams

# Record who/what we actually connected as, for summary.txt. Best-effort: older module builds may not
# expose Get-ConnectionInformation or these property names, in which case the summary falls back gracefully.
$connectedAccount = $null
$connectedTenantId = $null
try {
    $conn = Get-ConnectionInformation | Select-Object -First 1
    if ($conn) {
        $connectedAccount = $conn.UserPrincipalName
        $connectedTenantId = $conn.TenantID
    }
}
catch { Write-Verbose "Get-ConnectionInformation unavailable: $($_.Exception.Message)" }

try {
    New-Item -ItemType Directory -Path $OutputPath -Force | Out-Null
    $rulePackDir = Join-Path $OutputPath 'rule-packages'
    New-Item -ItemType Directory -Path $rulePackDir -Force | Out-Null

    # --- Custom sensitive information types ------------------------------------------------------------

    Write-Host 'Exporting custom sensitive information types...'
    $customSits = @(Get-DlpSensitiveInformationType | Where-Object { $_.Publisher -ne 'Microsoft Corporation' })
    $sitRows = foreach ($s in $customSits) {
        [pscustomobject]@{
            Name                  = $s.Name
            Id                    = $s.Id
            Publisher             = $s.Publisher
            Description           = $s.Description
            RecommendedConfidence = $s.RecommendedConfidence
            RulePackId            = $s.RulePackId
        }
    }
    Save-Export -Objects $customSits -Rows $sitRows -BaseName 'custom-sits'

    Write-Host 'Exporting SIT rule packages (XML definitions)...'
    $rulePacks = @(Get-DlpSensitiveInformationTypeRulePackage)
    $exportedPacks = @()
    $usedFileNames = @{}   # tracks filenames already written so duplicate package names don't overwrite each other
    foreach ($pack in $rulePacks) {
        $packName = if ($pack.Name) { "$($pack.Name)" } else { "$($pack.Identity)" }
        if ($packName -eq $BuiltInRulePackageName) {
            Write-Host "  skipping built-in rule package '$packName'"
            continue
        }
        $safeName = $packName -replace '[\\/:*?"<>|]', '_'
        if ($usedFileNames.ContainsKey($safeName.ToLowerInvariant())) {
            # Collision: disambiguate with the package identity (sanitized), or a counter as a last resort.
            $idPart = ("$($pack.Identity)" -replace '[\\/:*?"<>|]', '_')
            $safeName = if ($idPart -and $idPart -ne $safeName) { "${safeName}_$idPart" } else { "${safeName}_$($usedFileNames.Count)" }
        }
        $usedFileNames[$safeName.ToLowerInvariant()] = $true
        $file = Join-Path $rulePackDir "$safeName.xml"
        [System.IO.File]::WriteAllBytes($file, [byte[]]$pack.SerializedClassificationRuleCollection)
        Write-Host "  $packName -> $file"
        $exportedPacks += $packName
    }

    Write-Host 'Exporting keyword dictionaries...'
    $dictionaries = @(Get-DlpKeywordDictionary)
    $dictRows = foreach ($d in $dictionaries) {
        [pscustomobject]@{
            Name        = $d.Name
            Identity    = $d.Identity
            Description = $d.Description
        }
    }
    Save-Export -Objects $dictionaries -Rows $dictRows -BaseName 'keyword-dictionaries'

    # --- DLP policies ----------------------------------------------------------------------------------

    Write-Host 'Exporting DLP policies...'
    $policies = @(Get-DlpCompliancePolicy)
    $rules = @(Get-DlpComplianceRule)

    $policyRows = foreach ($p in $policies) {
        [pscustomobject]@{
            Name                                  = $p.Name
            Guid                                  = $p.Guid
            Mode                                  = $p.Mode
            Enabled                               = $p.Enabled
            Priority                              = $p.Priority
            Workload                              = Join-Values $p.Workload
            RuleCount                             = @($rules | Where-Object { "$($_.Policy)" -eq "$($p.Guid)" -or $_.ParentPolicyName -eq $p.Name }).Count
            ExchangeLocation                      = Join-Values $p.ExchangeLocation
            ExchangeSenderMemberOf                = Join-Values $p.ExchangeSenderMemberOf
            ExchangeSenderMemberOfException       = Join-Values $p.ExchangeSenderMemberOfException
            SharePointLocation                    = Join-Values $p.SharePointLocation
            SharePointLocationException           = Join-Values $p.SharePointLocationException
            OneDriveLocation                      = Join-Values $p.OneDriveLocation
            OneDriveLocationException             = Join-Values $p.OneDriveLocationException
            TeamsLocation                         = Join-Values $p.TeamsLocation
            TeamsLocationException                = Join-Values $p.TeamsLocationException
            EndpointDlpLocation                   = Join-Values $p.EndpointDlpLocation
            EndpointDlpLocationException          = Join-Values $p.EndpointDlpLocationException
            OnPremisesScannerDlpLocation          = Join-Values $p.OnPremisesScannerDlpLocation
            OnPremisesScannerDlpLocationException = Join-Values $p.OnPremisesScannerDlpLocationException
            ThirdPartyAppDlpLocation              = Join-Values $p.ThirdPartyAppDlpLocation
            ThirdPartyAppDlpLocationException     = Join-Values $p.ThirdPartyAppDlpLocationException
            PowerBIDlpLocation                    = Join-Values $p.PowerBIDlpLocation
            PowerBIDlpLocationException           = Join-Values $p.PowerBIDlpLocationException
            DistributionStatus                    = $p.DistributionStatus
            Comment                               = $p.Comment
            CreatedBy                             = $p.CreatedBy
            LastModifiedBy                        = $p.LastModifiedBy
            WhenCreatedUTC                        = $p.WhenCreatedUTC
            WhenChangedUTC                        = $p.WhenChangedUTC
        }
    }
    Save-Export -Objects $policies -Rows $policyRows -BaseName 'dlp-policies'

    # --- DLP rules -------------------------------------------------------------------------------------

    Write-Host 'Exporting DLP rules...'
    $ruleRows = foreach ($r in $rules) {
        $sitNames = @(
            Get-SitName $r.ContentContainsSensitiveInformation
            if ($r.AdvancedRule) {
                try { Get-SitName ($r.AdvancedRule | ConvertFrom-Json) }
                catch { Write-Warning "Could not parse AdvancedRule on rule '$($r.Name)'; see dlp-rules.json for the raw text." }
            }
        )
        $exceptSitNames = @(Get-SitName $r.ExceptIfContentContainsSensitiveInformation)

        [pscustomobject]@{
            Name                      = $r.Name
            Guid                      = $r.Guid
            Policy                    = $r.ParentPolicyName
            Priority                  = $r.Priority
            Disabled                  = $r.Disabled
            Mode                      = $r.Mode
            SensitiveInfoTypes        = (@($sitNames | Where-Object { $_ }) | Sort-Object -Unique) -join '; '
            ExceptSensitiveInfoTypes  = (@($exceptSitNames | Where-Object { $_ }) | Sort-Object -Unique) -join '; '
            UsesAdvancedRule          = [bool]$r.AdvancedRule
            AccessScope               = $r.AccessScope
            BlockAccess               = $r.BlockAccess
            BlockAccessScope          = $r.BlockAccessScope
            RestrictAccess            = ConvertTo-CompactJson $r.RestrictAccess
            EndpointDlpRestrictions   = ConvertTo-CompactJson $r.EndpointDlpRestrictions
            NotifyUser                = Join-Values $r.NotifyUser
            NotifyPolicyTipCustomText = $r.NotifyPolicyTipCustomText
            NotifyAllowOverride       = Join-Values $r.NotifyAllowOverride
            GenerateAlert             = Join-Values $r.GenerateAlert
            GenerateIncidentReport    = Join-Values $r.GenerateIncidentReport
            ReportSeverityLevel       = $r.ReportSeverityLevel
            Comment                   = $r.Comment
            LastModifiedBy            = $r.LastModifiedBy
            WhenChangedUTC            = $r.WhenChangedUTC
        }
    }
    Save-Export -Objects $rules -Rows $ruleRows -BaseName 'dlp-rules'

    # --- Summary ---------------------------------------------------------------------------------------

    $accountLine = if ($connectedAccount) { $connectedAccount }
                   elseif ($UserPrincipalName) { $UserPrincipalName }
                   else { '(interactive sign-in)' }
    $tenantLine = if ($connectedTenantId) { $connectedTenantId } else { '(unavailable)' }

    $summary = @(
        "Purview DLP export"
        "Exported:     $((Get-Date).ToUniversalTime().ToString('yyyy-MM-dd HH:mm:ss')) UTC"
        "Environment:  $Environment"
        "Account:      $accountLine"
        "Tenant ID:    $tenantLine"
        ''
        "Custom SITs:          $($customSits.Count)"
        "Rule packages (XML):  $($exportedPacks.Count)  [$($exportedPacks -join ', ')]"
        "Keyword dictionaries: $($dictionaries.Count)"
        "DLP policies:         $($policies.Count)"
        "DLP rules:            $($rules.Count)"
    )
    $summary | Set-Content -Path (Join-Path $OutputPath 'summary.txt') -Encoding UTF8
    ''
    $summary
    ''
    Write-Host "Done. Output: $OutputPath"
}
finally {
    if (-not $KeepSession) {
        Disconnect-ExchangeOnline -Confirm:$false -ErrorAction SilentlyContinue
    }
}