SIERRA Invoker Script Development Guide

Phantom Helix Intelligence

SIERRA Invoker Script Development Guide

Welcome to the SIERRA Invoker Script Development Guide. This guide will walk you through the process of creating custom Invoker scripts to extend SIERRA's functionality and automate tasks for your investigations.

Invoker scripts in SIERRA allow you to integrate external tools and scripts written in any language. By defining simple YAML configuration files, you can easily make your existing scripts and utilities accessible within SIERRA's interface.

Invoker Script Structure

An Invoker script in SIERRA is defined by a YAML configuration file. This file contains information about the script, its parameters, and the command to execute. Here's the basic structure:

# [Optional]: A list of directories where SIERRA should look for the script.
# If the same script exists in multiple locations, the first occurrence will be executed.
PATHS: 
    - /path/to/script/directory
    - /another/path
    

# [Mandatory]: Contains the list of Invoker scripts.
SCRIPTS:

  # [Mandatory]: The name of your script as it will appear in SIERRA.
  # Has to be unique among other script names
  - Name: Script Name
  
    # A brief description of what your script does.
    Description: Brief description of the script
    
    # [Mandatory]: A list of input parameters for your script.
    Params:

      # [Mandatory]: The name of the parameter.
      - Name: ParameterName

        # [Optional]: A description of what the parameter is for.
        Description: Parameter description

        # [Mandatory]: The data type of the parameter. Currently, only STRING is supported.
        Type: STRING

        # [Optional]: Additional options for the parameter.
        Options:
          - PRIMARY # indicates this parameter will be populated by the selected entity value
          - MANDATORY # means this parameter is required

    # [Mandatory]: The actual command to execute. Use
    Command: command_to_execute {ParameterName}

Result Format

For the Invoker script results to be recognized and incorporated into SIERRA's investigative graph, your script should return a JSON object in the following format:

{
    "type": "Tree",
    "results": [
        "Content of Entity A",
        "Content of Entity B",
        {
            "Content of Entity C (parent of D and E)": [
                "Content of Entity D",
                "Content of Entity E"
            ]
        }
    ]
}

The type field should be Tree. The results field is an array that can contain strings (for leaf entities) and nested objects (for parent entities with children).

Example Invoker Script Config

Here's an example Invoker script YAML configuration that contains a script of subdomain lookup utility:

PATHS:
  - /opt/scripts
  - /home/user/tools

SCRIPTS:          
  - Name: Subdomain Finder
    Description: Looks up subdomains of a given domain using crt.sh
    Params:
      - Name: Domain
        Description: The domain to find subdomains for
        Type: STRING
        Options:
          - PRIMARY
          - MANDATORY
    Command: python subfinder.py {Domain}

In this example, SIERRA will look for the subfinder.py script in the specified PATHS. When invoked, it will pass the Domain parameter to the script. The script is then expected to return the discovered subdomains in the JSON format described above, which will be added to the investigation graph.

SIERRA's Invoker scripts provide a flexible and powerful way to integrate your existing tools and automate investigative tasks. By defining simple YAML configurations, you can extend SIERRA's capabilities and streamline your workflows. We hope this guide has been helpful in getting you started with creating your own Invoker scripts. Happy investigating with SIERRA!