What a Shuffle implementation involves
Shuffle is an open-source security orchestration, automation and response (SOAR) platform. Analysts build workflows in a visual editor from apps, triggers and conditions, and Shuffle runs each action in a short-lived container. Apps are generated from OpenAPI specifications or written in Python with the Shuffle app SDK, so most security tools with an HTTP API can be connected.
Installing Shuffle takes little time. The implementation work sits in the playbooks: deciding which alerts are automated, what enrichment and response steps run, where a person must approve an action, and how results reach the case or ticket. A playbook that closes the wrong alert or isolates the wrong host causes more harm than no automation, so design, testing and change control carry most of the effort.
DeployOpen works with your SOC or MSSP team to turn runbooks into Shuffle workflows, build the apps your tools need and run the platform in your infrastructure.
Discovery and playbook design
List the alert types that reach analysts, how often each arrives, what the analyst does today and which tools they touch. Good first candidates are repetitive, well understood steps such as indicator enrichment, phishing triage or alert deduplication. Record the data each step needs.
Model each playbook as a trigger (webhook, schedule, subflow or user input), a sequence of app actions and the conditions between them. Decide early how alert payloads are normalized, what the datastore holds for deduplication and which steps become reusable subflows.
Containment actions such as disabling an account, blocking a domain or isolating an endpoint usually need a person in the loop. Shuffle's user input trigger can pause a workflow for approval. Agree which actions run automatically, which need approval, who may approve and what happens when nobody answers.
Shuffle keeps revisions of each workflow and can back workflows up to a GitHub or Azure DevOps repository. Use separate test and production tenants or environments, review changes before promotion, and record which playbook version handled an incident.
Configuration, custom apps and upgrade cost
Most needs are met with configuration. Custom apps fill the gaps and become code you maintain.
Prebuilt and OpenAPI apps
Shuffle ships many prebuilt apps, and its app creator generates new ones from an OpenAPI specification with API key, bearer, basic or OAuth2 authentication. Generated apps are the lowest-maintenance way to add a tool with a documented API.
Python apps
When an integration needs logic beyond HTTP calls, write a Python app with an api.yaml definition and the app SDK. Self-hosted instances can hot-load apps from a folder, and apps can be tested through a CI workflow that calls them via the API.
Workflow building blocks
Shuffle Tools, Liquid formatting, the datastore, subflows and loops cover parsing, filtering, deduplication and branching without new code.
Upgrade cost
Platform updates do not update installed apps automatically, and replacing an app version means re-adding it in workflows that use it. Each custom app needs an owner, tests and a place in the upgrade checklist.
Integrations to plan
Illustrative integration pattern for a SOC. Your tool list and actions will differ.
| System | Typical trigger or action | Design note |
|---|---|---|
| SIEM and XDR (for example Wazuh) | Alerts arrive through an inbound webhook and start a triage workflow. | Filter by rule level or group at the source so Shuffle receives alerts worth automating. |
| Threat intelligence (MISP, OpenCTI) | Look up indicators, add sightings or create events from confirmed findings. | Agree which confidence levels and markings may be written back. |
| Case management (for example TheHive) | Create or update cases, add observables and attach enrichment results. | Decide whether the case or the workflow is the record of analyst decisions. |
| Ticketing (Jira, ServiceNow and similar) | Open tickets for owners outside the SOC and sync status back. | Map severity and assignment groups once, in a shared subflow. |
| Identity, EDR and email | Disable accounts, isolate hosts or pull suspicious messages after approval. | Give each app credential the narrowest permissions the action needs. |
Architecture and execution model
Shuffle splits into a server layer and a runtime layer. The server layer holds the React frontend, the Go backend API and OpenSearch, which stores users, workflows, tenants, apps and execution results. The runtime layer is Orborus, which polls the backend for jobs, starts workers, and has workers launch an ephemeral container for each app action.
Runtime locations are matched by name to an Orborus instance. Placing an Orborus inside a restricted network segment lets workflows reach internal tools there without opening inbound ports to that segment.
Execution can run on a single Docker host, across a Docker Swarm cluster or on Kubernetes with the Helm chart. Orborus and workers need access to the container runtime, through the Docker socket or the documented docker socket proxy, which is the main host-level risk to design around.
Hosting, availability and hardening
How do we run Shuffle with high availability?
Run OpenSearch as a cluster, scale the backend and frontend across servers behind a load balancer, put shared file storage such as NFS under the files folder when several backends run, and run more than one Orborus per location. Memcached gives backend, Orborus and workers a shared cache once execution is spread across hosts.
How are API credentials for our tools protected?
Shuffle encrypts app authentication, protected datastore keys and files with a key derived from SHUFFLE_ENCRYPTION_MODIFIER. Set it before storing credentials, keep it in your secrets store and back it up, because losing or changing it breaks every saved authentication. Shuffle can also fetch credentials at runtime from an external store, such as HashiCorp Vault or a cloud key management service, through its KMS feature.
How should administrators sign in?
Shuffle supports SAML and OpenID Connect single sign-on per tenant, with MFA enforcement. Connect it to your identity provider, map roles for new users, decide whether SSO is required for each tenant and keep a documented break-glass admin path.
What else belongs in hardening?
Terminate TLS at the frontend or a reverse proxy, restrict access to the backend and OpenSearch ports, use your own OpenSearch certificates, limit container API access with the docker socket proxy, and allowlist the sources allowed to call webhooks.
What do we back up?
Back up the OpenSearch data, the Shuffle files folder, the environment file and the encryption modifier, and keep workflows in Git. Test a restore into a separate instance and run a sample workflow there before relying on it.
Migration, testing and rollout
Teams usually come to Shuffle from scripts and scheduled jobs, from automation inside a SIEM or case tool, or from a commercial SOAR whose renewal is due. Playbooks do not convert automatically between platforms. Treat each existing playbook as a specification, rebuild it with Shuffle apps and subflows, and run old and new side by side on the same alerts until the outputs match.
Test with recorded alert payloads in a test tenant or environment. Cover the expected path, malformed input, an unreachable API, an expired credential and a timed-out approval. Build containment playbooks so they can first run in a report-only mode that records what they would do.
Roll out one alert family at a time, starting with enrichment that only adds context, then automated closure of known benign alerts, then approved containment. Train analysts on reading executions and requesting playbook changes, and train engineers on app development.
Shuffle operating ownership
Automation that acts on production systems needs named owners for the platform, the playbooks and the credentials they use.
Platform team
- Runs OpenSearch, the backend, Orborus and the container hosts.
- Applies updates and checks app versions after each one.
- Monitors queues, failed executions and disk space.
Playbook owners
- Own each workflow, its trigger and its expected outcome.
- Review changes in a test environment before promotion.
- Retire playbooks whose source alerts no longer exist.
Security and IAM
- Issue scoped service credentials for each app.
- Hold the encryption modifier and break-glass access.
- Review which actions may run without approval.
SOC analysts
- Approve containment steps when a workflow pauses.
- Report wrong outcomes and missing enrichment.
- Propose new candidates for automation.
Shuffle implementation questions
How is Shuffle licensed?
The Shuffle repository states that the backend is licensed under AGPLv3, while apps, the app specification, the app SDK, workflows and documentation are under MIT. Shuffle's documentation also describes default limits for unlicensed on-premises instances, covering monthly app runs, sub-tenants and environments, and says production or scaled use needs an on-premises license. Review the current terms with the vendor before sizing a deployment.
Can an MSSP run one Shuffle for many clients?
Shuffle was built with MSSPs in mind and supports tenants and sub-tenants, with app credentials that a parent tenant can share with sub-tenants. Plan tenant boundaries, per-client runtime locations and credential separation before onboarding the first client.
Which version should we run?
Shuffle publishes versioned container images and recommends keeping frontend and backend on the same version. Pin a tested version in production and upgrade a test instance first. The documentation has announced the end of support for older versions, so plan regular upgrades.
Scope and handover
Effort depends on the number of playbooks and alert sources, how many custom apps are needed, approval and change requirements, tenant structure for MSSP use, and availability targets. Playbook design and testing usually take longer than building the platform.
DeployOpen runs discovery with your SOC, designs and builds the playbooks and apps, integrates SSO and your security tools, deploys and hardens Shuffle in your environment, and sets up backups and a restore test. Handover includes the playbook catalog with owners, the app repository, credential and encryption key procedures, the test payload library, upgrade runbook and restore test record.
