@query-ai/digital-workers 1.0.0

package/skills/templates/org-policy-template.md

@@ -0,0 +1,516 @@
+---
+name: org-policy
+description: Organization-specific policy — loaded automatically by alert-investigation at every gate to customize thresholds, criteria, and behavior
+---
+
+# Organization Policy
+
+> **How to use this template:**
+> 1. Copy this file into a new skill folder: `skills/<your-org>-org-policy/SKILL.md`
+> 2. Rename the skill in the YAML frontmatter (e.g., `name: acme-org-policy`)
+> 3. Customize the sections below to match your organization's security posture
+> 4. Any section you leave unchanged uses the built-in defaults shown here
+> 5. The `alert-investigation` skill reads this automatically at every gate
+>
+> You do not need to include every section. Delete sections you don't need to
+> customize -- the framework's built-in defaults will apply for anything missing.
+
+---
+
+## Alert Scope (Gate 1)
+
+These settings control which alerts the framework pulls during intake.
+
+### Severity Filter
+
+<!-- Which alert severities to pull. Remove levels you do NOT want investigated. -->
+<!-- Options: INFO, LOW, MEDIUM, HIGH, CRITICAL, FATAL -->
+
+```
+severity_filter:
+  - HIGH
+  - CRITICAL
+  - FATAL
+```
+
+### Time Range
+
+<!-- How far back to look for new alerts during intake. -->
+<!-- This is the default window; analysts can override per-investigation. -->
+
+```
+intake_time_range: 24h
+```
+
+### Connector Scope
+
+<!-- Which data connectors to pull alerts from. -->
+<!-- Use "all" to query every connected source, or list specific connectors. -->
+
+```
+connector_scope: all
+
+# To limit to specific connectors, replace "all" with a list:
+# connector_scope:
+#   - crowdstrike
+#   - sentinel
+#   - okta
+```
+
+---
+
+## Severity Weights (Gate 3)
+
+These weights control how the five scoring dimensions combine into the composite
+severity score that determines investigation depth.
+
+### Dimension Weights
+
+<!-- All five weights MUST add up to 1.0 -->
+<!-- Increase a weight to make that dimension matter more in routing decisions. -->
+
+```
+weights:
+  alert_severity:   0.20    # Raw severity from the detection tool
+  asset_criticality: 0.25   # How important the affected system is
+  business_impact:   0.25   # Potential harm to the organization
+  confidence:        0.15   # Quality and corroboration of evidence
+  threat_context:    0.15   # Threat intelligence relevance
+```
+
+**Examples of common adjustments:**
+
+- Heavily regulated environment (healthcare, finance): increase `business_impact` to 0.30, reduce `threat_context` to 0.10
+- Environment with noisy detection tools: increase `confidence` to 0.25, reduce `alert_severity` to 0.10
+- Organization frequently targeted by APTs: increase `threat_context` to 0.25, reduce `confidence` to 0.10
+
+### Depth Routing Thresholds
+
+<!-- Composite score ranges that determine investigation depth. -->
+<!-- Adjust these to make the framework more or less aggressive. -->
+
+```
+depth_routing:
+  auto_close:  1.0 - 1.9   # Low-risk alerts: document and close
+  standard:    2.0 - 2.9   # Moderate-risk: standard investigation with verdict
+  deep:        3.0 - 5.0   # High-risk: full specialist investigation
+```
+
+**Common adjustments:**
+
+- More aggressive (investigate more): change standard to `1.5 - 2.4` and deep to `2.5 - 5.0`
+- More conservative (close more): change auto\_close to `1.0 - 2.2` and standard to `2.3 - 3.2`
+
+### Override Rules
+
+<!-- Conditions that ALWAYS force DEEP investigation, regardless of composite score. -->
+<!-- These exist because certain patterns are too dangerous to under-investigate. -->
+<!-- Comment out any overrides you want to disable. Add custom ones as needed. -->
+
+```
+force_deep_overrides:
+  - lateral_movement_detected
+  - persistence_mechanism_discovered
+  - credential_compromise_indicators
+  - data_exfiltration_signals
+  - multiple_correlated_alerts_same_actor
+  - novel_unseen_technique
+
+# Add your own override rules:
+#   - vpn_from_sanctioned_country
+#   - service_account_interactive_login
+#   - access_to_pci_zone_after_hours
+```
+
+---
+
+## Crown Jewels / Asset Criticality (Gate 3)
+
+Define your organization's critical and high-value assets. The severity scorer
+uses this list to assign the Asset Criticality dimension score. Assets not listed
+here are scored by inference from hostname, IP range, and system role.
+
+### Critical Assets (score 5/5)
+
+<!-- These are your "crown jewels" -- compromise of any of these is a top-priority event. -->
+<!-- Use hostname patterns, IP ranges, or descriptions. -->
+
+```
+critical_assets:
+
+  # --- Hostname patterns (supports wildcards) ---
+  - pattern: "dc-*.corp.example.com"
+    description: "Domain controllers"
+
+  - pattern: "ca-*.corp.example.com"
+    description: "Certificate authority servers"
+
+  - pattern: "prod-db-*.example.com"
+    description: "Production customer databases"
+
+  - pattern: "vault-*.example.com"
+    description: "Secrets management / key vaults"
+
+  # --- IP ranges ---
+  - range: "10.1.100.0/24"
+    description: "PCI cardholder data environment"
+
+  - range: "10.2.50.0/28"
+    description: "Core banking systems"
+
+  # --- Named systems ---
+  - name: "FINANCIALS-PROD-01"
+    description: "ERP / financial reporting system"
+```
+
+### High-Value Assets (score 4/5)
+
+<!-- Important systems that are not crown jewels but still warrant elevated attention. -->
+
+```
+high_value_assets:
+
+  - pattern: "prod-app-*.example.com"
+    description: "Production application servers"
+
+  - pattern: "mail-*.example.com"
+    description: "Email gateway and exchange servers"
+
+  - pattern: "vpn-*.example.com"
+    description: "VPN concentrators"
+
+  - range: "10.1.200.0/24"
+    description: "Production application tier"
+
+  - name: "SIEM-COLLECTOR-01"
+    description: "Security log aggregation"
+```
+
+> **Tip:** Assets not listed in either category are scored 1-3 based on inference.
+> You only need to list assets that should receive elevated scoring.
+
+---
+
+## Incident Criteria (Gate 4)
+
+These criteria define when the framework recommends escalation to your Incident
+Response process. When a proposed disposition is "Critical Threat" AND any of
+these criteria are met, the framework flags the alert for incident escalation.
+
+### Escalation Triggers
+
+<!-- Conditions that warrant incident escalation when combined with a Critical Threat disposition. -->
+<!-- Customize this list to match your organization's incident response plan. -->
+
+```
+incident_criteria:
+  - active_ongoing_compromise
+  - data_exfiltration_confirmed
+  - lateral_movement_to_high_value_assets
+  - credential_compromise_with_privilege_escalation
+
+# Add criteria specific to your organization:
+#   - pci_environment_breach
+#   - pii_exposure_confirmed
+#   - ransomware_indicators
+#   - supply_chain_compromise_indicators
+#   - regulatory_notification_threshold_met
+```
+
+### Autonomy Level
+
+<!-- Controls what the framework does with low-risk alerts it wants to close. -->
+<!--   auto-close    = Framework closes False Positive / Benign alerts automatically, -->
+<!--                    documents reasoning, and moves on. Best for high-volume SOCs. -->
+<!--   recommend-close = Framework presents its disposition as a recommendation and -->
+<!--                     waits for analyst confirmation before closing. Best for -->
+<!--                     teams that require human sign-off on every disposition. -->
+
+```
+autonomy_level: auto-close
+```
+
+---
+
+## Disposition Categories (Gate 4)
+
+The framework uses four standard disposition categories. You can add custom
+categories for situations specific to your organization.
+
+### Standard Categories
+
+<!-- These four are built in and always available. You cannot remove them, -->
+<!-- but you can adjust the descriptions to match your internal terminology. -->
+
+```
+dispositions:
+
+  critical_threat:
+    label: "Critical Threat"
+    description: "Confirmed malicious activity. Evidence of compromise. Immediate response needed."
+
+  policy_violation:
+    label: "Policy Violation"
+    description: "Real activity violating policy. May not be malicious. Remediation needed."
+
+  false_positive:
+    label: "False Positive"
+    description: "Detection logic triggered incorrectly. No actual security event."
+
+  benign_activity:
+    label: "Benign Activity"
+    description: "Real activity that is expected or authorized. No action needed."
+```
+
+### Custom Categories
+
+<!-- Add categories for situations your team encounters regularly. -->
+<!-- Custom categories are used when an alert doesn't fit the four standard ones. -->
+
+```
+custom_dispositions:
+
+  # authorized_pen_test:
+  #   label: "Authorized Pen Test"
+  #   description: "Activity is part of a sanctioned penetration test or red team exercise."
+  #   action: "Log and correlate with engagement schedule. No remediation needed."
+
+  # known_risk_accepted:
+  #   label: "Known Risk Accepted"
+  #   description: "Activity relates to a risk that has been formally accepted by management."
+  #   action: "Document against risk acceptance record. Review at next risk committee."
+
+  # vendor_activity:
+  #   label: "Vendor Activity"
+  #   description: "Activity from an authorized third-party vendor within their approved scope."
+  #   action: "Verify against vendor access schedule and SOW. Log for audit trail."
+
+  # change_related:
+  #   label: "Change-Related Activity"
+  #   description: "Alert triggered by an approved change request or maintenance window."
+  #   action: "Correlate with change ticket. Close if activity matches approved scope."
+```
+
+> **Tip:** Uncomment and customize the examples above, or add your own following
+> the same format.
+
+---
+
+## Escalation Targets (Gate 6)
+
+Define where reports and notifications go based on the investigation outcome.
+By default, all results are presented in the current session. Add routing
+rules to direct specific disposition types to the right people.
+
+```
+escalation_targets:
+
+  critical_threat:
+    # Where to send Critical Threat findings
+    primary: "present in session"
+    # additional:
+    #   - channel: "#incident-response"
+    #     method: "slack"
+    #   - recipient: "soc-lead@example.com"
+    #     method: "email"
+    #   - recipient: "ir-oncall"
+    #     method: "pagerduty"
+
+  policy_violation:
+    primary: "present in session"
+    # additional:
+    #   - channel: "#security-policy"
+    #     method: "slack"
+    #   - recipient: "compliance-team@example.com"
+    #     method: "email"
+
+  false_positive:
+    primary: "present in session"
+    # additional:
+    #   - channel: "#detection-engineering"
+    #     method: "slack"
+    #     note: "Include tuning recommendation for rule improvement"
+
+  benign_activity:
+    primary: "present in session"
+```
+
+> **Note:** Notification integrations depend on your environment's available
+> connectors. The values above are routing instructions that the report writer
+> includes in the recommended next steps. Actual delivery requires integration
+> configuration outside of this policy file.
+
+---
+
+## Report Format (Gate 6)
+
+Control which sections appear in investigation reports. All sections are
+included by default. Set a section to `false` to exclude it.
+
+```
+report_sections:
+
+  business_summary:        true    # Plain-English summary (always recommended)
+  proposed_disposition:    true    # Disposition with evidence
+  five_ws:                 true    # Who, What, When, Where, Why table
+  mitre_attack_mapping:    true    # ATT&CK tactic and technique
+  ioc_table:               true    # Indicators of compromise with reputation
+  evidence_chain:          true    # Queries run and conclusions drawn
+  correlated_alerts:       true    # Related alerts discovered during investigation
+  recommended_next_steps:  true    # Actionable response guidance
+  show_your_work:          false   # Full query log and reasoning chain
+                                   # (verbose -- enable for audit or training)
+```
+
+### Additional Report Preferences
+
+```
+report_preferences:
+
+  # Include the severity score breakdown in every report
+  include_severity_breakdown: true
+
+  # Include timeline visualization for DEEP investigations
+  include_timeline: true
+
+  # Append the raw FSQL queries to the report for reproducibility
+  include_raw_queries: false
+
+  # Maximum length guidance for the business summary
+  business_summary_max_sentences: 6
+```
+
+---
+
+## Senior Analyst Review (Post-Gate 6)
+
+Controls when the automated senior analyst review runs after an investigation
+is complete.
+
+### Review Trigger
+
+<!-- When to automatically invoke the senior analyst review. -->
+<!--   all             = Review every completed investigation -->
+<!--   high_critical   = Review only investigations scored HIGH or CRITICAL (default) -->
+<!--   critical_only   = Review only CRITICAL dispositions and DEEP investigations -->
+<!--   manual          = Never auto-trigger; analyst invokes review manually -->
+
+```
+review_trigger: high_critical
+```
+
+### Review Cycle Limit
+
+<!-- Maximum number of review-and-fix cycles before presenting the investigation -->
+<!-- to the analyst with review notes attached. -->
+
+```
+max_review_cycles: 2
+```
+
+---
+
+## Default Time Ranges
+
+Default lookback windows for different query types. Analysts can override these
+per-investigation; these values are used when no override is specified.
+
+```
+time_ranges:
+
+  # Gate 1: How far back to pull alerts
+  alert_intake: 24h
+
+  # Gate 2: IOC enrichment (varies by IOC type)
+  ioc_enrichment:
+    ip_address:   24h     # IPs rotate frequently; short window reduces noise
+    file_hash:    30d     # Hashes are stable; longer window catches slow attacks
+    username:     7d      # User activity over a week shows patterns
+    domain:       7d      # DNS activity over a week
+    email:        30d     # Email-based attacks may have longer dwell time
+
+  # Gate 2: Threat intelligence lookback
+  threat_intel: 30d
+
+  # Identity investigator: Authentication pattern baseline
+  auth_patterns: 7d
+
+  # Identity investigator: Account change history
+  account_changes: 30d
+
+  # Network investigator: Flow and connection data
+  network_activity: 7d
+```
+
+> **Guidance:** Shorter time ranges run faster and return less noise, but may miss
+> slow-moving attacks. Longer ranges catch more but increase query time and require
+> more analysis. Adjust based on your data retention policies and typical attacker
+> dwell time in your environment.
+
+---
+
+## Custom Investigation Runbooks
+
+Link custom runbook skills for specific alert types. When the alert classifier
+identifies an alert type that matches a runbook, the framework invokes your
+custom skill in addition to (or instead of) the default investigation process.
+
+### How Runbooks Work
+
+1. Create a new skill in `skills/<your-runbook-name>/SKILL.md`
+2. Reference it below with the alert type or MITRE technique it handles
+3. The framework invokes your runbook at Gate 4 (Decide & Act) during DEEP investigations
+
+### Runbook Mappings
+
+```
+custom_runbooks:
+
+  # Map by alert type (from alert-classifier output)
+  # by_alert_type:
+  #   "Identity/Access":
+  #     skill: "digital-workers:acme-identity-runbook"
+  #     mode: "supplement"    # "supplement" runs alongside default investigator
+  #                           # "replace" runs instead of default investigator
+  #
+  #   "Phishing/Email":
+  #     skill: "digital-workers:acme-phishing-runbook"
+  #     mode: "replace"
+
+  # Map by MITRE ATT&CK technique ID
+  # by_technique:
+  #   "T1566":               # Phishing
+  #     skill: "digital-workers:acme-phishing-runbook"
+  #     mode: "replace"
+  #
+  #   "T1078":               # Valid Accounts
+  #     skill: "digital-workers:acme-compromised-creds-runbook"
+  #     mode: "supplement"
+
+  # Map by source connector (when a specific tool needs special handling)
+  # by_connector:
+  #   "crowdstrike":
+  #     skill: "digital-workers:acme-crowdstrike-procedures"
+  #     mode: "supplement"
+```
+
+> **Tip:** Start with `mode: "supplement"` so your custom runbook adds to the
+> built-in investigation. Switch to `mode: "replace"` only when your runbook
+> fully covers the investigation steps for that alert type.
+
+---
+
+## Quick Reference: Which Gate Uses What
+
+| Setting | Section | Gate |
+|---------|---------|------|
+| Severity filter, time range, connector scope | Alert Scope | Gate 1 |
+| Dimension weights, depth thresholds, overrides | Severity Weights | Gate 3 |
+| Crown jewels, asset lists | Crown Jewels / Asset Criticality | Gate 3 |
+| Incident criteria, autonomy level | Incident Criteria | Gate 4 |
+| Disposition categories | Disposition Categories | Gate 4 |
+| Escalation targets | Escalation Targets | Gate 6 |
+| Report sections, preferences | Report Format | Gate 6 |
+| Review trigger, cycle limit | Senior Analyst Review | Post-Gate 6 |
+| Lookback windows | Default Time Ranges | Gates 1, 2, 4 |
+| Runbook links | Custom Investigation Runbooks | Gate 4 |