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.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
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.pyindex 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.pyindex 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 textfrom app.api.v1.deps import AuthUser, DBSession, require_permissionfrom app.core.airgap import AirgapViolation, enforce_airgap_for_url+from app.services.autonomy_effective import resolve_effective_tierfrom app.services.llm_safety import LLMContractViolation, safe_chat_completions_requestfrom 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_purgefrom app.services.sandbox.enrichment import enrich_file_hashlogger = 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: AuthUserreturn _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.pyindex 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 = "") -> Repreturn 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.pynew file mode 100644index 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