diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index 28254c9..f5ff408 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -15,28 +15,55 @@ A manager can open Pulse on their phone and, in under 30 seconds, see the state of the business and triage tickets — without ever needing to switch to desktop for read-only awareness. -## Current Milestone: v2.0 PAX8 Integration +## Current Milestone: v3.0 Phishing Triage Automation -**Goal:** Sync PAX8 licensing/subscription data into Pulse, read-only, mapped -to Autotask companies, so managers can see subscription costs and seat counts -alongside existing company data. +**Goal:** Detect candidate phishing/spam report tickets in Autotask, extract +and parse original-message evidence, classify each as `SPAM` / `UNWANTED` / +`THREAT`, group duplicate reports into campaigns, and prepare (never +auto-execute) remediation actions behind an explicit human-approval gate. **Target features:** -- PAX8 client + factory (OAuth2 client-credentials; credentials already - provisioned) -- Read-only sync of companies, subscriptions, product catalog, and - orders/invoices into Postgres -- Fuzzy-name matching of PAX8 companies to Autotask companies, with a - manual-review path for unmatched/ambiguous cases -- New `/pax8` page (company list, subscriptions, cost breakdown) -- Daily sync via the existing scheduler pattern +- Ticket detector/scanner matching known phishing/spam-report patterns + (title/body keyword + Microsoft/KnowBe4 report signatures), idempotent + reprocessing +- `.eml` evidence extraction — prefers `rfc.eml` (original reported message) + over `OriginatingEmail.eml` (wrapper), case-insensitive name + `message/rfc822` + content-type matching +- RFC822/MIME parser producing normalized headers (From/Reply-To/Return-Path/ + To/Cc/Subject/Date/Message-ID/Received chain/auth results), URLs, and + attachment metadata (name/type/size/hash) — no URL detonation +- Campaign grouping/dedupe keyed on Message-ID, then attachment-hash/URL-domain + + subject + sender + time-window, then sender + normalized subject + client + + time-window +- Durable data model: campaigns, reports, messages, indicators, classifications, + remediation_actions, audit_events +- Mimecast blast-radius lookup abstraction (interface + normalized output), + gracefully `unavailable` when unconfigured — classification still proceeds + on ticket/email evidence alone +- Classifier service: deterministic rule layer + an LLM-abstraction plug point + (safe rule-based fallback if no LLM abstraction fits); structured evidence + in, not raw unbounded email; KnowBe4 simulations not auto-flagged as THREAT +- API surface under `/api/phishing/*`: list/get campaigns, analyze a ticket, + classify/approve/remediate/mark-false-positive a campaign +- Optional Autotask internal triage note (only if a safe note-write path + already exists; otherwise return note text via API) +- Remediation safety: destructive actions (purge/delete/block/reset) always + `requires_approval: true`, logged with approver/timestamp/params/result, + idempotent on re-run, fail closed if approval/config missing +- Tests: detection patterns, `.eml` selection logic, MIME parsing, campaign + dedupe, rule classification (SPAM/UNWANTED/THREAT), approval-required + safety, idempotent reprocessing, API happy-path + permission failures — + synthetic fixtures only, no real customer email -Unrelated in domain to the v1.0 Mobile Shell Redesign above — this milestone -adds a new backend integration and admin-facing surface, not a mobile change. -See `.planning/seeds/SEED-002-pax8-integration.md` for the exploration that -scoped this milestone. `.planning/seeds/SEED-003-general-pulse-data-assistant.md` -(NL chatbot over Pulse data) is explicitly out of scope here — a separate -future milestone that will consume this data once it exists. +Unrelated in domain to the v2.0 PAX8 Integration above — this milestone adds a +new security/triage backend feature (Autotask ticket + email evidence, not +subscription billing). No seeds matched this scope; introduced directly from +a detailed spec provided at milestone-start. + +**Non-goals:** no automatic tenant-wide purge, no automatic password +reset/session revocation, no URL sandbox/detonation, no fully automated ticket +closure, no assumption that Graph is the eventual purge mechanism (Defender/ +Exchange purge may be preferable later). ## Requirements @@ -187,9 +214,19 @@ future milestone that will consume this data once it exists. ### Active - + -None — all v2.0 PAX8 Integration hypotheses validated above. Milestone complete. +- Phishing/spam report tickets in Autotask can be reliably detected from + title/body patterns and reprocessed idempotently +- `.eml` evidence (when present) can be parsed into normalized, actionable + indicators without executing/fetching anything suspicious +- Duplicate reports of the same campaign can be grouped via a small set of + stable keys (Message-ID → indicator/subject/sender/window → sender/subject/ + client/window) +- A rule-based classifier (with a clean LLM plug-point) can produce a useful + SPAM/UNWANTED/THREAT verdict from structured evidence alone +- Remediation can be modeled and gated behind approval without ever executing + destructively in this milestone ### Out of Scope @@ -277,4 +314,4 @@ This document evolves at phase transitions and milestone boundaries. 4. Update Context with current state --- -*Last updated: 2026-07-12 — Phase 14: /pax8 UI Surface complete — v2.0 PAX8 Integration milestone complete* +*Last updated: 2026-07-14 — v3.0 Phishing Triage Automation milestone started* diff --git a/.planning/STATE.md b/.planning/STATE.md index e612416..5e039b0 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -1,17 +1,16 @@ --- gsd_state_version: 1.0 -milestone: v2.0 -milestone_name: PAX8 Integration -status: milestone_complete -stopped_at: Milestone complete (Phase 14 was final phase) -last_updated: 2026-07-12T22:29:05.191Z -last_activity: 2026-07-11 -- Phase 14 execution started +milestone: v3.0 +milestone_name: Phishing Triage Automation +status: planning +last_updated: "2026-07-15T03:33:51.575Z" +last_activity: 2026-07-15 progress: - total_phases: 5 - completed_phases: 4 - total_plans: 20 - completed_plans: 20 - percent: 80 + total_phases: 0 + completed_phases: 0 + total_plans: 0 + completed_plans: 0 + percent: 0 --- # Project State @@ -25,12 +24,10 @@ See: .planning/PROJECT.md (updated 2026-07-10) ## Current Position -Phase: 14 -Plan: Not started -Status: Milestone complete -Last activity: 2026-07-12 - -Progress: [░░░░░░░░░░] 0% +Phase: Not started (defining requirements) +Plan: — +Status: Defining requirements +Last activity: 2026-07-15 — Milestone v3.0 started ## Performance Metrics