Getting started with custom integration scripts

Platform

To set up the custom integration script, you will need to:

  1. Write the script.
  2. Optionally add credentials.
  3. Create an integration task.

Step 1: Write integration script

The script can be written in Starlark, a Python like language with some notable differences:

  1. There is no exception handling (try/catch)
  2. There is no f-string f'{var}' formatting - "{}".format(var) is the supported method of string interpolation.

Step 1a: Entrypoint

The script needs an entrypoint, a function that gets called by the runZero service and returns the Inventory Assets discovered by the script.

  1. The entrypoint must accept a variadic *args and **kwargs for parameters to be passed in.
  2. The entrypoint must return a list of ImportAssets to be imported.
  3. The entrypoint (function name) of the script will default to main, but can be set depending on the integration type scan probe or a connector task.
def main(*args, **kwargs):
    asset_one = ImportAsset(
            id=1,
            os='custom import os',
            osVersion='0.0.0.0.0.0.1-pre-alphabetazed',
            manufacturer='Name of manufacturer',
            model='Model of asset',
        )
    asset_two = ImportAsset(
            id=2,
            os='custom import os 2',
            osVersion='0.0.0.0.0.0.2-prezed',
            manufacturer='Name of manufacturer',
            model='model of asset',
        )
    return [asset_one, asset_two]

Step 2: Add the custom script Credential to runZero

The credential used for the script is a key-value pair passed into the script function as kwargs and can be used as username and password or for anything requiring a secret.

def main(*args, **kwargs):
    client_id = kwargs['access_key']
    client_secret = kwargs['access_secret']
  1. Go to the Credentials page in the runZero console and click Add Credential.
  2. Choose Custom Script Secret from the list of credential types.
  3. Provide a name for the credential, like Script Secret for the service being integrated with.
  4. Provide the following information:
    • Access Key - The username or client id that will be passed into the script as a kwargs named access_key.
    • Access Secret - The secret that will be passed into the script as a kwargs named access_secret.
  5. If you want other organizations to be able to use this credential, select the Make this a global credential option. Otherwise, you can configure access on a per organization basis.
  6. Save the credential.

Step 3: Create a new task

  1. Go to Tasks, click the Integrate button, and select Custom Scripts under Custom integrations from the dropdown.
  2. Provide a name for the task
  3. Select or create a custom integration
  4. Select or create credentials for the script
  5. Select an explorer
    • Custom integration scripts must be run on a hosted explorer
  6. Select Site, Task description, and Schedule as appropriate.
  7. Click Activate Connection to start the task.

Using the CLI

The runzero CLI includes a script sub-command to help in writing and debugging Starlark scripts that use the [[#runZero Types]] and [[#Libraries]] outlined below.

Running scripts

Hello World

def main(*args, **kwargs):
	print("Hello world!")

Save the file as print.star so it can be run from the CLI

$ runzero script --filename print.star
Dec 12 12:59:07.099 [INFO] script: Hello world
None

Running the script with args

def main(*args, **kwargs):
	print("Hello {}".format(args[0]))

$ runzero script --filename print.star --args Dave
Dec 12 13:01:20.707 [INFO] script: Hello Dave
None

Running the script with kwargs

def main(*args, **kwargs):
	print("Hello {}".format(kwargs["name"]))

runzero script --filename print.star --kwargs name=Dave
Dec 12 13:28:56.933 [INFO] script: Hello Dave
None

args and kwargs can be called multiple times to pass in as many arguments as needed

def main(*args, **kwargs):
	print("{} {}".format(args[0], args[1]))
	print("{} {}".format(kwargs["access_key"], kwargs["access_secret"]))

runzero script --filename print.star --args Hello --args Dave --kwargs access_key=foo --kwargs access_secret=bar
Dec 12 13:45:50.284 [INFO] script: Hello Dave
Dec 12 13:45:50.284 [INFO] script: foo bar
None

REPL

The sub-command script repl can be useful for larger scripts with multiple functions. The REPL will allow setting variables, calling functions, printing variables, and anything else that can be done in Starlark.

runzero script repl --filename print.star
>>> main(*("hello", "dave"), **{"access_key": "foo", "access_secret": "bar"})
Dec 12 14:53:42.384 [INFO] script: hello dave
Dec 12 14:53:42.384 [INFO] script: foo bar
>>> print("Hello {}".format("dave"))
Dec 12 14:57:28.961 [INFO] script: Hello dave
>>> args = ("hello", "dave")
>>> kwargs = {"access_key": "foo", "access_secret": "bar"}
>>> main(*args, **kwargs)
Dec 12 14:58:57.567 [INFO] script: hello dave
Dec 12 14:58:57.567 [INFO] script: foo bar
>>>

^D To exit the REPL

runZero Types

Resource types are implemented in Starlark and are equivalent with the Python SDK types:

  • load('runzero.types', 'ImportAsset', 'NetworkInterface', 'Service', 'ServiceProtocolData', 'Software', 'Vulnerability')

Libraries

runZero provides some additional libraries for basic functionality to make web requests.

  • http
    • load('http', http_post='post', http_get='get', 'url_encode')
      • url_encode
      • post
      • get
  • net
    • load('net', 'ip_address')
      • ip_address
  • json
    • load('json', json_encode='encode', json_decode='decode')
      • encode
      • decode
  • time
    • load('time', 'parse_time')
      • parse_time
  • uuid
    • load('uuid', 'new_uuid')
      • new_uuid

The types can be run from the CLI or loaded into the REPL.

runzero script repl --filename print.star
>>> load('json', json_encode='encode', json_decode='decode')
>>> greeter = json_decode('{"greeting":"hello", "name":"dave"}')
>>> print(greeter)
Dec 12 15:13:00.971 [INFO] script: {"greeting": "hello", "name": "dave"}
>>> ^D
Updated
Previous: Tanium API Gateway Next: Tenable