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:

1# [Optional]: A list of directories where SIERRA should look for the script.
2# If the same script exists in multiple locations, the first occurrence will be executed.
3PATHS: 
4    - /path/to/script/directory
5    - /another/path
6    
7# [Mandatory]: Contains the list of Invoker scripts.
8SCRIPTS:
9  - Name: Unique Script Name  # [Mandatory]
10    Description: Brief description of the script
11    Params:  # [Mandatory]
12      - Name: ParameterName  # [Mandatory]
13        Description: Parameter description  # [Optional]
14        # [Mandatory]: The data type of the parameter. Currently, only STRING is supported.
15        Type: STRING
16        Options:  # [Optional]
17          - PRIMARY # indicates this parameter will be populated by the selected entity value
18          - MANDATORY # indicates this parameter cannot be empty
19    Command: command_to_execute {ParameterName}  # [Mandatory]
20

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 one of the following formats:

Tree Type Output

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).

1{
2    "type": "Tree",
3    "results": [
4        "Content of Entity A",
5        "Content of Entity B",
6        {
7            "Content of Entity C (parent of D and E)": [
8                "Content of Entity D",
9                "Content of Entity E"
10            ]
11        }
12    ]
13}

Network Type Output

The type field should be Network. The origins field lists node IDs that directly link from the Invoker node. The nodes field defines all entities, and edges defines relationships between them.

1{
2  "type": "Network",
3  "origins": ["AliceID"],
4  "nodes": [
5    { "id": "AliceID", "content": "Alice" },
6    { "id": "BobID", "content": "Bob" },
7    { "id": "CharlieID", "content": "Charlie" }
8  ],
9  "edges": [
10    { "source": "AliceID", "target": "BobID", "label": "friend" },
11    { "source": "AliceID", "target": "CharlieID", "label": "colleague" }
12  ]
13}
14

Example Invoker Script Config

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

1PATHS:
2  - /opt/scripts
3  - /home/user/tools
4
5SCRIPTS:          
6  - Name: Subdomain Finder
7    Description: Looks up subdomains of a given domain using crt.sh
8    Params:
9      - Name: Domain
10        Description: The domain to find subdomains for
11        Type: STRING
12        Options:
13          - PRIMARY
14          - MANDATORY
15    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.

This guide provides the necessary structure and output specifications for developing custom Invoker scripts in SIERRA. By following these conventions, you can integrate external tools and automate investigation workflows efficiently.