PowerShell - Developer Guide - Cortex XSIAM - Cortex - Security Operations

Similar to Python, PowerShell integrations and scripts run in a Docker container. All of the Docker images that support PowerShell are named with a prefix of either demisto/powershell or demisto/pwsh. If you need to create a new image follow the instructions at demisto/dockerfiles project: https://github.com/demisto/dockerfiles.

Similar to Python, PowerShell integrations and scripts should follow the same directory structure as Python integrations and scripts, with one difference: unit test files must be named: <IntegrationFileName>.Tests.ps1, following the Pester unit testing naming convention. You can use demisto-sdk split  to convert an exported PowerShell integration or script to the correct directory structure. For more information, see the Demisto SDK guidesplit

PSScriptAnalyzer is used for linting and static code analysis of PowerShell integrations and scripts. If you receive a false positive from the Analyzer, you can suppress the rule by decorating the function/script with SuppressMessageAttribute. Specify a Justification in the attribute as to why the suppression is necessary. An example usage of suppression can be seen in CommonServerPowerShell.ps1. For more information about PSScriptAnalyzer suppression, see the PSScriptAnalyzer documentation .

The Python unit testing guidelines also apply for PowerShell. Unit tests should avoid performing communication with external APIs and should instead use mocking when possible. Testing actual interaction with external APIs should be performed via Test Playbooks. For running unit tests we use Pester.

Import CommonServerPowerShell.ps1

Your code must import CommonServerPowerShell.ps1 by adding the following to the beginning of the file:

. $PSScriptRoot\CommonServerPowerShell.ps1

When the integration or script code is unified by demisto-sdk for deployment to the instance the import line is automatically removed.

Use Main in integration/script code

When writing unit tests you import the integration or script file from the *.Tests.ps1 file. Therefore, the file must be written so that it will not execute when it is imported. This can be done with a simple Main function which is called depending on how the file was executed. Adding the following code ensures the script is not run when imported by the unit tests:

# Execute Main when not in Tests
if ($MyInvocation.ScriptName -notlike "*.Tests.ps1") {
    Main
}

Write unit tests

All unit tests should be written in a separate PowerShell file named <IntegrationFileName>.Tests.ps1. The unit test file should import the integration or script code file by adding the following line at the beginning of the file:

. $PSScriptRoot\<IntegrationFileName>.ps1

Group related unit tests using the Describe block. Use Context for grouping tests that use the same mock logic. Write your tests using the It command. Example unit tests can be seen for the VerifyJSON script. For more details, see the Pester documentation.

Mocking

Pester supports mocking PowerShell functions. You can mock any function defined in CommonServerPowerShell.ps1 and functions included in standard PowerShell and imported modules. Pester doesn't support mocking object methods. This includes methods of the $demisto object. You can, however, modify the $demisto object properties in a test. For example, you can set the ContextArgs property to control the return of $demisto.Args() method. Example code:

$demisto.ContextArgs = @{arg1 = 'val1' }

In addition, you can mock functions called by the $demisto object. For example, you can mock DemistoServerLog which is called by the $demisto object methods: Info, Debug, Error. Example of mocking can be seen for the VerifyJSON script script. See more information about mocking with Pester.

Run with Docker (demisto-sdk)

CircleCI build runs the unit tests within the Docker image that the integration/script runs with. We recommend using this method to run linting and test as it uses the same environment (Docker container) with all modules and operating system dependencies that are used by the integration/script. To run both linting and testing run: demisto-sdk lint -i <path to code directory>.

For example: demisto-sdk lint -i Packs/Legacy/Scripts/VerifyJSON

Sample output: