SPLK-2003 Using REST

Using REST Detailed Explanation

1. Overview

Splunk SOAR provides a RESTful API that allows external systems, scripts, and developers to interact with the platform programmatically.
This means you can automate operations, fetch data, trigger playbooks, and more — all without needing to log in to the web interface.

Think of the REST API as a remote control for Splunk SOAR.

2. API Capabilities

The SOAR REST API supports a wide variety of operations. You can:

a. Create and Update:

• Events (Containers)

  • Automatically send alerts into SOAR from other systems.

• Artifacts

  • Add indicators of compromise (IOCs) like IPs, hashes, domains.

• Cases

  • Create, assign, and update investigation cases.

b. Query System Objects:

• Playbooks

• Assets

• Users

• Roles

• Lists

You can retrieve current system settings, configurations, or object metadata.

c. Execute Playbooks Manually:

• You can use the API to trigger a specific playbook on a container or case.

Useful for integrating SOAR with external ticketing, detection, or workflow systems.

d. Upload Files:

• Attach logs, documents, screenshots, or forensic files to a case using the API.

3. Authentication

To use the REST API securely, you must authenticate each request.

Token-Based Authentication (Recommended)

• You can create API tokens in:

  • The Web UI (under User Profile > API Tokens)

  • The /login endpoint, using a script

Token Format:

Authorization: Bearer <your_api_token_here>

Best for scripts, integrations, and automation tools.

Session Cookie-Based Authentication

• Used when accessing the API from a browser-based client.

• Requires an authenticated session cookie.

Less secure for automation but useful for internal tools with UI elements.

4. Common Endpoints

Here are some frequently used API calls:

Endpoint	Description
POST /rest/container	Create a new container (event)
GET /rest/artifact	Retrieve artifact data
POST /rest/playbook_run	Trigger a playbook execution
GET /rest/system_info	Get system metadata like version, status, uptime

These endpoints help integrate SOAR with detection systems, ticketing tools, and case managers.

5. Security Considerations

Any time you're exposing an API, security is critical. Follow these practices:

a. Always Use HTTPS

• Do not expose your API over HTTP.

• Use a valid SSL certificate to encrypt all traffic.

b. Limit Token Permissions

• Don’t use admin-level tokens unless necessary.

• Create tokens with the minimum role or scope required.

c. Rotate Tokens Regularly

• Set expiry periods for tokens.

• Revoke and replace tokens periodically.

• Remove unused or inactive tokens.

d. Audit API Usage

• Monitor logs to detect suspicious behavior (e.g., failed logins, unexpected requests).

• Keep an eye on volume and access times.

6. Tools for API Testing and Integration

Postman

• A user-friendly API testing tool.

• Great for exploring endpoints, building requests, and debugging responses.

Curl

• Command-line tool for sending API requests.

• Useful for scripting and quick tests.

Example:

curl -X GET https://soar.company.com/rest/container \
  -H "Authorization: Bearer <your_token>"

Python + requests Library

• Ideal for building custom integrations or automation scripts.

• Easily handle GET/POST requests, headers, JSON payloads, and error handling.

Example:

import requests

headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}

response = requests.get("https://soar.company.com/rest/container", headers=headers)
print(response.json())

7. Real-World Use Cases

• Ticketing Integration: Auto-create SOAR events from ServiceNow or Jira tickets.

• Threat Feed Ingestion: Push threat indicators from intel platforms.

• Cross-SOAR Sync: Share containers, cases, and results across SOAR environments.

• Dashboards: Build custom dashboards outside of SOAR using live API data.

Summary

Feature	Description
REST API Purpose	Programmatically control and integrate with SOAR
Capabilities	Create/update containers, artifacts, playbooks, assets, users
Auth Methods	Token-based (preferred) or session cookie
Common Endpoints	/rest/container, /rest/playbook_run, /rest/artifact, /rest/system_info
Security Best Practices	Use HTTPS, restrict permissions, rotate tokens, monitor usage
Tools	Postman, curl, Python requests
Use Cases	Integrations with SIEMs, ticketing, threat intel, SOAR-to-SOAR syncing

Using REST (Additional Content)

1. Handling Authentication Failures

While token-based authentication is recommended, it’s essential to understand how to recognize and respond to authentication errors.

Common HTTP Response Codes and Their Meanings:

• 200 OK: The request was successful.

• 401 Unauthorized: The API token is missing, expired, or invalid.

• 403 Forbidden: The token is valid, but does not have permission to perform the action.

• 500 Internal Server Error: A generic server error, often due to misconfiguration or unexpected input.

Troubleshooting Authentication Issues:

• Check token scope and expiration.

• Inspect headers to confirm the format: Authorization: Bearer <token>

• Use phantom.debug() or external logging to capture the full response for inspection.

2. Pagination for Large Result Sets

Most REST endpoints in SOAR use pagination to limit the size of responses, especially for endpoints like:

• /rest/container

• /rest/artifact

• /rest/playbook_run

Example of Paginated API Call:

GET /rest/container?page=0&page_size=100

• page: The offset index (starting from 0).

• page_size: The number of records returned per page (commonly 50–100).

Retrieving All Records:

In integration scripts, loop through pages until the result set is empty:

containers = []
page = 0

while True:
    resp = requests.get(f"{base_url}/rest/container?page={page}&page_size=100", headers=headers)
    data = resp.json()
    if not data:
        break
    containers.extend(data)
    page += 1

3. Rate Limiting and API Usage Best Practices

Splunk SOAR does not impose strict public rate limits, but enterprise environments may configure network or proxy-layer rate limiting to protect system performance.

Recommendations:

• Avoid sending large bursts of requests (e.g., hundreds per second).

• Implement retry logic with backoff delays.

• Monitor for HTTP 429 (Too Many Requests), if applicable.

Some environments implement API quotas, especially in multi-tenant setups or via reverse proxies.

4. Asynchronous Operations and Monitoring Status

Some REST API operations, such as triggering a playbook, are asynchronous. This means the API call will return a response immediately, but the actual task continues to run in the background.

Monitoring Playbook Execution:

When calling /rest/playbook_run, you receive a run_id.

You can query the status using:

GET /rest/playbook_run/<run_id>

The response will include:

• status: e.g., “in_progress”, “completed”, “failed”

• summary: Outputs or errors returned by the playbook

Use this endpoint to check the outcome before proceeding in your integration logic.

5. Error Handling in Python Scripts (Developer Practice)

To build robust integrations with SOAR’s API, use structured error handling to manage connection failures, timeouts, or unexpected API responses.

Enhanced Python Sample:

import requests

try:
    response = requests.get("https://soar.company.com/rest/container", headers=headers)
    response.raise_for_status()
    containers = response.json()
except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred: {http_err}")
except requests.exceptions.RequestException as err:
    print(f"Network error occurred: {err}")

Benefits:

• Prevents script crashes

• Enables automated retry, logging, and alerts

6. Secure Storage of API Tokens

Never hard-code API tokens in your source code.

Recommended Practices:

• Store tokens in environment variables:

  export SOAR_TOKEN="your_token"
  

• In Python, access it with:

  import os
  token = os.getenv("SOAR_TOKEN")
  

• For production environments, use secret management tools like:

  • HashiCorp Vault

  • AWS Secrets Manager

  • Azure Key Vault

Tokens should be rotated regularly and scoped to the minimal required permissions.

Summary

Topic	Description
Auth Failures	Understand and handle 401/403 errors properly
Pagination	Use page and page_size to fetch large datasets
Rate Limiting	Avoid excessive calls; use retry with delay
Async Monitoring	Use /rest/playbook_run/<id> to check status
Error Handling	Wrap API calls in try/except for stability
Token Security	Store secrets outside code; use env vars or secret managers