Skip to content

incident-response-workflow.md

Latest commit

 

History

History
116 lines (88 loc) · 3.38 KB

incident-response-workflow.md

File metadata and controls

116 lines (88 loc) · 3.38 KB
Raw

Lightweight Incident Workflow

This project now includes a small incident workflow layer for PhishAnalyze and PayShield. It is intentionally a case tracker, not a SOAR platform.

Purpose

The workflow closes the gap between detection and response by preserving the minimum state needed for a manual incident review:

  • case ID tied to one scan_results.id
  • status: open, triaged, investigating, contained, or closed
  • severity: low, medium, high, or critical
  • owner from the workspace membership table
  • immutable event chain with scan evidence, status changes, owner changes, severity changes, notes, escalation markers, and audit-only remediation plans

This supports a practical NIST SP 800-61r3 / CSF 2.0 style response loop while avoiding automated remediation.

API

List cases:

GET /api/saas/cases

Create a case from a stored scan result:

POST /api/saas/cases
Content-Type: application/json

{
  "scan_result_id": "res_...",
  "severity": "high",
  "note": "Finance pilot case"
}

Record a user report for a stored scan result. This opens the linked case on first report, reuses it on later reports, and appends a user_reported event:

POST /api/saas/scans/res_.../report
Content-Type: application/json

{
  "channel": "browser_report_button",
  "note": "Finance user reported this after upload"
}

Update state, owner, severity, note, or escalation:

PATCH /api/saas/cases/case_...
Content-Type: application/json

{
  "status": "triaged",
  "escalate": true,
  "escalation_reason": "Finance owner review"
}

Read the evidence chain:

GET /api/saas/cases/case_...

Generate an audit-only remediation plan:

POST /api/saas/cases/case_.../remediation-plan
Content-Type: application/json

{}

The returned plan uses schema incident-remediation-plan.v1. It recommends manual actions such as preserving evidence, searching for related messages, holding payment review, verifying supplier details through trusted channels, reviewing blockable indicators, and checking whether a credential reset is needed. It does not perform those actions.

Security Boundary

  • Every case query is scoped by authenticated org_id.
  • Case creation requires the scan result to belong to the same organization.
  • Case owners must be active members of the same workspace.
  • Owner/admin case mutations are included in the passkey step-up matrix when PHISHANALYZE_PASSKEY_ENFORCEMENT=enforce and a passkey exists.
  • User-report intake is CSRF-protected and authenticated, but does not require a fresh passkey step-up so a report button remains usable during a live review.
  • Evidence events store scan identifiers, verdict, payment decision, and subject. They do not store raw email bodies.
  • Remediation-plan events store only summary evidence references, IOC counts, verdict/payment decision values, and recommended actions. They do not return raw headers, raw bodies, attachment content, credentials, or mailbox data.

Non-Goals

  • No auto-quarantine.
  • No external ticket creation.
  • No user notifications.
  • No playbook automation.
  • No automatic remediation from remediation plans.
  • No full SOAR workflow engine.

The fastest validation remains a 10-incident manual pilot. Track whether each case reaches closed, who owned it, whether it was escalated, and time from case creation to closure.