Sender List Information via API

Powershell Script Example 

This Powershell script that will capture a domain, data stack (us1, us2, us3, us4, us5, eu1) and your credentials for Proofpoint Essentials. The script will then run and capture, via the API, the sender list data and compile it into 4 .CSV files that will separate User (Blocked & Safe) Senders as well as Org (Blocked & Safe) Senders. 

Powershell Script: (To copy the script without the referencing numbers, hover over the script to get the Code View and Print Options, click on the Code View (looks like two brackets <>).

<#
    .REQUIREMENTS
        * API v1 from Proofpoint Essentials
        [Documentation: https://us1.proofpointessentials.com/api/v1/docs/specification.php]

        * Administrator Account for Proofpoint Essentials
            --Organization Admin
            --Channel Admin

    .DESCRIPTION
        This script is intended to use the API (v1) for Proofpoint Essentials to capture and export
        user and organization level Sender Lists in 4 separate CSV files.

    .INPUTS
        * Proofpoint Essentials Console Credentials
        * Domain that you are going to get Safe Sender information from
        * The Data Stack that the domain resides on. This is the beginning portion of your login site:
            (I.E. https://us2.proofpointessentials.com -- us2 would be the stack.)

    .OUTPUTS
        * This will output 4 files in the System Drive of your computer. These files will be located 
        in the following folder:
            ** (SystemDrive, C for example) C:\Temp\SenderListExport\domain.com\

        * Files Generated from this script
            ** UserSafeSenderList.csv
            ** UserBlockedSenderList.csv
            ** OrgSafeSender.csv
            ** OrgBlockedSender.csv

    .NOTES
        Version:         1.0
        Creation Date:   4/8/2021

    .DISCLAIMER
        This script works in it's current form. Any alterations or adjustments made to this script
        will not be supported or eligible for troubleshooting support. This script is used for
        data gathering only. Proofpoint Essentials Support does not currently offer services
        to troubleshoot scripting solutions or script configurations. This is a working example of
        how the API can be utilized to get management information together for securing your 
        customers and enabling partners with new tools for information. 

#>

#Establish global parameters that will be used throughout the script.
$Global:params = @{
    Domain      = ""
    Stack       = ""
    StackList   = ('us1','us2','us3','us4','us5','eu1')
    Headers     = ""
    Method      = 'GET'
    Body        = ""
    SMTP        = ""
    ContentType = 'application/json'
    FolderName  = ""
}

# This funciton will capture and prepare your credentials for the Proofpoint Essentials API.
function Snag-Creds {
    $domain = $Global:params.Domain
    $Creds = Get-Credential -Message "Enter your Credentials for Proofpoint Essentials."


    $headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
    $headers.Add("X-User",($Creds).UserName)
    $headers.Add("X-Password",($Creds.GetNetworkCredential()).Password)

    $Global:params.Headers = $headers

}

# This function will take the parameters collected in the main script and use them to cycle through
# the sender lists for the organization and each user within the provided domain.
function Check-SafeSenderLists ($Pdomain) {
    $targetStack = $Global:params.Stack
    $targetDomain = $Pdomain
    $targetCompanyUsers = "https://$targetStack.proofpointessentials.com/api/v1/orgs/$targetDomain/users"
    $targetCompanyOrg = "https://$targetStack.proofpointessentials.com/api/v1/orgs/$targetDomain/"
    $AllDomainCheck = '*@'


    $UserResponse = Invoke-RestMethod -Headers $Global:params.Headers -Uri $targetCompanyUsers -Method Get
    $OrgResponse = Invoke-RestMethod -Headers $Global:params.Headers -Uri $targetCompanyOrg -Method Get

    ## Export User Safe Sender
    $ExportFolder = "$ENV:SystemDrive\Temp\SenderListExport\$Pdomain"
    $UserSafeSenderList = "$ExportFolder\UserSafeSenderList.csv"
    $UserBlockedSenderList = "$ExportFolder\UserBlockedSenderList.csv"
    $UserSafeSender = @()
    $UserBlockedSender = @()
    IF (!(Test-Path $ExportFolder)) {New-Item $ExportFolder -ItemType Directory -Force}
    Write-Output "`nProcessing your request now..."
## Exporting MULTI HashTable
    
    #Safe Sender Expansion for Users
    foreach ($item in $UserResponse.users) {
        $primary = $item.primary_email
        
        foreach ($WL in $item.white_list_senders) {
            $SafetyTest = $null
            IF ($WL -eq $primary) {$SafetyTest = "match"}     
            IF ($WL -match '\*\@' -and $SafetyTest -eq $null) {$SafetyTest = "domain"}

            switch ($SafetyTest) {
                "match" {$UserSafeSender += @([pscustomobject]@{PrimaryEmail=$primary;Entry="$WL -- WARNING: Self-Safe Listed Email Address"});break}
                "domain" {$UserSafeSender += @([pscustomobject]@{PrimaryEmail=$primary;Entry="$WL -- WARNING: ALL Domain Email marked as Safe Sender"});break}
                default {$UserSafeSender += @([pscustomobject]@{PrimaryEmail=$primary;Entry="$WL"});break}
            }
        }
    
    foreach ($BL in $item.black_list_senders) {
    
            $SafetyTest = $null
            IF ($BL -eq $primary) {$SafetyTest = "match"}     
            IF ($BL -match '\*\@' -and $SafetyTest -eq $null) {$SafetyTest = "domain"}

            switch ($SafetyTest) {
                "match" {$UserBlockedSender += @([pscustomobject]@{PrimaryEmail=$primary;Entry="$BL -- WARNING: Self-Safe Listed Email Address"});break}
                "domain" {$UserBlockedSender += @([pscustomobject]@{PrimaryEmail=$primary;Entry="$BL -- WARNING: ALL Domain Email marked as Safe Sender"});break}
                default {$UserBlockedSender += @([pscustomobject]@{PrimaryEmail=$primary;Entry="$BL"});break}
            }
        }
    
    ## Export ORG Safe Sender List
    $OrgSafeListLog = "$ExportFolder\OrgSafeSender.csv"
    $OrgBlockedListLog = "$ExportFolder\OrgBlockedSender.csv"
    $OrgSafeSender = @()
    $OrgBlockedSender = @()


## Exporting MULTI HashTable
    #Safe Sender Expansion for Users
    $MainDomain = $OrgResponse.primary_domain
    foreach ($OWL in $OrgResponse.white_list_senders) {
        $OrgSafetyTest = $null
        IF ($OWL -match '\*\@') {$OrgSafetyTest = "domain"}

        switch ($OrgSafetyTest) {
            "domain" {$OrgSafeSender += @([pscustomobject]@{PrimaryDomain=$MainDomain;Entry="$OWL -- WARNING: ALL Domain Email listed as Safe Sender"});break}
            default {$OrgSafeSender += @([pscustomobject]@{PrimaryDomain=$MainDomain;Entry="$OWL"});break}
        }
    }

    foreach ($OBL in $OrgResponse.black_list_senders) {
        $OrgSafetyTest = $null
        IF ($OBL -match '\*\@') {$OrgSafetyTest = "domain"}

        switch ($OrgSafetyTest) {
            "domain" {$OrgBlockedSender += @([pscustomobject]@{PrimaryDomain=$MainDomain;Entry="$OBL -- WARNING: ALL Domain Email listed as Blocked Sender"});break}
            default {$OrgBlockedSender += @([pscustomobject]@{PrimaryDomain=$MainDomain;Entry="$OBL"});break}
        }
    }
    
    }

    $UserSafeSender | Export-Csv -Path $UserSafeSenderList -NoTypeInformation -Force
    $UserBlockedSender | Export-Csv -Path $UserBlockedSenderList -NoTypeInformation -Force
    $OrgSafeSender | Export-Csv -Path $OrgSafeListLog -NoTypeInformation -Force
    $OrgBlockedSender | Export-Csv -Path $OrgBlockedListLog -NoTypeInformation -Force
    
    #Open Explorer Window with new files inside.
    Invoke-Item $ExportFolder
}

# This script will begin with a clean Powershell Window and walk through the credentials capture.
cls
Write-Output "Enter your credentials for Proofpoint.`n"
Snag-Creds

# This will enable you to select the domain that you wish to get information from.
$TargetDomain = Read-Host -Prompt "Which domain are you going to pull sender lists from"

# This is a security check which will only accept appropriate data stacks that we currently use.
$Global:params.Stack = $null
do {
    $Global:params.Stack = (Read-Host "Which data stack are you accessing? (us1,us2,us3,us4,us5,eu1)").ToLower()
    } while ($Global:params.Stack -notin $Global:params.StackList)

# This will execute the main program and generate the files within the selected directory. 
Check-SafeSenderLists -Pdomain $TargetDomain