FortiSOAR playbooks automate security workflows across Fortinet and third-party systems through triggers, decisions, connectors, records, blocks, variables, and human interaction. Current FortiSOAR 8.0 design guidance emphasizes starting with a trigger, gating execution through decisions, grouping related logic in blocks, using reference blocks for reusable workflows, and choosing logging levels that support production operations without filling storage with unnecessary debug data.
Within Fortinet Security Operations, playbook design is the automation boundary between detection and action. The most important design decision is not how many steps can be automated, but which actions are deterministic enough to repeat safely and which still require human judgment.
The existing SOAR playbooks: where automation should stop article provides the broader governance model.
Every playbook should have one clear trigger contract
Triggers can come from record creation/update, schedules, manual execution, ingestion, or another automation path depending on the workflow.
The trigger should define exactly which incident, alert, indicator, or case state the playbook expects.
A broad trigger that launches remediation for every new alert pushes complexity into later steps and can create unnecessary connector traffic.
Use an early decision to reject out-of-scope records
Current FortiSOAR guidance recommends placing a decision step immediately after the trigger.
This keeps the expensive part of the workflow from running when required fields are missing, severity is too low, the source is excluded, or the case is already handled.
Early gating makes playbook intent easier to inspect and reduces side effects during testing.
Separate enrichment from remediation
Enrichment steps gather evidence: reputation, asset owner, vulnerability context, identity information, network history, or threat intelligence.
Remediation steps change state: block IP, disable account, isolate endpoint, close alert, or modify firewall policy.
Keep these phases logically separate so analysts can inspect evidence before a high-impact action and so enrichment failures do not automatically trigger remediation.
Reusable reference blocks reduce duplicated logic
FortiSOAR supports reference blocks that can be reused in other playbooks.
Common actions such as indicator enrichment, notification, account disablement, or firewall blocking can be standardized once.
Version and test these blocks carefully because one shared change can alter many response playbooks at once.
Connector errors should have explicit recovery paths
External systems fail, throttle, change APIs, and return partial data.
Design each connector step with expected timeout, retry, authentication-failure, not-found, and service-unavailable behavior.
Do not loop indefinitely on a permanent authorization error or treat a temporary API timeout as evidence that the indicator is benign.
Idempotency matters for every side effect
A playbook may be retried after timeout or recovered after partial failure.
Actions such as adding a firewall block, disabling an account, or creating a ticket should detect whether the intended state already exists.
Replay-safe automation prevents duplicate cases, repeated notifications, and conflicting control objects during incident recovery.
Human approval should be placed before irreversible action
FortiSOAR can automate human-in-the-loop decisions inside a playbook.
Use approval when evidence is ambiguous, the action has high business impact, or the affected identity/resource has special criticality.
The approval request should include enough context that the analyst can decide without leaving FortiSOAR to reconstruct the case manually.
Production logging should be informative without becoming excessive
Current FortiSOAR guidance recommends INFO as a normal production logging level and DEBUG for development/troubleshooting, with failed playbooks capturing richer diagnostic information.
Debug output can include variables and step details and can consume significant storage.
Log the identifiers, branch decisions, connector status, and action results needed for audit while protecting credentials and sensitive payloads.
Playbook recovery should preserve completed safe work
FortiSOAR includes playbook recovery concepts for failed execution.
A recovery strategy should know which steps can be resumed, which need revalidation, and which actions must not be repeated.
Designing recovery after a 60-step response playbook already exists is much harder than making each block restart-aware from the beginning.
Testing should use representative failure as well as success cases
Create test records for missing fields, connector timeout, malicious/benign ambiguity, duplicate indicators, high-value users, and failed remediation.
Verify branch behavior and side effects before enabling automatic production triggers.
A playbook that works only on the ideal sample alert is not ready for SOC automation.
Playbook design succeeds when automation remains explainable and reversible
The mature FortiSOAR workflow shows why it started, which evidence it collected, which decision branch it took, which external actions succeeded, what remains for an analyst, and how recovery behaves after failure.
Automation should make incident response faster and more consistent without turning response authority into hidden connector side effects.
Playbook collections should mirror how the SOC thinks about reusable capability. Current FortiSOAR guidance recommends separating integration-specific building blocks, generic actions such as enrichment/remediation, and higher-level response plans. That structure keeps one vendor connector change from forcing analysts to edit every incident workflow directly.
Dynamic values should be treated like typed inputs even though the platform passes them flexibly. Validate that required fields exist, normalize IP/domain/hash formats, and guard against unexpected nulls before a connector receives them. Many automation failures are data-shape problems rather than connector outages.
Case and record updates should be intentional. A playbook can create records, add notes, change status, and assign owners. Define which updates are authoritative and which are temporary enrichment so concurrent analyst work is not overwritten by automation.
Connector credentials should use least privilege. A FortiGate connector used only to add an address to a quarantine group should not have unrestricted administrative permission across every device. Separate connector accounts by function when one broad account would create unnecessary blast radius.
Rate limiting and concurrency should be considered for bulk incidents. A phishing campaign or malware outbreak can trigger hundreds of cases simultaneously, causing playbooks to hammer threat-intelligence APIs, firewalls, ticketing systems, or identity platforms. Queueing and deduplication protect both FortiSOAR and downstream services.
Reusable blocks should have change control because they are effectively shared libraries. Test new versions against dependent playbooks and document behavior changes before replacing a commonly referenced block. Shared automation can propagate one bug to many response plans faster than a human analyst ever could.
Metrics should include automation quality, not only time saved. Track successful completion, human intervention rate, rollback frequency, connector-error rate, false containment, and time to recovery from playbook failure. A fast automation that frequently needs repair can increase SOC risk despite reducing clicks.
Playbook ownership should remain with the response process, not solely the SOAR platform team. The incident-response owner defines when containment is appropriate, while the automation team implements and maintains the workflow. This keeps business/security judgment connected to the code that acts on it.
Playbook inputs and outputs should be documented like APIs. A reusable enrichment block might require indicator.value and return reputation fields; a containment block might require asset ID and approval state. Clear contracts make composition easier and reduce hidden assumptions between collections.
Secrets used by connectors should be rotated without breaking playbooks. Use FortiSOAR credential-management mechanisms and test connector reauthentication before production rotation. Hard-coded credentials inside dynamic values or scripts turn automation into a secret-distribution problem.
Content Hub updates should be treated like dependency upgrades. Vendor-provided connectors and playbooks can improve over time, but local customizations, field mappings, and behavior may differ. Review changelogs, test in a nonproduction environment, and preserve a rollback path before replacing widely used content.
Human steps should have timeout and escalation behavior. An approval that waits forever can stall incident containment just as badly as a broken connector. Define who receives the request, how long it can wait, who is escalated next, and what the playbook does if no decision arrives.
Automation should stop at a known safe state during uncertainty. If enrichment sources disagree or required context is unavailable, route the case to an analyst with evidence rather than guessing which remediation branch is correct. The playbookâs value includes consistent handoff, not only fully automated closure.
Production rollout should be staged. Start with manual invocation or observation-only enrichment, then enable automated case updates, and only later enable containment when the workflow has enough successful evidence. This lets analysts build trust in the automation and exposes edge cases before side effects become automatic.
Playbooks should also support decommissioning. When an integration, detection source, or incident process is retired, disable triggers, remove unused credentials, archive necessary execution evidence, and identify dependent playbooks or reference blocks. Old automation left active can fire unexpectedly against changed systems.
FortiSOAR is most effective when playbooks encode mature response practice: clear trigger, bounded decision logic, reusable enrichment, controlled side effects, human authority where needed, replay-safe recovery, and telemetry that shows whether automation improved the incident outcome.
Playbook documentation should name the business/security owner for every high-impact action. The SOAR team may maintain the connector and workflow, but identity disablement, host isolation, firewall blocking, or destructive remediation should still have an accountable policy owner who defines when the action is permitted and what evidence is required.
Treat playbook changes as production code changes with tests, review, and rollback.
Keep automation bounded by explicit operational authority and evidence.
Continuously.
A mature playbook also exposes its stop conditions. Analysts should be able to see which steps are safe to automate, where human approval is mandatory, what evidence is collected, and how partial execution is unwound when an upstream assumption proves wrong.
