Merge pull request #250 from CrowdStrike/2.2.3

2.2.3

PSFalcon.psd1

@@ -1,13 +1,13 @@
 @{
     RootModule           = 'PSFalcon.psm1'
-    ModuleVersion        = '2.2.2'
+    ModuleVersion        = '2.2.3'
     CompatiblePSEditions = @('Desktop','Core')
     GUID                 = 'd893eb9f-f6bb-4a40-9caf-aaff0e42acd1'
     Author               = 'Brendan Kremian'
     CompanyName          = 'CrowdStrike'
     Copyright            = '(c) CrowdStrike. All rights reserved.'
     Description          = 'PowerShell for the CrowdStrike Falcon OAuth2 APIs'
-    HelpInfoURI          = 'https://bk-cs.github.io/help/psfalcon/en-US'
+    HelpInfoURI          = 'https://github.com/CrowdStrike/psfalcon/wiki'
     PowerShellVersion    = '5.1'
     RequiredAssemblies   = @('System.Net.Http')
     ScriptsToProcess     = @('Class/Class.ps1')
@@ -318,6 +318,7 @@
       'Show-FalconModule',
 
       # psf-policies
+      'Compare-FalconPreventionPhase',
       'Copy-FalconDeviceControlPolicy',
       'Copy-FalconFirewallPolicy',
       'Copy-FalconPreventionPolicy',
@@ -413,6 +414,10 @@
       'Get-FalconVulnerability',
       'Get-FalconVulnerabilityLogic',
 
+      # ti
+      'Get-FalconTailoredEvent',
+      'Get-FalconTailoredRule',
+
       # user-management
       'Add-FalconRole',
       'Edit-FalconUser',
@@ -439,87 +444,69 @@
             ReleaseNotes = "@
 New Commands
 
-* cloud-connect-azure.ps1
-  Get-FalconDiscoverAzureCertificate
-
-* cloud-connect-cspm-azure.ps1
-  Get-FalconHorizonAzureCertificate
-
-* mobile-enrollment.ps1
-  Invoke-FalconMobileAction
+* psf-policies
+  'Compare-FalconPreventionPhase'
 
-* psf-devices.ps1
-  Find-FalconHostname
-
-* user-management.ps1
-  Invoke-FalconUserAction
+* ti
+  'Get-FalconTailoredEvent'
+  'Get-FalconTailoredRule'
 
 General Changes
 
-* Re-organized public functions into files named for their URL prefix rather than their respective Swagger
-  collection (which sometimes would match the prefix and sometimes wouldn't). Because of the number of endpoints
-  that fell under 'policy', it is segmented into specific files.
+* Created 'Confirm-Property' private function to filter [hashtable] and [PSCustomObject] into pre-defined
+  properties containing values.
 
-* The public 'users.ps1' and 'user-roles.ps1' files have been consolidated under 'user-management.ps1' and merged
-  with new /user-management/ endpoints.
+* Updated comment-based help to link directly to specific wiki pages for each command. Using 'Get-Help <command>
+  -Online' will launch the appropriate wiki page. These pages will be updated with current examples present within
+  existing wiki pages, and those pages will be re-organized.
 
-* Updated IPv4 regex used by 'Test-RegexValue' private function.
+* Modified 'Get-ParamSet' private function to look for 'ids' and 'samples' as potential body values to break into
+  groups of 'Max' values, instead of only 'ids'.
 
-* Streamlined looping functionality (used with '-All' parameter). Updated all commands to output groups of
-  results as they are retrieved instead of the entire result set at the end of a loop. Also verified that
-  authorization tokens are properly refreshed during a long running loop.
+* Updated Falcon X references to Falcon Intelligence due to product name change.
 
 Command Changes
 
-* Modified 'Add-FalconSensorTag' and 'Remove-FalconSensorTag' to include the uninstall token of the target device
-  and while adding and removing sensor tags with 'CsSensorSettings.exe' on Windows sensor versions v6.42 and above.
-
-* Modified 'Get-FalconSensorTag' to return the 'FalconSensorTags' values listed in a devices API response if the
-  target device is Windows sensor version 6.42 or above. If 'CsSensorSettings.exe' is updated to include a method
-  to 'get' sensor tags, 'Get-FalconSensorTag' will use that method in the future.
+* Updated 'Invoke-FalconIdentityGraph' to no longer modify the GraphQL statement when attempting to use '-All' for
+  pagination. Renamed 'Query' parameter to 'String' and made it work for both query and mutation statements but
+  kept 'Query' as an alias. Now, when your statement includes a 'Cursor' variable definition and the required
+  'pageInfo { hasNextPage endCursor }' properties, '-All' will automatically paginate results. If either of those
+  requirements are missing, a warning message will be displayed and pagination will not occur.
 
-* Removed mandatory requirement for 'TenantId' parameter within the 'Get-FalconDiscoverAzureAccount' command.
+* Modified 'Get-FalconUser' to remove deprecated API when using 'Username' parameter. 'Username' now submits
+  filtered searches for provided 'uid' values to the appropriate /user-management/ API.
 
-* Updated 'Invoke-FalconAlertAction' to use the new v2 endpoint which includes formatting corrections.
+* Added 'Max' of 1,000 sha256 values for 'New-FalconQuickScan'.
 
-* Based on code provided by @SleepySysadmin, 'Invoke-FalconIdentityGraph' now has an '-All' parameter when using
-  '-Query'!
+* Added 'sha256' as a PipelineByPropertyName value for 'New-FalconQuickScan' to support pipeline input from
+  'Send-FalconSample'.
 
-  When used with a query that includes 'pageInfo{endCursor hasNextPage}', results will be paginated automatically
-  and only relevant data will be output (similar to the rest of the PSFalcon commands) instead of the entire
-  object.
+* Added pattern validation to 'Remove-FalconUser' for the 'Id' parameter.
 
-  '-All' will automatically be added if a query begins with (`$after: Cursor) and has 'after' in the query
-  parameters, as it is assumed that all results are expected.
+* Modified 'Status' parameter for 'Edit-FalconDetection' to support ValueFromPipelineByPropertyName and changed
+  parameter to position 3.
 
-  If 'pageInfo' is not provided in the query and '-All' is specified, a warning message will be generated.
+* Modified 'Edit-FalconSensorUpdatePolicy' and 'New-FalconSensorUpdatePolicy' to filter out properties with
+  empty string values in order to prevent errors when creating and/or modifying Sensor Update policies.
 
-  A  query without '-All' will produce the same results as earlier versions of the module.
-
-* Added '-Mutation' parameter to 'Invoke-FalconIdentityGraph'.
-
-* Updated 'Add-FalconRole', 'Edit-FalconUser', 'Get-FalconUser', 'New-FalconUser', 'Remove-FalconRole', and
-  'Remove-FalconUser', to use new /user-management/ endpoints where appropriate. These commands behave as they
-  did before, unless using additional parameters to signify that requests are being performed within a
-  multi-CID environment.
-
-* 'Get-FalconRole' has been updated to produce results from new /user-management/ endpoints.
+* Modified 'Import-FalconConfig' to prevent an attempt to modify a policy when the policy was not successfully
+  created earlier in the import process. Also ensured that the precedence warnings when existing policies were
+  found would only be displayed once.
 
 Resolved Issues
 
-* Issue #170: 'Invoke-Loop' changes should eliminate token failures during retrieval of large result sets.
-
-* Issue #222: Updated comparison process to ensure an imported policy would be properly added to the list of
-  items to be modified, whether or not it was going to be created. Removed existing copy policy operation from
-  creation process.
+* Issue #241: Updated 'Confirm-Parameter' to eliminate 'Cannot validate argument on parameter 'Array'. Key cannot
+  be null. (Parameter 'key')' errors generated when using 'Import-FalconConfig'.
 
-* Issue #223: Removed extraneous 'Endpoint' definition that was generating an error.
+* Issue #242: Modified 'Edit-FalconDetection' to check whether a 'status' value is present with a 'comment' value
+  during command execution rather than during parameter validation. This will prevent errors from occurring when
+  parameters are specified in an unexpected order.
 
-* Issue #231: Corrected addition of 'FirewallRule' when using 'Export-FalconConfig -Item FirewallGroup'. This fix
-  should also resolve issues when exporting 'HostGroup' and a singular 'exclusion' item.
+* Issue #246: Created 'Confirm-Property' function to properly filter 'Rule' content for both [hashtable] and
+  [PSCustomObject] rules. This will eliminate errors caused by [hashtable] objects being improperly filtered
+  in PowerShell 5.1.
 
-* Issue #232: Re-added 'Outfile' designation for 'Path' parameter in 'Receive-FalconArtifact'. This should have
-  been present and was accidentally removed in an earlier module version.
+  * Issue #247: Updated 'Write-Warning' to use a PSCmdlet method in order to properly support 'WarningVariable'.
 @"
         }
     }

Private/Private.ps1

@@ -274,34 +274,59 @@ function Confirm-Parameter {
                 }
             }
         }
-        @($Content).foreach{
-            # Match property name with parameter name
-            [string]$Parameter = if ($Format -and $Format.$_) { $Format.$_ } else { $_ }
-            if ($Object.$_) {
-                # Verify that 'ValidValues' contains provided value
-                [string[]]$ValidValues = Get-ValidValues $Command $Endpoint $Parameter
-                if ($Object.$_ -is [array]) {
-                    foreach ($Item in $Object.$_) {
-                        if ($ValidValues -notcontains $Item) { "'$Item' is not a valid '$_' value. $ObjectString" }
+        if ($Content) {
+            @($Content).foreach{
+                # Match property name with parameter name
+                [string]$Parameter = if ($Format -and $Format.$_) { $Format.$_ } else { $_ }
+                if ($Object.$_) {
+                    # Verify that 'ValidValues' contains provided value
+                    [string[]]$ValidValues = Get-ValidValues $Command $Endpoint $Parameter
+                    if ($ValidValues) {
+                        if ($Object.$_ -is [array]) {
+                            foreach ($Item in $Object.$_) {
+                                if ($ValidValues -notcontains $Item) {
+                                    "'$Item' is not a valid '$_' value. $ObjectString"
+                                }
+                            }
+                        } elseif ($ValidValues -notcontains $Object.$_) {
+                            throw "'$($Object.$_)' is not a valid '$_' value. $ObjectString"
+                        }
                     }
-                } elseif ($ValidValues -notcontains $Object.$_) {
-                    throw "'$($Object.$_)' is not a valid '$_' value. $ObjectString"
                 }
             }
         }
-        @($Pattern).foreach{
-            # Match property name with parameter name
-            [string]$Parameter = if ($Format -and $Format.$_) { $Format.$_ } else { $_ }
-            if ($Object.$_) {
-                # Verify provided value matches 'ValidPattern'
-                $ValidPattern = Get-ValidPattern $Command $Endpoint $Parameter
-                if ($Object.$_ -notmatch $ValidPattern) {
-                    throw "'$($Object.$_)' is not a valid '$_' value. $ObjectString"
+        if ($Pattern) {
+            @($Pattern).foreach{
+                # Match property name with parameter name
+                [string]$Parameter = if ($Format -and $Format.$_) { $Format.$_ } else { $_ }
+                if ($Object.$_) {
+                    # Verify provided value matches 'ValidPattern'
+                    $ValidPattern = Get-ValidPattern $Command $Endpoint $Parameter
+                    if ($ValidPattern -and $Object.$_ -notmatch $ValidPattern) {
+                        throw "'$($Object.$_)' is not a valid '$_' value. $ObjectString"
+                    }
                 }
             }
         }
     }
 }
+function Confirm-Property {
+    [CmdletBinding()]
+    [OutputType([PSCustomObject[]])]
+    param(
+        [Parameter(Mandatory,Position=1)]
+        [string[]]$Property,
+        [Parameter(Position=2)]
+        [object[]]$Object
+    )
+    process {
+        foreach ($Item in $Object) {
+            # Filter to defined properties containing values
+            [string[]]$Select = @($Property).foreach{ if ($Item.$_) { $_ } }
+            if ($Select) { [PSCustomObject]$Item | Select-Object $Select }
+        }
+    }
+}
 function Convert-Rfc3339 {
     [CmdletBinding()]
     [OutputType([string])]
@@ -366,8 +391,11 @@ function Get-ParamSet {
             # Output maximum, no greater than 500
             $Max = if ($IdCount -and $IdCount -lt 500) { $IdCount } else { 500 }
         }
-        # Get 'Content' from user input
+        # Get 'Content' from user input and find identifier field
         $Content = Build-Content -Inputs $Inputs -Format $Format
+        [string]$Field = if ($Content.Body) {
+            if ($Content.Body.ids) { 'ids' } elseif ($Content.Body.samples) { 'samples' }
+        }
     }
     process {
         if ($Content.Query -and ($Content.Query | Measure-Object).Count -gt $Max) {
@@ -387,23 +415,23 @@ function Get-ParamSet {
                 }
                 ,$Split
             }
-        } elseif ($Content.Body -and ($Content.Body.ids | Measure-Object).Count -gt $Max) {
-            Write-Verbose "[Get-ParamSet] Creating groups of $Max 'ids'"
-            for ($i = 0; $i -lt ($Content.Body.ids | Measure-Object).Count; $i += $Max) {
-                # Split 'Body' content into groups using 'ids'
+        } elseif ($Content.Body -and $Field -and ($Content.Body.$Field | Measure-Object).Count -gt $Max) {
+            Write-Verbose "[Get-ParamSet] Creating groups of $Max '$Field' values"
+            for ($i = 0; $i -lt ($Content.Body.$Field | Measure-Object).Count; $i += $Max) {
+                # Split 'Body' content into groups using '$Field'
                 $Split = $Switches.Clone()
                 $Split.Add('Endpoint',$Base.Clone())
-                $Split.Endpoint.Add('Body',@{ ids = $Content.Body.ids[$i..($i + ($Max - 1))] })
+                $Split.Endpoint.Add('Body',@{ $Field = $Content.Body.$Field[$i..($i + ($Max - 1))] })
                 $Content.GetEnumerator().Where({ $_.Value }).foreach{
-                    # Add values other than 'Body.ids'
+                    # Add values other than 'Body.$Field'
                     if ($_.Key -eq 'Query') {
                         $Split.Endpoint.Path += if ($Split.Endpoint.Path -match '\?') {
                             "&$($_.Value -join '&')"
                         } else {
                             "?$($_.Value -join '&')"
                         }
                     } elseif ($_.Key -eq 'Body') {
-                        ($_.Value).GetEnumerator().Where({ $_.Key -ne 'ids' }).foreach{
+                        ($_.Value).GetEnumerator().Where({ $_.Key -ne $Field }).foreach{
                             $Split.Endpoint.Body.Add($_.Key,$_.Value)
                         }
                     } else {

Public/alerts.ps1

@@ -23,7 +23,7 @@ Repeat requests until all available results are retrieved
 .PARAMETER Total
 Display total result count instead of results
 .LINK
-https://github.com/crowdstrike/psfalcon/wiki/Alerts
+https://github.com/crowdstrike/psfalcon/wiki/Get-FalconAlert
 #>
     [CmdletBinding(DefaultParameterSetName='/alerts/queries/alerts/v1:get',SupportsShouldProcess)]
     param(
@@ -82,7 +82,7 @@ Value for the chosen action
 .PARAMETER Id
 Alert identifier
 .LINK
-https://github.com/crowdstrike/psfalcon/wiki/Alerts
+https://github.com/crowdstrike/psfalcon/wiki/Invoke-FalconAlertAction
 #>
     [CmdletBinding(DefaultParameterSetName='/alerts/entities/alerts/v2:patch',SupportsShouldProcess)]
     param(

Public/cloud-connect-aws.ps1

@@ -7,7 +7,7 @@ Requires 'AWS Accounts: Write'.
 .PARAMETER Id
 AWS account identifier
 .LINK
-https://github.com/CrowdStrike/psfalcon/wiki/Discover-for-Cloud-and-Containers
+https://github.com/CrowdStrike/psfalcon/wiki/Confirm-FalconDiscoverAwsAccess
 #>
     [CmdletBinding(DefaultParameterSetName='/cloud-connect-aws/entities/verify-account-access/v1:post',
         SupportsShouldProcess)]
@@ -55,7 +55,7 @@ Maximum number of requests within 'RateLimitTime'
 .PARAMETER Id
 AWS account identifier
 .LINK
-https://github.com/CrowdStrike/psfalcon/wiki/Discover-for-Cloud-and-Containers
+https://github.com/CrowdStrike/psfalcon/wiki/Edit-FalconDiscoverAwsAccount
 #>
     [CmdletBinding(DefaultParameterSetName='/cloud-connect-aws/entities/accounts/v1:patch',SupportsShouldProcess)]
     param(
@@ -125,7 +125,7 @@ Repeat requests until all available results are retrieved
 .PARAMETER Total
 Display total result count instead of results
 .LINK
-https://github.com/CrowdStrike/psfalcon/wiki/Discover-for-Cloud-and-Containers
+https://github.com/CrowdStrike/psfalcon/wiki/Get-FalconDiscoverAwsAccount
 #>
     [CmdletBinding(DefaultParameterSetName='/cloud-connect-aws/queries/accounts/v1:get',SupportsShouldProcess)]
     param(
@@ -176,7 +176,7 @@ Retrieve Global Settings Falcon Discover for Cloud AWS accounts
 .DESCRIPTION
 Requires 'AWS Accounts: Read'.
 .LINK
-https://github.com/CrowdStrike/psfalcon/wiki/Discover-for-Cloud-and-Containers
+https://github.com/CrowdStrike/psfalcon/wiki/Get-FalconDiscoverAwsSetting
 #>
     [CmdletBinding(DefaultParameterSetName='/cloud-connect-aws/combined/settings/v1:get',SupportsShouldProcess)]
     param()
@@ -205,7 +205,7 @@ Maximum number of requests within 'RateLimitTime'
 .PARAMETER Id
 AWS account identifier
 .LINK
-https://github.com/CrowdStrike/psfalcon/wiki/Discover-for-Cloud-and-Containers
+https://github.com/CrowdStrike/psfalcon/wiki/New-FalconDiscoverAwsAccount
 #>
     [CmdletBinding(DefaultParameterSetName='/cloud-connect-aws/entities/accounts/v1:post',SupportsShouldProcess)]
     param(
@@ -266,7 +266,7 @@ Requires 'AWS Accounts: Write'.
 .PARAMETER Id
 AWS account identifier
 .LINK
-https://github.com/CrowdStrike/psfalcon/wiki/Discover-for-Cloud-and-Containers
+https://github.com/CrowdStrike/psfalcon/wiki/Remove-FalconDiscoverAwsAccount
 #>
     [CmdletBinding(DefaultParameterSetName='/cloud-connect-aws/entities/accounts/v1:delete',SupportsShouldProcess)]
     param(
@@ -303,7 +303,7 @@ AWS account identifier containing cloudtrail logs
 .PARAMETER StaticExternalId
 Default external identifier to apply to AWS accounts
 .LINK
-https://github.com/CrowdStrike/psfalcon/wiki/Discover-for-Cloud-and-Containers
+https://github.com/CrowdStrike/psfalcon/wiki/Update-FalconDiscoverAwsSetting
 #>
     [CmdletBinding(DefaultParameterSetName='/cloud-connect-aws/entities/settings/v1:post',SupportsShouldProcess)]
     param(