SOAR platform migration playbook: move playbooks, integrations and cases safely

A SOAR migration is not an export and import of playbooks: the playbooks are tied to integrations, credentials, data fields and approval habits that differ on every platform, so each automated response has to be rebuilt, re-tested and re-approved before it is allowed to act on production systems again. Teams move security orchestration, automation and response (SOAR) platforms when they consolidate onto a SIEM or XDR suite with built-in automation, change managed security provider, move to a cloud service, or outgrow a platform that has become fragile. This playbook covers the migration itself: what has to move, how to triage the playbook library, translating and testing playbooks, the integration credentials the platform holds, case history, and how to retire the old platform without a gap in response. It is vendor-neutral and draws on the OASIS CACAO Security Playbooks v2.0 specification, NIST SP 800-61 Rev. 3 and the 2025 SIEM and SOAR implementation guidance from the Australian Signals Directorate and partner agencies including CISA. What SOAR does and what to automate first is covered in the SOAR and Security Automation Guide.

Key takeaways

• Migrate outcomes, not code. Rebuild each playbook from a written description of its trigger, decisions and actions; a line-by-line translation carries old workarounds into the new platform.
• Retire before you rebuild. Most libraries hold unused, duplicate and broken playbooks. Use run history to decide what moves.
• Containment actions come back last. Run migrated playbooks in enrichment-only or approval-required mode first, and restore autonomous actions such as host isolation and account disablement only after testing.
• The SOAR is a privileged non-human identity. It holds credentials for the firewall, EDR, identity provider, email and cloud. Issue new, narrower credentials for the new platform and revoke every old one.
• No response gap. Run both platforms in parallel per use case, with one clear owner for each alert type at all times.

What a SOAR migration actually moves

Triage the playbook library

Pull at least 90 days of run history (our recommendation; 12 months if quarterly or annual processes exist) and sort every playbook into one of four outcomes.

For each playbook that moves, write a one-page intent record: trigger, inputs, decision points, actions per tool, approvals, expected outputs, owner and failure handling. That record is the specification the rebuild is tested against, and it outlives the next migration too.

Using CACAO as a neutral format

OASIS CACAO Security Playbooks Version 2.0 (Committee Specification 01, 27 November 2023) defines a vendor-neutral JSON format for playbooks, with typed workflow steps (action, parallel, if-condition, while-condition, switch-condition and nested playbook steps), commands, agents and targets, authentication information held separately from agents and targets, data markings and optional digital signatures. Even where neither platform imports CACAO directly, writing intent records in CACAO terms gives a structure that separates logic from platform-specific connectors, and the specification notes that playbooks run in a new environment may need local adjustments for authentication and authorisation. See the OASIS CACAO Security Playbooks Standard Guide.

Testing migrated playbooks

The 2025 joint practitioner guidance on implementing SIEM and SOAR warns that a poorly configured SOAR may mistake normal user or system behaviour for an incident and take automated isolation measures that disrupt services, and recommends regular exercises to confirm the SOAR handles alerts as intended. Build that into the migration as promotion stages:

1. Replay: run the rebuilt playbook against recorded alerts from the old platform in a test environment and compare decisions with what the old playbook did.
2. Shadow: run it on live alerts with all write actions disabled; it enriches and recommends but changes nothing.
3. Approval required: enable actions behind a human approval step, and track how often analysts approve, modify or reject the proposed action.
4. Autonomous: only for actions with a high approval rate, a low blast radius and a tested reversal, such as blocking a known-bad hash or quarantining an email.

Keep high-impact actions (disabling privileged accounts, isolating servers, blocking network ranges, deleting mailbox content) behind approval in the new platform, whatever the old platform did. Test each one with a purple team exercise against known techniques before promotion. Approval gates and what to automate are in the SOAR and Security Automation Guide.

Choosing the target model

Many SOAR migrations are really a decision about where automation should live. The choice changes what has to be rebuilt.

The joint SIEM and SOAR guidance notes that SOAR is usually unsuited to immature environments and that effective SIEM log analysis generally comes first, and recommends a proof of concept with a defined scope before committing to a platform. If detection quality is the real problem, fix it before moving automation, because a new platform will automate the same noise. When a managed provider will run the target platform, treat its access as third-party access: record which actions it may take without asking, and keep the ability to revoke its credentials yourself.

Case history and evidence

• Finish, do not move, most open cases: set a date after which new cases open only on the target, and let old cases close where they started.
• Export closed cases with their evidence: timeline, artefacts, analyst notes and approvals, in a read-only archive that investigators can search.
• Check legal holds first: cases under legal hold or regulator enquiry must keep their chain of custody; agree the export method with legal before decommissioning.
• Keep the retention clock: archived history keeps the retention period it had on the old platform (NIST SP 800-53 AU-11).

Where identity fits

A SOAR platform authenticates to almost every security and IT system so that it can enrich and act. That makes it a concentrated store of privileged non-human credentials, and a migration is the best chance to shrink it.

• Inventory every integration credential: API keys, OAuth clients, service accounts, cloud roles, SSH keys and certificates, with the scope each one actually has and the actions the playbooks actually use.
• Issue new credentials scoped to used actions: if playbooks only read from a tool and isolate hosts, the new credential should not also be able to change policies (NIST SP 800-53 AC-6, least privilege). Prefer federated or short-lived credentials over static keys (IA-5).
• Keep secrets out of playbooks and scripts: store them in the platform's credential store or an external secrets manager; scan migrated code for embedded secrets.
• Separate playbook authors from approvers: the person who can edit a containment playbook should not be its only approver in production (AC-5).
• Revoke old credentials per wave: once a use case has moved, revoke the old platform's credentials for those tools rather than waiting for decommissioning.

Credential design for connectors is in the SOAR platform integration security guide, and hardening the platform itself in Securing the SOAR platform itself. The wider practice for these accounts is in the Service Account Security Guide.

The phased playbook

1. Baseline: record current metrics (alert volume handled automatically, mean time to acknowledge and contain per use case, playbook failure rate) so the new platform can be compared fairly.
2. Inventory and triage: list playbooks, integrations, credentials, scripts and open cases; retire, replace, rebuild or redesign each playbook.
3. Define the target data model: incident types, severity, fields and indicator types, aligned with the SIEM or XDR feeding the platform. Map every rebuilt playbook to it.
4. Build integrations: connect each tool with new scoped credentials; test read actions first, write actions second, in a non-production tenant where the tool has one.
5. Migrate by use case: move one alert type at a time (for example phishing triage first, then malware alerts, then identity alerts), through replay, shadow, approval and autonomous stages.
6. Cut over alert routing per use case: route that alert type to the new platform and switch the old playbook off in the same change. Never let both act on the same alert.
7. Close down the old platform: finish or transfer open cases, export and archive case history, revoke credentials, remove its network access and delete stored secrets.
8. Review: compare metrics with the baseline after a full month of operation and record lessons as an input to incident response improvement, which NIST SP 800-61 Rev. 3 frames through the CSF 2.0 Improvement category.

Rollback: until the old platform is closed down, rollback for a use case means routing its alerts back and re-enabling the old playbook; keep the old platform's credentials for that use case valid until the new playbook has run cleanly for an agreed period (our recommendation: 30 days). Small teams with a handful of playbooks can often replace them with native automation in their SIEM or XDR and skip a rebuild; large SOCs and MSSPs need the use-case wave model, a data model owner and formal promotion stages.

Detection and measurement

Log every automated action in the new platform with the playbook, version, triggering alert, approver and target, and send those logs to the SIEM. Alert on playbook edits outside change control and on integration credentials used from outside the platform (NIST SP 800-53 AU-2, CM-3).

Common failure patterns

• Lift and shift of the whole library: hundreds of dead playbooks rebuilt at great cost, while the few that matter get less testing.
• Both platforms acting: an alert type routed to both, so a host is isolated twice or an account is disabled by one platform and re-enabled by another.
• Silent mapping gaps: a field name differs in the new data model, a condition never matches, and the playbook quietly stops containing anything.
• Copied god-mode credentials: the old platform's broad admin keys reused in the new one, then left valid in the old one too.
• Autonomous actions on day one: containment enabled before shadow testing, causing an outage on the first false positive.
• Case history abandoned: evidence for an open investigation or legal hold left in a platform that is later switched off.

Framework mapping

Practitioner checklist

• Baseline response metrics before migration starts.
• Triage every playbook from run history: retire, replace, rebuild or redesign.
• Write an intent record per migrating playbook and test the rebuild against it.
• Define the target data model before mapping fields.
• Issue new, narrowly scoped integration credentials; never copy old secrets.
• Promote playbooks through replay, shadow, approval-required and autonomous stages.
• Keep high-impact containment actions behind human approval.
• Give every alert type exactly one owning platform, switched in one change.
• Archive closed case history and preserve legal holds before closing the old platform.
• Revoke all old platform credentials and remove its network access.

Standards and references

• OASIS: CACAO Security Playbooks Version 2.0
• NIST: SP 800-61 Rev. 3, Incident Response Recommendations and Considerations for Cybersecurity Risk Management
• ASD ACSC and partners: Implementing SIEM and SOAR Platforms, Practitioner Guidance
• CISA: Guidance for SIEM and SOAR Implementation
• NIST: SP 800-53 Rev 5, Security and Privacy Controls
• NIST: Cybersecurity Framework 2.0

Related NHI Mgmt Group resources: SOAR and Security Automation Guide · SOAR platform rollout playbook · SIEM Migration Guide · SOAR platform day-2 operations runbook