Parameters

Parameters in a BrazenCloud Action allow the Action to accept user supplied values when the Action is added to a Job.

For instance, the inventory:netstat Action accepts a boolean value to determine if a filter should be used and also a string value to define the filter. Here's what that looks like in the Job creation screen:

inventory:netstat parameters

These parameters are defined in JSON notation as an object array in a file called parameters.json in the root of the Action.

Here are the available properties for each parameter:

Name	Required	Description	Impact
Name	Yes	Name of the Parameter.	Displayed on the Action placard
Type	Yes	The type of data	Changes how the parameter is displayed on the Action placard
IsOptional	No	Boolean, whether the parameter is required	Tells the Action if the parameter is required before running
Description	No	A short description of the parameter	Displayed on the Action placard
DefaultValue	No	The default value if none is supplied	The Action placard autofills this value

Since the parameters must be a JSON array, a full parameters.json file might looks like this example from the inventory:netstat Action:

[
	{
		"Name":"Use Filter",
		"Type": 2,
		"IsOptional":true
	},
	{ 
		"Name":"IP Filter",
		"Type": 0,
		"DefaultValue":"192.168.*.*",
		"IsOptional":true
	}
]

Types

The possible types are:

Type Number	Type	Example
0	String	"string"
1	Number	17
2	Boolean	true
3	Password	"string"

The only difference between the Password and String parameter types is that the Password parameter is obscured in the UI when it is filled out. The parameter is NOT encrypted in the settings.json file.

We have encrypted parameters on the roadmap.

Until we implement encrypted parameters, you can work around the secrets being written to disk by immediately reading settings.json in the Action, securely storing the secret in memory, and then removing the secret from the settings.json file. Any changes made to the settings.json file will be reflected in the cache.

Accessing Parameters in your Script

When the Action is delivered to the BrazenAgent, the parameters are put into a JSON object in a file called settings.json. This file is placed in the root of the Action (which is the working directory when the Action is initiated). To access the parameters, simply load the JSON and access the parameters.

Here's a sample settings.json for your reference:

{
  "IP Filter":"192.168.*.*",
  "Use Filter":"false",
  "brazenagent_identity":"8c589a92-7130-425a-b98c-a9ba394a7827",
  "host":"https://portal.runway.host:443",
  "thread_id":"dee105f3-0d0e-4b96-a541-45ddbe4545f1",
  "job_id":"6faa7bee-c3a5-4b42-9849-ae852ee8ec01",
  "action_instance_id":"8b4f5b0e-37f5-4d21-9dcf-57e0352d0665",
  "repository_action_id":"bdfb6308-2221-4e73-833b-f9481a3441b9",
  "prodigal_object_id":"9941b7c2-4ab3-41dc-8654-d8cd48fb97e9",
  "prodigal_asset_name":"MobileWolf",
  "atoken":"7a0d4a3be298ea1f8145449f983efa59"
}

You can find a full explanation of each of those settings here:

Settings

Load parameters in PowerShell

In PowerShell, you can use Get-Content and ConvertFrom-Json to collect your parameters:

$settings = Get-Content .\settings.json | ConvertFrom-Json

# Access the 'IP Filter' parameter:
$settings.'IP Filter'

Load parameters in Python

In Python, you can use the open() command and json.load() from the json library:

import json

settings_file = open(".\\settings.json", "r")
settings = json.load(settings_file)

# Access the 'IP Filter' parameter:
settings["IP Filter"]

Note: If your manifest calls a script in a subfolder (i.e. .\Windows or .\Linux) that sets your working directory to that folder you may need to reference the settings.json by looking in the parent directory: ..\settings.json.

Reserved Parameter Names

Due to the way that parameters are passed to the BrazenAgent, the following values are reserved and cannot be used for a parameter name:

brazenagent_identity
host
thread_id
job_id
action_instance_id
repository_action_id
prodigal_object_id
prodigal_asset_name
atoken