Created
August 31, 2022 20:40
-
-
Save kevinelwell/eeaa0482baec8355d27d235aa1c2532b to your computer and use it in GitHub Desktop.
Testing PSFalcon
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| #Requires -Version 5.1 | |
| #Requires -Modules PSFalcon | |
| <# | |
| .SYNOPSIS | |
| This script will copy and execute the KAPE forensics tool on a remote | |
| Microsoft Windows host using CrowdStrike API's and RTR | |
| .DESCRIPTION | |
| Script that leverages the PSFalcom PowerShell module | |
| https://github.com/CrowdStrike/psfalcon | |
| Version 3.0 has ben tested with this script | |
| .INPUTS | |
| Users are prompted to select the appropriate CrowdStrike Cloud | |
| Users must supply their clientID and secret API keys | |
| Users must supply either the host's AID or host name | |
| .OUTPUTS | |
| Verbose logging to C:\Temp\PSFalcon-KAPE-Forensics.log | |
| .NOTES | |
| Version: 1.2 | |
| Script Name: PSFalcon-KAPE-Forensics.ps1 | |
| Author: Kevin Elwell | |
| Creation Date: 8/25/2022 | |
| Purpose/Change: Initial script development | |
| #> | |
| # Import the psfalcon module - REQUIRES the PSFalcon PowerShell Module be placed in one of the PowerShell Modules directories | |
| Import-Module -Name PSFalcon -Force -PassThru | |
| #region Variables | |
| # Initialize some Variables | |
| $LogFolder = "C:\Temp\PSFalcon" | |
| $LogFile = $LogFolder + "\" + "PSFalcon-KAPE-Forensics.log" | |
| # Create C:\Temp\PSFalcon directory | |
| New-Item -Path $LogFolder -ItemType Directory -Force -ErrorAction SilentlyContinue | |
| #Script Version | |
| $ScriptVersion = "1.2" | |
| #endregion Variables | |
| #region Functions | |
| # Logging function | |
| Function Write-Log | |
| { | |
| param ( | |
| [Parameter(Mandatory=$True)] | |
| [array]$LogOutput, | |
| [Parameter(Mandatory=$True)] | |
| [ValidateSet("INFO","WARN","ERROR","FATAL","DEBUG")] | |
| [string]$level = "INFO", | |
| [Parameter(Mandatory=$True)] | |
| [string]$Path | |
| ) | |
| "[" + (Get-Date -f g) + "] " + $level + ": " + $logOutput | Out-File $Path -Append | |
| # Write-Log -level DEBUG -LogOutput "Testing 456" -Path $LogFile | |
| # Produces the following line: [8/31/2022 12:44 PM] DEBUG: Testing 456 | |
| } | |
| Function Select-HostqueryType{ | |
| #Clear-Host | |
| do { | |
| Write-Host "`n========================== SELECT HOST ==============================" -ForegroundColor Cyan | |
| Write-Host " PLEASE SELECT AN OPTION BELOW TO EXECUTE THE KAPE FORENSICS TOOL" -ForegroundColor Cyan | |
| Write-Host "`'1' TARGET HOST USIN AID" -ForegroundColor Cyan | |
| Write-Host "`'2' TARGET HOST USING HOSTNAME" -ForegroundColor Cyan | |
| Write-Host "`'Q' QUIT" -ForegroundColor Cyan | |
| Write-Host "=======================================================================" -ForegroundColor Cyan | |
| # Prompt user to select one of the CrowdStrike Cloud environments | |
| $choice = Read-Host "`nENTER CHOICE" | |
| } until (($choice -eq '1') -or ($choice -eq '2') -or ($choice -eq 'Q') ) | |
| switch ($choice) { | |
| '1'{ | |
| Write-Host "`nYOU HAVE SELECTED TO USE THE AID OF THE HOST" -ForegroundColor Green | |
| $hostquerymethod = "aid" | |
| $hostquery = Read-Host "`nENTER THE AID" | |
| } | |
| '2'{ | |
| Write-Host "`nYOU HAVE SELECTED TO USE THE HOSTNAME OF THE HOST" -ForegroundColor Green | |
| $hostquerymethod = "hostname" | |
| $hostquery = Read-Host "`nENTER THE HOSTNAME" | |
| } | |
| 'Q'{ | |
| Write-Host "`nEXITING THE MENU. PLEASE NOTE YOU MUST SELECT EITHER AID OR HOSTNAME TO PROCEED." -ForegroundColor Red | |
| $hostquery = "quit" | |
| } | |
| } | |
| If($hostquery -ne "quit") { | |
| # Log the choice from above | |
| Write-Log -level INFO -LogOutput "User choose to find the host via $hostquerymethod." -Path $LogFile | |
| Return $hostquerymethod, $hostquery | |
| } | |
| If($hostquery -eq "quit") { | |
| # Log that the user choose to quit | |
| Write-Log -level INFO -LogOutput "User choose to quit the menu. Execution halting." -Path $LogFile | |
| Break | |
| } | |
| } | |
| Function CS-Cloud { | |
| Clear-Host | |
| do { | |
| Write-Host "`n============= SELECT THE APPROPRIATE CROWDSTRIKE CLOUD ==============" -ForegroundColor Cyan | |
| Write-Host "`'1' for US-1 Cloud" -ForegroundColor Cyan | |
| Write-Host "`'2' for US-2 Cloud" -ForegroundColor Cyan | |
| Write-Host "`'3' for EU Cloud" -ForegroundColor Cyan | |
| Write-Host "`'4' for GOV Cloud" -ForegroundColor Cyan | |
| Write-Host "`'Q' to Quit" -ForegroundColor Cyan | |
| Write-Host "=======================================================================" -ForegroundColor Cyan | |
| # Prompt user to select one of the CrowdStrike Cloud environments | |
| $choice = Read-Host "`nEnter Choice" | |
| } until (($choice -eq '1') -or ($choice -eq '2') -or ($choice -eq '3') -or ($choice -eq '4') -or ($choice -eq 'Q') ) | |
| switch ($choice) { | |
| '1'{ | |
| Write-Host "`nYou have selected the US-1 Cloud" -ForegroundColor Green | |
| $cloud = "us-1" | |
| } | |
| '2'{ | |
| Write-Host "`nYou have selected the US-2 Cloud" -ForegroundColor Green | |
| $cloud = "us-2" | |
| } | |
| '3'{ | |
| Write-Host "`nYou have selected the EU Cloud" -ForegroundColor Yellow | |
| $cloud = "eu-1" | |
| } | |
| '4'{ | |
| Write-Host "`nYou have selected the GOV Cloud" -ForegroundColor Cyan | |
| $cloud = "us-gov-1" | |
| } | |
| 'Q'{ | |
| Write-Host "`nExiting menu. Please note you MUST select one of the CrowdStrike Cloud environments." -ForegroundColor Red | |
| $cloud = "quit" | |
| } | |
| } | |
| If($cloud -ne "quit") { | |
| # Log the choice from above | |
| Write-Log -level INFO -LogOutput "User choose the CrowdStrike $cloud Cloud." -Path $LogFile | |
| Return $cloud | |
| } | |
| If($cloud -eq "quit") { | |
| # Log that the user choose to quit | |
| Write-Log -level INFO -LogOutput "User choose to quit the menu. Execution halting." -Path $LogFile | |
| Break | |
| } | |
| } | |
| #endregion Functions | |
| # Prompt the user for the CrowdStrike Cloud environment | |
| $cloudenv = CS-Cloud | |
| # Prompt for the API clientid and secret | |
| #$clientid = Read-Host -Prompt 'INPUT YOUR CLIENT ID API KEY' | |
| #$secret = Read-Host -Prompt 'INPUT YOUR API SECRET' | |
| # Force TLS 1.2 | |
| [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12 | |
| # Request an oAUTH2 token | |
| try { | |
| Request-FalconToken -ClientId $clientid -ClientSecret $secret -Cloud $cloudenv; | |
| If ((Test-FalconToken).Token -eq $true) { | |
| Write-Host "`n`rWE RECEIVED A TOKEN. PROCEEDING.`n`r" -ForegroundColor Green; | |
| # Log that a token was received | |
| Write-Log -level INFO -LogOutput "Token received successfully." -Path $LogFile | |
| } | |
| } catch { | |
| Write-Host "`n`rERROR! WE DID NOT RECEIVE A TOKEN!`n`r" -ForegroundColor Red; | |
| # Log that a token was NOT received | |
| Write-Log -level ERROR -LogOutput "Token was NOT received successfully." -Path $LogFile | |
| Break | |
| } | |
| # Gather information from the Select-HostQueryType function | |
| $Hostqmethod, $Hostq = Select-HostqueryType | |
| # Determine the operating system, hostname and/or AID | |
| If($Hostqmethod -ieq "aid") { $oscheck = Get-FalconHost -Ids $hostq | Select-Object os_version, hostname | |
| If($oscheck.os_version -inotmatch "windows") { | |
| Write-Host "`n`rERROR: THIS SCRIPT ONLY SUPPORTS MICROSOFT WINDOWS OPERATING SYSTEMS. QUITTING SCRIPT..`n`r" -ForegroundColor Red | |
| Write-Log -level ERROR -LogOutput "THIS SCRIPT ONLY SUPPORTS MICROSOFT WINDOWS OPERATING SYSTEMS. QUITTING SCRIPT" -Path $LogFile | |
| Revoke-FalconToken | |
| }else{ | |
| Write-Host "`n`rMICROSOFT WINDOWS OPERATING SYSTEM DETECTED. PROCEEDING..`n`r" -ForegroundColor Green | |
| Write-Log -level INFO -LogOutput "MICROSOFT WINDOWS OPERATING SYSTEM DETECTED. PROCEEDING" -Path $LogFile | |
| # Define a variable to hold the AID | |
| $hostaid = $hostq | |
| } | |
| } | |
| # Determine the operating system, hostname and/or AID | |
| If($hostqmethod -ieq "hostname") { $oscheck1 = Get-FalconHost -Filter "hostname:['$hostq']" -Detailed | Select-Object os_version, device_id | |
| If($oscheck.os_version -inotmatch "windows") { | |
| Write-Host "`n`rERROR: THIS SCRIPT ONLY SUPPORTS MICROSOFT WINDOWS OPERATING SYSTEMS. QUITTING SCRIPT..`n`r" -ForegroundColor Red | |
| Write-Log -level ERROR -LogOutput "THIS SCRIPT ONLY SUPPORTS MICROSOFT WINDOWS OPERATING SYSTEMS. QUITTING SCRIPT" -Path $LogFile | |
| Revoke-FalconToken | |
| Break | |
| }else{ | |
| Write-Host "`n`rMICROSOFT WINDOWS OPERATING SYSTEM DETECTED. PROCEEDING..`n`r" -ForegroundColor Green | |
| Write-Log -level INFO -LogOutput "MICROSOFT WINDOWS OPERATING SYSTEM DETECTED. PROCEEDING" -Path $LogFile | |
| # Define a variable to hold the AID | |
| $hostaid = $oscheck1.device_id | |
| } | |
| } | |
| # Initialize the connection to the remote machine | |
| #-------------------------------------------------------------------- | |
| #-------------------------------------------------------------------- | |
| # IMPORTANT - Start-FalconSession Requires: 'real-time-response:read' | |
| #-------------------------------------------------------------------- | |
| #-------------------------------------------------------------------- | |
| $Init = Start-FalconSession -HostId $hostaid | |
| # Drop KAPE-RTR.7z into C:\ directory | |
| $put1 = Invoke-FalconAdminCommand -SessionId $Init.session_id -Command put -Arguments KAPE-RTR.7z | |
| Confirm-FalconCommand -CloudRequestId $put1.cloud_request_id | |
| Start-Sleep -Seconds 2 | |
| # Drop 7za.exe into C:\ directory | |
| $put2 = Invoke-FalconAdminCommand -SessionId $Init.session_id -Command put -Arguments 7za.exe | |
| Confirm-FalconCommand -CloudRequestId $put2.cloud_request_id | |
| Start-Sleep -Seconds 5 | |
| # Execute C:\7za.exe to extract C:\KAPE-RTR.7z to C:\KAPE-RTR | |
| $x = Invoke-FalconAdminCommand -SessionId $Init.session_id -Command 'runscript' -Arguments '-Raw=```C:\7za.exe x C:\KAPE-RTR.7z``` -Timeout=500' | |
| Confirm-FalconCommand -CloudRequestId $x.cloud_request_id | |
| Start-Sleep -Seconds 8 | |
| # Move C:\KAPE-RTR to C:\Temp\KAPE-RTR | |
| $command3 = Invoke-FalconAdminCommand -SessionId $Init.session_id -Command mv -Arguments 'C:\KAPE-RTR C:\Temp\KAPE-RTR' | |
| Confirm-FalconCommand -CloudRequestId $command3.cloud_request_id | |
| Start-Sleep -Seconds 16 | |
| # Update the RTR session so expiration time is reset to 10 minutes | |
| #Update-FalconSession -SessionId $Session.session_id | |
| # Execute kape.exe --ul (this command will reference the C:\Temp\KAPE-RTR\_kape.cli file for instructions) | |
| $h = Invoke-FalconAdminCommand -SessionId $Init.session_id -Command 'runscript' -Arguments '-Raw=```C:\Temp\KAPE-RTR\kape.exe --ul``` -Timeout=900' | |
| Confirm-FalconCommand -CloudRequestId $h.cloud_request_id | |
| Start-Sleep 120 | |
| # Update the RTR session so expiration time is reset to 10 minutes | |
| #Update-FalconSession -SessionId $Session.session_id | |
| # Change directories into C:\Temp | |
| $1command = Invoke-FalconCommand -Command cd -Arguments 'C:\Temp\CSKAPE' -SessionId $Init.session_id | |
| #$confirmCD = | |
| Confirm-FalconCommand -CloudRequestId $1command.cloud_request_id | |
| Start-Sleep 2 | |
| # Zip up the results of the KAPE execution | |
| $z = Invoke-FalconAdminCommand -SessionId $Init.session_id -Command 'runscript' -Arguments '-Raw=```C:\7za.exe a -t7z C:\Temp\CSKAPE\$env:COMPUTERNAME.7z C:\Temp\CSKAPE\$env:COMPUTERNAME``` -Timeout=900' | |
| Confirm-FalconCommand -CloudRequestId $z.cloud_request_id | |
| Start-Sleep 120 | |
| # Update the RTR session so expiration time is reset to 10 minutes | |
| #Update-FalconSession -SessionId $Session.session_id | |
| # Pull the KAPE zipped file from the host | |
| $Get = Invoke-FalconAdminCommand -SessionId $Init.session_id -Command get -Arguments C:\Temp\CSKAPE\$env:COMPUTERNAME.7z | |
| $Confirm = Confirm-FalconGetFile -SessionId $Init.session_id | |
| #$Confirm | |
| # Receive the zipped KAPE file | |
| #$Confirm = Confirm-FalconGetFile -SessionId $Init.session_id | |
| Receive-FalconGetFile -Sha256 $Confirm.sha256 -SessionId $Init.session_id -Path $env.USERPROFILE\Downloads\$env:COMPUTERNAME.7z | |
| $ConfirmReceive = Confirm-FalconGetFile -SessionId $Init.session_id | |
| #$ConfirmReceive | |
| # Remove C:\KAPE-RTR.7z | |
| $removeput1 = Invoke-FalconAdminCommand -SessionId $Init.session_id -Command rm -Arguments '-Force C:\KAPE-RTR.7z' | |
| Confirm-FalconCommand -CloudRequestId $removeput1.cloud_request_id | |
| Start-Sleep -Seconds 2 | |
| # Remove C:\7za.exe | |
| $removeput2 = Invoke-FalconAdminCommand -SessionId $Init.session_id -Command rm -Arguments '-Force 7za.exe' | |
| Confirm-FalconCommand -CloudRequestId $removeput2.cloud_request_id | |
| Start-Sleep 2 | |
| # Remove the directory C:\Temp\KAPE-RTR and its contents | |
| $removeput3 = Invoke-FalconAdminCommand -SessionId $Init.session_id -Command rm -Arguments '-Force C:\Temp\KAPE-RTR' | |
| Confirm-FalconCommand -CloudRequestId $removeput3.cloud_request_id | |
| Start-Sleep 2 | |
| # Remove the directory C:\Temp\CSKAPE\$env:COMPUTERNAME and its contents | |
| $removeput4 = Invoke-FalconAdminCommand -SessionId $Init.session_id -Command 'runscript' -Arguments '-Raw=```Remove-Item -Path C:\Temp\CSKAPE\$env:COMPUTERNAME -Recurse -Force``` -Timeout=900' | |
| Confirm-FalconCommand -CloudRequestId $removeput4.cloud_request_id | |
| Start-Sleep 2 | |
| # Remove the file C:\Temp\CSKAPE\$env:COMPUTERNAME.7z and its contents | |
| $removeput5 = Invoke-FalconAdminCommand -SessionId $Init.session_id -Command 'runscript' -Arguments '-Raw=```Remove-Item -Path C:\Temp\CSKAPE\$env:COMPUTERNAME.7z -Force``` -Timeout=900' | |
| Confirm-FalconCommand -CloudRequestId $removeput5.cloud_request_id | |
| Start-Sleep 2 | |
| # Remove the file C:\Temp\CSKAPE\ | |
| $removeput6 = Invoke-FalconAdminCommand -SessionId $Init.session_id -Command 'runscript' -Arguments '-Raw=```Remove-Item -Path C:\Temp\CSKAPE -Force``` -Timeout=900' | |
| Confirm-FalconCommand -CloudRequestId $removeput6.cloud_request_id | |
| # Revoke Falcon Token | |
| Revoke-FalconToken | |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment