PoshSophos

0.3.4

PoshSophos.psm1

#requires -Version 2 -Modules NetTCPIP

#region Core Functions

function Get-SophosCredential {

    try {

        Write-Verbose -Message 'Retrieving Sophos API Credentials'

        if (!$Global:sophosClientID) {

            $Global:sophosClientID = Read-Host 'Enter Sophos Client ID (push ctrl + c to exit)'
        }

        if (!$Global:sophosClientSecret) {

            $Global:sophosClientSecret = Read-Host 'Enter Sophos Client Secret (push ctrl + c to exit)'
        }

        @{
            'ClientID'     = $Global:sophosClientID
            'ClientSecret' = $Global:sophosClientSecret
        }

        Write-Verbose -Message 'Retrieved API Credentials'
    }
    catch {

        Write-Error -Message 'Problem getting Sophos credential variables'
    }
}

function Connect-SophosCentral {

    [CmdletBinding()]
    param (

        [Parameter(Mandatory, HelpMessage = 'The client ID from the Sophos Central API credential/service principal')]
        [String] $ClientID,

        [Parameter(HelpMessage = 'The client secret from the Sophos Central API credential/service principal')]
        [String] $ClientSecret
    )

    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

    if ($null -eq $ClientSecret) {

        $ClientSecret = Read-Host -AsSecureString -Prompt 'Client Secret: '
    }

    $loginUri = 'https://id.sophos.com/api/v2/oauth2/token'

    $body = @{

        grant_type    = 'client_credentials'
        client_id     = $ClientID
        client_secret = $ClientSecret
        scope         = 'token'
    }

    try {

        $response = Invoke-WebRequest -Uri $loginUri -Body $body -ContentType 'application/x-www-form-urlencoded' -Method Post -UseBasicParsing
    }
    catch {

        throw 'Error requesting access token: {0}' -f $_
    }

    if ($response.Content) {

        $authDetails = $response.Content | ConvertFrom-Json
        $expiresAt = (Get-Date).AddSeconds($authDetails.expires_in - 60)


        $authDetails | Add-Member -MemberType NoteProperty -Name expires_at -Value $expiresAt
        $authDetails.access_token = $authDetails.access_token | ConvertTo-SecureString -AsPlainText -Force
        $Script:SophosCentral = $authDetails
    }

    $Script:SophosCentral
}

function New-SophosHeaders {

    $sophosCredentials = Get-SophosCredential

    $null = Connect-SophosCentral -ClientID $sophosCredentials.ClientID -ClientSecret $sophosCredentials.ClientSecret

    $Script:sophosHeaders = @{

        Authorization = 'Bearer ' + (Unprotect-Secret -Secret $Script:SophosCentral.access_token)
    }

    $tenantUri = 'https://api.central.sophos.com/whoami/v1'

    $tenantInfo = Invoke-RestMethod -Uri $tenantUri -Headers $Script:sophosHeaders -Method Get -UseBasicParsing

    $Script:SophosCentral | Add-Member -MemberType NoteProperty -Name GlobalEndpoint -Value $tenantInfo.apiHosts.global
    $Script:SophosCentral | Add-Member -MemberType NoteProperty -Name RegionEndpoint -Value $tenantInfo.apiHosts.dataRegion
    $Script:SophosCentral | Add-Member -MemberType NoteProperty -Name TenantID -Value $tenantInfo.id
    $Script:SophosCentral | Add-Member -MemberType NoteProperty -Name IDType -Value $tenantInfo.idType

    $Script:sophosHeaders.Add('X-Tenant-ID', $Script:SophosCentral.TenantID)
}

function Invoke-SophosCentralWebRequest {

    [CmdletBinding()]
    param (

        [Parameter(Mandatory)]
        [System.URI] $Uri,

        [ValidateSet('Get', 'Post', 'Put', 'Delete')]
        [string] $Method = 'Get',

        [System.Collections.Hashtable] $Body
    )

    $requestParams = @{
        Uri             = $uri
        Headers         = $Script:sophosHeaders
        UseBasicParsing = $true
        Method          = $Method
    }

    if ((!$Body) -and ($Method -in ('Post', 'Put'))) {

        $bodyTemp = @{} | ConvertTo-Json

        $requestParams.Add('Body', $bodyTemp)
    }
    elseif (($Body) -and ($Method -eq 'Get')) {

        $requestParams.Add('Body', $Body)
    }
    elseif ($Body) {

        $requestParams.Add('Body', ($Body | ConvertTo-Json -Depth 5))
    }

    if ($Method -notin ('Delete', 'Get')) {

        $requestParams.Add('ContentType', 'application/json')
    }

    try {

        $response = Invoke-RestMethod @requestParams

        if ($response.items) {

            $response.items
        }
        else {

            $response
        }
    }
    catch {

        $errorDetails = ConvertFrom-Json -InputObject $_.ErrorDetails.Message

        throw $errorDetails.message
    }


    $finished = $false

    do {
        if ($response.pages.nextKey) {

            if ($uri.AbsoluteUri -like '*`?*') {

                $requestParams['Uri'] = $uri.AbsoluteUri + '&pageFromKey=' + $response.pages.nextKey
            }
            else {

                $requestParams['Uri'] = $uri.AbsoluteUri + '?pageFromKey=' + $response.pages.nextKey
            }

            $response = Invoke-RestMethod @requestParams

            $response.items
        }
        elseif ($response.has_more) {

            if ($uri.AbsoluteUri -like '*`?*') {

                $requestParams['Uri'] = $uri.AbsoluteUri + '&cursor=' + $response.next_cursor
            }
            else {

                $requestParams['Uri'] = $uri.AbsoluteUri + '?cursor=' + $response.next_cursor
            }

            $response = Invoke-RestMethod @requestParams

            $response.items
        }
        else {

            $finished = $true
        }
    } while ($finished -eq $false)
}


#endregion

#region Helper Functions


function Invoke-UriBuilder {

    [CmdletBinding()]
    param (

        [Parameter(Mandatory)]
        [System.Uri] $Uri,

        [hashtable] $OriginalPsBoundParameters,

        [array] $FilteredParameters
    )

    New-SophosHeaders

    $regionEndpoint = $Script:SophosCentral.RegionEndpoint

    $Uri = $regionEndpoint + $Uri

    $uriBuilder = [System.UriBuilder]::New($Uri.AbsoluteUri)

    $blockedParams = 'Verbose', 'Force', 'Debug', 'WhatIf' + $FilteredParameters

    $keys = $OriginalPsBoundParameters.Keys | Where-Object { $blockedParams -notcontains $_ }

    foreach ($param in $keys) {

        if (($OriginalPsBoundParameters[$param]) -and ($param)) {

            $paramToLower = $param.ToString()[0].ToString().ToLower() + $param.ToString().Substring(1)

            if ($OriginalPsBoundParameters[$param] -is [array]) {

                $queryBuilder = $paramToLower + '=' + ($OriginalPsBoundParameters[$param] -join ',')
            }
            else {

                if ($OriginalPsBoundParameters[$param].GetType().Name -eq 'DateTime') {

                    $OriginalPsBoundParameters[$param] = $OriginalPsBoundParameters[$param].ToUniversalTime().ToString('u').Replace(' ', 'T')
                }

                $queryBuilder = $paramToLower + '=' + $OriginalPsBoundParameters[$param]
            }
            if (($null -eq $uriBuilder.Query) -or ($uriBuilder.Query.Length -le 1 )) {

                $uriBuilder.Query = $queryBuilder
            }
            else {

                $uriBuilder.Query = $uriBuilder.Query.Substring(1) + '&' + $queryBuilder
            }
        }
    }

    [System.Uri]::New($uriBuilder.Uri)
}

function Unprotect-Secret {

    [CmdletBinding()]
    [OutputType([System.String])]
    param (

        [Parameter(Mandatory, HelpMessage = 'The Secure String to convert to plain text')]
        [SecureString] $Secret
    )

    $bstr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($Secret)
    [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($bstr)
}


#endregion

#region Endpoint Functions


function Get-SophosCentralEndpoint {

    [CmdletBinding()]
    param (

        [ValidateSet('bad', 'good', 'suspicious', 'unknown')]
        [string[]] $HealthStatus,

        [ValidateSet('computer', 'server', 'securityVm')]
        [string[]] $Type,

        [System.Boolean] $TamperProtectionEnabled,

        [ValidateSet('creatingWhitelist', 'installing', 'locked', 'notInstalled', 'registering', 'starting', 'stopping', 'unavailable', 'uninstalled', 'unlocked')]
        [string[]] $LockdownStatus,

        [ValidateSet('isolated', 'notIsolated')]
        [string] $IsolationStatus,

        [string] $HostnameContains,

        [string] $IpAddresses,

        [string] $MacAddresses,

        [string] $Search,

        [ValidateSet('hostname', 'groupName', 'associatedPersonName', 'ipAddress', 'osName')]
        [string] $SearchField = 'hostname',

        [datetime] $LastSeenBefore,

        [datetime] $LastSeenAfter,

        [ValidateScript({
                if ($false -eq [System.Guid]::TryParse($_, $([ref][guid]::Empty))) {
                    throw 'Not a valid GUID'
                }
                else {
                    return $true
                }
            })]
        [string[]] $ID
    )

    if ($ID.count -gt 0) {

        $PsBoundParameters.Add('ids', $PsBoundParameters['ID'])

        $null = $PsBoundParameters.Remove('ID')
    }

    $uriEndpoint = '/endpoint/v1/endpoints'

    $uri = Invoke-UriBuilder -Uri $uriEndpoint -OriginalPsBoundParameters $PsBoundParameters

    Invoke-SophosCentralWebRequest -Uri $uri
}

function Remove-SophosCentralEndpoint {

    [CmdletBinding()]
    param (

        [Parameter(Mandatory, ValueFromPipelineByPropertyName = $True)]
        [Alias('ID')]
        [string[]] $EndpointId
    )

    begin {

    }

    process {

        foreach ($endpoint in $EndpointId) {

            $uriEndpoint = '/endpoint/v1/endpoints/{0}' -f $endpoint

            $uri = Invoke-UriBuilder -Uri $uriEndpoint

            Invoke-SophosCentralWebRequest -Uri $uri -Method Delete
        }
    }

    end {

    }
}


#endregion

#regoin SIEM Integration Functions


function Get-SophosCentralSiemEvents {

    [CmdletBinding()]
    param (

        # The starting date from which alerts will be retrieved defined as Unix timestamp in UTC. Ignored if cursor is set. Must be within last 24 hours.
        [datetime] $FromDate,

        [string] $ExcludedTypes,

        # The maximum number of items to return (per page), default is 200, max is 1000.
        [int] $Limit
    )

    $params = @{}

    if ($FromDate) {

        $params = @{

            from_date = $FromDate
        }
    }

    if ($ExcludedTypes) {

        $params += @{

            excluded_types = $ExcludedTypes
        }
    }

    $uriEndpoint = '/siem/v1/events'

    $uri = Invoke-UriBuilder -Uri $uriEndpoint -OriginalPsBoundParameters $params

    $response = Invoke-SophosCentralWebRequest -Uri $uri

    if ($response.created_at) {

        $response
    }
    else {

        Write-Host -Object 'No events found at this time'
    }
}

function Get-SophosCentralSiemAlerts {

    [CmdletBinding()]
    param (

        # The starting date from which alerts will be retrieved defined as Unix timestamp in UTC. Ignored if cursor is set. Must be within last 24 hours.
        [datetime] $FromDate,

        # The maximum number of items to return (per page), default is 200, max is 1000.
        [int] $Limit
    )

    $params = @{}

    if ($FromDate) {

        $params = @{

            from_date = $FromDate
        }
    }

    $uriEndpoint = '/siem/v1/alerts'

    $uri = Invoke-UriBuilder -Uri $uriEndpoint -OriginalPsBoundParameters $params

    $response = Invoke-SophosCentralWebRequest -Uri $uri

    if ($response.created_at) {

        $response
    }
    else {

        Write-Host -Object 'No alerts found at this time'
    }
}

#endregion