Runbook Executor

Instructions

When asked to execute a runbook and document evidence:

1. Run the evidence creation script: ./runbook-executor/scripts/create-evidence.sh <runbook-path>
2. Follow the runbook steps in <runbook-path>/STEPS.md
3. Document each step's execution in the generated evidence file
4. Capture actual commands, outputs, and results
5. Note any deviations or issues encountered
6. Complete all validation sections
7. Add screenshots or logs to the evidence directory if needed
8. Write the conclusion with overall assessment

When asked to review past executions:

1. Run the list script: ./runbook-executor/scripts/list-evidence.sh <runbook-path>
2. Review the list of executions ordered by date (newest first)
3. Open the relevant result.md file from the desired timestamp

Examples

Execute a runbook and create evidence:

./runbook-executor/scripts/create-evidence.sh runbooks/user-login-flow

Execute an API testing runbook:

./runbook-executor/scripts/create-evidence.sh runbooks/api-payment-flow

List all evidence executions for a runbook (newest first):

./runbook-executor/scripts/list-evidence.sh runbooks/user-login-flow

HTTP Requests in Runbooks

When a runbook contains HTTP requests that can be executed locally, create scripts using httpie to automate the requests and save responses for evidence.

Important: All scripts must be executed under supervision. Review each script before execution and verify the target endpoints are correct for your environment.

Structure for HTTP Scripts

<runbook-path>/
├── STEPS.md
├── scripts/
│   ├── activation.sh        # Environment setup and aliases
│   ├── .env                  # Secrets (git-ignored)
│   ├── .env.example          # Example configuration
│   ├── login.httpie.sh
│   ├── get-user.httpie.sh
│   └── responses/
│       ├── 1738500000-login.httpie.http
│       └── 1738500100-get-user.httpie.http
└── evidence/

Activation Script

The activation.sh script sets up the environment for HTTP scripts:

1. Loads environment variables from .env file (for secrets)
2. Creates the script-http function that wraps httpie and saves responses automatically

Usage

# First, activate the environment
source ./scripts/activation.sh

# Then run your scripts
./scripts/login.httpie.sh

Configuration with .env

Create a .env file for secrets (copy from .env.example):

cp .env.example .env

Example .env:

API_BASE_URL=https://api.example.com
API_USERNAME=your-username
API_PASSWORD=your-password
API_TOKEN=your-bearer-token

Script Requirements

Each httpie script should:

1. Use script-http instead of http directly
2. Use environment variables for secrets and configuration
3. Include a comment indicating to run source ./activation.sh first

Naming Convention

Response files follow this pattern:

<unix-timestamp>-<endpoint-name>.httpie.http

Examples:

• 1738500000-login.httpie.http
• 1738500100-get-users.httpie.http
• 1738500200-create-order.httpie.http

Example Script

#!/bin/bash
# Login API request using httpie
# Usage: source ./activation.sh && ./login.httpie.sh

set -e

BASE_URL="${API_BASE_URL:-https://api.example.com}"

script-http POST "$BASE_URL/login" \
    username="${API_USERNAME:[email protected]}" \
    password="${API_PASSWORD:-secret123}"

Common httpie Commands

# GET request
http GET https://api.example.com/users -v

# POST with JSON body
http POST https://api.example.com/login username=user password=pass -v

# POST with custom headers
http POST https://api.example.com/data \
    Authorization:"Bearer token123" \
    -v

# PUT request
http PUT https://api.example.com/users/1 name="Updated Name" -v

# DELETE request
http DELETE https://api.example.com/users/1 -v

STEPS.md Integration

When documenting HTTP steps in STEPS.md, reference the activation and scripts:

## Step 1: Activate environment

\`\`\`bash
source ./scripts/activation.sh
\`\`\`

## Step 2: Authenticate with API

Execute the login script to authenticate:

\`\`\`bash
./scripts/login.httpie.sh
\`\`\`

Expected response: HTTP 200 with JWT token in response body.
Response saved to: `scripts/responses/<timestamp>-login.httpie.http`

Resources

• Template: assets/evidence-template.md
• Creation script: scripts/create-evidence.sh
• List script: scripts/list-evidence.sh
• Example httpie script: scripts/login.httpie.sh