public/falconx.ps1

function Get-FalconReport {
<#
.SYNOPSIS
Search for Falcon Intelligence Sandbox reports
.DESCRIPTION
Requires 'Sandbox (Falcon Intelligence): Read'.
.PARAMETER Id
Report identifier
.PARAMETER Filter
Falcon Query Language expression to limit results
.PARAMETER Sort
Property and direction to sort results
.PARAMETER Limit
Maximum number of results per request
.PARAMETER Offset
Position to begin retrieving results
.PARAMETER Summary
Return a summary version
.PARAMETER Detailed
Retrieve detailed information
.PARAMETER All
Repeat requests until all available results are retrieved
.PARAMETER Total
Display total result count instead of results
.LINK
https://github.com/crowdstrike/psfalcon/wiki/Get-FalconReport
#>

  [CmdletBinding(DefaultParameterSetName='/falconx/queries/reports/v1:get',SupportsShouldProcess)]
  param(
    [Parameter(ParameterSetName='/falconx/entities/reports/v1:get',Mandatory,ValueFromPipelineByPropertyName,
      ValueFromPipeline)]
    [Parameter(ParameterSetName='/falconx/entities/report-summaries/v1:get',Mandatory,
      ValueFromPipelineByPropertyName,ValueFromPipeline)]
    [ValidatePattern('^[a-fA-F0-9]{32}_[a-fA-F0-9]{32}$')]
    [Alias('ids')]
    [string[]]$Id,
    [Parameter(ParameterSetName='/falconx/queries/reports/v1:get',Position=1)]
    [ValidateScript({ Test-FqlStatement $_ })]
    [string]$Filter,
    [Parameter(ParameterSetName='/falconx/queries/reports/v1:get',Position=2)]
    [string]$Sort,
    [Parameter(ParameterSetName='/falconx/queries/reports/v1:get',Position=3)]
    [ValidateRange(1,5000)]
    [int32]$Limit,
    [Parameter(ParameterSetName='/falconx/queries/reports/v1:get')]
    [int32]$Offset,
    [Parameter(ParameterSetName='/falconx/entities/report-summaries/v1:get',Mandatory)]
    [switch]$Summary,
    [Parameter(ParameterSetName='/falconx/queries/reports/v1:get')]
    [switch]$Detailed,
    [Parameter(ParameterSetName='/falconx/queries/reports/v1:get')]
    [switch]$All,
    [Parameter(ParameterSetName='/falconx/queries/reports/v1:get')]
    [switch]$Total
  )
  begin {
    $Param = @{ Command = $MyInvocation.MyCommand.Name; Endpoint = $PSCmdlet.ParameterSetName }
    [System.Collections.Generic.List[string]]$List = @()
  }
  process {
    if ($Id) { @($Id).foreach{ $List.Add($_) }} else { Invoke-Falcon @Param -UserInput $PSBoundParameters }
  }
  end {
    if ($List) {
      $PSBoundParameters['Id'] = @($List)
      Invoke-Falcon @Param -UserInput $PSBoundParameters
    }
  }
}
function Get-FalconSubmission {
<#
.SYNOPSIS
Search for Falcon Intelligence Sandbox submissions
.DESCRIPTION
Requires 'Sandbox (Falcon Intelligence): Read'.
.PARAMETER Id
Submission identifier
.PARAMETER Filter
Falcon Query Language expression to limit results
.PARAMETER Sort
Property and direction to sort results
.PARAMETER Limit
Maximum number of results per request
.PARAMETER Offset
Position to begin retrieving results
.PARAMETER Detailed
Retrieve detailed information
.PARAMETER All
Repeat requests until all available results are retrieved
.PARAMETER Total
Display total result count instead of results
.LINK
https://github.com/crowdstrike/psfalcon/wiki/Get-FalconSubmission
#>

  [CmdletBinding(DefaultParameterSetName='/falconx/queries/submissions/v1:get',SupportsShouldProcess)]
  param(
    [Parameter(ParameterSetName='/falconx/entities/submissions/v1:get',Mandatory,ValueFromPipelineByPropertyName,
      ValueFromPipeline)]
    [ValidatePattern('^[a-fA-F0-9]{32}_[a-fA-F0-9]{32}$')]
    [Alias('ids')]
    [string[]]$Id,
    [Parameter(ParameterSetName='/falconx/queries/submissions/v1:get',Position=1)]
    [ValidateScript({ Test-FqlStatement $_ })]
    [string]$Filter,
    [Parameter(ParameterSetName='/falconx/queries/submissions/v1:get',Position=2)]
    [string]$Sort,
    [Parameter(ParameterSetName='/falconx/queries/submissions/v1:get',Position=3)]
    [ValidateRange(1,5000)]
    [int32]$Limit,
    [Parameter(ParameterSetName='/falconx/queries/submissions/v1:get')]
    [int32]$Offset,
    [Parameter(ParameterSetName='/falconx/queries/submissions/v1:get')]
    [switch]$Detailed,
    [Parameter(ParameterSetName='/falconx/queries/submissions/v1:get')]
    [switch]$All,
    [Parameter(ParameterSetName='/falconx/queries/submissions/v1:get')]
    [switch]$Total
  )
  begin {
    $Param = @{ Command = $MyInvocation.MyCommand.Name; Endpoint = $PSCmdlet.ParameterSetName }
    [System.Collections.Generic.List[string]]$List = @()
  }
  process {
    if ($Id) { @($Id).foreach{ $List.Add($_) }} else { Invoke-Falcon @Param -UserInput $PSBoundParameters }
  }
  end {
    if ($List) {
      $PSBoundParameters['Id'] = @($List)
      Invoke-Falcon @Param -UserInput $PSBoundParameters
    }
  }
}
function Get-FalconSubmissionQuota {
<#
.SYNOPSIS
Retrieve monthly Falcon Intelligence Sandbox submission quota
.DESCRIPTION
Requires 'Sandbox (Falcon Intelligence): Read'.
.LINK
https://github.com/crowdstrike/psfalcon/wiki/Get-FalconSubmissionQuota
#>

  [CmdletBinding(DefaultParameterSetName='/falconx/queries/submissions/v1:get',SupportsShouldProcess)]
  param()
  begin {
    $Param = @{
      Command = $MyInvocation.MyCommand.Name
      Endpoint = $PSCmdlet.ParameterSetName
      RawOutput = $true
    }
  }
  process {
    $Request = Invoke-Falcon @Param -EA 0
    if ($Request.Result.Content) {
      (ConvertFrom-Json ($Request.Result.Content).ReadAsStringAsync().Result).meta.quota
    } elseif ($Request) {
      throw "Unable to retrieve submission quota. Check client permissions."
    }
  }
}
function New-FalconSubmission {
<#
.SYNOPSIS
Submit a sample to the Falcon Intelligence Sandbox
.DESCRIPTION
'Sha256' values are retrieved from files that are uploaded using 'Send-FalconSample'. Files must be uploaded
before they can be provided to the Falcon Intelligence Sandbox.
 
Requires 'Sandbox (Falcon Intelligence): Write'.
.PARAMETER EnvironmentId
Analysis environment
.PARAMETER Url
A webpage or file URL
.PARAMETER ActionScript
Runtime script for sandbox analysis
.PARAMETER CommandLine
Command line script passed to the submitted file at runtime
.PARAMETER SystemDate
A custom date to use in the analysis environment
.PARAMETER SystemTime
A custom time to use in the analysis environment
.PARAMETER DocumentPassword
Auto-filled for Adobe or Office files that prompt for a password
.PARAMETER NetworkSetting
Network settings to use in the analysis environment
.PARAMETER EnableTor
Route traffic via TOR
.PARAMETER UserTag
Tags to categorize the submission
.PARAMETER SubmitName
Submission name
.PARAMETER Sha256
Sha256 hash value
.LINK
https://github.com/crowdstrike/psfalcon/wiki/New-FalconSubmission
#>

  [CmdletBinding(DefaultParameterSetName='/falconx/entities/submissions/v1:post',SupportsShouldProcess)]
  param(
    [Parameter(ParameterSetName='/falconx/entities/submissions/v1:post',Mandatory,Position=1)]
    [ValidateSet('android','macOS_10.15','ubuntu16_x64','win7_x64','win7_x86','win10_x64',IgnoreCase=$false)]
    [Alias('environment_id')]
    [string]$EnvironmentId,
    [Parameter(ParameterSetName='/falconx/entities/submissions/v1:post',Position=2)]
    [string]$Url,
    [Parameter(ParameterSetName='/falconx/entities/submissions/v1:post',Position=3)]
    [ValidateSet('default','default_maxantievasion','default_randomfiles','default_randomtheme',
      'default_openie',IgnoreCase=$false)]
    [Alias('action_script')]
    [string]$ActionScript,
    [Parameter(ParameterSetName='/falconx/entities/submissions/v1:post',Position=4)]
    [Alias('command_line')]
    [string]$CommandLine,
    [Parameter(ParameterSetName='/falconx/entities/submissions/v1:post',Position=5)]
    [ValidatePattern('^\d{4}-\d{2}-\d{2}$')]
    [Alias('system_date')]
    [string]$SystemDate,
    [Parameter(ParameterSetName='/falconx/entities/submissions/v1:post',Position=6)]
    [ValidatePattern('^\d{2}:\d{2}$')]
    [Alias('system_time')]
    [string]$SystemTime,
    [Parameter(ParameterSetName='/falconx/entities/submissions/v1:post',Position=7)]
    [Alias('document_password')]
    [string]$DocumentPassword,
    [Parameter(ParameterSetName='/falconx/entities/submissions/v1:post',Position=8)]
    [ValidateSet('default','tor','simulated','offline',IgnoreCase=$false)]
    [Alias('network_settings','NetworkSettings')]
    [string]$NetworkSetting,
    [Parameter(ParameterSetName='/falconx/entities/submissions/v1:post',Position=9)]
    [Alias('enable_tor')]
    [boolean]$EnableTor,
    [Parameter(ParameterSetName='/falconx/entities/submissions/v1:post',Position=10)]
    [Alias('user_tags','UserTags')]
    [string[]]$UserTag,
    [Parameter(ParameterSetName='/falconx/entities/submissions/v1:post',ValueFromPipelineByPropertyName,
      Position=11)]
    [Alias('submit_name','file_name')]
    [string]$SubmitName,
    [Parameter(ParameterSetName='/falconx/entities/submissions/v1:post',ValueFromPipelineByPropertyName,
      ValueFromPipeline,Position=12)]
    [ValidatePattern('^[A-Fa-f0-9]{64}$')]
    [string]$Sha256
  )
  begin {
    $Param = @{
      Command = $MyInvocation.MyCommand.Name
      Endpoint = $PSCmdlet.ParameterSetName
      Format = @{
        Body = @{
          root = @('user_tags')
          sandbox = @('submit_name','system_date','action_script','environment_id','command_line','system_time',
            'url','document_password','enable_tor','sha256','network_settings')
        }
      }
    }
  }
  process {
    if ($PSBoundParameters.Url -and $PSBoundParameters.Sha256) {
      throw "'Url' and 'Sha256' can not be combined in a submission."
    } else {
      $PSBoundParameters.EnvironmentId = switch ($PSBoundParameters.EnvironmentId) {
        'android' { 200 }
        'macOS_10.15' { 400 }
        'ubuntu16_x64' { 300 }
        'win7_x64' { 110 }
        'win7_x86' { 100 }
        'win10_x64' { 160 }
      }
      Invoke-Falcon @Param -UserInput $PSBoundParameters
    }
  }
}
function Receive-FalconArtifact {
<#
.SYNOPSIS
Download an artifact from a Falcon Intelligence Sandbox report
.DESCRIPTION
Artifact identifier values can be retrieved for specific Falcon Intelligence Sandbox reports using
'Get-FalconReport'.
 
Requires 'Sandbox (Falcon Intelligence): Read'.
.PARAMETER Path
Destination path
.PARAMETER Id
Artifact identifier
.PARAMETER Force
Overwrite an existing file when present
.LINK
https://github.com/crowdstrike/psfalcon/wiki/Receive-FalconArtifact
#>

  [CmdletBinding(DefaultParameterSetName='/falconx/entities/artifacts/v1:get',SupportsShouldProcess)]
  param(
    [Parameter(ParameterSetName='/falconx/entities/artifacts/v1:get',Mandatory,Position=1)]
    [string]$Path,
    [Parameter(ParameterSetName='/falconx/entities/artifacts/v1:get',Mandatory,ValueFromPipelineByPropertyName,
      ValueFromPipeline,Position=2)]
    [ValidatePattern('^[A-Fa-f0-9]{64}$')]
    [string]$Id,
    [Parameter(ParameterSetName='/falconx/entities/artifacts/v1:get')]
    [switch]$Force
  )
  begin {
    $Param = @{
      Command = $MyInvocation.MyCommand.Name
      Endpoint = $PSCmdlet.ParameterSetName
      Headers = @{ Accept = 'application/octet-stream' }
      Format = Get-EndpointFormat $PSCmdlet.ParameterSetName
    }
    $Param.Format['Outfile'] = 'path'
  }
  process {
    $OutPath = Test-OutFile $PSBoundParameters.Path
    if ($OutPath.Category -eq 'ObjectNotFound') {
      Write-Error @OutPath
    } elseif ($PSBoundParameters.Path) {
      if ($OutPath.Category -eq 'WriteError' -and !$Force) {
        Write-Error @OutPath
      } else {
        Invoke-Falcon @Param -UserInput $PSBoundParameters
      }
    }
  }
}
function Receive-FalconMemoryDump {
<#
.SYNOPSIS
Download a memory dump or extracted strings from a Falcon Intelligence Sandbox report
.DESCRIPTION
Requires 'Sandbox (Falcon Intelligence): Read'.
.PARAMETER Path
Destination path
.PARAMETER BinaryId
Binary content dump identifier
.PARAMETER ExtractId
Extracted string identifier
.PARAMETER HexId
Hex dump identifier
.PARAMETER Force
Overwrite an existing file when present
.LINK
https://github.com/crowdstrike/psfalcon/wiki/Receive-FalconMemoryDump
#>

  [CmdletBinding(DefaultParameterSetName='/falconx/entities/memory-dump/v1:get',SupportsShouldProcess)]
  param(
    [Parameter(ParameterSetName='/falconx/entities/memory-dump/v1:get',Position=1)]
    [Parameter(ParameterSetName='/falconx/entities/memory-dump/extracted-strings/v1:get',Position=1)]
    [Parameter(ParameterSetName='/falconx/entities/memory-dump/hex-dump/v1:get',Position=1)]
    [ValidatePattern('\.gzip$')]
    [string]$Path,
    [Parameter(ParameterSetName='/falconx/entities/memory-dump/v1:get',Mandatory,ValueFromPipelineByPropertyName,
      ValueFromPipeline,Position=2)]
    [ValidatePattern('^[A-Fa-f0-9]{64}$')]
    [Alias('binary_content_id')]
    [string]$BinaryId,
    [Parameter(ParameterSetName='/falconx/entities/memory-dump/extracted-strings/v1:get',Mandatory,
      ValueFromPipelineByPropertyName,Position=2)]
    [ValidatePattern('^[A-Fa-f0-9]{64}$')]
    [Alias('extracted_strings_id')]
    [string]$ExtractId,
    [Parameter(ParameterSetName='/falconx/entities/memory-dump/hex-dump/v1:get',Mandatory,
      ValueFromPipelineByPropertyName,Position=2)]
    [ValidatePattern('^[A-Fa-f0-9]{64}$')]
    [Alias('hex_dump_id')]
    [string]$HexId,
    [Parameter(ParameterSetName='/falconx/entities/memory-dump/v1:get')]
    [Parameter(ParameterSetName='/falconx/entities/memory-dump/extracted-strings/v1:get')]
    [Parameter(ParameterSetName='/falconx/entities/memory-dump/hex-dump/v1:get')]
    [switch]$Force
  )
  begin {
    $Param = @{
      Command = $MyInvocation.MyCommand.Name
      Endpoint = $PSCmdlet.ParameterSetName
      Headers = @{ Accept = 'application/octet-stream'; 'Accept-Encoding' = 'gzip' }
      Format = @{ Query = @('name','id') }
    }
    $PSBoundParameters['id'] = switch ($PSBoundParameters) {
      { $_.BinaryId } { $PSBoundParameters.BinaryId }
      { $_.ExtractId } { $PSBoundParameters.ExtractId }
      { $_.HexId } { $PSBoundParameters.HexId }
    }
    @('BinaryId','ExtractId','HexId').foreach{ if ($PSBoundParameters.$_) { [void]$PSBoundParameters.Remove($_) }}
  }
  process {
    $OutPath = Test-OutFile $PSBoundParameters.Path
    if ($OutPath.Category -eq 'ObjectNotFound') {
      Write-Error @OutPath
    } elseif ($PSBoundParameters.Path) {
      if ($OutPath.Category -eq 'WriteError' -and !$Force) {
        Write-Error @OutPath
      } else {
        Invoke-Falcon @Param -UserInput $PSBoundParameters
      }
    }
  }
}
function Remove-FalconReport {
<#
.SYNOPSIS
Remove a Falcon Intelligence Sandbox report
.DESCRIPTION
Requires 'Sandbox (Falcon Intelligence): Write'.
.PARAMETER Id
Report identifier
.LINK
https://github.com/crowdstrike/psfalcon/wiki/Remove-FalconReport
#>

  [CmdletBinding(DefaultParameterSetName='/falconx/entities/reports/v1:delete',SupportsShouldProcess)]
  param(
    [Parameter(ParameterSetName='/falconx/entities/reports/v1:delete',Mandatory,ValueFromPipelineByPropertyName,
      ValueFromPipeline,Position=1)]
    [Alias('ids')]
    [string]$Id
  )
  begin { $Param = @{ Command = $MyInvocation.MyCommand.Name; Endpoint = $PSCmdlet.ParameterSetName }}
  process { Invoke-Falcon @Param -UserInput $PSBoundParameters }
}