docs: Email Security CLI and AI triage - #363
Merged
Merged
Conversation
Documents the agent, its key, and the trigger rules as examples an operator adapts rather than records an extension installs. The extension deliberately installs nothing: a disabled record that still needs a credential and an edit before it works is the worst of both, and it makes the product opinionated about a composition that belongs to the customer. Keeps the reasoning the code carried: what the agent may do is the mailsec.act permission on its key rather than a product setting, budgets are the session's, the user-report trigger has no verdict filter, and the message trigger fires on suspicious rather than malicious. NOT PUSHED — see the note on the branch. This repo is public and Email Security is pre-GA.
Two pages for the Email Security section. CLI: the whole `limacharlie mailsec` surface, plus the five behaviours that bite a script author if they are not stated — actions preview until --confirm, `alert_only` is a success rather than a failure, filters are tri-state so an unset boolean means unconstrained rather than false, the EML download is audited and requires a justification, and backtest reports what it could NOT examine so a precision figure is never read as covering more than it did. AI TRIAGE: worked examples rather than anything installed for you. An earlier draft had the extension write these records on subscribe, disabled and deliberately incomplete — which left an operator hunting for records they did not ask for, while the extension had already made shape decisions that belong to them. Documented examples an operator adapts is the honest form. The reasoning the code carried survives as why the example looks the way it does: what the agent may DO is the mailsec.act permission on its key rather than a product setting (a prompt is a request, not a control), budgets and turn limits are the session's, the user-report trigger has no verdict filter because a human reporting something is evidence the scorer did not have, and the message trigger fires on `suspicious` rather than `malicious` because the undecided band is where the analyst toil is. Commands and flags verified against the CLI rather than from memory: all 22 documented commands resolve, and documenting `message eml` surfaced a real collision — its file option was `--output`, which shadowed the global `--output <format>` so that `--output yaml` would silently write a file named 'yaml'. Fixed in python-limacharlie and documented here as --out-file.
lcbill
previously approved these changes
Aug 28, 2026
A `!!! warning "Private beta"` at the top of both pages, and the nav section titled "Email Security (Private Beta)" so the status is visible in the sidebar without opening a page. Says the three things a reader actually needs: access is per-organization and the extension will simply be absent if they do not have it; the surface may change in ways that are not backwards compatible, so pin a CLI version if you script against it; and talk to us before relying on it in production. Worth being explicit rather than tasteful about this. These pages describe commands that ship in an unreleased CLI, against an API whose event shapes are still moving — a reader who scripts against them on the assumption of stability has been misled by our silence, not by anything we said.
lcbill
approved these changes
Aug 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two pages for a new Email Security section.
CLI
The whole
limacharlie mailsecsurface, plus the five behaviours that bite a script author if nobody states them:--confirm— right default for an operation whose blast radius is every mailbox that received an attack.alert_onlyis a success, not a failure — the action was decided and deliberately not performed because the org is not in enforce mode.false.skipped_no_raw,truncated, andprecision: nullrather than0), so a precision figure is never read as covering more than it did.AI triage
Worked examples rather than anything installed for you. An earlier draft had the extension write these records on subscribe — disabled and deliberately incomplete — which left an operator hunting for records they never asked for while the extension had already made shape decisions that belong to them. Documented examples an operator adapts is the honest form.
The reasoning survives as why the example looks this way: what the agent may do is the
mailsec.actpermission on its key rather than a product setting (a prompt is a request, not a control); budgets and turn limits belong to the session; the user-report trigger has no verdict filter because a human reporting something is evidence the scorer did not have; and the message trigger fires onsuspiciousrather thanmaliciousbecause the undecided band is where the analyst toil is.Verification
Commands and flags checked against the CLI rather than written from memory — all 22 documented commands resolve. Doing that surfaced a real bug:
message eml's file option was--output, shadowing the global--output <format>, so--output yamlwould have silently written a file namedyaml. Fixed in python-limacharlie#344 and documented here as--out-file.Note: the
limacharlie mailsecCLI ships in that PR and is not in a released package yet, so these pages describe a surface that lands with it.