PSSophos

This PowerShell module streamlines the administration of Sophos, enabling automated configuration for efficient setup. Ideal for release pipelines, it simplifies device management and ensures consistent deployment.

SHORT DESCRIPTION

Powershell Wrapper for the Sophos APIs.

EXAMPLES

The example below shows how the module can be used to add a local website to a tenant.

Warning

PSCredential for PSSophos

The PSCredential object must be formed with the Client ID as the username and Client Secret as the password. Follow this Guide if you are not sure how to create the api keys.

Creating a pscredential object to use with PSSophos

$ClientId = "be41eddf-b44d-4ae1-8ecc-bf982874b861"
$ClientSecret = "f6540472f1c0080803045f4ddef91a91d76f69534abafecc98d0fde0949ed157d3482a2693f094d8e31a354d46cce8273085"
$SecureString = ConvertTo-SecureString -String $ClientSecret -AsPlainText -Force
$Credential = [pscredential]::new($ClientId,$SecureString)
# Using credential to get the access token
$AccessToken = Get-SophosAccessToken -Credential $Credential -ErrorAction Stop

Example

ScriptFunction

Add-SophosLocalWebsite.ps1

[cmdletbinding(SupportsShouldProcess=$true, ConfirmImpact='High')]
param(
    [Parameter(Mandatory=$true)]
    [string]$TenantName,
    [Parameter(Mandatory=$true)]
    [string]$Url,
    [Parameter(Mandatory=$true)]
    [string[]]$Tag,
    [Parameter(Mandatory=$true)]
    [string]$Comment,
    [Parameter(Mandatory=$true)]
    [pscredential]$Credential
)
Begin {
    try {
        $AccessToken = Get-SophosAccessToken -Credential $Credential -ErrorAction Stop
    }
    catch {
        throw $_.Exception.Message
    }
    if(-not ($AccessToken.Success))
    {
        throw $AccessToken
    }
    $PartnerId = Get-SophosPartnerId -Token $AccessToken.Token
    if(-not ($PartnerId.Success))
    {
        throw $PartnerId
    }
    $Output = $null

}
Process {
    if($PSCmdlet.ShouldProcess($TenantName,'Add local website'))
    {
        try {
            $Results = Get-SophosPartnerTenant -Token $AccessToken.Token -PartnerId $PartnerId.PartnerId -ErrorAction Stop
        }
        catch{
            throw $_.Exception.Message
        }

        $Tenant = $Results.Result | Where-Object {$_.showAs -ieq "$TenantName"}
        $web = New-SophosEndpointWebControlLocalSite -Token $AccessToken.Token -TenantId $Tenant.id -ApiHost $Tenant.apiHost -Url "$Url" -Tags $Tag -Comment "$Comment" -Confirm:$false
        if(-not $($web.Success -ieq "True"))
        {
            throw $web
        }
        $Output = $web.Result
    }
}
End {
    return $Output
}

Add-SophosLocalWebsite

function Add-SophosLocalWebsite {
    <#
    .SYNOPSIS
    Add local website to a tenant

    .DESCRIPTION
    Add local website to a tenant

    .PARAMETER TenantName
    Target tenant name

    .PARAMETER Url
    URL to be added

    .PARAMETER Tags
    Tags for the URL. Single or array of tags

    .PARAMETER Comment
    Reason for adding the URL

    .PARAMETER Credential
    PSCredential for the sophos API

    .EXAMPLE
    PS>.\Add-SophosLocalWebsite.ps1 -TenantName "MyTenant" -Url "https://example.com" -Tags "example" -Comment "just testing" -Credential $Credential
    #>

    [cmdletbinding(SupportsShouldProcess=$true, ConfirmImpact='High')]
    param(
        [Parameter(Mandatory=$true)]
        [string]$TenantName,
        [Parameter(Mandatory=$true)]
        [string]$Url,
        [Parameter(Mandatory=$true)]
        [string[]]$Tag,
        [Parameter(Mandatory=$true)]
        [string]$Comment,
        [Parameter(Mandatory=$true)]
        [pscredential]$Credential
    )
    Begin {
        try {
            $AccessToken = Get-SophosAccessToken -Credential $Credential -ErrorAction Stop
        }
        catch {
            throw $_.Exception.Message
        }
        if(-not ($AccessToken.Success))
        {
            throw $AccessToken
        }
        $PartnerId = Get-SophosPartnerId -Token $AccessToken.Token
        if(-not ($PartnerId.Success))
        {
            throw $PartnerId
        }
        $Output = $null

    }
    Process {
        if($PSCmdlet.ShouldProcess($TenantName,'Add local website'))
        {
            try {
                $Results = Get-SophosPartnerTenant -Token $AccessToken.Token -PartnerId $PartnerId.PartnerId -ErrorAction Stop
            }
            catch{
                throw $_.Exception.Message
            }

            $Tenant = $Results.Result | Where-Object {$_.showAs -ieq "$TenantName"}
            $web = New-SophosEndpointWebControlLocalSite -Token $AccessToken.Token -TenantId $Tenant.id -ApiHost $Tenant.apiHost -Url "$Url" -Tags $Tag -Comment "$Comment" -Confirm:$false
            if(-not $($web.Success -ieq "True"))
            {
                throw $web
            }
            $Output = $web.Result
        }
    }
    End {
        return $Output
    }
}

Execution

ScriptFunction

.\Add-SophosLocalWebsite.ps1 -TenantName "MyTenant" -Url "https://example.com" -Tags "example.com" -Comment "just testing" -Credential $Credential

Add-SophosLocalWebsite -TenantName "MyTenant" -Url "https://example.com" -Tags "example.com" -Comment "just testing" -Credential $Credential

NOTE

This PowerShell module is provided "as-is" without any guarantees or warranty. Use it at your own risk. The authors and contributors are not responsible for any damage or issues that may arise from using this module.

LICENSE

This project is under the MIT license.

KEYWORDS

• Sophos
• Sophos API