Quickstart: your first automated runbook in 15 minutes

This guide walks you through creating a Parachute workspace, connecting your alerting tool, and writing your first runbook that automatically isolates an EC2 host on a critical alert.

What you'll need: A Parachute account (free Developer plan is sufficient), an AWS account with IAM permissions, and either a PagerDuty, Datadog, or Opsgenie account to send test alerts.

Step 1: Create a Parachute workspace

Sign up at withparachute.org/login/register.html and create your workspace. Give it a name that matches your team or environment (e.g. "prod-security" or "platform-team").

Each workspace has its own runbooks, integrations, and evidence store. On the Developer plan you get one workspace.

Step 2: Connect your alerting tool

Go to Workspace settings > Integrations and click the integration you want to connect. The setup flow for each tool takes about 2 minutes:

  • PagerDuty: Authorise via OAuth. Select which services send alerts to Parachute.
  • Datadog: Create a webhook in Datadog pointing to your Parachute intake URL. Paste the HMAC secret from the integration setup screen.
  • Opsgenie: Use the Opsgenie integration API key flow. Configure which alert priorities to forward.

Your intake URL is shown on the integration setup screen. It looks like: https://intake.withparachute.org/v1/{workspace_id}/alerts

Step 3: Define your first runbook in YAML

Go to Runbooks > New runbook and select YAML editor. Paste the example below as a starting point.

ec2-brute-force-response.yaml 
name: EC2 Brute Force Response
version: "1.0"
trigger:
  sources: [datadog, pagerduty, opsgenie]
  conditions:
    - alert.tags includes "brute-force"
    - alert.severity in [high, critical]
steps:
  - id: isolate
    action: isolate_host
    target: "{{ alert.host_id }}"
    provider: aws
    method: security_group_swap
    isolation_sg: "{{ workspace.isolation_sg }}"
  - id: collect
    action: pull_logs
    sources: [cloudtrail, vpc_flow_logs]
    window: 60m
    parallel: true
  - id: timeline
    action: draft_timeline
    ai: true
  - id: notify
    action: post_slack
    channel: "{{ workspace.incident_channel }}"
    template: incident_summary
    on_call: true
on_no_match:
  forward_to: "{{ workspace.fallback_channel }}"

Set your workspace variables: Before saving, go to Workspace settings > Variables and define isolation_sg (your AWS quarantine security group ID, e.g. sg-0abc123) and incident_channel (your Slack channel name, e.g. #incidents).

Step 4: Test with a simulated alert

Click Test runbook in the editor toolbar. The test panel lets you craft a simulated alert payload that will run through your runbook in dry-run mode. Dry-run executes every step except the ones that modify real infrastructure (isolate_host, pull_logs are sandboxed; post_slack sends to a test channel).

You should see each step execute and get a pass/fail status. Fix any errors before proceeding.

Step 5: Go live

Click Activate runbook. The runbook is now live. Any alert matching the trigger conditions will execute it automatically.

To verify the live connection, trigger a test alert from your monitoring tool (e.g. a Datadog manual alert, or a PagerDuty test incident). You should see it appear in your Parachute incident feed within seconds.

Runbook action reference

The following actions are available in runbook steps:

  • isolate_host - Isolate a cloud host (AWS, GCP, Azure)
  • pull_logs - Collect logs from cloud providers or SIEMs
  • capture_process_list - Capture running processes via SSM or cloud agent
  • draft_timeline - Generate an AI incident timeline from collected evidence
  • post_slack - Post a notification to a Slack channel
  • create_ticket - Create a Jira or Linear ticket
  • escalate_pagerduty - Create or update a PagerDuty incident
  • http_request - Call any REST endpoint (custom integrations)

Trigger condition syntax

Conditions are evaluated as a conjunction (AND) by default. To use OR logic, group conditions under any::

Trigger with OR conditions 
trigger:
  sources: [datadog]
  any:
    - alert.tags includes "ransomware"
    - alert.tags includes "data-exfil"
    - alert.severity == "critical" and alert.tags includes "ec2"

Key concepts

Workspaces are isolated environments within your Parachute account. Each workspace has its own runbooks, integrations, variables, evidence store, and user access list.

Evidence retention is configurable per workspace. When the retention window expires, evidence artifacts are permanently deleted. Deletion events are logged to your audit trail. The retention window cannot be extended retroactively after evidence has been collected.

Dry-run mode executes all runbook logic except infrastructure-modifying steps. It is the recommended way to test a runbook before activating it on live alerts.

Recent changes

See the documentation home for a list of recently updated pages.

What to read next