Skip to content

Authentication

Jump to bottom
bk-cs edited this page Mar 24, 2023 · 32 revisions

CrowdStrike Falcon

API DocumentationEU 1US-1US-2US-GOV-1

Command Permission
Request-FalconToken
Revoke-FalconToken
Test-FalconToken

Get an auth token

During a PowerShell session, you must have a valid OAuth2 access token in order to make requests to the CrowdStrike Falcon APIs. You can do this using Request-FalconToken, or input your ClientId/ClientSecret when prompted after issuing a PSFalcon command.

After a valid OAuth2 token is received, it is cached with your credentials. Your cached token is checked and refreshed as needed while running PSFalcon commands.

Request-FalconToken -ClientId 'client_id' -ClientSecret 'client_secret'

WARNING: Request-FalconToken defaults to the us-1 cloud. If your environment exists within a different cloud, the module will attempt to use automatic redirection, except when the target cloud is us-gov-1. Defining Cloud or Hostname ensures that your token request goes to the proper cloud without relying on re-direction and is required when using us-gov-1.

Alternate clouds

Authentication token requests are sent to the us-1 cloud by default. You may use the Cloud or Hostname parameters to set it using a cloud, or full URL value. The accepted hostname values can be viewed using tab auto-completion. Your Cloud/Hostname choice is saved and all requests are sent using the cached information.

Child environments

In MSSP (also known as "Flight Control") configurations, you can target specific child environments ("CIDs") using the MemberCid parameter during authentication token requests. Your choice is saved and all requests are sent to that particular member CID unless a new Request-FalconToken request is made specifying a new member CID, or you Revoke-FalconToken.

Verifying token status

Test-FalconToken can be used to verify whether you have an active OAuth2 access token cached.

Test-FalconToken

Token Hostname                    ClientId                         MemberCid
----- --------                    --------                         ---------
 True https://api.crowdstrike.com <redacted>

The Token property of the output from Test-FalconToken provides a [boolean] value of your current status.

(Test-FalconToken).Token
True

Revoke an auth token

The command Revoke-FalconToken will revoke your current authorization token and clear it from your local cache.

Revoke-FalconToken

Securing credentials

PSFalcon does not provide a method for securely handling your API client credentials. The Microsoft.PowerShell.SecretStore module is a cross-platform option that works with PSFalcon. You can follow the steps below to install the module and use it with Request-FalconToken.

NOTE: Microsoft.PowerShell.SecretManagement is a pre-requisite for the Microsoft.PowerShell.SecretStore module. It will be installed during the Install-Module step.

Install-Module -Name Microsoft.PowerShell.SecretStore -Scope CurrentUser

NOTE: Using the default configuration, Microsoft.PowerShell.SecretStore will prompt for a password to access your secret vault. You can remove the password requirement to use the vault with a script or as part of a scheduled task, which leaves the vault accessible to the account that was used to create it. You will be asked to create, confirm and remove a password after entering this command.

Set-SecretStoreConfiguration -Scope CurrentUser -Authentication None -Interaction None

Once the module is installed and configured as desired, create a vault to store your API client(s):

Register-SecretVault -ModuleName Microsoft.PowerShell.SecretStore -Name MyVault

Request-FalconToken requires multiple parameters to request a token. Each individual API client can be stored with the relevant parameters (including MemberCid) in your new vault:

$ApiClient = @{
    ClientId     = 'my_client_id'
    ClientSecret = 'my_client_value'
    Hostname     = 'https://api.crowdstrike.com'
}
Set-Secret -Name MyApiClient -Secret $ApiClient -Vault MyVault

Once stored, credentials can be retrieved using your chosen Name, and you can splat the parameters with Request-FalconToken:

Get-Secret -Name MyApiClient -Vault MyVault -AsPlainText | ForEach-Object { Request-FalconToken @_ }

If desired, a simple function can be added to your PowerShell profile to retrieve your credentials and request a token by name:

function Request-SecretToken ([string] $Name) {
    if (-not(Get-Module -Name PSFalcon)) {
        Import-Module -Name PSFalcon
    } elseif ((Test-FalconToken -ErrorAction SilentlyContinue).Token -eq $true) {
        Revoke-FalconToken
    }
    $Secret = Get-Secret -Name $Name -Vault MyVault -AsPlainText
    if ($Secret) {
        Request-FalconToken @Secret
    } else {
        throw "No secret found matching '$String'."
    }
}

Once added to your profile, you can retrieve your credential set and request a token in a single step:

Request-SecretToken MyApiClient

Authentication within a script

Request authorization token and run a command

The request of an authorization token can happen as part of a script that performs other tasks. Here is a re-usable example which defines the necessary parameters, and can optionally authenticate within a specific member CID (found within Flight Control environments).

#Requires -Version 5.1
using module @{ModuleName='PSFalcon';ModuleVersion='2.2'}
[CmdletBinding()]
param(
    [Parameter(Mandatory,Position=1)]
    [ValidatePattern('^[a-fA-F0-9]{32}$')]
    [string]$ClientId,
    [Parameter(Mandatory,Position=2)]
    [ValidatePattern('^\w{40}$')]
    [string]$ClientSecret,
    [Parameter(Position=3)]
    [ValidatePattern('^[a-fA-F0-9]{32}$')]
    [string]$MemberCid,
    [Parameter(Position=4)]
    [ValidateSet('us-1','us-2','us-gov-1','eu-1')]
    [string]$Cloud
)
begin {
    $Token = @{}
    @('ClientId','ClientSecret','Cloud','MemberCid').foreach{
        if ($PSBoundParameters.$_) { $Token[$_] = $PSBoundParameters.$_ }
    }
}
process {
    try {
        Request-FalconToken @Token
        if ((Test-FalconToken).Token -eq $true) {
            # Insert code to run here
        }
    } catch {
        throw $_
    } finally {
        if ((Test-FalconToken).Token -eq $true) { Revoke-FalconToken }
    }
}

Authorize and run commands across member CIDs

In multi-CID configurations, you can create an OAuth2 API Client Id/Secret in the "parent" CID that has access to the "member" (a.k.a. "child") CIDs. A lot of data is visible at the parent level, but some data is only visible within each child. After creating an API Client, you can use that to retrieve a list of all available member CIDs (or provide specific members using MemberCid) and run PSFalcon commands within each child, while pausing between authorization token request attempts to avoid rate limiting.

#Requires -Version 5.1
using module @{ModuleName='PSFalcon';ModuleVersion='2.2'}
[CmdletBinding()]
param(
    [Parameter(Mandatory,Position=1)]
    [ValidatePattern('^[a-fA-F0-9]{32}$')]
    [string]$ClientId,
    [Parameter(Mandatory,Position=2)]
    [ValidatePattern('^\w{40}$')]
    [string]$ClientSecret,
    [Parameter(Position=3)]
    [ValidatePattern('^[a-fA-F0-9]{32}$')]
    [string[]]$MemberCid,
    [Parameter(Position=4)]
    [ValidateSet('us-1','us-2','us-gov-1','eu-1')]
    [string]$Cloud
)
begin {
    $Token = @{}
    @('ClientId','ClientSecret','Cloud').foreach{
        if ($PSBoundParameters.$_) { $Token[$_] = $PSBoundParameters.$_ }
    }
    if (!$MemberCid) {
        Request-FalconToken @Token
        if ((Test-FalconToken).Token -eq $true) {
            # Gather available Member CIDs
            [string[]]$MemberCid = Get-FalconMemberCid -Detailed -All | Where-Object { $_.status -eq 'active' } |
                Select-Object -ExpandProperty child_cid
            Revoke-FalconToken
        }
    }
}
process {
    foreach ($Cid in $MemberCid) {
        try {
            Request-FalconToken @Token -MemberCid $Cid
            if ((Test-FalconToken).Token -eq $true) {
                # Insert code to run in each CID here
            }
        } catch {
            Write-Error $_
        } finally {
            if ((Test-FalconToken).Token -eq $true) {
                Revoke-FalconToken
                Start-Sleep -Seconds 5
            }
        }
    }
}

Clone this wiki locally