2.2.0

[bk-cs]

New Commands

* spotlight-vulnerabilities.ps1
  Get-FalconVulnerabilityLogic

General Changes

* Re-added basic help information to each command. This will increase module size, but will eliminate the
  need to 'Update-Help' to get descriptions for each command, its parameters and the required API
  permission(s).

* Thanks to some knowledge shared by @kra-ts, PowerShell pipeline support is now cross-module and no longer
  restricted to specific commands!

  Before this release, PSFalcon supported pipeline input when a command accepted a single 'id'. With these
  changes, PSFalcon collects multiple 'ids' passed through the pipeline, groups them and sends appropriately
  sized API requests.

  This change also required the re-positioning of many parameters, the addition of aliases, and the majority of
  [array] parameters being converted into [string[]] or [int[]]. When it was logically possible, [array] values
  were also converted into [object[]] to allow for the processing of both 'id' and 'detailed' values.

* Warning messages have been added when hosts are not included in a batch Real-time Response session
  ('Start-FalconSession') or when Real-time Response commands produce errors ('Invoke-FalconCommand',
  'Invoke-FalconResponderCommand', 'Invoke-FalconAdminCommand', 'Invoke-FalconBatchGet') so it will be more
  obvious what happened when hosts are missing from the final result that was passed through the pipeline.

* Renamed plural parameters ('Ids') to singular ('Id') to follow PowerShell best practices. Each updated
  parameter kept maintains the plural version as an alias (or the original parameter name when switching to the
  singular was not possible due to incompatibilities with PowerShell) to prevent errors with existing scripts.

* Modified commands to use the alias values for parameters instead of the 'Fields' variable that was used to
  to rename parameters to fit API submission structure. Removing 'Fields' also enabled the removal of the
  private function 'Update-FieldName'.

* When applicable, the 'Id' parameter attributes were modified to ensure that 'Get-Help' properly displayed
  that the parameter name needs to be explicitly included.

* Added case enforcement to all 'ValidateSet' values. This ensures that proper case is used with parameters
  that have a pre-defined list of accepted values and preventing errors from the resulting API.

* Added 'raw_array' as a field to be used when defining the format of a 'body' submission inside of a PSFalcon
  command. Using it will instruct the module to create a 'body' object that has a base [array] value containing
  the object properties to be converted to Json.

* Updated 'Build-Formdata' private function to attempt to gather file content for the 'content' field, or
  supply the original value if that fails. This change was made to allow 'Send-FalconScript' to use a file
  path or string-based script content.

* Created 'Add-Include' private function to append 'Include' content to command results.

* Created 'Assert-Extension' private function to validate a given file extension when using 'Receive' commands.

* Renamed 'Add-Property' private function to 'Set-Property' and updated it to add a property when it doesn't
  exist, or update the value if it does exist.

* Updated 'Get-RtrCommand' private function to output available Real-time Response commands by permission,
  or all available Real-time Response commands if permission is not defined.

* Created 'Test-OutFile' private function to validate the presence of an existing file and generate error
  messages when using 'Receive' commands.

* Moved verbose output of 'body' and 'formdata' payloads from 'Build-Content' to ApiClient.Invoke() during a
  request. This ensures that individual submissions are displayed, rather than the initial submission before it
  has been broken up into groups.

* Moved verbose output of Header keys and values within an API response from 'Write-Result' to
  ApiClient.Invoke(). 'Write-Result' continues to display the 'meta' Json values due to the addition of an
  internal function called 'Write-Meta'.

* Added '-Force' parameter to the following commands to overwrite an existing file when present:
  Export-FalconConfig
  Receive-FalconHorizonAwsScript
  Receive-FalconHorizonAzureScript
  Receive-FalconDiscoverAzureScript
  Receive-FalconDiscoverGcpScript
  Receive-FalconIntel
  Receive-FalconRule
  Receive-FalconArtifact
  Receive-FalconContainerYaml
  Receive-FalconMalQuerySample
  Receive-FalconCompleteAttachment
  Receive-FalconGetFile
  Receive-FalconSample
  Receive-FalconScheduledReport
  Receive-FalconInstaller

* Added '-Include' parameter to append 'members' to the following commands:
  Get-FalconHostGroup
  Get-FalconDeviceControlPolicy
  Get-FalconFirewallPolicy
  Get-FalconPreventionPolicy
  Get-FalconResponsePolicy
  Get-FalconSensorUpdatePolicy

* Updated commands that output to CSV ('Import-FalconConfig', 'Export-FalconReport', 'Get-FalconQueue',
'Invoke-FalconDeploy') to send their results to 'Write-Output' when unable to write to CSV.

* Removed position attribute from all pagination parameters ('After', 'Offset', 'NextToken').

Command Changes

* Confirm-FalconGetFile, Remove-FalconGetFile
  Updated to use v2 API endpoint that includes upload progress.

* ConvertTo-FalconMlExclusion, ConvertTo-FalconIoaExclusion
  Commands have been corrected to properly produce individual exclusions for each relevant behavior within a
  detection (rather than one exclusion with values from multiple behaviors).

* Edit-FalconFirewallSetting, Edit-FalconHorizonPolicy
  Renamed '-PolicyId' to '-Id'.

* Export-FalconConfig
  Now includes 'Script' (Real-time Response scripts) as an exportable item.

  Output filename now contains a 'FileDateTime' timestamp instead of simply 'FileDate'. This was done to
  match changes made to 'Import-FalconConfig'.

* Find-FalconDuplicate
  Updated to accommodate multiple 'Filter' values.

* Get-FalconAsset
  Added '-Account' and '-Login' switch parameters to toggle access of Falcon Discover user account assets
  and user login events.

  Added '-Include' to append login events both the default hardware asset and user account output.

* Get-FalconDetection
  Added valid 'Sort' values.

* Get-FalconFirewallPolicy
  Re-added the 'policy_id' in the 'settings' sub-object that is created when using '-Include settings'. This
  was originally removed for being redundant, but needed to be restored to be utilized by the 
  'Copy-FalconFirewallPolicy' command.

* Get-FalconHorizonIoa, Get-FalconHorizonIoaEvent, Get-FalconHorizonIoaUser, Get-FalconHorizonIom
  Removed 'Mandatory' status for '-CloudPlatform', instead populating it if 'AwsAccountId' (or 'AccountId',
  in the case of 'Get-FalconHorizonIom'), 'AzureSubscriptionId', or 'AzureTenantId' are provided. Without one
  of the four values, the command will produce an exception.

* Get-FalconHorizonIoaEvent, Get-FalconHorizonIoaUser
  Replaced '-AccountId' with '-AwsAccountId' and added '-AzureSubscriptionId' and '-AzureTenantId' to match
  'Get-FalconHorizonIoa'.

* Get-FalconHorizonIom
  Renamed parameter '-AwsAccountId' to '-AccountId', which accepts an AWS account ID or GCP Project Number
  value. Also corrected the accepted '-Status' value 'recurring' to 'reoccurring'.

* Get-FalconHost
  '-Detailed' output will no longer be forced when using '-Include group_names', and instead will include
  'device_id' and 'groups'. Using '-Detailed' and '-Include group_names' maintains full output.

  Added 'online_state' to '-Include' to retrieve detail from new 'online status' API.

  Added '-State' switch to be used with '-Id' to retrieve detail from the new 'online status' API.

* Get-FalconQueue
  Updated command to write progress to host stream instead of verbose stream.

* Get-FalconVulnerability
  Added 'evaluation_logic' to the 'Facet' parameter.

* Import-FalconConfig
  Completely re-written to utilize the pipeline and excluded items (with the reason they were excluded) are
  now included within the resulting CSV output.

  Now includes 'Script' (Real-time Response scripts) as an importable item.

  Output filename now contains a 'FileDateTime' timestamp instead of simply 'FileDate'. This was done because
  verbosity of the output was increased and appending to an existing file would cause output problems.

  Removed warning message that was generated when no items were created because the CSV output now displays
  both excluded and created items.

* Invoke-FalconBatchGet, Invoke-FalconCommand, Invoke-FalconAdminCommand, Invoke-FalconResponderCommand
  Added a new '-Confirm' parameter to confirm and retrieve the output from both single-host commands and batch
  'get' commands.

  'Invoke-FalconAdminCommand' and 'Invoke-FalconResponderCommand' will now redirect to 'Invoke-FalconBatchGet'
  when used to 'get' within a multi-host session.

  Each of the commands now appends 'batch_id' to the output of commands issued within a batch session.

* Invoke-FalconCommand, Invoke-FalconAdminCommand, Invoke-FalconResponderCommand, Invoke-FalconRtr
  Split the 'eventlog' command into 'eventlog backup', 'eventlog export', 'eventlog list', and 'eventlog view'.

* Invoke-FalconDeploy
  Contribution from @soggysec: Changed '-Path' to '-File' (with a 'Path' alias) and added '-Archive' (with a
  corresponding '-Run' parameter) to allow for a file or archive to be specified. If 'Archive' is used,
  Real-time Response will be used to 'runscript' and extract the files, then 'run' the specified 'Run' file,
  allowing the deployment of files that require additional files to be present in order to execute.

  Added 'mkdir' step to create a temporary folder in order to ensure that a unique file will be 'put' and 'run'
  each time, instead of failing when a previous 'put' occurred. CSV output was slightly modified as a result.

  If you specify a .ps1, .sh or .zsh file within the '-File' or '-Run' parameter, the command will use
  'runscript' instead of 'run'.

* Invoke-FalconRtr
  Updated to use 'Get-RtrCommand' private function to determine valid 'Command' values automatically from the
  other Real-time Response commands.

  Added 'Include' parameter to append device properties to output.

* New-FalconDeviceControlPolicy, New-FalconFirewallPolicy, New-FalconPreventionPolicy
  Removed the '-CloneId' parameter from the following commands due to inconsistencies in created policies. The
  'Copy-Falcon...Policy' commands continue to be available for use instead.

* Request-FalconToken
  Contribution from @kra-ts: Added support for a CCID value in the '-MemberCid' parameter which leads to the
  checksum value being silently dropped but the CID itself being accepted.

* Send-FalconScript
  Updated to allow 'Path' to contain string based script content or a path to a file.

* Start-FalconSession
  Now uses '-Id' to define both single-host and multi-host sessions. When a single host identifier is passed in
  the pipeline, a single-host session will be created. A multi-host session can be forced by specifying the
  'Timeout' or 'ExistingBatchId' parameter(s).

  Additionally, this command now appends 'batch_id' to each host that was successfully initiated within a
  multi-host session.

---

This discussion was created from the release 2.2.0.