After the future removal of the classic playbook editor, your existing classic playbooks will continue to run, However, you will no longer be able to visualize or modify existing classic playbooks.
For details, see:
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 API to 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.
phantom.build_phantom_rest_url(*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: >>> phantom.build_phantom_rest_url() 'https://127.0.0.1/rest/' >>> phantom.build_phantom_rest_url('container') 'https://127.0.0.1/rest/container' >>> phantom.build_phantom_rest_url('container', 7) 'https://127.0.0.1/rest/container/7' >>> phantom.build_phantom_rest_url('container', '7/') 'https://127.0.0.1/rest/container/7' >>> phantom.build_phantom_rest_url('container/7/edit_options') 'https://127.0.0.1/rest/container/7/edit_options' >>> phantom.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:
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.showing the custom HTTPS port:
Thu Jan 03 2019 16:36:31 GMT-0800 (Pacific Standard Time): https://127.0.0.1:8443/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)
Data access automation API | Vault automation API |
This documentation applies to the following versions of Splunk® SOAR (On-premises): 5.5.0, 6.0.0, 6.0.1, 6.0.2, 6.1.0, 6.1.1, 6.2.0, 6.2.1, 6.2.2
Feedback submitted, thanks!