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
refactor(actions): search_mailboxes is a read, not a state change
Beenu Aroradb02af90495b
diff --git a/services/actions/app/executors/mailbox.py b/services/actions/app/executors/mailbox.pyindex 7ae5161cb..9c78defb9 100644--- a/services/actions/app/executors/mailbox.py+++ b/services/actions/app/executors/mailbox.py@@ -168,48 +168,6 @@ class _MailboxExecutor(BaseExecutor):return vendor, client, None-class SearchMailboxesExecutor(_MailboxExecutor):- """Find the copies of one reported message. The read the others depend on."""-- action_type = ActionType.SEARCH_MAILBOXES-- async def execute(self, request: ActionRequest) -> ActionResult:- vendor, client, early = self._preamble(request)- if early is not None:- return early- params = dict(request.parameters or {})- try:- if vendor == M365:- matches = await client.search_messages(- request.target,- internet_message_id=str(params.get("internet_message_id") or ""),- sender=str(params.get("sender") or ""),- subject=str(params.get("subject") or ""),- received_after=str(params.get("received_after") or ""),- limit=int(params.get("limit") or 25),- )- else:- matches = await client.search_messages(- request.target,- internet_message_id=str(params.get("internet_message_id") or ""),- sender=str(params.get("sender") or ""),- limit=int(params.get("limit") or 25),- )- except ValueError as exc:- # The Gmail sanitiser refuses rather than escapes, and a refusal- # is a failure rather than an empty result: an escaped value that- # reaches the API and matches nothing reports a clean mailbox- # from a search that never ran.- return self._refused(request, f"{vendor} search refused the query: {exc}", vendor=vendor)- except Exception as exc: # noqa: BLE001 - a vendor error is FAILED, never silent- return self._failed(request, vendor, exc)- return self._ok(- request,- vendor,- {"mailbox": request.target, "matches": matches, "match_count": len(matches)},- )--class PurgeEmailExecutor(_MailboxExecutor):"""Soft-delete one copy of a message. Reversible by ``RestoreEmailExecutor``."""@@ -436,7 +394,6 @@ __all__ = ["PurgeEmailExecutor","RECOVERABLE_ITEMS","RestoreEmailExecutor",- "SearchMailboxesExecutor","UnblockSenderExecutor","choose_vendor",]diff --git a/services/actions/app/live_actions/builtins.py b/services/actions/app/live_actions/builtins.pyindex 5469e3cbb..bb4085147 100644--- a/services/actions/app/live_actions/builtins.py+++ b/services/actions/app/live_actions/builtins.py@@ -64,7 +64,6 @@ from app.executors.mailbox import (BlockSenderExecutor,PurgeEmailExecutor,RestoreEmailExecutor,- SearchMailboxesExecutor,UnblockSenderExecutor,)from app.executors.network import (@@ -101,7 +100,9 @@ from .investigation_reads import (DefenderLookupEndpointTelemetry,DefenderUnisolateHost,EntraGetUserActivity,+ GmailSearchMailboxes,GoogleWorkspaceGetUserActivity,+ M365SearchMailboxes,OktaGetUserActivity,SentinelOneGetDetections,SentinelOneGetHost,@@ -1033,18 +1034,6 @@ class _MailboxAdapter(_LegacyExecutorAdapter):return str(output.get("summary") or super()._summarise(output, status))-@apply_contract-class M365SearchMailboxes(_MailboxAdapter):- vendor_id = M365- capability = "search_mailboxes"- description = "Find copies of a reported message in a Microsoft 365 mailbox."- requires_credentials = True- _legacy_executor = SearchMailboxesExecutor()- _legacy_action_type = ActionType.SEARCH_MAILBOXES- _credential_keys = M365_CLIENT_PARAM_KEYS- _vendor_pin = M365--@apply_contractclass M365PurgeEmail(_MailboxAdapter):vendor_id = M365@@ -1093,18 +1082,6 @@ class M365UnblockSender(_MailboxAdapter):_vendor_pin = M365-@apply_contract-class GmailSearchMailboxes(_MailboxAdapter):- vendor_id = GOOGLE_WORKSPACE- capability = "search_mailboxes"- description = "Find copies of a reported message in a Gmail mailbox."- requires_credentials = True- _legacy_executor = SearchMailboxesExecutor()- _legacy_action_type = ActionType.SEARCH_MAILBOXES- _credential_keys = GMAIL_CLIENT_PARAM_KEYS- _vendor_pin = GOOGLE_WORKSPACE--@apply_contractclass GmailPurgeEmail(_MailboxAdapter):vendor_id = GOOGLE_WORKSPACE@@ -1177,6 +1154,11 @@ _BUILTIN_ADAPTERS: tuple[type[LiveActionExecutor], ...] = (GoogleWorkspaceGetUserActivity,AWSLookupCloudAudit,DefenderLookupEndpointTelemetry,+ # Depth 7.1. The read every mailbox-remediation verb depends on: a+ # purge takes a per-mailbox message id, and only a search maps one+ # internet message id onto the mailboxes holding a copy.+ M365SearchMailboxes,+ GmailSearchMailboxes,# Rollback for the most disruptive action, which had no executor.CrowdStrikeUnisolateHost,DefenderUnisolateHost,@@ -1253,12 +1235,10 @@ _BUILTIN_ADAPTERS: tuple[type[LiveActionExecutor], ...] = (# AISOC_FEATURE_MAILBOX_REMEDIATION is set. Gating registration instead# would make a disabled deployment answer executor_not_found, which# reads as a missing integration rather than as a deliberate setting.- M365SearchMailboxes,M365PurgeEmail,M365RestoreEmail,M365BlockSender,M365UnblockSender,- GmailSearchMailboxes,GmailPurgeEmail,GmailRestoreEmail,GmailBlockSender,diff --git a/services/actions/app/live_actions/investigation_reads.py b/services/actions/app/live_actions/investigation_reads.pyindex 01898e594..10ae07df3 100644--- a/services/actions/app/live_actions/investigation_reads.py+++ b/services/actions/app/live_actions/investigation_reads.py@@ -35,7 +35,9 @@ from app.clients.factories import (_cloudtrail_client,_cs_client,_entra_client,+ _gmail_client,_gws_client,+ _m365_mail_client,_mde_client,_okta_client,_s1_client,@@ -844,3 +846,134 @@ class DefenderUnisolateHost(LiveActionExecutor):"Defender release failed",error=f"Defender release failed: {exc}",)+++# ─── Depth 7.1: find a reported message across mailboxes ────────────────────+#+# `search_mailboxes` is the read every mailbox-remediation verb depends on: a+# purge takes a per-mailbox message id, and only a search maps one internet+# message id onto the mailboxes holding a copy. It lives here rather than+# beside the state-changing arms in `builtins.py` because it is a read, and+# because reads are what this module is.+#+# It is gated by the same feature flag as the purge. A read of somebody's+# mailbox is not a neutral act, and a deployment that has not enabled mailbox+# remediation has not consented to AiSOC enumerating its mail either.+++def _mailbox_feature_enabled() -> bool:+ # Imported at call time rather than at module scope: `get_settings` is+ # `lru_cache`d and reading it at import would freeze the value before a+ # test or an entrypoint has had a chance to set the environment.+ from app.core.config import get_settings++ return bool(get_settings().AISOC_FEATURE_MAILBOX_REMEDIATION)+++def _mailbox_disabled(executor: LiveActionExecutor, request: LiveActionRequest) -> LiveActionResult:+ from app.executors.mailbox import DISABLED_REASON++ return _result(+ executor,+ request,+ LiveActionStatus.FAILED,+ "mailbox search not attempted",+ details={"executed": False},+ error=DISABLED_REASON,+ )+++@apply_contract+class M365SearchMailboxes(LiveActionExecutor):+ vendor_id = "m365"+ capability = "search_mailboxes"+ description = "Find copies of a reported message in a Microsoft 365 mailbox."+ requires_credentials = True++ async def execute(self, request: LiveActionRequest) -> LiveActionResult:+ params: dict[str, Any] = request.params or {}+ target = str(request.target or "")+ if not _mailbox_feature_enabled():+ return _mailbox_disabled(self, request)+ if request.dry_run:+ return _preview(self, request, target, "Microsoft 365")++ client = _m365_mail_client(params)+ if client is None:+ return _missing_credentials(self, request, "Microsoft 365")+ try:+ matches = await client.search_messages(+ target,+ internet_message_id=str(params.get("internet_message_id") or ""),+ sender=str(params.get("sender") or ""),+ subject=str(params.get("subject") or ""),+ received_after=str(params.get("received_after") or ""),+ limit=int(params.get("limit") or 25),+ )+ except ValueError as exc:+ return _result(self, request, LiveActionStatus.FAILED, "Microsoft 365 search refused", error=str(exc))+ except Exception as exc: # noqa: BLE001+ logger.warning("search_mailboxes.failed", vendor="m365", error=str(exc))+ return _result(+ self,+ request,+ LiveActionStatus.FAILED,+ "Microsoft 365 mailbox search failed",+ error=f"Microsoft 365 mailbox search failed: {exc}",+ )+ return _result(+ self,+ request,+ LiveActionStatus.SUCCEEDED,+ f"{len(matches)} matching message(s) in {target}",+ details={"executed": True, "mailbox": target, "matches": matches, "match_count": len(matches)},+ )+++@apply_contract+class GmailSearchMailboxes(LiveActionExecutor):+ vendor_id = "google_workspace"+ capability = "search_mailboxes"+ description = "Find copies of a reported message in a Gmail mailbox."+ requires_credentials = True++ async def execute(self, request: LiveActionRequest) -> LiveActionResult:+ params: dict[str, Any] = request.params or {}+ target = str(request.target or "")+ if not _mailbox_feature_enabled():+ return _mailbox_disabled(self, request)+ if request.dry_run:+ return _preview(self, request, target, "Google Workspace")++ client = _gmail_client(params)+ if client is None:+ return _missing_credentials(self, request, "Google Workspace")+ try:+ matches = await client.search_messages(+ target,+ internet_message_id=str(params.get("internet_message_id") or ""),+ sender=str(params.get("sender") or ""),+ limit=int(params.get("limit") or 25),+ )+ except ValueError as exc:+ # The Gmail query sanitiser refuses rather than escapes, and a+ # refusal is a failure rather than an empty result: an escaped+ # value that reaches the API and matches nothing reports a clean+ # mailbox from a search that never ran.+ return _result(self, request, LiveActionStatus.FAILED, "Gmail search refused the query", error=str(exc))+ except Exception as exc: # noqa: BLE001+ logger.warning("search_mailboxes.failed", vendor="google_workspace", error=str(exc))+ return _result(+ self,+ request,+ LiveActionStatus.FAILED,+ "Gmail mailbox search failed",+ error=f"Gmail mailbox search failed: {exc}",+ )+ return _result(+ self,+ request,+ LiveActionStatus.SUCCEEDED,+ f"{len(matches)} matching message(s) in {target}",+ details={"executed": True, "mailbox": target, "matches": matches, "match_count": len(matches)},+ )diff --git a/services/actions/app/models/action.py b/services/actions/app/models/action.pyindex ff1a326a3..3ce585bf8 100644--- a/services/actions/app/models/action.py+++ b/services/actions/app/models/action.py@@ -92,7 +92,11 @@ class ActionType(str, Enum):# property of the dispatch rather than of the verb, so the entry in# ACTION_BLAST_RADIUS below is its single-mailbox floor and# `capability_contracts.scaled_impact` raises it per campaign.- SEARCH_MAILBOXES = "search_mailboxes"+ #+ # `search_mailboxes` is deliberately absent: it is read-only, declares no+ # verification probe, and so needs nothing this enum provides. Adding it+ # anyway would put a read on the ungoverned `POST /actions` surface for+ # no gain. Its arms are native read executors in `investigation_reads`.PURGE_EMAIL = "purge_email"RESTORE_EMAIL = "restore_email"BLOCK_SENDER = "block_sender"@@ -163,7 +167,6 @@ ACTION_BLAST_RADIUS: dict[ActionType, BlastRadius] = {# contract where the parameters are in scope. MEDIUM is already above# `_AUTO_EXECUTE_LIMIT`'s sibling tiers for the legacy door's purposes# and `APPROVAL_REQUIRED_ACTIONS` below makes the point unconditional.- ActionType.SEARCH_MAILBOXES: BlastRadius.MINIMAL,ActionType.PURGE_EMAIL: BlastRadius.MEDIUM,ActionType.RESTORE_EMAIL: BlastRadius.LOW,ActionType.BLOCK_SENDER: BlastRadius.LOW,diff --git a/services/actions/app/services/executor_registry.py b/services/actions/app/services/executor_registry.pyindex 655c60493..c5ba68db8 100644--- a/services/actions/app/services/executor_registry.py+++ b/services/actions/app/services/executor_registry.py@@ -25,7 +25,6 @@ from app.executors.mailbox import (BlockSenderExecutor,PurgeEmailExecutor,RestoreEmailExecutor,- SearchMailboxesExecutor,UnblockSenderExecutor,)from app.executors.network import AllowIPExecutor, BlockDomainExecutor, BlockIPExecutor@@ -77,7 +76,6 @@ EXECUTOR_REGISTRY = {# message" and both doors reach it. They are here because the post-action# verifier is keyed by ActionType: a capability that declares a probe and# has no ActionType declares a probe nothing can call.- ActionType.SEARCH_MAILBOXES: SearchMailboxesExecutor(),ActionType.PURGE_EMAIL: PurgeEmailExecutor(),ActionType.RESTORE_EMAIL: RestoreEmailExecutor(),ActionType.BLOCK_SENDER: BlockSenderExecutor(),diff --git a/services/actions/tests/test_mailbox_remediation.py b/services/actions/tests/test_mailbox_remediation.pyindex 17a536671..d17a9bff1 100644--- a/services/actions/tests/test_mailbox_remediation.py+++ b/services/actions/tests/test_mailbox_remediation.py@@ -41,7 +41,6 @@ from app.executors import mailboxfrom app.executors.mailbox import (BlockSenderExecutor,PurgeEmailExecutor,- SearchMailboxesExecutor,choose_vendor,)from app.live_actions import builtins, dispatcher, registry@@ -51,11 +50,16 @@ from app.live_actions.capability_contracts import (scaled_impact,)from app.live_actions.contract import ActionImpact, ApprovalRequirement, Reversal+from app.live_actions.investigation_reads import M365SearchMailboxesfrom app.live_actions.models import LiveActionRequest, LiveActionStatusfrom app.models.action import ActionRequest, ActionStatus, ActionTypefrom app.services.verification import PostActionVerifier, VerificationOutcomeMAILBOX_VERBS = ("search_mailboxes", "purge_email", "restore_email", "block_sender", "unblock_sender")+#: The four that change state. `search_mailboxes` is a native read in+#: `investigation_reads` with no ActionType and no legacy executor behind+#: it, so the adapter-shaped assertions below do not apply to it.+STATE_CHANGING_VERBS = ("purge_email", "restore_email", "block_sender", "unblock_sender")VENDORS = ("m365", "google_workspace")#: RFC 5737 documentation addresses and RFC 2606 names throughout. Nothing@@ -164,10 +168,9 @@ class TestOffByDefault:assert ActionsSettings.model_fields["AISOC_FEATURE_MAILBOX_REMEDIATION"].default is False@pytest.mark.asyncio- @pytest.mark.parametrize("action_type", [ActionType.SEARCH_MAILBOXES, ActionType.PURGE_EMAIL, ActionType.BLOCK_SENDER])+ @pytest.mark.parametrize("action_type", [ActionType.PURGE_EMAIL, ActionType.BLOCK_SENDER])async def test_disabled_fails_and_says_why_rather_than_simulating(self, action_type: ActionType) -> None:executor = {- ActionType.SEARCH_MAILBOXES: SearchMailboxesExecutor(),ActionType.PURGE_EMAIL: PurgeEmailExecutor(),ActionType.BLOCK_SENDER: BlockSenderExecutor(),}[action_type]@@ -176,6 +179,20 @@ class TestOffByDefault:assert result.output["executed"] is Falseassert "AISOC_FEATURE_MAILBOX_REMEDIATION" in (result.error or "")+ @pytest.mark.asyncio+ async def test_the_read_is_gated_too(self) -> None:+ """Enumerating a tenant's mail is not a neutral act, so the read is gated with the writes."""+ result = await M365SearchMailboxes().execute(+ LiveActionRequest(+ capability="search_mailboxes",+ vendor_id="m365",+ target=MAILBOX,+ params={"internet_message_id": INTERNET_ID, **M365_CREDENTIALS},+ )+ )+ assert result.status is LiveActionStatus.FAILED+ assert "AISOC_FEATURE_MAILBOX_REMEDIATION" in (result.error or "")+@pytest.mark.asyncioasync def test_disabled_reads_differently_from_a_missing_credential(self, monkeypatch: pytest.MonkeyPatch) -> None:"""Three causes, three next steps. A shared message sends an operator to the wrong one."""@@ -244,11 +261,16 @@ class TestTheRequestShapeIsWhatTheVendorDocuments:route = respx.get(url__regex=r"https://graph\.microsoft\.com/v1\.0/users/.*/messages").mock(return_value=httpx.Response(200, json={"value": [GRAPH_MESSAGE]}))- result = await SearchMailboxesExecutor().execute(- _request(ActionType.SEARCH_MAILBOXES, internet_message_id=INTERNET_ID.strip("<>"), **M365_CREDENTIALS)+ result = await M365SearchMailboxes().execute(+ LiveActionRequest(+ capability="search_mailboxes",+ vendor_id="m365",+ target=MAILBOX,+ params={"internet_message_id": INTERNET_ID.strip("<>"), **M365_CREDENTIALS},+ ))- assert result.status is ActionStatus.COMPLETED- assert result.output["match_count"] == 1+ assert result.status is LiveActionStatus.SUCCEEDED+ assert result.details["match_count"] == 1# Read the decoded parameters, not the raw URL: percent-encoding# would hide both of these assertions behind `%27%3C`.params = route.calls.last.request.url.params@@ -509,7 +531,7 @@ class TestVendorSelection:def test_the_adapter_pins_its_own_vendor(self) -> None:for vendor in VENDORS:- for capability in MAILBOX_VERBS:+ for capability in STATE_CHANGING_VERBS:executor = registry.get_executor(vendor, capability)assert executor._vendor_pin == vendor # noqa: SLF001@@ -520,7 +542,7 @@ class TestVendorSelection:"google_workspace": set(mailbox.GMAIL_CLIENT_PARAM_KEYS),}for vendor in VENDORS:- for capability in MAILBOX_VERBS:+ for capability in STATE_CHANGING_VERBS:executor = registry.get_executor(vendor, capability)assert set(executor._credential_keys) == expected[vendor] # noqa: SLF001diff --git a/services/api/app/services/agent_tools/vendor_aliases.py b/services/api/app/services/agent_tools/vendor_aliases.pyindex cc5e2390a..232826233 100644--- a/services/api/app/services/agent_tools/vendor_aliases.py+++ b/services/api/app/services/agent_tools/vendor_aliases.py@@ -52,6 +52,13 @@ VENDOR_CONNECTOR_TYPES: dict[str, tuple[str, ...]] = {"defender": ("azure_defender",),"entra": ("azure_entra",),"aws": ("aws_cloudtrail", "aws_guardduty", "aws_security_hub"),+ # Depth 7.1. The mailbox arms are named for the product, `m365`, and the+ # connector a tenant saves is `m365_audit`. `azure_entra` is listed+ # second because the three credentials both read are the same Azure app+ # registration: a tenant that configured Entra ID for identity response+ # has already granted what Graph mail needs, and refusing to find them+ # would report `no_integration` for a tenant that has one.+ "m365": ("m365_audit", "azure_entra"),}