KnowBe4

1.3.1

KnowBe4.psm1

#Region Account
function Get-KnowBe4Account {
    Param(
        [CmdletBinding()]

        [Parameter(Mandatory = $true,
            HelpMessage = "If your server URL is training.knowbe4.com, your base URL is 'US'. If your server URL is eu.knowbe4.com, your base URL is 'EU.'")]
        [ValidateSet('US', 'EU')]
        [String]$BaseURL,

        [Parameter(Mandatory = $true,
            HelpMessage = "This token is generated by KnowBe4 and accessible from your Account Settings page under 'API.' You must check 'Enable API Access' to use this token.")]
        [String]$AccessToken,

        [Parameter(Mandatory = $false,
            HelpMessage = "Include the entire risk score history of your organization. If this parameter isn't used, six months of data will show by default.")]
        [Switch]$Full
    )

    $BaseURL = $BaseURL.ToUpper()
    switch ($BaseURL) {
        'US' { $URL = 'https://us.api.knowbe4.com/v1/account' }
        'EU' { $URL = 'https://eu.api.knowbe4.com/v1/account' }
    }

    if ($Full) {
        $URL = $URL + '?full=true'
    }

    $authorizationHeader = "Authorization: Bearer $AccessToken"
    $response = curl.exe --url $URL --header $authorizationHeader --silent

    return ($response | ConvertFrom-Json)
}
#EndRegion Account

#Region Users
function Get-KnowBe4User {
    Param(
        [CmdletBinding()]
        
        [Parameter(Mandatory = $true,
            HelpMessage = "If your server URL is training.knowbe4.com, your base URL is 'US'. If your server URL is eu.knowbe4.com, your base URL is 'EU.'")]
        [ValidateSet('US', 'EU')]
        [String]$BaseURL,

        [Parameter(Mandatory = $true,
            HelpMessage = "This token is generated by KnowBe4 and accessible from your Account Settings page under 'API.' You must check 'Enable API Access' to use this token.")]
        [String]$AccessToken,

        [Parameter(Mandatory = $false,
            HelpMessage = "Return all users of this status. Ex. Active, Archived.")]
        [ValidateSet('Active', 'Archived')]
        [String]$Status,

        [Parameter(Mandatory = $false,
            HelpMessage = "Get a specific user.")]
        [String]$UserID,

        [Parameter(Mandatory = $false,
            HelpMessage = "Specify a user group to return.")]
        [String]$GroupID,

        [Parameter(Mandatory = $false,
            HelpMessage = "Expands groups to provide additional details.")]
        [Switch]$Expand
    )

    $BaseURL = $BaseURL.ToUpper()
    switch ($BaseURL) {
        'US' { $URL = 'https://us.api.knowbe4.com/v1/users' }
        'EU' { $URL = 'https://eu.api.knowbe4.com/v1/users' }
    }

    # Conflicts
    if ($GroupID -and $UserID) {
        Write-Error 'UserID and GroupID are not compatible. Use one or the other.'
        Break
    }

    if ($Status -and $GroupID -or $Status -and $UserID) {
        Write-Error 'Status and GroupID/UserID is not compatible.'
        Break
    }

    # URL modification
    if ($Status) {
        $Status = $Status.ToLower()
        $URL = $URL + "?status=$Status"
    }    

    if ($UserID) {
        $URL = $URL + "/$UserID"
    }

    if ($GroupID) {
        $URL = $URL + "/$GroupID/members"
    }

    if ($Expand) {
        if ($URL -match '\?') {
            $URL = $URL + '&expand=group'
        }
        else {
            $URL = $URL + '?expand=group'
        }
    }

    $authorizationHeader = "Authorization: Bearer $AccessToken"
    $response = curl.exe --url $URL --header $authorizationHeader --silent

    return ($response | ConvertFrom-Json)
}
#EndRegion Users

#Region Groups
function Get-KnowBe4Group {
    Param(
        [CmdletBinding()]
        
        [Parameter(Mandatory = $true,
            HelpMessage = "If your server URL is training.knowbe4.com, your base URL is 'US'. If your server URL is eu.knowbe4.com, your base URL is 'EU.'")]
        [ValidateSet('US', 'EU')]
        [String]$BaseURL,

        [Parameter(Mandatory = $true,
            HelpMessage = "This token is generated by KnowBe4 and accessible from your Account Settings page under 'API.' You must check 'Enable API Access' to use this token.")]
        [String]$AccessToken,

        [Parameter(Mandatory = $false,
            HelpMessage = "Return all users of this status. Ex. Active, Archived.")]
        [ValidateSet('Active', 'Archived')]
        [String]$Status,

        [Parameter(Mandatory = $false,
            HelpMessage = "Specific group to return.")]
        [String]$GroupID
    )

    $BaseURL = $BaseURL.ToUpper()
    switch ($BaseURL) {
        'US' { $URL = 'https://us.api.knowbe4.com//v1/groups' }
        'EU' { $URL = 'https://eu.api.knowbe4.com//v1/groups' }
    }

    if ($Status -and $GroupID) {
        Write-Error 'Status and GroupID are not compatible.'
        Break
    }

    if ($GroupID) {
        $URL = $URL + "/$GroupID"   
    }

    if ($Status) {
        $Status = $Status.ToLower()
        $URL = $URL + "?status=$Status"
    }
    
    $authorizationHeader = "Authorization: Bearer $AccessToken"
    $response = curl.exe --url $URL --header $authorizationHeader --silent

    return ($response | ConvertFrom-Json)
}
#EndRegion Groups

#Region Phishing
function Get-PhishingCampaign {
    Param(
        [CmdletBinding()]
        
        [Parameter(Mandatory = $true,
            HelpMessage = "If your server URL is training.knowbe4.com, your base URL is 'US'. If your server URL is eu.knowbe4.com, your base URL is 'EU.'")]
        [ValidateSet('US', 'EU')]
        [String]$BaseURL,

        [Parameter(Mandatory = $true,
            HelpMessage = "This token is generated by KnowBe4 and accessible from your Account Settings page under 'API.' You must check 'Enable API Access' to use this token.")]
        [String]$AccessToken,

        [Parameter(Mandatory = $false,
            HelpMessage = 'Specific phishing campaign to return.')]
        [String]$CampaignID
    )

    $BaseURL = $BaseURL.ToUpper()
    switch ($BaseURL) {
        'US' { $URL = 'https://us.api.knowbe4.com/v1/phishing/campaigns' }
        'EU' { $URL = 'https://eu.api.knowbe4.com/v1/phishing/campaigns' }
    }

    if ($CampaignID) {
        $URL = $URL + "/$CampaignID"
    }

    $authorizationHeader = "Authorization: Bearer $AccessToken"
    $response = curl.exe --url $URL --header $authorizationHeader --silent

    return ($response | ConvertFrom-Json)
}

function Get-PhishingSecurityTest {
    Param(
        [CmdletBinding()]
        
        [Parameter(Mandatory = $true,
            HelpMessage = "If your server URL is training.knowbe4.com, your base URL is 'US'. If your server URL is eu.knowbe4.com, your base URL is 'EU.'")]
        [ValidateSet('US', 'EU')]
        [String]$BaseURL,

        [Parameter(Mandatory = $true,
            HelpMessage = "This token is generated by KnowBe4 and accessible from your Account Settings page under 'API.' You must check 'Enable API Access' to use this token.")]
        [String]$AccessToken,

        [Parameter(Mandatory = $false,
            HelpMessage = 'Returns a specific phishing security test.')]
        [String]$PstId,

        [Parameter(Mandatory = $false,
            HelpMessage = 'Specific a campaign from which to return all phishing security tests.')]
        [String]$CampaignID,

        [Parameter(Mandatory = $false,
            HelpMessage = 'Return all recpients of a specific phishing security test.')]
        [Switch]$Recipient
    )

    $BaseURL = $BaseURL.ToUpper()
    switch ($BaseURL) {
        'US' { $URL = 'https://us.api.knowbe4.com/v1/phishing/security_tests/' }
        'EU' { $URL = 'https://eu.api.knowbe4.com/v1/phishing/security_tests/' }
    }

    # Conflicts
    if ($CampaignID -and $PstId) {
        Write-Error 'CampaignID and Phishing Security Test ID are not compatible.'
        Break
    }

    if ($Recipient -and !($PstID)) {
        Write-Error 'Specify which campaign to return recipients for.'
        Break
    }

    # URL Modification
    if ($CampaignID) {
        $URL = $URL.Replace('security_tests/', "campaigns/$CampaignID/security_tests")
    }

    if ($PstId) {
        $URL = $URL + $PstId
    }

    if ($Recipient) {
        $URL = $URL + '/recipients'
    }

    $authorizationHeader = "Authorization: Bearer $AccessToken"
    $response = curl.exe --url $URL --header $authorizationHeader --silent

    return ($response | ConvertFrom-Json)
}
#EndRegion Phishing

#Region Training
function Get-TrainingCampaign {
    Param(
        [CmdletBinding()]
        
        [Parameter(Mandatory = $true,
            HelpMessage = "If your server URL is training.knowbe4.com, your base URL is 'US'. If your server URL is eu.knowbe4.com, your base URL is 'EU.'")]
        [ValidateSet('US', 'EU')]
        [String]$BaseURL,

        [Parameter(Mandatory = $true,
            HelpMessage = "This token is generated by KnowBe4 and accessible from your Account Settings page under 'API.' You must check 'Enable API Access' to use this token.")]
        [String]$AccessToken,

        [Parameter(Mandatory = $false,
            HelpMessage = 'A specific training campaign to reutrn.')]
        [String]$CampaignID
    )

    $BaseURL = $BaseURL.ToUpper()
    switch ($BaseURL) {
        'US' { $URL = 'https://us.api.knowbe4.com/v1/training/campaigns/' }
        'EU' { $URL = 'https://eu.api.knowbe4.com/v1/training/campaigns/' }
    }

    if ($CampaignID) {
        $URL = $URL + $CampaignID
    }

    $authorizationHeader = "Authorization: Bearer $AccessToken"    
    $response = curl.exe --url $URL --header $authorizationHeader --silent

    return ($response | ConvertFrom-Json)
}

function Get-TrainingEnrollment {
    Param(
        [CmdletBinding()]
        
        [Parameter(Mandatory = $true,
            HelpMessage = "If your server URL is training.knowbe4.com, your base URL is 'US'. If your server URL is eu.knowbe4.com, your base URL is 'EU.'")]
        [ValidateSet('US', 'EU')]
        [String]$BaseURL,
        
        [Parameter(Mandatory = $true,
            HelpMessage = "This token is generated by KnowBe4 and accessible from your Account Settings page under 'API.' You must check 'Enable API Access' to use this token.")]
        [String]$AccessToken,

        [Parameter(Mandatory = $false,
            HelpMessage = 'Return all training enrollments for a specific campaign.')]
        [String]$CampaignID,

        [Parameter(Mandatory = $false,
            HelpMessage = 'Return all training enrollments for a specific user.')]
        [String]$UserID
    )

    $BaseURL = $BaseURL.ToUpper()
    switch ($BaseURL) {
        'US' { $URL = 'https://us.api.knowbe4.com/v1/training/enrollments/' }
        'EU' { $URL = 'https://eu.api.knowbe4.com/v1/training/enrollments/' }
    }

    # Conflicts
    if ($CampaignID -and $UserID) {
        Write-Error 'CampaignID and UserID are not compatible.'
        Break
    }

    # URL Modifcation
    if ($CampaignID) {
        $URL = $URL + "?campaign_id=$CampaignID"
    }

    if ($UserID) {
        $URL = $URL + "?user_id=$UserID"
    }

    $authorizationHeader = "Authorization: Bearer $AccessToken"
    $response = curl.exe --url $URL --header $authorizationHeader --silent

    return ($response | ConvertFrom-Json)
}

#EndRegion Training