feat: add optional ai and mcp automation
This commit is contained in:
Christian Krakau-Louis
@@ -121,8 +121,8 @@ The milestone breakdown in `docs/milestones.md` is intentionally focused on exit
|
||||
|
||||
### Priority (Now / Next / Later)
|
||||
|
||||
- **Now**: Milestone 16 (optional AI/MCP automation).
|
||||
- **Next**: release hardening and follow-up triage.
|
||||
- **Now**: release hardening and follow-up triage.
|
||||
- **Next**: production smoke testing and deployment feedback.
|
||||
- **Later**: production-driven improvements from deployment feedback.
|
||||
|
||||
### Tentative Release Plan (Subject to Change)
|
||||
|
||||
@@ -28,3 +28,5 @@ For Microsoft 365 setup, see [Microsoft 365 Mail Sources](user_guide/microsoft36
|
||||
For SMTP TLS reporting imports and privacy controls, see [TLS Reports](user_guide/tls_reports.md).
|
||||
|
||||
For aggregate-report parser support, known edge cases, and fixture guidance, see [DMARC Aggregate Format Compatibility](reference/dmarc-compatibility.md).
|
||||
|
||||
For opt-in AI summaries and read-only MCP automation, see [AI and MCP Automation](reference/ai-mcp-automation.md).
|
||||
|
||||
+18
-5
@@ -270,15 +270,28 @@ Exit criteria:
|
||||
|
||||
## Milestone 16: Optional AI + MCP Automation Layer
|
||||
|
||||
Status: Backlog
|
||||
Status: Delivered
|
||||
|
||||
Goal: provide opt-in assistance and agent-friendly automation without compromising privacy or safety.
|
||||
|
||||
Planned:
|
||||
- Evidence-first summaries and remediation plans that link back to the underlying DMARC data.
|
||||
- Pluggable model provider support with strong redaction and “no secrets in prompts” guarantees.
|
||||
- A DMARQ MCP server that starts read-only (posture queries, reports, recommendations).
|
||||
- Optional action tools (e.g., proposing DNS changes) gated behind explicit human confirmation and audit logging.
|
||||
- Evidence-first summaries and remediation plans that link back to the
|
||||
underlying DMARC data. Delivered with redacted safe-context generation,
|
||||
deterministic summaries, recommendations, and evidence links back to domain
|
||||
detail views.
|
||||
- Pluggable model provider support with strong redaction and “no secrets in
|
||||
prompts” guarantees. Delivered with explicit admin settings for template,
|
||||
local, and remote provider modes, model/base-URL configuration, strict or
|
||||
balanced redaction, and no stored provider secrets.
|
||||
- A DMARQ MCP server that starts read-only (posture queries, reports,
|
||||
recommendations). Delivered with an opt-in `/api/v1/mcp` JSON-RPC surface,
|
||||
`mcp:read` scoped API tokens, read-only tool metadata, and audited tool
|
||||
calls.
|
||||
- Optional action tools (e.g., proposing DNS changes) gated behind explicit
|
||||
human confirmation and audit logging. Delivered as reproducible proposal
|
||||
artifacts that never mutate DNS or DMARQ state unless action tools are
|
||||
explicitly enabled and a human confirms the proposal ID; confirmation is
|
||||
audited and no external changes are applied.
|
||||
|
||||
Exit criteria:
|
||||
- Users can enable AI/agent workflows intentionally, understand what data is shared, and keep deployments safe by default.
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
# AI and MCP Automation
|
||||
|
||||
Milestone 16 adds optional automation surfaces that are safe by default:
|
||||
|
||||
- AI assistance is disabled until `ai.enabled=true`.
|
||||
- MCP access is disabled until `mcp.enabled=true`.
|
||||
- MCP requires scoped API tokens with `mcp:read`.
|
||||
- Provider secrets are not stored in DMARQ settings.
|
||||
- Safe context redacts secret-like key/value fragments, bearer tokens, long
|
||||
opaque values, and email local-parts in strict mode.
|
||||
- Action tools produce reviewable proposals first. Confirmation is audited, and
|
||||
the current implementation does not apply DNS or other external changes.
|
||||
|
||||
## Settings
|
||||
|
||||
| Key | Default | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `ai.enabled` | `false` | Enables AI assistance endpoints |
|
||||
| `ai.provider` | `template` | `template`, `local`, or `remote` provider mode |
|
||||
| `ai.model` | empty | Optional model name |
|
||||
| `ai.remote_base_url` | empty | Optional remote provider URL |
|
||||
| `ai.redaction_mode` | `strict` | `strict` or `balanced` safe-context redaction |
|
||||
| `ai.action_tools_enabled` | `false` | Allows proposal confirmation records |
|
||||
| `mcp.enabled` | `false` | Enables the read-only MCP endpoint |
|
||||
|
||||
Use 1Password or another deployment secret injector for provider credentials.
|
||||
Do not put provider API keys into DMARQ settings.
|
||||
|
||||
## Safe Context
|
||||
|
||||
`GET /api/v1/ai/domains/{domain}/context` builds the payload that model or
|
||||
agent surfaces are allowed to inspect. It includes:
|
||||
|
||||
- domain summary counts
|
||||
- recent report metadata
|
||||
- top sending sources
|
||||
- evidence links to the UI
|
||||
- redaction metadata
|
||||
|
||||
The payload deliberately excludes raw report XML, mailbox credentials, OAuth
|
||||
tokens, notification target URLs, and original forensic message content.
|
||||
|
||||
## MCP
|
||||
|
||||
`POST /api/v1/mcp` accepts minimal JSON-RPC requests for:
|
||||
|
||||
- `initialize`
|
||||
- `tools/list`
|
||||
- `tools/call`
|
||||
|
||||
The current tools are read-only:
|
||||
|
||||
- `list_domains`
|
||||
- `domain_summary`
|
||||
- `action_proposals`
|
||||
|
||||
Create a token with the `mcp:read` scope and send it through `X-API-Key`.
|
||||
|
||||
## Audit
|
||||
|
||||
DMARQ records sanitized workspace audit events for:
|
||||
|
||||
- `ai.summary_generated`
|
||||
- `ai.action_proposals_generated`
|
||||
- `ai.action_proposal_confirmed`
|
||||
- `mcp.tool_called`
|
||||
|
||||
Audit details are sanitized with the same secret-field redaction used for other
|
||||
workspace audit logs.
|
||||
@@ -61,6 +61,7 @@ through the `/public` path and avoid UI-specific payloads.
|
||||
| `GET /public/domains/{domain_id}/reports` | `reports:read` | Recent DMARC aggregate report summaries |
|
||||
| `GET /public/domains/{domain_id}/posture` | `posture:read` | Evidence-first posture dashboard payload |
|
||||
| `GET /public/tls-reports/summary` | `tls-reports:read` | SMTP TLS report trends and failure groups |
|
||||
| `POST /mcp` | `mcp:read` | Read-only MCP-style JSON-RPC tool endpoint |
|
||||
|
||||
Successful public API calls update the token's last-used timestamp, source IP,
|
||||
and usage count for auditing.
|
||||
@@ -214,6 +215,86 @@ Request:
|
||||
Updates workspace retention controls and writes a sanitized
|
||||
`workspace.retention_updated` audit event.
|
||||
|
||||
### Optional AI Assistance
|
||||
|
||||
AI assistance endpoints require administrator access and remain disabled until
|
||||
`ai.enabled=true` is set in Settings.
|
||||
|
||||
#### Read AI Configuration
|
||||
|
||||
```text
|
||||
GET /ai/config
|
||||
```
|
||||
|
||||
Returns provider mode, model name, whether a remote base URL is configured,
|
||||
redaction mode, action-tool state, MCP state, and data-handling guarantees. Raw
|
||||
provider credentials are not stored or returned.
|
||||
|
||||
#### Build Safe Context
|
||||
|
||||
```text
|
||||
GET /ai/domains/{domain}/context
|
||||
```
|
||||
|
||||
Returns a redacted context payload for a domain. The payload includes summary
|
||||
counts, recent reports, top sources, evidence links, and the redaction rules
|
||||
that were applied.
|
||||
|
||||
#### Build Evidence Summary
|
||||
|
||||
```text
|
||||
GET /ai/domains/{domain}/summary
|
||||
```
|
||||
|
||||
Returns a deterministic evidence-first summary and remediation plan. Each
|
||||
recommendation includes evidence links back to the underlying DMARC data.
|
||||
|
||||
#### Build Action Proposals
|
||||
|
||||
```text
|
||||
GET /ai/domains/{domain}/action-proposals
|
||||
```
|
||||
|
||||
Returns reproducible proposal artifacts. Proposal generation is read-only and
|
||||
does not apply DNS or configuration changes.
|
||||
|
||||
#### Confirm Proposal
|
||||
|
||||
```text
|
||||
POST /ai/domains/{domain}/action-proposals/confirm
|
||||
```
|
||||
|
||||
Requires `ai.action_tools_enabled=true` and a `confirmation_text` equal to the
|
||||
proposal ID. Confirmation is written to the workspace audit log. The current
|
||||
implementation records human confirmation but does not apply external changes.
|
||||
|
||||
### MCP Endpoint
|
||||
|
||||
The MCP endpoint is disabled until `mcp.enabled=true` is set. It requires a
|
||||
scoped API token with `mcp:read`.
|
||||
|
||||
```text
|
||||
POST /mcp
|
||||
```
|
||||
|
||||
Supported JSON-RPC methods:
|
||||
|
||||
| Method | Purpose |
|
||||
| --- | --- |
|
||||
| `initialize` | Return server capabilities |
|
||||
| `tools/list` | List read-only tool metadata |
|
||||
| `tools/call` | Call a read-only tool |
|
||||
|
||||
Available tools:
|
||||
|
||||
| Tool | Purpose |
|
||||
| --- | --- |
|
||||
| `list_domains` | List monitored domains and aggregate counts |
|
||||
| `domain_summary` | Return an evidence-first summary for one domain |
|
||||
| `action_proposals` | Return reviewable remediation proposals without applying changes |
|
||||
|
||||
Every successful tool call is audited as `mcp.tool_called`.
|
||||
|
||||
### Domains
|
||||
|
||||
#### List Domains
|
||||
|
||||
@@ -59,6 +59,8 @@ Current audit coverage includes:
|
||||
- notification and forensic setting changes
|
||||
- webhook creation, update, disable, and test actions
|
||||
- manual DKIM selector add/remove actions
|
||||
- AI summary generation, action proposal generation/confirmation, and MCP
|
||||
read-only tool calls
|
||||
|
||||
Audit details redact secret-like fields such as passwords, OAuth tokens, API
|
||||
keys, and webhook signing secrets.
|
||||
|
||||
Reference in New Issue
Block a user