sentinel-one/ai-siem/hyperautomation

SentinelOne Hyperautomation Skill

<!-- CONFIG-FILE-ADDRESSING v1 -->

SDL config files: address by `udoId`, and do not trust a REST listing.

REST listFiles / getFile cannot see udoId-addressed /dashboards/ files, so getFile

returns 404 on a dashboard the console is displaying and the listing under-reports (measured on

one tenant: REST 8, GraphQL 17, console 48 files). **If a listing disagrees with what the UI

shows, the listing is wrong until proven otherwise**, change read path before concluding the

object is missing or the token lacks scope. Use the GraphQL configFiles / configFile surface.

A name-addressed addConfigFile to /dashboards/ creates a duplicate instead of updating;

address dashboards by udoId with expectedVersion. content is HJSON, not JSON. S1-Scope

changes which files exist as far as the caller can tell.

Full detail: `sdl-api/references/config-file-graphql.md`

This skill enables Claude to design and generate valid SentinelOne Hyperautomation workflow JSON, explain the logic behind workflows, and optionally submit them to a live console via API.

Talk to the console through the `s1-secops-mcp` MCP tools. ha_list_workflows, ha_get_workflow, ha_import_workflow, ha_export_workflow (pass outputFile to save the ZIP to disk) and ha_delete_workflow cover the workflow lifecycle; s1_api_post / s1_api_put / s1_api_delete cover publish, activate, deactivate and run-now. The server runs on the user's machine, so it reaches *.sentinelone.net where the Cowork sandbox cannot, and it reads credentials from environment variables or the OS keychain. If the tools are missing, point the user to the s1-secops-mcp README (s1-secops-mcp/README.md in the s1-secops-skills source repo, mcp/s1-secops-mcp/README.md in ai-siem; not shipped inside the plugin).

Minimum viable workflow JSON (smoke test)

Before building production workflows, validate your token + scope using the smallest payload the /import endpoint accepts: a manual trigger with no inputs. Use this to confirm the API path works end-to-end (import → activate) before iterating on real action graphs.

Which of the two forms you need depends on how you are calling. The block

below is the raw HTTP request body, so it includes the {"data": {...}}

envelope the /import endpoint requires. If you are calling through the

ha_import_workflow MCP tool, pass the bare workflow object instead: the

tool adds that envelope for you, and sending a wrapped payload produces

{"data":{"data":{...}}} and a 422 body.data.name Field required, which reads

like a broken workflow rather than one extra level of nesting. Since 1.3.9 the

tool unwraps a wrapped payload and says so in its response, but pass the bare

object and the round trip is clean.

Form A, raw API body (curl, requests, anything hitting the endpoint directly):

{
  "data": {
    "name": "minimal-smoke-test",
    "description": "validates the import path",
    "actions": [
      {
        "action": {
          "client_data": {
            "collapsed": false,
            "dimensions": { "height": 76.0, "width": 256.0 },
            "position": { "x": 286.0, "y": -29.0 }
          },
          "connection_id": null,
          "connection_name": null,
          "data": {
            "action_type": "manual_trigger",
            "dynamic_properties": {},
            "name": "Manual Trigger",
            "static_payload": "{}",
            "trigger_type": "dynamic"
          },
          "description": null,
          "integration_id": null,
          "tag": "core_action",
          "type": "manual_trigger",
          "use_connection_name": false
        },
        "connected_to": [],
        "export_id": 0,
        "parent_action": null
      }
    ]
  }
}

Form B, `ha_import_workflow` MCP tool: the same workflow with the envelope removed. This is the value of the workflowJson argument.

{
  "name": "minimal-smoke-test",
  "description": "validates the import path",
  "actions": [
    {
      "action": {
        "client_data": {
          "collapsed": false,
          "dimensions": { "height": 76.0, "width": 256.0 },
          "position": { "x": 286.0, "y": -29.0 }
        },
        "connection_id": null,
        "connection_name": null,
        "data": {
          "action_type": "manual_trigger",
          "dynamic_properties": {},
          "name": "Manual Trigger",
          "static_payload": "{}",
          "trigger_type": "dynamic"
        },
        "description": null,
        "integration_id": null,
        "tag": "core_action",
        "type": "manual_trigger",
        "use_connection_name": false
      },
      "connected_to": [],
      "export_id": 0,
      "parent_action": null
    }
  ]
}

Pass the scope as the tool's accountIds or siteIds argument, not in the JSON. Form B is live-verified: it returns 201 with the new workflow id and version_id, in state draft.

Notes:

• dynamic_properties: {} is valid: the manual-trigger node renders with no input fields.
• Import is not complete until published: treat create/import and publish as ONE atomic step, publish in the SAME step, never as a follow-up. ALWAYS publish a newly created or imported workflow to a Shared Draft. A workflow created or imported via the API lands as a Private Draft owned by the API token's user (for example, the service user), so it is invisible in the console to the human who requested it. Immediately after a successful import, publish it: POST /hyper-automate/api/v1/workflows/{workflow_id}/publish?accountIds=<acct> (bodyless {}, returns 204; state stays inactive, meaning shared but not running). Use siteIds=<id> for a site-scoped workflow. See references/api-integration.md section 8a. Skip this only when you are activating the workflow, since activation auto-publishes. You can only publish a draft owned by the token's user; publishing another user's private draft returns 403 "Workflow can't be published".
• Activate the imported workflow with

POST /workflows/{workflow_id}/{version_id}/activation?siteIds=<id> (returns 204).

• Don't forget the scope param: see references/api-integration.md for the

siteIds= pitfall (the wrong shape returns 403 "Insufficient permissions" that looks like a missing role).

How to use this skill

When a user asks to build a workflow, follow this process:

Step 1: Understand the intent

Ask (or infer from context):

• What should trigger the workflow? (alert, schedule, webhook, manual, email)
• What integrations are needed? (SentinelOne, M365, Slack, VirusTotal, etc.)
• What is the desired outcome? (enrich alert, disable user, send notification, etc.)
• Should the workflow run automatically or on-demand?

Step 2: Warn about integrations

CRITICAL: Before generating JSON, identify any integration-backed actions (tag = "integration"). These require a connection under their integration. A connection CAN be created via API (POST /hyper-automate/api/v1/connections?siteIds=<site> with a data wrapper, returns 201; the operator supplies the secret; see references/api-integration.md section 16). (An EXISTING connection CAN be pre-bound programmatically: set integration_id = the connection's id on each http_request action in the import JSON with use_authentication_data: true, then activate via POST .../workflows/{id}/{version_id}/activation; no manual UI binding needed. One connection also serves actions that hit different hosts, e.g. the LRQ console host and the /v1/alerts ingest host, since auth is header-injected regardless of the URL, PROVIDED both endpoints take the same credential. HEC event-collector actions (/services/collector/*) do not: they need their own connection holding an SDL Log Write Key, see "Connection requirement" below.) Always tell the user: "This workflow uses the [X, Y, Z] integrations. Before importing, you must configure connections for these in your Hyperautomation → Integrations section."

Integration-backed actions have "tag": "integration" and a non-null integration_id. Core actions (Variable, Loop, Condition, Delay, Send Email, HTTP Request without integration, Break Loop, Snippet, Wait for Slack, Create Interaction, LLM) have "tag": "core_action".

Packaged vs ad-hoc integration actions. Every built-in integration ships an action pack. A packaged action carries data.public_action_id (a pack UUID) and a pre-filled data.url_path; an ad-hoc action has public_action_id: null and a URL you write yourself. In production, 71% of http_request steps (3,822 of 5,418) use a packaged action. Prefer a packaged action when one exists and keep url, url_path and public_action_id consistent.

The action packs are not queryable: GET /integrations/{id} returns connection and auth metadata only, /integrations/{id}/actions is 404, and there is no GET /integrations list endpoint (405). So use references/integration-catalog.md, which records all 266 packaged actions across 45 integrations plus the ad-hoc calls, mined from a live tenant. To see what a specific console has, enumerate with GET /hyper-automate/api/v1/connections/scope and resolve each distinct integration_id via GET /hyper-automate/api/v1/integrations/{id}.

Step 3: Generate the JSON

Read references/workflow-schema.md to produce a valid workflow JSON. Read references/building-blocks.md for the correct action type structures. Read references/functions-reference.md for available functions and their syntax.

Step 4: Validate before outputting

Self-check against references/validation-rules.md before presenting the workflow.

If the workflow chains Function.JQ steps, builds a time window, or fails a run deliberately, also read references/expressions-gotchas.md. It covers the failures that only appear at runtime or activation: Function.JQ(...,true) returns a STRING so the next JQ cannot index it; PARSE_JSON rejects an already-materialised object; a local_var is invisible to the action that defines it; quote-bearing expressions inlined in an http_request payload fail at ACTIVATION with invalid_references; absolute calendar-day windows via FORMATTED_DATE; using evaluate-expression as a pre-deploy test loop; the fake-attribute throw idiom; and why retrying a poll cannot revive a dead LRQ.

Step 5: API submission (optional)

If the user wants to submit to a live console, read references/api-integration.md.

Read-only mode. From 1.5.5, s1-secops-mcp is read-only by default (S1_READ_ONLY unset or true). ha_import_workflow, ha_delete_workflow and the s1_api_post calls for publish, activate, deactivate and run-now are refused in that mode; ha_list_workflows, ha_get_workflow and ha_export_workflow still run. Check the mode before an import-publish-activate sequence: read mode.readOnly from the sentinelone://credentials-status resource, or the server's initialize instructions.

• If a write returns "s1-secops-mcp is in read-only mode (S1_READ_ONLY).", stop. Do not retry, and do not route around it with another tool (s1_api_post to a different endpoint, a hand-built GraphQL mutation).
• Tell the user which action was refused and how to enable write: Docker launcher s1-secops-mcp-launch.sh install --read-write (Windows -ReadWrite), then restart Claude Desktop; .mcpb extension: turn off "Read-only mode (recommended)"; Node install: "S1_READ_ONLY": "false" in the server's env block. Detail: docs/read-only.md in the source repo (not shipped).
• Offer the workflow JSON as a local file via the Write tool so the user can import it in the console or retry later.
• Never enable write on the user's behalf by editing their MCP client config.