API Reference

This section documents the public API of the Splunk SOAR SDK.

Core Functionality

App

class soar_sdk.app.App(*, name, app_type, logo, logo_dark, product_vendor, product_name, publisher, appid, python_version=None, min_phantom_version='6.4.0', fips_compliant=False, asset_cls=<class 'soar_sdk.asset.BaseAsset'>)

Bases: object

Main application class for SOAR connectors.

This class provides the foundation for building SOAR connectors. It handles action registration, asset management, test connectivity, polling, and webhook functionality.

The App class serves as the central coordinator for all app functionality, providing decorators for action registration and managing the lifecycle of SOAR operations.

Parameters:

• name (str) – Human-readable name of the app.

• app_type (str) – Type of the app (e.g., “investigative”, “corrective”).

• logo (str) – Path to the app’s logo image.

• logo_dark (str) – Path to the app’s dark theme logo image.

• product_vendor (str) – Vendor of the product this app integrates with.

• product_name (str) – Name of the product this app integrates with.

• publisher (str) – Publisher of the app.

• appid (str) – Unique UUID identifier for the app.

• python_version (Optional[list[PythonVersion]]) – List of supported Python versions. Defaults to all supported versions.

• min_phantom_version (str) – Minimum required SOAR version. Defaults to configured minimum.

• fips_compliant (bool) – Whether the app is FIPS compliant. Defaults to False.

• asset_cls (type[BaseAsset]) – Asset class to use for configuration. Defaults to BaseAsset.

Raises:

ValueError – If appid is not a valid UUID.

Example

>>> app = App(
...     name="My SOAR App",
...     app_type="investigative",
...     logo="logo.png",
...     logo_dark="logo_dark.png",
...     product_vendor="Acme Corp",
...     product_name="Security Platform",
...     publisher="My Company",
...     appid="12345678-1234-5678-9012-123456789012",
... )

__init__(*, name, app_type, logo, logo_dark, product_vendor, product_name, publisher, appid, python_version=None, min_phantom_version='6.4.0', fips_compliant=False, asset_cls=<class 'soar_sdk.asset.BaseAsset'>)

Parameters:

• name (str)

• app_type (str)

• logo (str)

• logo_dark (str)

• product_vendor (str)

• product_name (str)

• publisher (str)

• appid (str)

• python_version (Optional[list[PythonVersion]])

• min_phantom_version (str)

• fips_compliant (bool)

• asset_cls (type[BaseAsset])

The main class for creating SOAR applications.

Key Methods

App.action(*, name=None, identifier=None, description=None, verbose='', action_type='generic', read_only=True, params_class=None, output_class=None, view_handler=None, versions='EQ(*)')

Decorator for registering an action function.

This decorator marks a function as an action handler for the app. For more information on how to write action functions, see the follow actions documentation:

• Action Anatomy

• Action Parameters

• Action Outputs

Parameters:

• name (Optional[str])

• identifier (Optional[str])

• description (Optional[str])

• verbose (str)

• action_type (str)

• read_only (bool)

• params_class (Optional[type[Params]])

• output_class (Optional[type[ActionOutput]])

• view_handler (Optional[Callable])

• versions (str)

Return type:

ActionDecorator

App.test_connectivity()

Decorator for registering a test connectivity function.

This decorator marks a function as the test connectivity action for the app. Test connectivity is used to verify that the app can successfully connect to its configured external service or API. Only one test connectivity function is allowed per app.

Returns:

A decorator instance that handles test

connectivity registration.

Return type:

ConnectivityTestDecorator

Example

>>> @app.test_connectivity()
... def test_connectivity_handler(self, asset: Asset):
...     logger.info(f"testing connectivity against {asset.base_url}")

Note

The test connectivity function should not return anything or raise an exception if it fails.

App.on_poll()

Decorator for the on_poll action.

The decorated function must be a generator (using yield) or return an Iterator that yields Container and/or Artifact objects. Only one on_poll action is allowed per app.

Usage: If a Container is yielded first, all subsequent Artifacts will be added to that container unless they already have a container_id. If an Artifact is yielded without a container and no container_id is set, it will be skipped.

Return type:

OnPollDecorator

Example

>>> @app.on_poll()
... def on_poll(
...     params: OnPollParams, client: SOARClient, asset: Asset
... ) -> Iterator[Union[Container, Artifact]]:
...     yield Container(
...         name="Network Alerts",
...         description="Some network-related alerts",
...         severity="medium",
...     )

App.register_action(action, *, name=None, identifier=None, description=None, verbose='', action_type='generic', read_only=True, params_class=None, output_class=None, view_handler=None, view_template=None, versions='EQ(*)')

Dynamically register an action function defined in another module.

This method allows an app to dynamically import and register an action function that is defined in a separate module. It provides a programmatic way to register actions without using decorators directly on the action function.

Parameters:

• action (Callable) – Function import for the action. Must be a callable function that follows SOAR action function conventions and is imported from another module.

• name (Optional[str]) – Human-readable name for the action. If not provided, defaults to the function name with underscores replaced by spaces.

• identifier (Optional[str]) – Unique identifier for the action. If not provided, defaults to the function name.

• description (Optional[str]) – Brief description of what the action does. Used in the app manifest and UI.

• verbose (str) – Detailed description or usage information for the action.

• action_type (str) – Type of action (e.g., “generic”, “investigate”, “correct”). Defaults to “generic”.

• read_only (bool) – Whether the action only reads data without making changes. Defaults to True for safety.

• params_class (Optional[type[Params]]) – Pydantic model class for validating action parameters. If not provided, uses generic parameter validation.

• output_class (Optional[type[ActionOutput]]) – Pydantic model class for structuring action output. If not provided, uses generic output format.

• view_handler (Optional[Callable]) – Optional raw view handler function to associate with this action. Will be automatically decorated with the view_handler decorator.

• view_template (Optional[str]) – Template name to use with the view handler. Only relevant if view_handler is provided.

• versions (str) – Version constraint string for when this action is available. Defaults to “EQ(*)” (all versions).

Return type:

Action

Returns:

The registered Action instance with all metadata and handlers configured.

Raises:

ActionRegistrationError – If view_handler is provided but cannot be found in its original module for replacement.

Example

>>> from my_actions_module import my_action_function
>>> from my_views_module import my_view_handler
>>>
>>> action = app.register_action(
...     my_action_function,
...     name="Dynamic Action",
...     description="Action imported from another module",
...     view_handler=my_view_handler,
...     view_template="custom_template.html",
... )

App.enable_webhooks(default_requires_auth=True, default_allowed_headers=None, default_ip_allowlist=None)

Enable webhook functionality for the app.

This method configures the app to handle incoming webhook requests by setting up the security and routing configurations.

Parameters:

• default_requires_auth (bool) – Whether webhooks require authentication by default.

• default_allowed_headers (Optional[list[str]]) – List of HTTP headers allowed in webhook requests.

• default_ip_allowlist (Optional[list[str]]) – List of IP addresses/CIDR blocks allowed to send webhooks. Defaults to [“0.0.0.0/0”, “::/0”] (allow all).

Return type:

App

Returns:

The App instance for method chaining.

Example

>>> app.enable_webhooks(
...     default_requires_auth=True,
...     default_allowed_headers=["X-Custom-Header"],
...     default_ip_allowlist=["192.168.1.0/24"],
... )

App.view_handler(*, template=None)

Decorator for custom view functions with output parsing and template rendering.

The decorated function receives parsed ActionOutput objects and can return either a dict for template rendering, HTML string, or component data model. If a template is provided, dict results will be rendered using the template. Component type is automatically inferred from the return type annotation.

For more information on custom views, see the following custom views documentation:

Example

>>> @app.view_handler(template="my_template.html")
... def my_view(outputs: List[MyActionOutput]) -> dict:
...     return {"data": outputs[0].some_field}

>>> @app.view_handler()
... def my_chart_view(outputs: List[MyActionOutput]) -> PieChartData:
...     return PieChartData(
...         title="Chart",
...         labels=["A", "B"],
...         values=[1, 2],
...         colors=["red", "blue"],
...     )

Parameters:

template (Optional[str])

Return type:

ViewHandlerDecorator

App.generic_action(output_class=None)

Decorator for registering a generic action function.

This decorator marks a function as the generic action for the app. Generic action is used to call any endpoint of the underlying API service this app implements. Only one generic action is allowed per app. The function you define needs to accept at least one parameter of type GenericActionParams and can accept any other parameters you need. Other useful parameters to accept are the SOARClient and the asset.

Returns:

A decorator instance that handles generic action registration.

Return type:

GenericActionDecorator

Example

>>> @app.generic_action()
... def http_action(
...     self, params: GenericActionParams, asset: Asset
... ) -> GenericActionOutput:
...     logger.info(f"testing connectivity against {asset.base_url}")
...     return GenericActionOutput(
...         status_code=200,
...         response_body=f"Base url is {asset.base_url}",
...     )

Note

The generic action function should return either a GenericActionOutput object or an output class derived from ActionOutput/GenericActionOutput.

Parameters:

output_class (Optional[type[ActionOutput]])

Asset Configuration

AssetField

soar_sdk.asset.AssetField(description=None, required=True, default=None, value_list=None, sensitive=False)

Representation of an asset configuration field.

The field needs extra metadata that is later used for the configuration of the app. This function takes care of the required information for the manifest JSON file and fills in defaults.

Parameters:

• description (Optional[str]) – A short description of this parameter. The description is shown in the asset form as the input’s title.

• required (bool) – Whether or not this config key is mandatory for this asset to function. If this configuration is not provided, actions cannot be executed on the app.

• value_list (Optional[list]) – To allow the user to choose from a pre-defined list of values displayed in a drop-down for this configuration key, specify them as a list for example, [“one”, “two”, “three”].

• sensitive (bool) – When True, the field is treated as a password and will be encrypted and hidden from logs.

• default (Optional[Any])

Return type:

Any

Returns:

The FieldInfo object as pydantic.Field.

BaseAsset

class soar_sdk.asset.BaseAsset(**data)

Bases: BaseModel

Base class for asset models in SOAR SDK.

This class provides the foundation for defining an asset configuration for SOAR apps. It extends Pydantic’s BaseModel to provide validation, serialization, and manifest generation capabilities for asset configurations.

Asset classes define the configuration parameters that users need to provide when setting up an app instance in SOAR. These typically include connection details, authentication credentials, and other app-specific settings.

The class automatically validates field names to prevent conflicts with platform-reserved fields and provides methods to generate JSON schemas compatible with SOAR’s asset configuration system.

Example

>>> class MyAsset(BaseAsset):
...     base_url: str = AssetField(description="API base URL", required=True)
...     api_key: str = AssetField(
...         description="API authentication key", sensitive=True
...     )
...     timeout: int = AssetField(
...         description="Request timeout in seconds", default=30
...     )

Note

Field names cannot start with “_reserved_” or use names reserved by the SOAR platform to avoid conflicts with internal fields.

Parameters:

data (Any)

classmethod to_json_schema()

Generate a JSON schema representation of the asset configuration.

Converts the Pydantic model fields into a format compatible with SOAR’s asset configuration system. This includes data type mapping, validation rules, and UI hints for the SOAR platform.

Return type:

dict[str, AssetFieldSpecification]

Returns:

A dictionary mapping field names to their schema specifications, including data types, descriptions, requirements, and other metadata.

Raises:

TypeError – If a field type cannot be serialized or if a sensitive field is not of type str.

Example

>>> class MyAsset(BaseAsset):
...     host: str = AssetField(description="Server hostname")
...     port: int = AssetField(description="Server port", default=443)
>>> schema = MyAsset.to_json_schema()
>>> schema["host"]["data_type"]
'string'
>>> schema["host"]["required"]
True

Note

Sensitive fields are automatically converted to “password” type regardless of their Python type annotation, and must be str type.

classmethod fields_requiring_decryption()

Set of fields that require decryption.

Return type:

set[str]

Returns:

A set of field names that are marked as sensitive and need decryption before use.

Action Parameters

Action parameters are defined in Pydantic models, which extend the soar_sdk.params.Params class. At their most basic, parameters can have a simple data type such as str or int.

from soar_sdk.params import Params


class CreateUserParams(Params):
   username: str
   first_name: str
   last_name: str
   email: str
   is_admin: bool
   uid: int

Adding extra metadata

You can use the Param function to add extra information to a parameter type. For example, let’s give the uid field a Common Event Format (CEF) type and make it optional.

from soar_sdk.params import Params, Param


class CreateUserParams(Params):
   username: str
   first_name: str
   last_name: str
   email: str
   is_admin: bool
   uid: int = Param(required=False, cef_types=["user id"])

For a full list of Param options, see the Params class and Param function below:

class soar_sdk.params.Params(**data)

Params defines the inputs for an action. It can contain strings, booleans, or numbers – no lists or dictionaries.

Params fields can be optional if desired, or optionally have a default value, CEF type, and other metadata defined in soar_sdk.params.Param.

Parameters:

data (Any)

soar_sdk.params.Param(description=None, required=True, primary=False, default=None, value_list=None, cef_types=None, allow_list=False, sensitive=False)

Representation of the param passed into the action. The param needs extra meta information that is later used for the configuration of the app and use in playbooks. This function takes care of the required information for the manifest JSON file and fills in defaults.

Parameters:

• order – The order key, starting at 0, allows the app author to control the display order of the controls in the UI.

• description (Optional[str]) – A short description of this parameter. The description is shown in the user interface when running an action manually.

• default (Optional[Any]) – To set the default value of a variable in the UI, use this key. The user will be able to modify this value, so the app will need to validate it. This key also works in conjunction with value_list.

• required (bool) – Whether or not this parameter is mandatory for this action to function. If this parameter is not provided, the action fails.

• primary (bool) – Specifies if the action acts primarily on this parameter or not. It is used in conjunction with the contains field to display a list of contextual actions where the user clicks on a piece of data in the UI.

• value_list (Optional[list]) – To allow the user to choose from a pre-defined list of values displayed in a drop-down for this parameter, specify them as a list for example, [“one”, “two”, “three”]. An action can be run from the playbook, in which case the user can pass an arbitrary value for the parameter, so the app needs to validate this parameter on its own.

• contains – Specifies what kind of content this field contains.

• data_type – The type of variable. Supported types are string, password, numeric, and boolean.

• allow_list (bool) – Use this key to specify if the parameter supports specifying multiple values as a comma separated string.

• kwargs – additional kwargs accepted by pydantic.Field

• cef_types (Optional[list])

• sensitive (bool)

Return type:

Any

Returns:

returns the FieldInfo object as pydantic.Field

Parameters for on poll

On poll functions require a specific parameter class called OnPollParams. YYou should use this class as-is, instead of overriding it.

class soar_sdk.params.OnPollParams(**data)

Parameters for on_poll.

Used to define the specific parameters for the on_poll action.

Parameters:

data (Any)

start_time: int

end_time: int

container_count: int

artifact_count: int

container_id: str

Parameters for generic action

Generic action functions require a specific parameter class called GenericActionParams. You should use this class as-is, instead of overriding it.

class soar_sdk.params.GenericActionParams(**data)

Parameters for generic actions.

Used to define the specific parameters for the generic action.

Parameters:

data (Any)

http_method: str

endpoint: str

headers: str

query_params: str

body: str

timeout: int

verify_ssl: bool

Action Outputs

Action outputs are defined in Pydantic models, which extend the soar_sdk.action_results.ActionOutput class.

Much like parameters, outputs can have simple data types such as str or int, or be annotated with the OutputField function to add extra metadata.

from soar_sdk.action_results import ActionOutput, OutputField

class CreateUserOutput(ActionOutput):
   uid: int = OutputField(cef_types=["user id"])
   create_date: str

By default, your action will display an “Action completed successfully” message in the SOAR UI. To customize this message, you can override the generate_action_summary_message method in your output class: .. code-block:: python

from soar_sdk.action_results import ActionOutput

class CreateUserOutput(ActionOutput):

uid: int create_date: str

def generate_action_summary_message(self) -> str:

return f”User created with UID: {self.uid} on {self.create_date}”

Output models can be nested, allowing you to create complex data structures:

from soar_sdk.action_results import ActionOutput, OutputField

class UserDetails(ActionOutput):
   uid: int = OutputField(cef_types=["user id"])
   username: str
   email: str

class CreateUserOutput(ActionOutput):
   user_details: UserDetails
   create_date: str

class ListUsersOutput(ActionOutput):
   users: list[UserDetails]

For more details, see the ActionOutput class and the OutputField function below:

class soar_sdk.action_results.ActionOutput(**data)

Base class for defining structured action output schemas.

ActionOutput defines the JSON schema that an action is expected to output. It is translated into datapaths, example values, and CEF fields for integration with the SOAR platform.

Subclasses should define fields using type annotations and OutputField() for metadata. The schema is automatically converted to SOAR-compatible format for manifest generation and data validation.

Example

>>> class MyActionOutput(ActionOutput):
...     hostname: str = OutputField(
...         cef_types=["destinationHostName"],
...         example_values=["server1.example.com"],
...     )
...     port: int = OutputField(example_values=[80, 443, 8080])
...     is_secure: bool  # Automatically gets True/False examples

Note

Fields cannot be Union or Optional types. Use specific types only. Nested ActionOutput classes are supported for complex data structures.

Parameters:

data (Any)

generate_action_summary_message()

Generate a summary message for the action output.

This method provides a human-readable summary of the action results, which appears when running the action in a SOAR playbook or container.

Return type:

str

Returns:

A string summarizing the action output.

soar_sdk.action_results.OutputField(cef_types=None, example_values=None, alias=None)

Define metadata for an action output field.

This function creates field metadata that is used to describe how action output fields should look like, including CEF mapping and example values for documentation and validation.

Parameters:

• cef_types (Optional[list[str]]) – Optional list of CEF (Common Event Format) field names that this output field maps to. Used for integration with SIEM systems.

• example_values (Optional[list[Union[str, float, bool]]]) – Optional list of example values for this field, used in documentation and for testing/validation purposes.

• alias (Optional[str]) – Optional alternative name for the field when serialized.

Return type:

Any

Returns:

A Pydantic Field object with the specified metadata.

Example

>>> class MyActionOutput(ActionOutput):
...     ip_address: str = OutputField(
...         cef_types=["sourceAddress", "destinationAddress"],
...         example_values=["192.168.1.1", "10.0.0.1"],
...     )
...     count: int = OutputField(example_values=[1, 5, 10])

Generic Action Output

For generic action functions we have provided a convenience class called GenericActionOutput. This class extends the ActionOutput class and adds a status_code and response_body field. You can use this class to return the response from the generic action.

class soar_sdk.action_results.GenericActionOutput(**data)

Output class for generic actions.

This class extends the ActionOutput class and adds a status_code and response_body field. You can use this class as is or extend it to add more fields.

Example

>>> class CustomGenericActionOutput(GenericActionOutput):
...     error: str = OutputField(example_values=["Invalid credentials"])

Note

The status_code field is used to return the HTTP status code of the response. The response_body field is used to return the response body of the response.

Parameters:

data (Any)

status_code: int

response_body: str

APIs

Artifact API

class soar_sdk.apis.artifact.Artifact(soar_client)

Bases: object

API interface for managing SOAR artifacts.

This class provides methods to create and manage artifacts within SOAR.

soar_client

The SOAR client instance for API communication.

Type:

SOARClient

Parameters:

soar_client (SOARClient)

__init__(soar_client)

Initialize the Artifact API interface.

Sets up the artifact interface with default artifact properties and initializes internal artifact storage for unauthenticated clients.

Parameters:

soar_client (SOARClient) – The SOAR client instance for API communication.

create(artifact)

Create a new artifact in the SOAR platform.

Creates an artifact with the provided data, applying default values for common fields if not specified. For authenticated clients, the artifact is created via the REST API. For unauthenticated clients, the artifact is stored locally for testing purposes.

Parameters:

artifact (dict) – The artifact data to create. Must be JSON-serializable. Common fields include: - container_id: ID of the container to associate with - cef: Common Event Format data - label: Artifact label (defaults to ‘artifact’) - type: Artifact type (defaults to ‘generic’) - description: Human-readable description

Returns:

The ID of the created artifact.

Return type:

int

Raises:

• ActionFailure – If the artifact data cannot be serialized to JSON.

• SoarAPIError – If the API request fails or the artifact cannot be created. For unauthenticated clients, raised if no container_id is provided.

Example

>>> artifact_data = {
...     "container_id": 123,
...     "cef": {"sourceAddress": "192.168.1.1"},
...     "label": "ip",
...     "type": "network",
... }
>>> artifact_id = artifact_api.create(artifact_data)
>>> print(f"Created artifact with ID: {artifact_id}")

Container API

class soar_sdk.apis.container.Container(soar_client)

Bases: object

API interface for managing SOAR containers.

This class provides methods to create and manage containers within the SOAR platform. Containers represent security incidents or cases that group related artifacts and serve as the primary organizational unit for security investigations.

soar_client

The SOAR client instance for API communication.

Type:

SOARClient

Parameters:

soar_client (SOARClient)

__init__(soar_client)

Initialize the Container API interface.

Sets up the container interface with default container properties and initializes internal container storage for unauthenticated clients.

Parameters:

soar_client (SOARClient) – The SOAR client instance for API communication.

set_executing_asset(asset_id)

Set the executing asset for containers created by this interface.

The executing asset ID will be automatically added to all containers created through this interface. This identifies which SOAR asset (app instance) is responsible for creating the container.

Parameters:

asset_id (str) – The ID of the asset that will be set as the executing asset.

Return type:

None

create(container, fail_on_duplicate=False)

Create a new container in the SOAR platform.

Creates a container with the provided data, applying default values for common fields if not specified. For authenticated clients, the container is created via the REST API. For unauthenticated clients, the container is stored locally for testing purposes.

Parameters:

• container (dict) – The container data to create. Must be JSON-serializable. Common fields include: - name: Container name/title - description: Human-readable description - severity: Severity level (low, medium, high, critical) - status: Container status (new, open, closed) - artifacts: List of artifacts to create with the container - asset_id: ID of the executing asset (required)

• fail_on_duplicate (bool, optional) – If True, raise an exception when a duplicate container is found. If False, return the existing container ID. Defaults to False.

Returns:

The ID of the created or existing container.

Return type:

int

Raises:

• ActionFailure – If container preparation fails or the container data cannot be serialized to JSON.

• SoarAPIError – If the API request fails, the container cannot be created, or if fail_on_duplicate=True and a duplicate is found.

• ValueError – If required fields (like asset_id) are missing.

Example

>>> container_data = {
...     "name": "Suspicious Network Activity",
...     "description": "Detected unusual traffic patterns",
...     "severity": "medium",
...     "artifacts": [
...         {
...             "cef": {"sourceAddress": "192.168.1.100"},
...             "label": "ip",
...             "type": "network",
...         }
...     ],
... }
>>> container_id = container_api.create(container_data)
>>> print(f"Created container with ID: {container_id}")

Vault API

class soar_sdk.apis.vault.Vault(soar_client)

Bases: object

API interface for managing SOAR vault operations.

This class provides methods to interact with the SOAR vault system for file storage and retrieval. The vault is used to store files, attachments, and other binary data associated with containers and investigations.

phantom_vault

The underlying vault implementation for file operations.

Type:

VaultBase

Parameters:

soar_client (SOARClient)

__init__(soar_client)

Initialize the Vault API interface.

Sets up the vault interface using the appropriate vault implementation based on the SOAR client configuration.

Parameters:

soar_client (SOARClient) – The SOAR client instance for API communication.

get_vault_tmp_dir()

Get the vault temporary directory path.

Returns the file system path to the temporary directory used by the vault for storing temporary files during processing operations.

Returns:

The absolute path to the vault temporary directory.

Return type:

str

Example

>>> vault_tmp = vault_api.get_vault_tmp_dir()
>>> print(f"Vault temp directory: {vault_tmp}")

create_attachment(container_id, file_content, file_name, metadata=None)

Create a vault attachment from file content.

Creates a new file in the vault using the provided content and associates it with the specified container. The content can be either string or binary data.

Parameters:

• container_id (int) – The ID of the container to associate the attachment with.

• file_content (Union[str, bytes]) – The content of the file to create. Can be text (str) or binary data (bytes).

• file_name (str) – The name to give the file in the vault.

• metadata (Optional[dict[str, str]], optional) – Additional metadata to associate with the file. Defaults to None.

Returns:

The vault ID of the created attachment.

Return type:

str

Example

>>> content = "This is a sample text file content"
>>> vault_id = vault_api.create_attachment(
...     container_id=123,
...     file_content=content,
...     file_name="sample.txt",
...     metadata={"source": "user_upload"},
... )
>>> print(f"Created attachment with vault ID: {vault_id}")

add_attachment(container_id, file_location, file_name, metadata=None)

Add an existing file to the vault as an attachment.

Takes an existing file from the file system and adds it to the vault, associating it with the specified container. The original file is typically copied or moved to the vault storage.

Parameters:

• container_id (int) – The ID of the container to associate the attachment with.

• file_location (str) – The file system path to the existing file to add.

• file_name (str) – The name to give the file in the vault.

• metadata (Optional[dict[str, str]], optional) – Additional metadata to associate with the file. Defaults to None.

Returns:

The vault ID of the added attachment.

Return type:

str

Example

>>> vault_id = vault_api.add_attachment(
...     container_id=123,
...     file_location="/tmp/evidence.pdf",
...     file_name="evidence_report.pdf",
...     metadata={"type": "report", "classification": "internal"},
... )
>>> print(f"Added attachment with vault ID: {vault_id}")

get_attachment(vault_id=None, file_name=None, container_id=None)

Retrieve attachment(s) from the vault.

Retrieves one or more attachments from the vault based on the provided search criteria. Can search by vault ID, file name, or container ID.

Parameters:

• vault_id (Optional[str], optional) – The specific vault ID to retrieve. If provided, returns only that attachment. Defaults to None.

• file_name (Optional[str], optional) – Search for attachments with this file name. Defaults to None.

• container_id (Optional[int], optional) – Search for attachments associated with this container. Defaults to None.

Returns:

List of attachment objects containing

metadata and file content. Each object typically includes keys like ‘vault_id’, ‘name’, ‘size’, ‘metadata’, and ‘path’.

Return type:

list[VaultAttachment]

Example

>>> # Get a specific attachment by vault ID
>>> attachments = vault_api.get_attachment(vault_id="abc123")
>>>
>>> # Get all attachments for a container
>>> attachments = vault_api.get_attachment(container_id=123)

delete_attachment(vault_id=None, file_name=None, container_id=None, remove_all=False)

Delete attachment(s) from the vault.

Removes one or more attachments from the vault based on the provided search criteria. Can delete by vault ID, file name, or all attachments in a container.

Parameters:

• vault_id (Optional[str], optional) – The specific vault ID to delete. If provided, deletes only that attachment. Defaults to None.

• file_name (Optional[str], optional) – Delete attachments with this file name. Defaults to None.

• container_id (Optional[int], optional) – Delete attachments associated with this container. Defaults to None.

• remove_all (bool, optional) – If True and container_id is provided, removes all attachments from the container. Defaults to False.

Returns:

List of vault IDs of the deleted attachments.

Return type:

list[str]

Example

>>> # Delete a specific attachment
>>> deleted = vault_api.delete_attachment(vault_id="abc123")
>>> print(f"Deleted attachments: {deleted}")
>>>
>>> # Delete all attachments from a container
>>> deleted = vault_api.delete_attachment(container_id=123, remove_all=True)
>>>
>>> # Delete attachments by filename
>>> deleted = vault_api.delete_attachment(file_name="temp_file.txt")

Data Models

class soar_sdk.models.artifact.Artifact(**data)

Represents an artifact to be created during on_poll.

This class allows users to create and configure artifacts when yielding from an on_poll function.

Parameters:

data (Any)

name: Optional[str]

label: Optional[str]

description: Optional[str]

type: Optional[str]

severity: Optional[str]

source_data_identifier: Optional[str]

container_id: Optional[int]

data: Optional[dict[str, Any]]

run_automation: bool

owner_id: Union[int, str, None]

cef: Optional[dict[str, Any]]

cef_types: Optional[dict[str, list[str]]]

ingest_app_id: Union[int, str, None]

tags: Union[list[str], str, None]

start_time: Optional[str]

end_time: Optional[str]

kill_chain: Optional[str]

to_dict()

Convert the artifact to a dictionary (needed for save_artifact).

Return type:

dict[str, Any]

class soar_sdk.models.container.Container(**data)

Represents a container to be created during on_poll.

This class allows users to specify container properties when yielding from an on_poll function.

Parameters:

data (Any)

name: str

label: Optional[str]

description: Optional[str]

source_data_identifier: Optional[str]

severity: Optional[str]

status: Optional[str]

tags: Union[list[str], str, None]

owner_id: Union[int, str, None]

sensitivity: Optional[str]

artifacts: Optional[list[dict[str, Any]]]

asset_id: Optional[int]

close_time: Optional[str]

custom_fields: Optional[dict[str, Any]]

data: Optional[dict[str, Any]]

due_time: Optional[str]

end_time: Optional[str]

ingest_app_id: Optional[int]

kill_chain: Optional[str]

role_id: Union[int, str, None]

run_automation: bool

start_time: Optional[str]

open_time: Optional[str]

tenant_id: Union[int, str, None]

container_type: Optional[str]

template_id: Optional[int]

authorized_users: Optional[list[int]]

artifact_count: Optional[int]

container_id: Optional[str]

to_dict()

Convert the container to a dictionary (needed for save_container).

Return type:

dict[str, Any]

class soar_sdk.models.vault_attachment.VaultAttachment(**data)

Model representing a vault attachment.

This model is used to represent the metadata and content of a file stored in the SOAR vault. It includes attributes such as vault ID, file name, size, metadata, and the file path.

Parameters:

data (Any)

id: int

created_via: Optional[str]

container: str

task: Optional[str]

create_time: str

name: str

user: str

vault_document: int

mime_type: Optional[str]

es_attachment_id: Optional[str]

hash: str

vault_id: str

size: int

path: str

metadata: dict

aka: list[str]

container_id: int

contains: list[str]

open(mode='r')

Open the vault attachment file.

Parameters:

mode (str) – The mode in which to open the file. Defaults to ‘r’.

Returns:

A file-like object for reading the attachment content.

Return type:

file

class soar_sdk.models.view.ViewContext(**data)

Model representing the context dictionary passed to view functions.

Parameters:

data (Any)

QS: dict[str, list[str]]

container: int

app: int

no_connection: bool

google_maps_key: Union[bool, str]

dark_title_logo: Optional[str]

title_logo: Optional[str]

app_name: Optional[str]

results: Optional[list[dict[str, Any]]]

html_content: Optional[str]

class soar_sdk.models.view.ResultSummary(**data)

Summary statistics for an app run.

Parameters:

data (Any)

total_objects: int

total_objects_successful: int

Logging

exception soar_sdk.logging.getLogger(name='phantom_logger')

Bases:

Get the recommended logger for SOAR SDK applications.

This is the standard logger you should use in all SOAR applications built with the SDK. It provides all normal Python logging capabilities with additional SOAR-specific features like progress logging and integration with the SOAR platform’s logging system.

The logger supports all standard Python logging levels (DEBUG, INFO, WARNING, ERROR, CRITICAL) plus a custom PROGRESS level for tracking action progress.

Parameters:

name (str, optional) – The name for the logger instance. Defaults to “phantom_logger” for compatibility.

Returns:

A logger instance with SOAR-specific capabilities that

extends the standard Python logger interface.

Return type:

PhantomLogger

Example

>>> from soar_sdk.logging import getLogger
>>> logger = getLogger()
>>> logger.debug("Debug message for troubleshooting")
>>> logger.info("Informational message")
>>> logger.warning("Warning about potential issue")
>>> logger.error("Error occurred during processing")
>>> logger.progress("Action is 50% complete")
>>>
>>> # Logger supports all standard logging methods
>>> logger.setLevel(logging.DEBUG)
>>> logger.addHandler(custom_handler)
>>> logger.log(logging.INFO, "Custom level logging")

Note

This function returns a singleton instance, so multiple calls with the same name will return the same logger object for consistency across your application.

exception soar_sdk.logging.info(msg, *args, **kwargs)

Bases:

Log an informational message using the default SOAR logger.

Convenience function for info-level logging without needing to instantiate a logger. Use this for general informational messages about normal program execution and important events.

Parameters:

• msg (str) – The log message. Supports Python string formatting with positional arguments.

• *args (Any) – Variable length argument list for string formatting.

• **kwargs (Any) – Arbitrary keyword arguments passed to the underlying logger.

Return type:

None

Example

>>> from soar_sdk.logging import info
>>> info("Action started successfully")

exception soar_sdk.logging.debug(msg, *args, **kwargs)

Bases:

Log a debug message using the default SOAR logger.

Convenience function for debug-level logging without needing to instantiate a logger. This function uses the singleton SOAR logger instance and supports all standard Python logging formatting and options.

Parameters:

• msg (str) – The log message. Supports Python string formatting with positional arguments.

• *args (Any) – Variable length argument list for string formatting.

• **kwargs (Any) – Arbitrary keyword arguments passed to the underlying logger.

Return type:

None

Example

>>> from soar_sdk.logging import debug
>>> debug("Processing user: %s", username)

exception soar_sdk.logging.progress(msg, *args, **kwargs)

Bases:

Log a progress message using the default SOAR logger.

Convenience function for progress-level logging without needing to instantiate a logger. This is a custom logging level specific to SOAR that’s used to report action progress and status updates to users. Progress messages are typically displayed in the SOAR UI to show action execution status.

Parameters:

• msg (str) – The progress message. Supports Python string formatting with positional arguments.

• *args (Any) – Variable length argument list for string formatting.

• **kwargs (Any) – Arbitrary keyword arguments passed to the underlying logger.

Return type:

None

Example

>>> from soar_sdk.logging import progress
>>> progress("Starting data collection...")

Note

Progress messages are displayed to end users in the SOAR interface, so they should be clear, informative, and user-friendly.

exception soar_sdk.logging.warning(msg, *args, **kwargs)

Bases:

Log a warning message using the default SOAR logger.

Convenience function for warning-level logging without needing to instantiate a logger. Use this for potentially harmful situations that don’t prevent the program from continuing but warrant attention.

Parameters:

• msg (str) – The log message. Supports Python string formatting with positional arguments.

• *args (Any) – Variable length argument list for string formatting.

• **kwargs (Any) – Arbitrary keyword arguments passed to the underlying logger.

Return type:

None

Example

>>> from soar_sdk.logging import warning
>>> warning("API rate limit approaching")

exception soar_sdk.logging.error(msg, *args, **kwargs)

Bases:

Log an error message using the default SOAR logger.

Convenience function for error-level logging without needing to instantiate a logger. Use this for error conditions that are serious but allow the program to continue running.

Parameters:

• msg (str) – The log message. Supports Python string formatting with positional arguments.

• *args (Any) – Variable length argument list for string formatting.

• **kwargs (Any) – Arbitrary keyword arguments passed to the underlying logger.

Return type:

None

Example

>>> from soar_sdk.logging import error
>>> error("Failed to connect to external API")

exception soar_sdk.logging.critical(msg, *args, **kwargs)

Bases:

Log a critical error message using the default SOAR logger.

Convenience function for critical-level logging without needing to instantiate a logger. Use this for very serious error events that may cause the program to abort or require immediate attention.

Parameters:

• msg (str) – The log message. Supports Python string formatting with positional arguments.

• *args (Any) – Variable length argument list for string formatting.

• **kwargs (Any) – Arbitrary keyword arguments passed to the underlying logger.

Return type:

None

Example

>>> from soar_sdk.logging import critical
>>> critical("Database connection lost, cannot continue")

Exceptions

exception soar_sdk.exceptions.ActionFailure(message, action_name=None)

Bases: Exception

Exception raised when an action fails to execute successfully.

Parameters:

• message (str)

• action_name (Optional[str])

__str__()

Return a formatted error message.

Return type:

str

exception soar_sdk.exceptions.ActionRegistrationError(action)

Bases: Exception

Exception raised when there is an error registering an action.

Parameters:

action (str)

exception soar_sdk.exceptions.AssetMisconfiguration(message, action_name=None)

Bases: ActionFailure

Exception raised when an asset is misconfigured.

Parameters:

• message (str)

• action_name (Optional[str])

__str__()

Return a formatted error message.

Return type:

str

exception soar_sdk.exceptions.SoarAPIError(message, action_name=None)

Bases: ActionFailure

Exception raised when there is an error with the SOAR REST API.

Parameters:

• message (str)

• action_name (Optional[str])

__str__()

Return a formatted error message.

Return type:

str