[ ENHANCEMENT ] Add ParameterSet to `Invoke-FalconAlertAction` and `Invoke-FalconIncidentAction` to allow for multiple actions in one API query

[datorr2]

Description of your enhancement Both of the following API calls:

• PATCH ​/alerts​/entities​/alerts​/v3
• POST ​/incidents​/entities​/incident-actions​/v1

... allow for multiple Name/Value pairs in an array to group multiple actions in one API call, instead of having to make multiple API calls for each action.

It would be nice to be able to provide an array of name/value hashes to a parameter, perhaps called -Action.

How it would work

$Actions = (
  @{ name = "remove_tag"; value = "Lateral Movement" },
  @{ name = "add_tag"; value = "False Positive" },
  @{ name = "update_assigned_to_v2"; value = "uuid" },
  @{ name = "update_status"; value = "closed" }
)

Invoke-FalconIncidentAction -Id $IncidentIds -Action $Actions

Expected result All applicable incidents are modified.

Additional context Body for Incident Actions:

{
  "action_parameters": [
    {
      "name": "add_tag",
      "value": "string"
    }
  ],
  "ids": [
    "string"
  ]
}

Body for Alert Actions:

{
  "action_parameters": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "composite_ids": [
    "string"
  ]
}

[bk-cs]

Thanks! I'm out of the office but I will take a look at this next week.

[bk-cs]

@datorr2

I've implemented a draft of your suggestion that uses an array of Hashtable values to supply the name and value. Example:

Invoke-FalconIncidentAction -Action @{ add_tag = 'example_tag' },@{ update_status = 'closed' } -Id <id>,<id>

You can also supply the proper integer value for update_status like so:

Invoke-FalconIncidentAction -Action @{ add_tag = 'example_tag' },@{ update_status = 40 } -Id <id>,<id>

• How do you feel about that?
• Do you think that is self-explanatory and easy to use?

I chose [hashtable[]] because I've seen it used in other PowerShell commands, so it fit PowerShell style and was a bit easier for me to validate.

[datorr2]

Looks fine and makes sense to me.

For the record: A single hashtable with multiple action/values would be simpler for the user, but I just figured the array of hashtables would be most consistent with how the API works and would require the least amount of work to the module code.

[bk-cs]

Thanks for the suggestion and your feedback! I have added the Action parameter to both Invoke-FalconAlertAction and Invoke-FalconIncidentAction, along with a supporting private function (Test-ActionParameter) that is used to validate user input.

These changes will be available in the next PSFalcon release.