AI Governance

AI gives you speed. ai_governance gives you the receipts, at speed.

When an AI agent acts through Drupal, whether it's calling a tool via Drupal's own MCP server, going through an external MCP gateway on top of that, or running through Drupal AI's own generation pipeline, this module records what Drupal authorized, its "governance leg" of the audit record. If an external gateway is also involved, its own execution report becomes a matching "gateway leg," correlated against Drupal's. You get one auditable trail instead of two logs you have to cross-reference by hand.

Built in the spirit of Drupal's Outside AI workstream: agents using Drupal, not just Drupal using AI.

Built with AI assistance. This module's code, tests, and docs were written with substantial help from Claude Code, an AI coding assistant, and reviewed by the maintainer. If that affects your evaluation, say so in the issue queue.

Features

• Two-leg correlation. Drupal's own authorization, whether it comes from an MCP tool call or from this module's own guardrail on Drupal AI's generation pipeline, is recorded as a governance leg on its own. No external gateway is required for that. When a gateway is also in the loop, its after-the-fact webhook report is recorded as a matching gateway leg, keyed on tool_call_id. The two legs are grouped into an AuditCorrelation record that moves from pending to correlated to approved or rejected as each leg arrives.
• Idempotent. Retried webhooks and reused tokens don't produce duplicate rows. A gateway plugin should return its own stable per-delivery id (the same pattern Stripe and GitHub use) via extractGatewayCallId(). If it returns NULL, the module falls back to a derived key and logs a notice.
• Signed, replay-protected ingestion. HMAC-SHA256 verification, stale-payload rejection, and zero-downtime secret rotation.
• Server-resolved accountability. executor_uid comes only from the validated OAuth token. A plugin that tries to supply it is rejected outright, not silently overridden.
• Access-gated by default. Records sit behind a dedicated view ai governance records permission, so there's no anonymous read path.
• Self-service reporting. Ships an MCP tool an agent can call to look up its own governance history.
• Safe to uninstall around. A check blocks removal while audit data still exists.

The correlation key for a leg is a per-call tool_call_id, not the OAuth token's jti claim. One access token is normally reused across many calls (that's the recommended OAuth pattern, not an edge case), so keying records on jti alone would silently drop every call after the first. The module keeps three identities separate: jti for which credential was used, tool_call_id for which call this was, and executor_uid for who's accountable. See SCHEMA.md for the full model.

Current limitation: the AuditCorrelation record itself still groups legs by the authorizing token, not per call. If a token gets reused, the correlation surfaces only the most recent leg of each kind. Every individual leg row still stays stored and queryable.

EU AI Act compliance

ai_governance is not a compliance product. Installing it doesn't automatically satisfy Articles 12, 13, or 14, and it's not a substitute for legal advice. What the table above gives you is evidence: correlated call records, server-verified executor identity, recorded oversight decisions, and an AI-facing self-report tool, all things that can support your own governance and oversight processes.

A few things worth knowing before citing this module in a compliance narrative. Human oversight is observational, not enforced: approval_status records a decision made elsewhere, and this module never blocks or gates a call itself. The hash chain is tamper-evident, not tamper-proof, absent external anchoring, and it needs the optional Midgard Integration submodule, which isn't currently installable alongside this module (see Recommended modules below). JSON:API exposure is opt-in and unredacted at the field level. See SECURITY.md for the full caveats and GOVERNANCE.md for the narrative behind the table.

Post-Installation

1. Enable ai_governance, or run the bundled Drupal Recipe (which also grants admins read-only audit access). Two more recipes compose on top of it for a one-step setup of each capture path: ai_governance_gateway (Path A) and ai_governance_pipeline (Path B, which also wires the AI Guardrail plugin into a guardrail set — no separate manual step). An ai_governance_demo recipe is included for evaluators.
2. Go to Configuration → AI → Safety & Compliance (/admin/config/ai/ai-governance) and set a webhook shared secret via Key. The endpoint fails closed until you do. The same page doubles as a live status dashboard.
3. The audit trail lives at Reports → AI Governance Log (/admin/reports/ai-governance). From the command line, drush ai-governance:status, :sync-governance, and :retention-sweep run the same checks and cron-queued work on demand.

Additional Requirements

• Drupal core ^11 (targets 11.3.x and 11.4.x)
• Key, Simple OAuth, core Views and User
• For the gateway leg only: a gateway that posts signed webhook audit reports, and a small McpGatewayInterface plugin for its payload shape. No production plugin ships by default (a demo plugin ships for the test suite only). You don't need either of these for the in-Drupal leg alone.

Neither MCP Server nor AI (Drupal AI) is required by the base module. Each is required only by the bundled submodule that wraps it, so a site using only one capture path never has to install the other.

Recommended modules/libraries

• AI Governance — MCP Server Capture (bundled) records Drupal-side authorization for MCP tool calls (Path A) and exposes the self-report MCP tool. Requires MCP Server.
• AI Governance — AI Guardrail Capture (bundled) records Drupal AI generation-pipeline authorization (Path B) as an audit-only guardrail. Requires AI (Drupal AI).
• AI Governance — Midgard Integration (bundled) records Heimdall approval decisions as governance legs, resolved live against Midgard's own ledger. It's not currently installable alongside AI Governance — MCP Server Capture: Midgard's composer.json pins mcp_server to a dev-1.x commit that conflicts with that submodule's ^2.0@beta requirement. Tracked at midgard's issue #2, not yet resolved.
• AI Governance — FlowDrop Integration (bundled) correlates FlowDrop pipeline runs triggered by a tool call into the same audit trail.

Related and adjacent projects

This module records and correlates. It never gates. Here's where it overlaps with other projects:

• MCP Sentinel does policy enforcement, redaction, rate-limiting, and audit on Drupal's own MCP/JSON:API/GraphQL surface, and it's the more mature project. It governs what an agent may reach. This module correlates Drupal's decision with an external gateway's report.
• Midgard (with its Heimdall and Bifrost submodules) decides and enforces AI-initiated config changes, with its own hash-chained log and rollback. This module records and correlates across the Drupal/gateway boundary. The two compose through the bundled integration submodule.
• Audit Trail and Admin Audit Trail do generic tamper-evident or admin-action logging. Neither is AI- or tool-call-specific.
• AI Logging/Observability (AI submodules) and Langfuse trace AI provider calls (prompts, completions, tokens) for debugging generation, not tool-call authorization.

Know of overlapping work not listed here? Open an issue. We'd rather link to it than duplicate it.

Supporting this Module

No funding links at this time.

Community Documentation

ARCHITECTURE.md, SECURITY.md, SCHEMA.md, and GOVERNANCE.md cover the entity model, trust boundaries, the cross-platform audit-record schema proposal (including how it relates to MCP's own MAAR discussion), and the two-leg governance narrative. For a reviewer-runnable demo, see scripts/setup-reviewer-site.sh and SETUP.md. It's key-free and doesn't need Midgard.