@query-ai/digital-workers 1.0.0

package/skills/templates/runbook-template.md

@@ -0,0 +1,300 @@
+---
+name: [your-org]-[runbook-name]
+description: Use when [specific trigger condition -- e.g., "VPN alerts fire from contractor accounts"]
+---
+
+# [Runbook Name]
+
+> **How to use this template:**
+> 1. Copy this file into a new skill folder: `skills/<your-org>-<runbook-name>/SKILL.md`
+> 2. Rename the skill in the YAML frontmatter (e.g., `name: acme-vpn-investigation`)
+> 3. Write a `description` that tells the framework exactly when to invoke this runbook
+> 4. Fill in every section below -- the examples show the level of detail you should aim for
+> 5. Reference this runbook in your org-policy under **Custom Investigation Runbooks**
+>
+> Delete all example/placeholder content before deploying. Keep only what applies
+> to your investigation type.
+
+---
+
+## Iron Law
+
+<!-- State the ONE non-negotiable rule for this investigation type. -->
+<!-- This is the constraint the framework must never violate, no matter what. -->
+<!-- Keep it short, memorable, and uppercase. -->
+
+```
+NEVER [action that must never happen] WITHOUT [safeguard that must always be performed].
+```
+
+**Examples for inspiration (delete these):**
+
+- `NEVER CLOSE A VPN ALERT WITHOUT CHECKING THE CONTRACTOR SCHEDULE.`
+- `NEVER MARK A PRIVILEGE ESCALATION AS BENIGN WITHOUT VERIFYING THE CHANGE TICKET.`
+- `NEVER DISMISS A DATA EXFILTRATION ALERT WITHOUT CONFIRMING VOLUME IS BELOW 50 MB.`
+
+---
+
+## When to Invoke
+
+This runbook is called by `alert-investigation` at **Gate 4** (Decide & Act) during
+DEEP investigations when the following conditions are met:
+
+### Trigger Conditions
+
+<!-- All conditions must be true for this runbook to activate. -->
+
+| Condition | Match Value |
+|-----------|-------------|
+| Alert type (from alert-classifier) | `[e.g., Identity/Access]` |
+| Alert source / connector | `[e.g., okta, crowdstrike]` |
+| Additional condition | `[e.g., user is in "contractors" group]` |
+| Additional condition | `[e.g., source country is not in approved-countries list]` |
+
+### Example Trigger Scenario
+
+<!-- Describe a concrete scenario where this runbook fires. -->
+<!-- This helps analysts understand the intent. -->
+
+> An Okta alert fires for a failed MFA challenge followed by a successful login
+> from a new device. The user belongs to the "contractors" group. The login
+> originates from a country not on the approved-countries list. The framework
+> invokes this runbook because all three conditions match: Identity/Access alert
+> type, Okta source, and contractor user from an unapproved location.
+
+---
+
+## Prerequisites
+
+### Required Data Sources
+
+<!-- List every data source this runbook queries. -->
+<!-- If a source is missing, the runbook should fail gracefully, not silently skip steps. -->
+
+| Data Source | Purpose | Required? |
+|-------------|---------|-----------|
+| `[e.g., okta_logs]` | Authentication events, MFA status | Yes |
+| `[e.g., crowdstrike_detections]` | Endpoint activity post-login | Yes |
+| `[e.g., hrms_contractor_schedule]` | Validate contractor active dates | Yes |
+| `[e.g., geo_ip_enrichment]` | Resolve login source location | Recommended |
+
+### Org-Specific Knowledge
+
+<!-- List any internal knowledge this runbook depends on. -->
+<!-- These are things the framework cannot discover from data alone. -->
+
+- **Contractor schedule source:** Where to find the current contractor roster and active engagement dates (e.g., HRMS export, SharePoint list, ServiceNow table).
+- **Approved countries list:** Which countries are authorized for remote access by contractors (e.g., US, CA, GB, DE).
+- **VPN gateway mapping:** Which VPN concentrators serve which office locations or contractor pools.
+- **Escalation contacts:** Names or on-call rotations for the teams listed in the Escalation section.
+
+---
+
+## Context
+
+<!-- Provide the background an analyst needs to understand WHY this investigation type -->
+<!-- matters and WHAT to expect. This section trains the framework on domain knowledge -->
+<!-- that is not available in the alert data itself. -->
+
+### Why This Matters
+
+[Explain the business risk. Why does your organization care about this specific
+alert pattern? What is the worst-case outcome if it is missed?]
+
+**Example (delete this):**
+
+> Contractor accounts have elevated risk because they are often provisioned with
+> broad access for short engagements, rarely monitored after the engagement ends,
+> and targeted by adversaries who know that contractor credentials receive less
+> scrutiny. A compromised contractor VPN session can provide an attacker with
+> persistent access to internal networks without triggering the usual employee-focused
+> detections.
+
+### Common Scenarios
+
+<!-- List the 3-5 most common reasons this alert fires. -->
+<!-- Include both malicious and benign scenarios so the framework calibrates correctly. -->
+
+1. **Benign -- travel:** Contractor is traveling and logs in from a hotel in a country not on the approved list. MFA succeeds on second attempt after typo.
+2. **Benign -- schedule mismatch:** Contractor's engagement was extended but the schedule was not updated. Alert fires because the contractor appears inactive.
+3. **Suspicious -- credential stuffing:** Attacker uses stolen contractor credentials from a third-party breach. Multiple failed MFA attempts followed by a successful bypass.
+4. **Malicious -- session hijacking:** Attacker intercepts a valid session token and replays it from a different geographic location within minutes of the legitimate login.
+
+### What to Watch For
+
+<!-- Key indicators that shift the investigation from benign toward malicious. -->
+
+- Time gap between failed and successful authentication is under 2 minutes (suggests automated tooling, not a human retyping)
+- Login location is > 500 miles from the contractor's registered home location AND no travel request is on file
+- Post-login activity includes access to systems outside the contractor's documented scope of work
+- The contractor account was supposed to be deactivated more than 7 days ago
+
+---
+
+## Investigation Steps
+
+<!-- Numbered steps the framework follows. Each step should include: -->
+<!--   1. What to do (the query or action) -->
+<!--   2. What to look for in the results -->
+<!--   3. Decision point: what happens based on findings -->
+<!-- -->
+<!-- Use FSQL query patterns wherever possible. The framework executes these directly. -->
+
+### Step 1: Pull the Alert and Confirm Trigger Conditions
+
+Run the initial alert query to retrieve the full alert record and confirm this
+runbook's trigger conditions are actually met.
+
+```fsql
+-- Pull the triggering alert with full detail
+SELECT *
+FROM alerts
+WHERE alert_id = '{alert_id}'
+```
+
+**What to look for:**
+- Confirm alert type matches `[your alert type]`
+- Confirm source connector matches `[your connector]`
+- Extract the `user_id`, `source_ip`, `timestamp`, and `session_id` for use in subsequent steps
+
+**Decision point:**
+- If the trigger conditions are NOT met (e.g., user is not a contractor), stop and return to the standard investigation flow.
+- If conditions are met, continue to Step 2.
+
+### Step 2: Establish the User's Authentication Baseline
+
+Query the user's authentication history to understand what "normal" looks like
+for this account.
+
+```fsql
+-- 14-day authentication baseline for the user
+SELECT timestamp, source_ip, geo_country, geo_city, user_agent, mfa_status, outcome
+FROM [auth_source]
+WHERE user_id = '{user_id}'
+  AND timestamp > ago(14d)
+ORDER BY timestamp DESC
+```
+
+**What to look for:**
+- Typical login times (business hours vs. off-hours)
+- Usual source countries and cities
+- Consistent user-agent strings (browser/OS)
+- MFA success rate (frequent failures may indicate shared credentials)
+- Any previous logins from the same `source_ip` as the alert
+
+**Decision point:**
+- If the alert's source IP, location, and user-agent are consistent with the baseline, lower suspicion and continue to Step 3 for schedule verification.
+- If the alert's source IP or location has never been seen before for this user, raise suspicion and flag for deeper inspection in Step 3.
+
+### Step 3: Verify Against the Contractor Schedule
+
+Check whether the contractor is currently authorized to be active.
+
+```fsql
+-- Check contractor engagement status
+SELECT user_id, contractor_name, engagement_start, engagement_end, status, manager
+FROM [contractor_schedule_source]
+WHERE user_id = '{user_id}'
+ORDER BY engagement_end DESC
+LIMIT 1
+```
+
+**What to look for:**
+- Is `engagement_end` in the past? If so, how long ago?
+- Is `status` set to "active" or has it been changed to "terminated" / "suspended"?
+- Who is the listed `manager`? (needed for escalation)
+
+**Decision point:**
+- If the contractor is active and within their engagement window, continue to Step 4.
+- If the engagement ended within the last 7 days, this may be a schedule update lag -- flag as **suspicious** and continue to Step 4.
+- If the engagement ended more than 7 days ago, flag as **high suspicion** -- the account should have been deactivated. Continue to Step 4 with elevated urgency.
+
+### Step 4: Examine Post-Login Activity
+
+Query endpoint and application logs to see what happened AFTER the authenticated
+session began.
+
+```fsql
+-- Post-login activity within 1 hour of the alert
+SELECT timestamp, event_type, target_resource, action, outcome, source_ip
+FROM [activity_source]
+WHERE user_id = '{user_id}'
+  AND timestamp BETWEEN '{alert_timestamp}' AND dateadd('{alert_timestamp}', 1h)
+ORDER BY timestamp ASC
+```
+
+**What to look for:**
+- Access to resources outside the contractor's documented scope of work
+- Reconnaissance patterns: listing users, groups, shares, or permissions
+- Data access or download volume exceeding normal patterns
+- Lateral movement: connections to internal systems the contractor does not typically access
+- Any attempt to modify account permissions or create new accounts
+
+**Decision point:**
+- If post-login activity is consistent with the contractor's normal work, proceed to the Decision Matrix with **low suspicion**.
+- If post-login activity includes out-of-scope access or reconnaissance, proceed with **high suspicion**.
+- If post-login activity includes data exfiltration or lateral movement, proceed with **critical suspicion** and recommend immediate session termination.
+
+---
+
+## Decision Matrix
+
+<!-- Map combinations of findings to dispositions and recommended actions. -->
+<!-- The framework uses this table to determine its proposed disposition. -->
+
+| Schedule Status | Login Location | Post-Login Activity | Suspicion | Proposed Disposition | Recommended Action |
+|-----------------|---------------|---------------------|-----------|---------------------|--------------------|
+| Active | Known/approved | Normal, in-scope | Low | **Benign Activity** | Close. Document baseline confirmation. |
+| Active | New but plausible | Normal, in-scope | Low-Medium | **Benign Activity** | Close. Note new location for baseline update. |
+| Active | Unapproved country | Normal, in-scope | Medium | **Policy Violation** | Notify contractor manager. Review access policy. |
+| Active | Any | Out-of-scope access | High | **Critical Threat** | Suspend session. Escalate to IR. |
+| Expired (<7 days) | Any | Any | Medium-High | **Policy Violation** | Disable account. Notify IT and contractor manager. Audit recent activity. |
+| Expired (>7 days) | Any | Any | High | **Critical Threat** | Disable account immediately. Escalate to IR. Full forensic review. |
+| Any | Impossible travel | Any | High | **Critical Threat** | Suspend session. Escalate to IR. Assume credential compromise. |
+| Any | Any | Lateral movement or data exfiltration | Critical | **Critical Threat** | Terminate session. Isolate endpoint. Invoke incident response. |
+
+---
+
+## Escalation
+
+<!-- Define who to contact for each escalation condition. -->
+<!-- Use role names or on-call rotation names, not individual names (people change). -->
+
+| Condition | Escalate To | Method | SLA |
+|-----------|-------------|--------|-----|
+| Credential compromise confirmed | IR On-Call | PagerDuty | 15 minutes |
+| Contractor account active past engagement end | IT Identity Team | Slack #identity-ops | 1 hour |
+| Policy violation (unapproved country) | Contractor's Manager + Security Governance | Email | 4 hours |
+| Lateral movement or data exfiltration | IR On-Call + CISO | PagerDuty + Phone | Immediate |
+| Schedule data unavailable (cannot verify) | SOC Lead | Slack #soc-escalations | 1 hour |
+
+> **Note:** If you cannot reach the escalation target within the SLA, escalate to
+> the next level up. Never let an unresolved critical finding sit without an owner.
+
+---
+
+## Red Flags
+
+<!-- Common mistakes, shortcuts, or assumptions that lead to bad outcomes -->
+<!-- for this specific investigation type. These are guardrails for the framework -->
+<!-- and for human analysts reviewing the output. -->
+
+1. **Trusting the schedule alone.** A contractor marked "active" in the schedule may still be compromised. Schedule status tells you whether the account *should* exist, not whether the *current session* is legitimate. Always complete the post-login activity check (Step 4).
+
+2. **Ignoring "benign" logins from new locations.** Contractor travel is common, but it is also the easiest cover story for a compromised credential. If the location is new AND the contractor has no travel on file, treat it as suspicious until verified.
+
+3. **Closing on MFA success alone.** MFA is not proof of identity. Session hijacking, SIM swapping, and MFA fatigue attacks all produce successful MFA events. Look at the full authentication sequence, not just the outcome.
+
+4. **Skipping the post-login activity check for "low severity" alerts.** The alert severity reflects what the detection tool thinks. Your runbook exists because your organization knows this alert pattern carries risk that the detection tool underweights. Always run Step 4.
+
+5. **Assuming deactivated accounts are harmless.** An account that should have been deactivated but was not is a high-value target for attackers. Treat active sessions on expired accounts as critical, not as an IT hygiene issue.
+
+---
+
+## Revision History
+
+<!-- Track changes to this runbook so analysts know when procedures were last updated. -->
+
+| Date | Author | Change |
+|------|--------|--------|
+| YYYY-MM-DD | [your name] | Initial version |