User Stages

Create user stages to customize and save stages for use within bot creation. Once created the stages are available for reuse on the Neurons Bots editor, under Stages > User .

To create a User Stage

1. In Neurons Bots, select Create Bot.
2. On the Create bot page, select Create for either Schedule or Custom action.
3. On the New bots editor page, select Manage user stages to display the User Stage Manager page.
4. On the User Stage Manager page select Create and the stage from the following:
   • PowerShell Query
   • PowerShell Action
   • Bash Action
   • Command Action
   • OSQuery
5. On the User Stage Editor page, enter the Stage name. For example, Compress File/Folder.
6. Optionally enter a description. The descriptive text displays when in the bot editor and Stage Information is selected from the Stage Settings panel. For example, This stage compresses source files from a specified path to a destination path to the specified compression level.
7. Enter the script code.
   Example:
   Compress-Archive -path C:\logs\file.txt 
   -destinationpath C:\logs\file.zip 
   -compressionlevel Optimal

You can make this script more flexible by replacing some of the hard code with variables. This would allow elements to be customized when using the stage.
Example:
Compress-Archive -path __Path to Source File or Folder__
-destinationpath __Destination Path__
-compressionlevel __Compression level|options:Fastest,Optimal,No Compression_

Select Ctrl + Space to insert an Options Variable or a Value Variable:

• An Options Variable is displayed in the settings as a select drop-down, the options available will be the ones you enter into the script. In this example: Compression level options Fastest, Optimal, No Compression.

• A Value Variable is displayed in the settings as a text box, with the label you enter in the script. In this example: Patch to Source File or Folder, Destination Path, and Compression level.

For this example the Stage Settings would look like this:

8. Complete the Stage Settings, the settings available depend on the type of user stage you are creating:
Powershell Query

Run As:

• System
• Logged-On User

Type:

• PowerShell
• Core
• Auto

Output: Add an output for each column name returned by the PowerShell query that you want to use in a downstream filter results stage or as a variable in another stage.

Singular Result: Toggle on/off. Use single/multiple results to define whether the query will return single or multiple results per device. This determines whether variables are available as token inputs in downstream stages directly (single) or whether they are only available to stages in a for-each results block (multiple) to loop those stages for each result.

PowerShell Query example:

Use PowerShell to query your environment when the desired custom behaviors are not achievable using standard bot stages.

To run the query successfully, ensure that:

• The script output is JSON (you can use the ConvertTo-JSON commandlet).
• You can name each data field as an output entry in the Stage settings.

By default the script time out is 25 minutes.

PowerShell types:

• If you select PowerShell type as Core, PowerShell script runs on the PowerShell Core .Net Core 3.1 Desktop Runtime, version 24.64.28315 or greater must be installed on the machine that you are running on.
• If you select PowerShell type as Auto, the query searches for Net Core 3.1 Desktop Runtime, version 24.64.28315 or greater. The following are the outcomes:
  • When the runtime is installed, the script will be executed against PowerShell Core.
  • When the runtime is not installed, the script will be executed against PowerShell.

Output types:

Toggle on if you want the results to appear in multiples, and toggle off if you want the results to appear in singles.

• Single - If the output type is specified as single, one object can be returned in JSON format.

$name = [System.Net.Dns]::GetHostName()

ConvertTo-Json @([customobject]@{Name = $name;})

• Multiple - If the output type is specified as multiple, you must return the data as an array of objects in JSON format.

  [{“Example Field”: “A”}, {“Example Field”: “B”}]
  

  The objects within the array contains the primitive types. In the Output field of the Stage Inspector, you must bind the Example field and enter Name.
  

  $processes = Get-Process | Select-Object Name
  ConvertTo-Json $processes
  

Powershell Action

Run As:

• System
• Logged-On User

Type:

• PowerShell
• Core
• Auto

PowerShell Action example:


PowerShell Action is similar to the PowerShell Query, except there are no outputs in the PowerShell Action. To know more, see PowerShell Query example.

Bash Action

Run As:

• System
• Logged-On User

Bash Action example:

To reduce the size by removing first 100 entries, use the following command:

sed 1,100d your-filename

Command Action

Run As:

• System
• Logged-On User

Command Action example:

• To scan and repair corrupted file(s):

sfc /scannow

• To check and fix the status of the physical disk:

chkdsk /offlinescanandfix

OSQuery

Singular Result: Toggle on/off. Use single/multiple results to define whether the query will return single or multiple results per device. This determines whether variables are available as token inputs in downstream stages directly (single) or whether they are only available to stages in a for-each results block (multiple) to loop those stages for each result.

Add Column mapping: Add a column mapping for each column name returned by the osquery that you want to use in a downstream filter results stage or as a variable in another stage.

OSQuery example:

To discover the most frequently launched applications per device run the script:

select path,last_execution_time,count,
sid from userassist order by count desc
limit __Number of Apps to return|options:1,5,10__

9. Select Apply and Close to save the user stage.
   If you have made edits to an existing user stage, a new version is created. On saving, a dialog displays to warn that any bots using the user stage will need updating to use the latest version.

Actions

You can perform the following actions to any of the user stages:

• Clone: Select a user stage, select Actions > Clone. The Clone Stage dialog displays. Enter a unique name and select Clone. A pop-up message displays to inform you the stage creation was successful. The cloned stage appears in the list for you to select and edit.

• Delete: Select one or more user stages, select Actions > Delete. The Delete stages dialog displays. Select Delete to confirm deletion of the stage. This action cannot be undone and will deprecate the stage from any bot that uses it. Deprecated stages are indicated by a red border.

Related topics

Neurons Bots Stages