Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

docs: mailbox remediation operations page, changelog and claim row

Beenu Arora34c8082cc1bd
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b368ea898..65e7e092c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -191,6 +191,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
+- **Reported phish now goes from intake to purge (depth 7.1).** The gap was
+ not that phishing was unhandled — `POST /phishing/submit` has triaged
+ artefacts since migration 015 — but that nothing in the product could
+ *remove a message*. The live-action registry held 79 builtin arms and not
+ one could touch a mailbox, so governed dispatch answered
+ `executor_not_found` for `purge_email`: a response that could block the
+ sender's domain at the firewall and could not take back the mail. Five
+ verbs enter both halves of the capability vocabulary (`search_mailboxes`,
+ `purge_email`, `restore_email`, `block_sender`, `unblock_sender`) with ten
+ vendor arms over Microsoft Graph and the Gmail API. Only what the vendors
+ document: purge is a move to `recoverableitemsdeletions` or to Trash, never
+ a hard delete, and `restore_email` is a real reverse rather than a declared
+ one. There is deliberately **no tenant-wide blocked-sender verb**, because
+ neither vendor exposes its organisation-level block list through these
+ APIs; the sender block is per mailbox and says so in the summary an analyst
+ reads, not only in a docstring. Reported-message intake normalises three
+ sources into one record — an M365 report mailbox over Graph, Workspace user
+ reports, and the existing `email_inbox` connector — and the hard case is
+ the common one: a user who reports by forwarding becomes the *sender*, so
+ the adapter reads the original sender and recipients out of the preserved
+ headers and leaves the sender empty rather than naming the victim as the
+ attacker. Campaign grouping is a five-step ladder and `grouping_basis`
+ records which step matched, because four are facts about the message and
+ subject similarity is a judgement. The purge is **one proposal and one
+ dispatch per mailbox**: handing a single executor twenty-five addresses
+ would be one approval covering a list the approver never read.
+ `scaled_impact` turns the recipient count into the tier — MODERATE at one,
+ HIGH at five, SEVERE at twenty-five, where `NEVER_AUTONOMOUS` makes it
+ mandatory-human at any confidence and any autonomy tier — and the proposal
+ and every dispatch under it read the same function, so the approver and the
+ executor cannot see different actions. Verification re-queries the mailbox,
+ and that probe is the one in the service whose confirming answer is an
+ *absence*. Everything ships **off**: `AISOC_FEATURE_MAILBOX_REMEDIATION`
+ and `PHISHING_INTAKE_WORKER_ENABLED` both default false, and a disabled
+ deployment answers FAILED naming the setting rather than simulating a purge
+ — `NotifySlackExecutor` reporting `message_sent: true` for a message it
+ never sent is the precedent. Migration `104`. Gates:
+ `check_action_contract.py` (86 → 97 executors), `check_module_reachability.py`
+ (981 → 986 reachable), `check_vendor_catalog_ids.py`,
+ `test_mailbox_remediation.py` (60 cases through real `respx` HTTP) and
+ `test_phishing_campaign_purge_live.py` (17 cases against a real Postgres
+ with the full chain). **No Microsoft 365 or Google Workspace tenant was
+ exercised**: every vendor claim rests on the documented request shape and a
+ mock.
- `services/api/app/models/detection_rule.py` maps the `author` column, which
has existed since `001_init.sql` and was mapped by nothing — while fusion's
tenant overlay reads it on every reload to say *who* silenced a rule when it
diff --git a/apps/docs/docs/operations/mailbox-remediation.md b/apps/docs/docs/operations/mailbox-remediation.md
new file mode 100644
index 000000000..984d841a4
--- /dev/null
+++ b/apps/docs/docs/operations/mailbox-remediation.md
@@ -0,0 +1,179 @@
+---
+title: Mailbox remediation
+sidebar_label: Mailbox remediation
+---
+
+# Mailbox remediation
+
+Reported phish goes from a report mailbox to a purge across the recipients
+who received it, with the approval tier scaled by how many of them there are.
+
+Everything on this page is **off until you turn it on**. AiSOC does not
+acquire the ability to delete from your mailboxes by being upgraded.
+
+## What is actually supported
+
+Only verbs Microsoft Graph and the Gmail API document.
+
+| Verb | Microsoft 365 | Google Workspace | Reverse |
+|---|---|---|---|
+| `search_mailboxes` | `GET /users/{id}/messages?$filter=internetMessageId eq '…'` | `users.messages.list?q=rfc822msgid:…` | n/a (read) |
+| `purge_email` | move to `recoverableitemsdeletions` | `users.messages.trash` | `restore_email` |
+| `restore_email` | move back to the original folder | `users.messages.untrash` | `purge_email` |
+| `block_sender` | inbox `messageRules` entry | `users.settings.filters` entry | `unblock_sender` |
+| `unblock_sender` | delete the rule | delete the filter | `block_sender` |
+
+Two absences are deliberate and worth reading before you plan around them.
+
+**There is no hard delete.** A purge is a soft delete on both vendors —
+recoverable items on Microsoft, Trash on Gmail — because `restore_email` has
+to be a real reverse rather than a declared one. A verb that cannot be undone
+has no business being dispatched across a thousand mailboxes.
+
+**There is no tenant-wide sender block.** Exchange Online's Tenant Allow/Block
+List is reached through Exchange Online PowerShell and the Defender portal,
+and Workspace's domain block list through the Admin console; neither is in the
+API this platform speaks. `block_sender` is therefore **per mailbox**, and the
+summary an analyst reads says so. An analyst who reads "sender blocked" and
+believes the organisation is covered has been misled by the product, which is
+worse than the product not offering the button.
+
+## Enabling it
+
+Three things, in this order.
+
+1. **Grant the application permissions.** Microsoft 365 needs `Mail.ReadWrite`
+ on the same app registration the Entra ID identity actions use —
+ `azure_tenant_id`, `azure_client_id` and `azure_client_secret` are the same
+ three credentials, deliberately, so you do not register a second app to
+ purge a message. Google Workspace needs domain-wide delegation for
+ `gmail.readonly`, `gmail.modify` and `gmail.settings.basic`.
+
+2. **Turn the capability on** in `services/actions`:
+
+ ```bash
+ AISOC_FEATURE_MAILBOX_REMEDIATION=true
+ ```
+
+ With it unset, every mailbox verb — including the read — answers `failed`
+ and names this variable. It does not simulate, and it does not report a
+ purge that did not happen.
+
+3. **Nominate a report mailbox**, if you want the poller. Set
+ `phishing_report_mailbox` in the `connector_config` of an enabled
+ `m365_audit`, `azure_entra` or `google_workspace` connector, and enable the
+ worker:
+
+ ```bash
+ PHISHING_INTAKE_WORKER_ENABLED=true
+ ```
+
+ The worker polls every five minutes by default. It never guesses an
+ address: with the flag on and no mailbox nominated it logs which half is
+ missing rather than going quiet.
+
+## The three intake doors
+
+| Door | How it arrives | Use it when |
+|---|---|---|
+| Report-mailbox poller | AiSOC reads the mailbox over Graph or Gmail | Users forward phish to a shared address |
+| `POST /api/v1/phishing/reports` | Your automation posts the vendor payload | You already have a bot or a webhook |
+| `email_inbox` connector | IMAP poll, through the existing connector | Neither API is available to you |
+
+All three normalise to one record, so the campaign and the purge do not know
+which door a report came through.
+
+The adapter reads **through a forward**. A user who reports phish by
+forwarding it becomes the sender of the outer message, so a naive reader would
+name the victim as the attacker and put your report mailbox in the recipient
+list the purge then proposes to clean. The Graph adapter reads the original
+sender and the original recipients out of the preserved internet headers, and
+where a forward dropped them it leaves the sender empty rather than guessing.
+
+## Campaign grouping
+
+Reports are joined into a campaign by the strongest attribute they carry:
+
+1. the internet message id — the same message, by definition;
+2. an attachment hash — the same file reached several people;
+3. the first URL — the same landing page;
+4. the sender;
+5. a normalised subject.
+
+The campaign records **which** of these matched, as `grouping_basis`, and
+publishes `grouping_is_factual`. The first four are facts about the message.
+Subject similarity is a judgement: it strips reply prefixes and collapses
+digits and long opaque tokens, so `Invoice 10452 overdue` and
+`Invoice 98113 overdue` group — which is the point, and is also why it is last
+and why the basis is published. You are entitled to know which kind of claim
+you are about to act on across forty mailboxes.
+
+## The purge, and what it will ask of you
+
+```bash
+# Preview. Nothing is removed; every mailbox is graded and reported.
+curl -X POST .../api/v1/phishing/campaigns/{id}/purge \
+ -H 'Content-Type: application/json' -d '{"execute": false}'
+```
+
+The blast radius scales with the recipient count:
+
+| Recipients | Impact | What that means |
+|---|---|---|
+| 1–4 | `moderate` | Analyst approval |
+| 5–24 | `high` | Analyst approval, and the confidence floor rises |
+| 25+ | `severe` | A human must approve, at **any** confidence and **any** autonomy tier |
+
+The campaign is graded once and every per-mailbox dispatch underneath it is
+held to the same grading, because both read the same function. The alternative
+— grading each mailbox as a one-recipient purge — is the quiet way a severe
+action becomes a moderate one.
+
+Each recipient gets **its own dispatch**: its own contract check, its own
+audit row, its own verification probe and its own restore handle. One approval
+covering a list the approver never read is the thing the capability contract
+exists to refuse.
+
+### What counts as purged
+
+Only a dispatch that reached the vendor. A mailbox that never held the message
+is recorded as `not_found`, a preview as `simulated`, and a campaign where any
+mailbox did not complete lands on `partially_purged` rather than `purged`.
+Twenty of twenty-five reported as a purge teaches you to trust a number that
+means nothing.
+
+### Verification
+
+After a purge, AiSOC re-queries the mailbox. This is the one probe in the
+product whose confirming answer is an **absence**: on Microsoft the message
+must no longer be findable, and on Gmail it must carry the `TRASH` label.
+Absent credentials, or with the feature disabled, the result is `unverified`
+— never `verified`.
+
+### Reversing it
+
+```bash
+curl -X POST .../api/v1/phishing/campaigns/{id}/restore
+```
+
+Only mailboxes the purge executed on are restored; attempting the others would
+report work that did not happen. Microsoft's move gives the message a new id
+in the destination folder and the original folder is only knowable before the
+move, so both were stored at purge time. Gmail keeps the id and untrash
+restores the labels the message had.
+
+## What has not been verified
+
+**No Microsoft 365 or Google Workspace tenant has been exercised.** Every
+request shape here is taken from the vendors' API reference and asserted
+against a recorded mock, including the Graph filter, the move destination, the
+inbox-rule body and the Gmail filter body. Nobody has watched Graph accept the
+move or Gmail accept the trash. Treat the first run against your own tenant as
+the first run.
+
+The playbook pack's `Retract the message via the tenant's email gateway` step
+is **not** this path and never was. It posts to `EMAIL_GATEWAY_URL`, which no
+compose file or `.env.example` sets, under `on_failure: continue` — so on a
+default deployment it is skipped and the message is not retracted. The
+playbook engine has no `purge_email` step type, so the purge above is reached
+through the route rather than from a playbook.
diff --git a/apps/docs/sidebars.ts b/apps/docs/sidebars.ts
index f0e423059..7f804df97 100644
--- a/apps/docs/sidebars.ts
+++ b/apps/docs/sidebars.ts
@@ -210,6 +210,7 @@ const sidebars: SidebarsConfig = {
"operations/airgap",
"operations/air-gapped",
"operations/sandbox-providers",
+ "operations/mailbox-remediation",
"operations/llm-gateway",
"operations/llm-cost",
"operations/mcp-client",
diff --git a/docs/audit/CLAIM_TO_GATE_MATRIX.md b/docs/audit/CLAIM_TO_GATE_MATRIX.md
index bbcc6e6db..e7ba4efd4 100644
--- a/docs/audit/CLAIM_TO_GATE_MATRIX.md
+++ b/docs/audit/CLAIM_TO_GATE_MATRIX.md
@@ -310,12 +310,13 @@ Statuses: `GATED` (a CI job fails when the claim stops being true) · `PARTIAL`
| A stored report schedule produces a report, and says whether it was delivered | `apps/docs/docs/operations/notifications.md` (scheduled reports) | `ci.yml :: Python — Tests` (api, `test_delivery_5_2.py::TestCronMatching` — nine match cases, six unparseable expressions that raise rather than matching everything, a schedule falling between two five-minute polls, an already-run schedule not firing twice, and a week-long outage collapsing into one report) | core | GATED | `report_templates.cron_schedule` was storable, editable and **read by nothing**, so a tenant could set a schedule, see it saved and never receive anything. Asking "does the current minute match" would have checked 08:57 and 09:02 and never 09:00; the matcher asks over the interval since the last run. Migration 098 adds `delivery_status`, because `delivered_at` alone cannot tell "no relay configured" from "the relay refused" from "not run yet" |
| An outbound event webhook is signed, retried, and its failures are visible | `apps/docs/docs/operations/notifications.md` (outbound webhooks) | `ci.yml :: Python — Tests` (api, `test_delivery_5_2.py::TestWebhookSignature` and `::TestWebhookDelivery` — signature round-trip through the real client, a modified body and a re-stamped timestamp both refused, five malformed headers refused without raising, the 4xx/5xx split, the ladder ending in the dead-letter view, byte-identical bodies across attempts, and an undecryptable secret killing the delivery rather than sending it unsigned) | core | GATED | AiSOC could be told things and could tell nobody anything: `grep -rln outbound_webhook` over `services/` and `apps/` returned nothing. The signature is the shape Stripe, GitHub and Slack use, because a scheme nobody recognises is a scheme nobody verifies. The retry queue and the dead-letter list are one table at different points on one ladder, so there is no window where a delivery is in neither |
| The fix for `fake_tool_output` is measured on payloads authored after it was frozen, and that measurement carries no floor | `services/agents/tests/adversarial/behavioural_holdout.py`; `apps/docs/docs/benchmark.md` | `ci.yml :: Python — Tests` (`tests/adversarial/test_behavioural_holdout.py` pins the held-out flip, catch and unsafe-action rates **exactly**, in both directions, so a change moving any of them either way has to say so in the same commit; every payload is asserted to carry a steering phrase or an action trigger so the denominator cannot be padded with strings that were never going to work, asserted disjoint from the tuned corpus, and every declared seam asserted to have a payload) + `test_tool_result_channel.py` (the channel invariant the guard rule rests on, walked out of the service's syntax tree, plus a 20-entry good corpus and a negative control that lifts the rule from the table and watches the family reopen) | core | GATED | **Flip 85% and catch 10% on 20 held-out payloads, against 0% and 100% on the 3 tuned ones.** Published rather than closed, because tuning until they agree is the move this repository has measured the cost of. A worst-case probe rather than a neutral sample: the tuned payloads predate the fix and the held-out ones were aimed at named properties of it, so part of the gap is adversarial-versus-naive. The sharper finding is that the guard and the ledger-provenance demotion **share a detector**, so they are one control counted twice rather than two layers, which a test asserts. No floor and no ratchet, deliberately: a target on a held-out set is an instruction to tune against it, and a test fails if the two rates ever agree so that agreement cannot pass silently |
+| A reported phishing message can be grouped into a campaign and purged across its recipients, at the tier the recipient count earns | `apps/docs/docs/operations/mailbox-remediation.md`; depth plan 7.1 | `ci.yml :: Python — Lint & Type-check` (`check_action_contract.py` — the five mailbox verbs are in both halves of the vocabulary, every one has an executor, `purge_email` declares `restore_email` as a platform reverse that exists, and the probe it declares is reachable through an `ActionType`; `check_module_reachability.py` — the intake adapters have a production caller, which is the report-mailbox worker rather than only the route) + `ci.yml :: Python — Tests` (actions, `test_mailbox_remediation.py` — 60 cases driving the real arms over `respx`: the Graph filter is asserted to carry the **bracketed** message id and to request `parentFolderId`, because a mock that answers whatever is asked cannot notice a field the query never requested; a hard `DELETE` route is wired to raise, so a purge that stopped being a soft delete fails rather than passes; a dry run is asserted to make **zero** HTTP calls; a mailbox with no copy answers FAILED with `match_count` 0 rather than counting toward a purge total; the rollback is asserted by call count and destination folder rather than by a boolean; and the verification probe's polarity has its own inverted-control test, because for a purge the confirming answer is an absence) + `ci.yml :: Python — Tests` (api, `test_phishing_intake_adapters.py` — 27 cases over the documented Graph, Gmail and `email_inbox` shapes, including the forwarded report where the reporter is the envelope sender) + `integration.yml` (api, `test_phishing_campaign_purge_live.py` — 17 cases against a real Postgres with the migration chain applied: two reports of one message join one campaign, `recipient_count` is recomputed rather than incremented, a 25-recipient campaign is `severe`/`mandatory_human` at every tier and every confidence, each mailbox gets its own dispatch carrying the campaign's count, and twenty of twenty-five purged is `partially_purged`) | core | PARTIAL (no Microsoft 365 or Google Workspace tenant is reachable from CI or from this maintainer, so every vendor claim rests on the documented request shape and a recorded mock. Two consequences stated rather than implied: nobody has observed Graph accept the `move` to `recoverableitemsdeletions` or Gmail accept the `trash`, and the Gmail filter and Graph inbox-rule bodies were written from the API reference rather than taken from a working call. Returns to GATED when a live tenant is available) | a maintainer-supplied M365 and Workspace test tenant |
## Summary
-- Total: 302
+- Total: 303
- GATED: 299
-- PARTIAL: 3
+- PARTIAL: 4
- NO GATE: 0
Counts come from `scripts/check_claim_gate_matrix.py`, which is also the gate. Recompute