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.

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.py
index 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.py
index 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_contract
class 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_contract
class 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.py
index 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.py
index 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.py
index 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.py
index 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 mailbox
from 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 M365SearchMailboxes
from app.live_actions.models import LiveActionRequest, LiveActionStatus
from app.models.action import ActionRequest, ActionStatus, ActionType
from app.services.verification import PostActionVerifier, VerificationOutcome
MAILBOX_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 False
assert "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.asyncio
async 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: SLF001
diff --git a/services/api/app/services/agent_tools/vendor_aliases.py b/services/api/app/services/agent_tools/vendor_aliases.py
index 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"),
}