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.

feat(api): reported-phish intake, campaign and governed purge routes

Beenu Arorae34d8a389fc2
diff --git a/services/api/app/_vendor/action_contracts/capability_contracts.py b/services/api/app/_vendor/action_contracts/capability_contracts.py
index 97ced04a6..1ed1a5b26 100644
--- a/services/api/app/_vendor/action_contracts/capability_contracts.py
+++ b/services/api/app/_vendor/action_contracts/capability_contracts.py
@@ -705,9 +705,184 @@ CAPABILITY_CONTRACTS: dict[str, CapabilityContract] = {
),
note=("A message cannot be unsent, but paging the wrong channel is embarrassment rather than impact."),
),
+ # ── Mailbox remediation ───────────────────────────────────────────────
+ #
+ # These are the only verbs in the vocabulary whose impact genuinely is
+ # not a constant: purging one copy of a message out of one mailbox and
+ # purging it out of a thousand are different acts. The constant below is
+ # the floor, and `scaled_impact` raises it from the recipient count —
+ # see that function for why the scaling lives outside the table.
+ "search_mailboxes": CapabilityContract(
+ impact=ActionImpact.READ_ONLY,
+ approval=ApprovalRequirement.AUTOMATIC,
+ reversal=Reversal.NOT_APPLICABLE,
+ required_permission=_INVESTIGATE,
+ has_verification_probe=False,
+ verification_gap=("A read leaves nothing behind to read back, the same gap search_siem and lookup_cloud_audit record."),
+ note=(
+ "Find the copies of one reported message across mailboxes, by "
+ "internet message id, sender, subject or receipt window. Every "
+ "other verb here depends on it: a purge needs a per-mailbox "
+ "message id and only this maps one message onto the mailboxes "
+ "holding it."
+ ),
+ ),
+ "purge_email": CapabilityContract(
+ impact=ActionImpact.MODERATE,
+ approval=ApprovalRequirement.ANALYST,
+ reversal=Reversal.PLATFORM,
+ reverse_capability="restore_email",
+ required_permission=_CONTAIN,
+ has_verification_probe=True,
+ note=(
+ "Soft-delete one copy of a message from one mailbox: a move to "
+ "recoverableitemsdeletions on Microsoft, a move to Trash on "
+ "Gmail. Never a hard delete, which has no reverse. MODERATE is "
+ "the single-recipient floor and scaled_impact raises it with the "
+ "campaign's size; ANALYST rather than AUTOMATIC because a wrong "
+ "purge removes a message the recipient may have needed and the "
+ "restore, while real, is not instantaneous."
+ ),
+ ),
+ "restore_email": CapabilityContract(
+ impact=ActionImpact.LOW,
+ approval=ApprovalRequirement.AUTOMATIC,
+ reversal=Reversal.PLATFORM,
+ reverse_capability="purge_email",
+ required_permission=_CONTAIN,
+ has_verification_probe=True,
+ note=(
+ "Put a soft-deleted message back. The declared rollback for "
+ "purge_email, and the reason that verb may be dispatched at all: "
+ "a reverse that resolves to nothing is the defect "
+ "KNOWN_ORPHANS exists to catch, and it would be at its worst on "
+ "the most disruptive verb in the product. LOW and automatic "
+ "because undoing a containment must never be harder than "
+ "applying it."
+ ),
+ ),
+ "block_sender": CapabilityContract(
+ impact=ActionImpact.LOW,
+ approval=ApprovalRequirement.ANALYST,
+ reversal=Reversal.PLATFORM,
+ reverse_capability="unblock_sender",
+ required_permission=_CONTAIN,
+ has_verification_probe=True,
+ note=(
+ "Stop future mail from one sender reaching one mailbox: an inbox "
+ "message rule on Microsoft, a filter on Gmail. Per-mailbox, not "
+ "tenant-wide — neither vendor exposes its organisation-level "
+ "block list through the API this platform speaks, and declaring "
+ "the broader verb would have an analyst believe the organisation "
+ "is covered when one mailbox is."
+ ),
+ ),
+ "unblock_sender": CapabilityContract(
+ impact=ActionImpact.LOW,
+ approval=ApprovalRequirement.AUTOMATIC,
+ reversal=Reversal.PLATFORM,
+ reverse_capability="block_sender",
+ required_permission=_CONTAIN,
+ has_verification_probe=True,
+ note="Remove the rule or filter block_sender created. Its declared reverse.",
+ ),
}
+#: Recipient counts at which ``purge_email`` stops being the verb its base
+#: contract describes. Ascending, and read as "at least this many".
+#:
+#: The numbers are a judgement and are stated rather than hidden in an `if`
+#: so a deployment reviewing its own posture can read them:
+#:
+#: * **1–4** stays MODERATE. One analyst clearing a message from a handful of
+#: mailboxes is routine phishing work.
+#: * **5+** is HIGH. It is no longer one person's mail; a mistake now
+#: disrupts a team and several people notice at once.
+#: * **25+** is SEVERE, which ``NEVER_AUTONOMOUS`` makes mandatory-human at
+#: any confidence and any autonomy tier. A purge at that scale is an
+#: organisation-visible event, and the gap-closure plan names exactly this
+#: case: a 25-recipient campaign must yield one proposal that requires
+#: approval.
+RECIPIENT_IMPACT_LADDER: tuple[tuple[int, ActionImpact], ...] = (
+ (25, ActionImpact.SEVERE),
+ (5, ActionImpact.HIGH),
+)
+
+#: Capabilities whose impact scales with how many mailboxes they touch.
+#: ``restore_email`` is deliberately absent: putting a thousand messages back
+#: is not disruptive in the way taking them away is, and making the rollback
+#: harder to authorise than the action is how a containment becomes permanent.
+_RECIPIENT_SCALED: frozenset[str] = frozenset({"purge_email", "block_sender"})
+
+#: Parameter keys a caller may use to declare the blast radius. Several
+#: because the count arrives from three places — a campaign proposal knows it
+#: up front, a fan-out executor counts its own targets, and a single-mailbox
+#: dispatch has one.
+_RECIPIENT_COUNT_KEYS: tuple[str, ...] = ("recipient_count", "mailbox_count", "affected_recipients")
+
+
+def recipient_count_from(params: dict | None) -> int:
+ """How many mailboxes an action says it will touch. Unknown reads as one.
+
+ Unknown is **not** treated as zero and not treated as large. Zero would
+ let a caller omit the field to dodge the ladder, which is the same shape
+ as "missing confidence is not high confidence". Large would route every
+ single-mailbox purge to a mandatory human and train people to approve
+ without reading. One is the honest floor: a dispatch with no count is a
+ dispatch against the one mailbox in ``target``.
+ """
+ if not params:
+ return 1
+ for key in _RECIPIENT_COUNT_KEYS:
+ raw = params.get(key)
+ if raw is None:
+ continue
+ try:
+ value = int(raw)
+ except (TypeError, ValueError):
+ continue
+ return max(1, value)
+ recipients = params.get("recipients")
+ if isinstance(recipients, (list, tuple, set)):
+ return max(1, len(recipients))
+ return 1
+
+
+def scaled_impact(capability: str, params: dict | None) -> ActionImpact:
+ """The impact this dispatch actually carries, given its blast radius.
+
+ Why this is a function and not more rows in the table: the contract
+ belongs to the *verb*, and ``purge_email`` is one verb. Splitting it into
+ ``purge_email_small`` and ``purge_email_large`` would hand a caller the
+ choice of which contract to be graded under, which is the opposite of
+ what a contract is for. The verb stays one entry and the dispatch
+ declares its size.
+
+ **It only ever raises.** A ladder entry below the contract's own floor is
+ ignored, so no parameter a caller supplies can make an action cheaper
+ than its contract says it is — the same one-way property the approval
+ matrix has.
+ """
+ contract = CAPABILITY_CONTRACTS.get(capability)
+ base = contract.impact if contract else ActionImpact.IRREVERSIBLE
+ if capability not in _RECIPIENT_SCALED:
+ return base
+ count = recipient_count_from(params)
+ order = (
+ ActionImpact.READ_ONLY,
+ ActionImpact.LOW,
+ ActionImpact.MODERATE,
+ ActionImpact.HIGH,
+ ActionImpact.SEVERE,
+ ActionImpact.IRREVERSIBLE,
+ )
+ for threshold, impact in RECIPIENT_IMPACT_LADDER:
+ if count >= threshold:
+ return impact if order.index(impact) > order.index(base) else base
+ return base
+
+
#: Legacy ``ActionType`` value -> capability name, for the cases where the
#: two vocabularies chose different words for the same verb.
#:
diff --git a/services/api/app/api/v1/endpoints/phishing.py b/services/api/app/api/v1/endpoints/phishing.py
index 1c2751026..dbfc73a43 100644
--- a/services/api/app/api/v1/endpoints/phishing.py
+++ b/services/api/app/api/v1/endpoints/phishing.py
@@ -40,8 +40,12 @@ from sqlalchemy import text
from app.api.v1.deps import AuthUser, DBSession, require_permission
from app.core.airgap import AirgapViolation, enforce_airgap_for_url
+from app.services.autonomy_effective import resolve_effective_tier
from app.services.llm_safety import LLMContractViolation, safe_chat_completions_request
from app.services.model_aliases import chat_completions_url, resolve_api_key, resolve_model_alias
+from app.services.phishing import campaigns as phishing_campaigns
+from app.services.phishing import intake as phishing_intake
+from app.services.phishing import purge as phishing_purge
from app.services.sandbox.enrichment import enrich_file_hash
logger = logging.getLogger(__name__)
@@ -353,6 +357,229 @@ async def submit(
raise HTTPException(status_code=503, detail="Database error") from exc
+# ────────────────────────────────────────────────────────────────────────────
+# Reported-message intake, campaigns and the governed purge (depth 7.1)
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class ReportRequest(BaseModel):
+ source: Literal["m365_graph", "google_workspace", "email_inbox"]
+ payload: dict[str, Any] = Field(
+ description=(
+ "The vendor's own payload, unmodified: a Microsoft Graph message resource, a Gmail "
+ "Message, or the event the email_inbox connector emits. Normalised server-side by "
+ "app.services.phishing.intake, which is the only place that knows the three shapes."
+ )
+ )
+ reported_by: str = Field("", description="Who reported it, when the payload does not say.")
+
+
+class ReportResponse(BaseModel):
+ submission: SubmissionResponse
+ campaign_id: uuid.UUID | None
+ campaign_created: bool
+ #: Which attribute joined this report to its campaign, and whether that
+ #: attribute is a fact about the message or a similarity judgement.
+ #: Published rather than left to the reader to infer from the basis
+ #: name, because the purge proposal this feeds is graded on the
+ #: recipient count it produces.
+ grouping_basis: str = ""
+ grouping_is_factual: bool = False
+ recipient_count: int = 0
+
+
+class PurgeRequest(BaseModel):
+ execute: bool = Field(
+ False,
+ description=(
+ "False previews: every mailbox is graded and reported, nothing is removed, and no row "
+ "reads 'purged'. Preview is the default because this is the most disruptive verb the "
+ "product offers."
+ ),
+ )
+ confidence: float | None = Field(None, ge=0.0, le=1.0)
+
+
[email protected]("/reports", response_model=ReportResponse, status_code=status.HTTP_201_CREATED, summary="Intake a reported phishing message")
+async def report(
+ body: ReportRequest, db: DBSession, user: Annotated[AuthUser, Depends(require_permission("cases:write"))]
+) -> ReportResponse:
+ """Take a reported message from one of the three intake doors.
+
+ Distinct from ``/submit``, which takes an artefact an analyst typed. This
+ takes a *message somebody received*, so it carries the two fields the
+ response turns on and ``/submit`` has never had: the internet message id
+ that finds the copies, and the recipients that bound the purge.
+ """
+ try:
+ message = phishing_intake.normalise(body.source, body.payload, reported_by=body.reported_by)
+ except ValueError as exc:
+ raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+ # The same triage the manual path runs, on the message's own text. The
+ # attachment lookups keep their honest "not analysed" indicator: an
+ # unanalysed attachment must never read as a clean one.
+ try:
+ result = await _triage("email", message.body_text, list(message.urls))
+ except AirgapViolation:
+ result = None
+ if not result:
+ result = _heuristic_triage(message.body_text, list(message.urls))
+ result = _merge_attachment_verdict(result, await _attachment_indicators(list(message.attachment_hashes)))
+
+ now = datetime.now(UTC)
+ sub_id = uuid.uuid4()
+ insert = text("""
+ INSERT INTO aisoc_phishing_submissions (
+ id, tenant_id, submitted_by, artifact_kind, raw_content, sender, subject,
+ urls, verdict, confidence, indicators, mitre_technique,
+ internet_message_id, recipients, reported_by, intake_source,
+ submitted_at, triaged_at, created_at
+ ) VALUES (
+ :id, :tenant_id, :by, 'email', :content, :sender, :subject,
+ CAST(:urls AS text[]), :verdict, :conf, CAST(:iocs AS jsonb), :mitre,
+ :message_id, CAST(:recipients AS text[]), :reported_by, :source,
+ :now, :now, :now
+ ) RETURNING *
+ """).bindparams(
+ id=sub_id,
+ tenant_id=user.tenant_id,
+ by=user.email if user else "system",
+ content=message.body_text,
+ sender=message.sender,
+ subject=message.subject,
+ urls=list(message.urls),
+ verdict=result.verdict,
+ conf=result.confidence,
+ iocs=json.dumps(result.indicators),
+ mitre=result.mitre_technique,
+ message_id=message.internet_message_id or None,
+ recipients=list(message.recipients),
+ reported_by=message.reported_by,
+ source=message.intake_source,
+ now=now,
+ )
+ try:
+ row = (await db.execute(insert)).fetchone()
+ campaign = await phishing_campaigns.record_report(db, tenant_id=user.tenant_id, message=message, submission_id=sub_id)
+ await db.commit()
+ except Exception as exc:
+ await db.rollback()
+ logger.exception("Database error in phishing report intake")
+ raise HTTPException(status_code=503, detail="Database error") from exc
+
+ return ReportResponse(
+ submission=_row_to_submission(row),
+ campaign_id=campaign.id if campaign else None,
+ campaign_created=bool(campaign and campaign.created),
+ grouping_basis=campaign.grouping_basis if campaign else "",
+ grouping_is_factual=(campaign.grouping_basis in phishing_campaigns.FACTUAL_BASES) if campaign else False,
+ recipient_count=campaign.recipient_count if campaign else 0,
+ )
+
+
[email protected]("/campaigns", summary="List phishing campaigns")
+async def list_campaigns(
+ db: DBSession,
+ user: AuthUser,
+ limit: int = Query(50, ge=1, le=200),
+ offset: int = Query(0, ge=0),
+) -> list[dict[str, Any]]:
+ try:
+ return await phishing_campaigns.list_campaigns(db, tenant_id=user.tenant_id, limit=limit, offset=offset)
+ except Exception as exc:
+ logger.exception("Database error listing phishing campaigns")
+ raise HTTPException(status_code=503, detail="Database error") from exc
+
+
[email protected]("/campaigns/{campaign_id}", summary="Get a phishing campaign and its recipients")
+async def get_campaign(campaign_id: uuid.UUID, db: DBSession, user: AuthUser) -> dict[str, Any]:
+ try:
+ found = await phishing_campaigns.get_campaign(db, tenant_id=user.tenant_id, campaign_id=campaign_id)
+ except Exception as exc:
+ logger.exception("Database error reading phishing campaign")
+ raise HTTPException(status_code=503, detail="Database error") from exc
+ if found is None:
+ raise HTTPException(status_code=404, detail="Campaign not found.")
+ return found
+
+
[email protected]("/campaigns/{campaign_id}/purge", summary="Propose or run a purge across a campaign's recipients")
+async def purge_campaign(
+ campaign_id: uuid.UUID,
+ body: PurgeRequest,
+ db: DBSession,
+ user: Annotated[AuthUser, Depends(require_permission("actions:execute"))],
+) -> dict[str, Any]:
+ """One proposal, one dispatch per mailbox, each graded on its own.
+
+ ``actions:execute`` rather than ``cases:write``: this reaches out of the
+ platform and removes mail, so it is gated like every other action
+ surface in this service rather than like a case note.
+
+ Deliberately **not** ``actions:contain``, which is what the capability
+ contract declares. That string is held by no role in ``ROLE_PERMISSIONS``
+ except the two wildcards, so gating the route on it would ship a route
+ only an administrator could reach while reading as though analysts
+ could. The contract's permission is enforced at the dispatcher, where a
+ principal exists; here the question is who may *ask*, and
+ ``actions:execute`` is the permission this service already means by
+ that — its own comment says it "gates the dry-run preview only; a live
+ containment goes through the approval path", which is exactly the split
+ between ``execute: false`` and ``execute: true`` below.
+ """
+ # The tenant's own tier, read the way the dispatcher reads it. Grading
+ # the proposal against a different tier than the dispatch would be the
+ # console's "autopilot posture" defect one layer down: the analyst would
+ # be told a purge auto-executes and then watch it queue for approval.
+ effective = await resolve_effective_tier(db, str(user.tenant_id))
+ try:
+ outcome = await phishing_purge.propose_purge(
+ db,
+ tenant_id=user.tenant_id,
+ campaign_id=campaign_id,
+ confidence=body.confidence,
+ tier=effective.tier,
+ execute=body.execute,
+ requested_by=(user.email or "aisoc-phishing") if user else "aisoc-phishing",
+ )
+ except Exception as exc:
+ await db.rollback()
+ logger.exception("Error running phishing campaign purge")
+ raise HTTPException(status_code=503, detail="Purge dispatch failed") from exc
+ if outcome is None:
+ raise HTTPException(status_code=404, detail="Campaign not found.")
+ return outcome.as_dict()
+
+
[email protected]("/campaigns/{campaign_id}/restore", summary="Restore a purged campaign's messages")
+async def restore_campaign(
+ campaign_id: uuid.UUID,
+ db: DBSession,
+ user: Annotated[AuthUser, Depends(require_permission("actions:execute"))],
+) -> dict[str, Any]:
+ """The reverse of the purge, over the mailboxes it actually executed on.
+
+ Only rows the purge executed on are restored. Attempting a restore on a
+ mailbox that was previewed, failed, or never held the message would
+ report work that did not happen.
+ """
+ try:
+ outcome = await phishing_purge.restore_campaign(
+ db,
+ tenant_id=user.tenant_id,
+ campaign_id=campaign_id,
+ requested_by=(user.email or "aisoc-phishing") if user else "aisoc-phishing",
+ )
+ except Exception as exc:
+ await db.rollback()
+ logger.exception("Error restoring phishing campaign")
+ raise HTTPException(status_code=503, detail="Restore dispatch failed") from exc
+ if outcome is None:
+ raise HTTPException(status_code=404, detail="Campaign not found.")
+ return outcome.as_dict()
+
+
@router.get("/submissions", response_model=list[SubmissionResponse], summary="List phishing submissions")
async def list_submissions(
db: DBSession,
@@ -377,7 +604,14 @@ async def list_submissions(
raise HTTPException(status_code=503, detail="Database error") from exc
[email protected]("/{submission_id}", response_model=SubmissionResponse, summary="Get submission")
+# ``:uuid`` is load-bearing, not decoration. A bare ``{submission_id}``
+# compiles to ``[^/]+`` and swallows every sibling literal under this prefix,
+# so ``GET /phishing/campaigns`` would match here and answer 422 for a
+# resource that exists — the shape that 404'd the console's hunt run history.
+# The built-in convertor puts the UUID form in the route's own matching
+# regex, so a literal falls through whatever order the decorators are read
+# in, and a later edit cannot undo it by moving a function.
[email protected]("/{submission_id:uuid}", response_model=SubmissionResponse, summary="Get submission")
async def get_submission(submission_id: uuid.UUID, db: DBSession, user: AuthUser) -> SubmissionResponse:
row = (
await db.execute(
@@ -391,7 +625,7 @@ async def get_submission(submission_id: uuid.UUID, db: DBSession, user: AuthUser
return _row_to_submission(row)
[email protected]("/{submission_id}/retriage", response_model=SubmissionResponse, summary="Re-run triage on submission")
[email protected]("/{submission_id:uuid}/retriage", response_model=SubmissionResponse, summary="Re-run triage on submission")
async def retriage(
submission_id: uuid.UUID, db: DBSession, user: Annotated[AuthUser, Depends(require_permission("cases:write"))]
) -> SubmissionResponse:
diff --git a/services/api/app/services/phishing/intake.py b/services/api/app/services/phishing/intake.py
index 49401d013..9dfae4da5 100644
--- a/services/api/app/services/phishing/intake.py
+++ b/services/api/app/services/phishing/intake.py
@@ -240,9 +240,7 @@ def from_graph_message(payload: dict[str, Any], *, reported_by: str = "") -> Rep
return ReportedMessage(
intake_source="m365_graph",
- internet_message_id=normalise_message_id(
- headers.get("message-id") or str(payload.get("internetMessageId") or "")
- ),
+ internet_message_id=normalise_message_id(headers.get("message-id") or str(payload.get("internetMessageId") or "")),
sender=sender,
subject=str(payload.get("subject") or ""),
recipients=recipients,
diff --git a/services/api/app/services/phishing/purge.py b/services/api/app/services/phishing/purge.py
new file mode 100644
index 000000000..97929a028
--- /dev/null
+++ b/services/api/app/services/phishing/purge.py
@@ -0,0 +1,389 @@
+"""The governed purge fan-out: one dispatch per mailbox, one grading each.
+
+Gap-closure 10.3 asks for "one governed purge proposal across all
+recipients". The word doing the work is *governed*, and it decides the whole
+shape of this module.
+
+One request per mailbox, not one request with a list
+-----------------------------------------------------
+Handing a single executor twenty-five addresses would produce one approval
+covering a list the approver never read, which is exactly the defect the
+per-capability contract exists to refuse — "approving a playbook must never
+authorise whatever its steps happen to contain". So the fan-out happens here,
+above the dispatcher, and every mailbox gets its own capability contract
+grading, its own audit row, its own verification probe and its own restore
+handle.
+
+The *proposal* is still one thing. The campaign is graded once, from its
+recipient count, so an analyst approves "purge this message from 25
+mailboxes" rather than twenty-five separate prompts — and the grading they
+see is the one each dispatch will be held to, because both read the same
+``scaled_impact``.
+
+Preview is the default
+----------------------
+``execute=False`` is the signature's default and the route's default. The
+preview reports, per mailbox, what would be attempted and at what tier; it
+reports ``simulated`` and never ``purged``. ``executed`` is the single field
+meaning a vendor was touched and it is false on every preview row.
+
+What counts as purged
+---------------------
+Only a dispatch whose report says ``executed``. ``simulated``, ``dry_run``,
+``pending_approval``, ``blocked``, ``no_integration``, ``unsupported`` and
+``failed`` are all recorded under their own name, and the campaign lands on
+``partially_purged`` rather than ``purged`` when any mailbox did not. A
+fan-out that reports forty of forty purged when the message was in thirty of
+them teaches an analyst to trust a number that means nothing.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+import structlog
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.services.phishing.intake import utcnow
+from app.services.playbook_step_dispatch import dispatch_step
+
+logger = structlog.get_logger(__name__)
+
+PURGE_CAPABILITY = "purge_email"
+RESTORE_CAPABILITY = "restore_email"
+
+#: Step statuses that map onto a recipient's ``purge_state``. Anything not
+#: listed is recorded as ``failed`` with the status in ``purge_detail``, so a
+#: new step status cannot quietly become a success.
+_STATE_FROM_STATUS: dict[str, str] = {
+ "executed": "purged",
+ "simulated": "simulated",
+ "dry_run": "simulated",
+ "pending_approval": "pending_approval",
+}
+
+
+@dataclass
+class RecipientOutcome:
+ recipient: str
+ purge_state: str
+ executed: bool
+ summary: str
+ detail: str = ""
+ vendor: str = ""
+ verification: str = ""
+
+
+@dataclass
+class PurgeOutcome:
+ campaign_id: uuid.UUID
+ recipient_count: int
+ requested_impact: str
+ approval_requirement: str
+ approval_reason: str
+ executed_count: int = 0
+ preview: bool = True
+ status: str = "open"
+ recipients: list[RecipientOutcome] = field(default_factory=list)
+
+ def as_dict(self) -> dict[str, Any]:
+ return {
+ "campaign_id": str(self.campaign_id),
+ "recipient_count": self.recipient_count,
+ "impact": self.requested_impact,
+ "approval": self.approval_requirement,
+ "approval_reason": self.approval_reason,
+ "preview": self.preview,
+ "executed_count": self.executed_count,
+ "status": self.status,
+ "recipients": [
+ {
+ "recipient": r.recipient,
+ "purge_state": r.purge_state,
+ "executed": r.executed,
+ "summary": r.summary,
+ "detail": r.detail,
+ "vendor": r.vendor,
+ "verification": r.verification,
+ }
+ for r in self.recipients
+ ],
+ }
+
+
+def grade(recipient_count: int, confidence: float | None, tier: str) -> tuple[str, str, str]:
+ """``(impact, requirement, reason)`` for a purge over this many mailboxes.
+
+ Imported from the vendored action contracts so the console, the
+ dispatcher and this proposal cannot answer the question three ways — the
+ arrangement already used for the LLM input contract and the deterministic
+ narrative. ``scripts/sync_vendored_action_contracts.py --check`` keeps the
+ copy byte-identical with ``services/actions``.
+ """
+ from app._vendor.action_contracts.approval_rules import evaluate
+ from app._vendor.action_contracts.capability_contracts import CAPABILITY_CONTRACTS, scaled_impact
+
+ impact = scaled_impact(PURGE_CAPABILITY, {"recipient_count": recipient_count})
+ contract = CAPABILITY_CONTRACTS[PURGE_CAPABILITY]
+ decision = evaluate(impact=impact, declared_approval=contract.approval, confidence=confidence, tier=tier)
+ return impact.value, decision.requirement.value, decision.reason
+
+
+async def propose_purge(
+ db: AsyncSession,
+ *,
+ tenant_id: uuid.UUID,
+ campaign_id: uuid.UUID,
+ confidence: float | None = None,
+ tier: str = "L1",
+ execute: bool = False,
+ requested_by: str = "aisoc-phishing",
+) -> PurgeOutcome | None:
+ """Raise one purge proposal across a campaign's recipients.
+
+ Returns ``None`` when the campaign does not exist for this tenant, which
+ the route turns into a 404. Every other condition — no recipients, no
+ integration, an approval the tier will not grant — is reported inside the
+ outcome, because each sends an operator somewhere different and a bare
+ 404 sends them nowhere.
+ """
+ campaign = (
+ await db.execute(
+ text("""
+ SELECT id, sender, subject, recipient_count, status
+ FROM aisoc_phishing_campaigns
+ WHERE tenant_id = :tenant_id AND id = :id
+ """).bindparams(tenant_id=tenant_id, id=campaign_id)
+ )
+ ).fetchone()
+ if campaign is None:
+ return None
+
+ recipients = (
+ await db.execute(
+ text("""
+ SELECT recipient, internet_message_id
+ FROM aisoc_phishing_campaign_recipients
+ WHERE tenant_id = :tenant_id AND campaign_id = :id
+ ORDER BY recipient
+ """).bindparams(tenant_id=tenant_id, id=campaign_id)
+ )
+ ).fetchall()
+
+ impact, requirement, reason = grade(len(recipients), confidence, tier)
+ outcome = PurgeOutcome(
+ campaign_id=campaign_id,
+ recipient_count=len(recipients),
+ requested_impact=impact,
+ approval_requirement=requirement,
+ approval_reason=reason,
+ preview=not execute,
+ )
+
+ if not recipients:
+ # Not an error and not a success. A campaign whose reports named no
+ # recipients has nothing to purge, and saying so is how somebody
+ # notices an intake adapter that stopped parsing a `To` header.
+ outcome.status = campaign.status
+ logger.info("phishing_purge.no_recipients", campaign_id=str(campaign_id), tenant_id=str(tenant_id))
+ return outcome
+
+ # The campaign is graded once and every dispatch below is held to the
+ # same grading, because both read `scaled_impact` over the same count.
+ # The per-mailbox dispatch carries the count so the dispatcher's own
+ # contract check reaches the same tier rather than grading each mailbox
+ # as a one-recipient purge.
+ now = utcnow()
+ for row in recipients:
+ report = await dispatch_step(
+ db,
+ tenant_id=tenant_id,
+ capability=PURGE_CAPABILITY,
+ target=row.recipient,
+ params={
+ "internet_message_id": row.internet_message_id,
+ "recipient_count": len(recipients),
+ "campaign_id": str(campaign_id),
+ },
+ confidence=confidence,
+ dry_run=not execute,
+ requested_by=requested_by,
+ )
+ state = _STATE_FROM_STATUS.get("executed" if report.executed else report.status, "failed")
+ if state == "failed" and "not found" in (report.detail or report.summary or "").lower():
+ # A mailbox that never held the message is a distinct outcome
+ # from a mailbox the purge failed on, and only one of them is
+ # worth an operator's attention.
+ state = "not_found"
+
+ details = report.details or {}
+ await db.execute(
+ text("""
+ UPDATE aisoc_phishing_campaign_recipients
+ SET purge_state = :state,
+ purge_detail = :detail,
+ vendor = :vendor,
+ restore_message_id = COALESCE(NULLIF(:restore_id, ''), restore_message_id),
+ restore_folder_id = COALESCE(NULLIF(:restore_folder, ''), restore_folder_id),
+ last_action_at = :now
+ WHERE tenant_id = :tenant_id AND campaign_id = :cid AND recipient = :recipient
+ """).bindparams(
+ state=state,
+ detail=(report.detail or report.summary)[:2000],
+ vendor=report.vendor_id,
+ restore_id=str(details.get("restore_message_id") or ""),
+ restore_folder=str(details.get("restore_folder_id") or ""),
+ now=now,
+ tenant_id=tenant_id,
+ cid=campaign_id,
+ recipient=row.recipient,
+ )
+ )
+ outcome.recipients.append(
+ RecipientOutcome(
+ recipient=row.recipient,
+ purge_state=state,
+ executed=report.executed,
+ summary=report.summary,
+ detail=report.detail,
+ vendor=report.vendor_id,
+ verification=report.verification,
+ )
+ )
+ if report.executed:
+ outcome.executed_count += 1
+
+ outcome.status = _campaign_status(outcome, preview=not execute)
+ await _set_status(db, tenant_id=tenant_id, campaign_id=campaign_id, status=outcome.status, now=now)
+ await db.commit()
+ return outcome
+
+
+async def _set_status(db: AsyncSession, *, tenant_id: uuid.UUID, campaign_id: uuid.UUID, status: str, now: Any) -> None:
+ await db.execute(
+ text("""
+ UPDATE aisoc_phishing_campaigns
+ SET status = :status, updated_at = :now
+ WHERE id = :id AND tenant_id = :tenant_id
+ """).bindparams(status=status, now=now, id=campaign_id, tenant_id=tenant_id)
+ )
+
+
+def _campaign_status(outcome: PurgeOutcome, *, preview: bool) -> str:
+ """Where the campaign stands after this run.
+
+ A preview never advances past ``purge_proposed``: nothing was removed, so
+ a status implying it was would be the same lie as an executed count that
+ includes previews.
+ """
+ if preview:
+ return "purge_proposed"
+ if outcome.executed_count == 0:
+ return "purge_proposed"
+ if outcome.executed_count == outcome.recipient_count:
+ return "purged"
+ return "partially_purged"
+
+
+async def restore_campaign(
+ db: AsyncSession,
+ *,
+ tenant_id: uuid.UUID,
+ campaign_id: uuid.UUID,
+ confidence: float | None = None,
+ requested_by: str = "aisoc-phishing",
+) -> PurgeOutcome | None:
+ """Put a purged campaign's messages back, one mailbox at a time.
+
+ The reverse exists because the forward verb is the most disruptive one
+ this product offers. It reads the restore handles the purge stored —
+ Microsoft's move gives the message a new id in the destination folder and
+ the original folder is only knowable before the move — so this is a real
+ reversal rather than a declared one.
+
+ Only rows the purge actually executed on are restored. Attempting a
+ restore on a mailbox that was previewed, failed or never held the message
+ would report work that did not happen.
+ """
+ rows = (
+ await db.execute(
+ text("""
+ SELECT recipient, internet_message_id, restore_message_id, restore_folder_id, vendor
+ FROM aisoc_phishing_campaign_recipients
+ WHERE tenant_id = :tenant_id AND campaign_id = :id AND purge_state = 'purged'
+ ORDER BY recipient
+ """).bindparams(tenant_id=tenant_id, id=campaign_id)
+ )
+ ).fetchall()
+
+ exists = (
+ await db.execute(
+ text("SELECT 1 FROM aisoc_phishing_campaigns WHERE tenant_id = :tenant_id AND id = :id").bindparams(
+ tenant_id=tenant_id, id=campaign_id
+ )
+ )
+ ).fetchone()
+ if exists is None:
+ return None
+
+ impact, requirement, reason = grade(len(rows), confidence, "L4")
+ outcome = PurgeOutcome(
+ campaign_id=campaign_id,
+ recipient_count=len(rows),
+ requested_impact=impact,
+ approval_requirement=requirement,
+ approval_reason=reason,
+ preview=False,
+ )
+ now = utcnow()
+ for row in rows:
+ report = await dispatch_step(
+ db,
+ tenant_id=tenant_id,
+ capability=RESTORE_CAPABILITY,
+ target=row.recipient,
+ params={
+ "restore_message_id": row.restore_message_id,
+ "restore_folder_id": row.restore_folder_id,
+ "internet_message_id": row.internet_message_id,
+ "alert_vendor": row.vendor,
+ },
+ vendor_id=row.vendor,
+ confidence=confidence,
+ dry_run=False,
+ requested_by=requested_by,
+ )
+ if report.executed:
+ outcome.executed_count += 1
+ await db.execute(
+ text("""
+ UPDATE aisoc_phishing_campaign_recipients
+ SET purge_state = 'restored', purge_detail = :detail, last_action_at = :now
+ WHERE tenant_id = :tenant_id AND campaign_id = :cid AND recipient = :recipient
+ """).bindparams(
+ detail=(report.detail or report.summary)[:2000],
+ now=now,
+ tenant_id=tenant_id,
+ cid=campaign_id,
+ recipient=row.recipient,
+ )
+ )
+ outcome.recipients.append(
+ RecipientOutcome(
+ recipient=row.recipient,
+ purge_state="restored" if report.executed else "purged",
+ executed=report.executed,
+ summary=report.summary,
+ detail=report.detail,
+ vendor=report.vendor_id,
+ verification=report.verification,
+ )
+ )
+
+ outcome.status = "restored" if rows and outcome.executed_count == len(rows) else "partially_purged"
+ await _set_status(db, tenant_id=tenant_id, campaign_id=campaign_id, status=outcome.status, now=now)
+ await db.commit()
+ return outcome