Session automation API

The Automation API allows security operations teams to develop detailed and precise automation strategies. Playbooks can serve many purposes, ranging from automating minimal investigative tasks that can speed up analysis to large-scale responses to a security breach. The following APIs are supported to leverage the capabilities of session automation using playbooks.

build_phantom_rest_url

Use the build_phantom_rest_url APIto combine the base URL and the specific resource path, such as /rest/artifact.

The build_phantom_rest_url API is supported from within a custom function.

phantom.build_phantom_rest_url()

This sample uses the phantom.build_phantom_rest_url API.

build_phantom_rest_urll(*args)
    Constructs a REST route given a list of part paths. Quotes each path part individually.
    Note that you must not pass in quoted endpoints, or they'll get re-quoted.

    Examples:
    >>> build_phantom_rest_url()
    'https://127.0.0.1/rest/'

    >>> build_phantom_rest_url('container')
    'https://127.0.0.1/rest/container'

    >>> build_phantom_rest_url('container', 7)
    'https://127.0.0.1/rest/container/7'

    >>> build_phantom_rest_url('container', '7/')
    'https://127.0.0.1/rest/container/7'

    >>> build_phantom_rest_url('container/7/edit_options')
    'https://127.0.0.1/rest/container/7/edit_options'

    >>> build_phantom_rest_url('decided_list', 'foo bar')
    'https://127.0.0.1/rest/decided_list/foo%20bar'

    Args:
        *args (str|int): args to join together

    Returns:
        str

get_base_url

Use the get_base_url API to retrieve the URL that points to your instance.

The get_base_url API is supported from within a custom function.

phantom.get_base_url()

This sample uses the phantom.get_base_url() API.

import phantom.rules as phantom
import json

def on_start(container):
    url = phantom.get_base_url()
    phantom.debug(url)
    return

def on_finish(container, summary):
    return

The return value is the base URL of the platform as configured in Administration > System Settings > Company Settings.

2016-02-13T01:29:25.977000+00:00: calling on_start(): on incident 'test', id: 107.
2016-02-13T01:29:26.020179+00:00: phantom.get_base_url(): called for playbook run '219'
2016-02-13T01:29:26.022549+00:00: https://10.10.0.10
2016-02-13T01:29:26.025000+00:00: No actions were executed
2016-02-13T01:29:26.034220+00:00: calling on_finish()
2016-02-13T01:29:26.049943+00:00:
Playbook 'get_base_url (id: 175)' executed (playbook_run_id: 219) on incident 'test'(id: 107).
Playbook execution status is:'success'
	No actions were executed for this playbook and 'incident'
{"message":"No actions were executed","playbook_run_id":219,"result":[],"status":"success"}

 *** The Playbook has completed. Result: success ***

get_phantom_home

Use the get_phantom_home API to return the path to the home directory.

The get_phantom_home is supported from within a custom function.

phantom.get_phantom_home()

The following examples show the return values for the get_phantom_home API on different types of installs.

On a release OVA or privileged install:

Thu Jan 03 2019 16:37:23 GMT-0800 (Pacific Standard Time): /opt/phantom

On an unprivileged install:

Thu Jan 03 2019 16:36:31 GMT-0800 (Pacific Standard Time): /home/username/directory_name

get_rest_base_url

Use the get_rest_base_url API to return the base URL to the REST API of your instance. This API works on all instances, regardless of installation type, or the base URL found in the in Company Settings.

The get_rest_base_url is supported from within a custom function.

phantom.get_rest_base_url()

The following examples show the return values for the get_rest_base_url API on different types of installs.

On a release OVA or privileged install:

Thu Jan 03 2019 16:37:23 GMT-0800 (Pacific Standard Time): https://127.0.0.1/rest/

On an unprivileged install, showing the custom HTTPS port:

Thu Jan 03 2019 16:36:31 GMT-0800 (Pacific Standard Time): https://127.0.0.1:9999/rest/

requests

Use the requests API to interact with the platform through the REST API. By using phantom.requests instead of directly importing requests from site packages, you avoid the need to set the request headers by hand, meaning that you don't need to authenticate with the platform. For more information on how to use the requests package, see https://pypi.org/project/requests.

The requests API is supported from within a custom function.

phantom.requests

This sample uses the phantom.requests() API.

def list_indicator_tags(indicator_id=None, **kwargs):
    """
    List the tags on the indicator with the given ID
    
    Args:
        indicator_id: The ID of the indicator to list the tags for
    
    Returns a JSON-serializable object that implements the configured data paths:
        tags: The tags associated with the given indicator
    """
    ############################ Custom Code Goes Below This Line #################################
    import json
    import phantom.rules as phantom
    outputs = {}

    # Validate the input
    if indicator_id is None:
        raise ValueError('indicator_id is a required parameter')

    # phantom.build_phantom_rest_url will join positional arguments like you'd expect (with URL encoding)
    indicator_tag_url = phantom.build_phantom_rest_url('indicator', indicator_id, 'tags')

    # Using phantom.requests ensures the correct headers for authentication
    response = phantom.requests.get(
        indicator_tag_url,
        verify=False,
    )
    phantom.debug("phantom returned status code {} with message {}".format(response.status_code, response.text))

    # Get the tags from the HTTP response
    indicator_tag_list = response.json()['tags']
    phantom.debug("the following tags were found on the indicator: {}".format(indicator_tag_list))
    outputs['tags'] = indicator_tag_list

    # Return a JSON-serializable object
    assert json.dumps(outputs)  # Will raise an exception if the :outputs: object is not JSON-serializable
    return outputs

set_action_limit

Use set_action_limit in your playbook's on_start() block to set the maximum number of action calls that can be executed. The default is 50 action calls per container per Playbook. Each phantom.act() call can still result in multiple actions performed, resulting in more actions than this setting.

set_action_limit is not supported from within a custom function.

phantom.set_action_limit(limit)