MODULE REFERENCE

What each module does, how to configure it, and what it enforces.

Aegis governs MCP actions. One engine makes every decision; the other modules carry the protocol, read configuration, authenticate callers, reach backends, keep state, and host the endpoint. This page describes the core modules in the root Maven reactor and the examples aggregator from source code and tests.

MODULE MAP

Thirteen core modules in six layers, plus examples.

The root pom.xml is the source of truth for this core module map. It builds, in order: aegis-engine, aegis-mcp, aegis-observability-otlp, aegis-config, aegis-mcp-guardrails, aegis-mcp-security, aegis-gateway, aegis-source-jdbc, aegis-source-zookeeper, aegis-source-a2a, aegis-state-derby, aegis-state-postgres, aegis-knox3-extension and examples. The examples entry is an aggregator with its own default and opt-in child modules. Java 17 is the compiler release. This table is manually maintained rather than generated, so verify the root and examples POMs when freshness matters.

Six layers of Aegis modules: engine at the bottom, then MCP protocol, OTLP export, configuration, extension modules, and the two hosts at the top.

Three rules hold across every module and are enforced in code:

The modules at a glance

ModuleWhat it isUse it when
aegis-engineThe decision maker. Every tool call, resource read, prompt and completion passes through its fixed chain of checks before anything reaches a backend.Always. Every deployment includes it.
aegis-mcpThe MCP protocol layer. It turns MCP messages over Streamable HTTP or stdio into engine calls and turns the decisions back into MCP replies. It also serves the admin API and provides the clients that reach existing MCP servers.Always.
aegis-observability-otlpAn optional exporter that sends one OpenTelemetry span per governance decision to an OTLP/HTTP collector.You run an OTLP collector and want decisions joined to request traces.
aegis-configThe builder. It reads one JSON or YAML file and assembles the running gateway: engine, sources, policy, hooks, audit journal, state and the MCP and admin handlers.Always.
aegis-mcp-securityIdentity and route admission for the own host: who is calling, and may they reach this route at all.You run the own host (aegis-gateway). Inside Knox, Knox does this job.
aegis-mcp-guardrailsAn optional hook for project-owned rules: protected resources that nobody may touch, and an evidence reference required on high-impact actions.A project wants evidence attached to high-impact actions.
aegis-source-jdbcGoverned SQL and metadata tools over any JDBC driver.The engine you want to govern has a JDBC driver.
aegis-source-zookeeperGoverned tools over the Apache ZooKeeper data tree, through ZooKeeper's own client protocol.You govern znodes, for example coordination data used by HBase, Solr or older Kafka deployments.
aegis-source-a2aOne Agent2Agent (A2A) agent offered as one governed tool.An agent should call an A2A 1.0 agent through Aegis.
aegis-state-derbyDurable governance state for one gateway process, on embedded Apache Derby.One gateway process needs state that survives restarts.
aegis-state-postgresShared governance state for several gateway processes, on PostgreSQL.More than one Aegis process governs the same tools: high availability, Kubernetes replicas, rolling upgrades.
aegis-gatewayThe program you run: an MCP endpoint over HTTP(S) and stdio, plus offline commands, in one runnable jar.You run Aegis on its own server, in a container or on a laptop.
aegis-knox3-extensionAegis as a service inside an existing Apache Knox 3.0.0 gateway.Knox already fronts the cluster.
examplesRunnable examples, adopter profiles with retained real-engine runs, and the opt-in validation harness.You want to try Aegis or check how a profile behaves against a real engine.

REQUEST PATH

How a governed tools/call crosses the modules.

  1. Host (aegis-gateway or aegis-knox3-extension): accepts HTTP(S) or stdio, authenticates the caller, admits the route, and bounds the body.
  2. Protocol (aegis-mcp): checks origin, JSON-RPC shape, MCP revision and headers, then dispatches the method.
  3. Engine (aegis-engine): runs the fixed governance chain, writes the intent record, then resolves the backend credential and calls the source.
  4. Source (mcp, http, jdbc, zookeeper or a plugin): performs the backend action with a configured static or service credential, or with an execution-time per-caller exchanged credential.
  5. Observers (DecisionMetrics, aegis-observability-otlp): record the decision. Observers are read-only and cannot change it.

CORE

aegis-engine

Dependencies: JDK onlyPackage io.github.vaquarkhan.aegis.engine

What it is. The decision maker. Every tool call, resource read, prompt and completion passes through its fixed chain of checks before anything reaches a backend.

Why we built it. Governance has to give the same answer whichever host, transport or source is in use. Putting every decision in one engine, with no third-party runtime libraries, keeps the rules in one place that can be read and tested on its own.

What you get. The same decision on the own host, inside Knox and over stdio; a fail-closed order that denies when a check cannot run; every allowed action journaled before it runs; approvals and dry-run receipts bound to the exact action, caller and tool definition.

Use it when. Always. Every deployment includes it.

The governance core. GovernanceEngine.call() runs every tool call through one fixed, fail-closed chain. The module also holds the tool catalog with definition pinning, signed approval and dry-run receipt tokens, the hash-chained audit journal, bounded in-memory state, the JSON parser with size limits, and the service interfaces that sources, hooks, policy engines and state stores implement.

Governance chain

Any unexpected exception inside a control becomes a POLICY_DENIED denial. Step numbers are stable and appear in audit records and denials.

OrderControl (step)What is checkedDenial
1Exposure (1)Tool exists and is active; quarantined entries are hidden; allowedGroups; write and destructive groups for MUTATE and DESTRUCTIVE tools.NOT_EXPOSED, CATALOG_INTEGRITY, READONLY_CALLER
2Input and scope (2)Schema validation (depth 64), control-token parsing, typed resources by JSON pointer, per-tool actionScopes (exact verified OAuth scopes), resource scopes.INVALID_INPUT, SCOPE_DENIED
3Policy (3)Rule policy (deny overrides, default deny) and optional OPA. A missing or failed decision denies.POLICY_DENIED
4Egress (5)Every executor target and every URL found in the arguments: scheme, host allow list, user-info, and every DNS answer against denied address classes unless an allowed CIDR covers it.EGRESS_DENIED
5Rate and budget (6)Per-caller and per-caller-per-tool windows and an hourly cost budget.RATE_LIMITED, BUDGET_EXCEEDED
6Circuit breaker (7)Per-source breaker with exactly one probe while half-open.BREAKER_OPEN
7Screening and hooks (8)13 built-in injection phrases matched over the whole text in overlapping 64 Ki-character windows, with Base64 decoding on by default and governance hooks. A hook that throws, times out or returns nothing denies in ENFORCE mode.PROMPT_INJECTION, POLICY_DENIED, INVALID_INPUT
8Approval (4)Per-call approval token for the classes in approval.requiredFor: bound to caller, action, gateway, source, resources and tool definition; single use; separation of duties.APPROVAL_REQUIRED
9Dry-run receipt (9)DESTRUCTIVE calls need a fresh, single-use receipt from a dry run of the same arguments, caller and definition.VRP_FAILED
10Audit intentALLOW_INTENT must be appended to the journal before anything runs.AUDIT_UNAVAILABLE
11Execute (10)Credentials are resolved only now; backend timeouts and failures are classified; error text is redacted.TIMEOUT, BACKEND_ERROR
12Output guardDefault redactions (AWS access key ids, PEM private keys, bearer tokens, JWT shapes) plus operator patterns, and an output byte bound with a truncation note. Binary parts are withheld unless output.allowBinary is set.Output redacted or truncated; POLICY_DENIED for refused binary

Security controls in detail

Operator responsibility. Tool classes and resource pointers are operator-authored. Use REQUIRE_PINS for catalogs with MUTATE or DESTRUCTIVE tools; in TOFU mode the first definition seen becomes the pin. The egress guard covers HTTP destinations Aegis contacts; stdio children, database and ZooKeeper clients, and plugins that open their own sockets need a default-deny network policy around the process. Screening and redaction reduce risk and are heuristic. Between the egress check and the executor's own connection a name can be re-resolved; use IP literals or CIDRs where that matters. A local hash chain is tamper-evident when its head is also retained elsewhere: AuditCheckpointPolicy makes the journal export its head to a separate file and refuse to reopen a journal that is shorter than or different at the last exported head, and AuditCheckpointVerifier checks every exported head offline. SignedCatalogManifest verifies Ed25519-signed pin lists before reading them.

Tests: GovernanceEngineTest, ControlsTest, OutputGuardTest, ContentGovernorTest, HooksTest, ContentHooksTest, SeparationOfDutiesTest, HashChainFileAuditSinkTest, AuditCheckpointTest, SignedCatalogManifestTest, JsonTest, ObservabilityTest.

PROTOCOL

aegis-mcp

Dependencies: aegis-engineNo third-party runtime libraries

What it is. The MCP protocol layer. It turns MCP messages over Streamable HTTP or stdio into engine calls and turns the decisions back into MCP replies. It also serves the admin API and provides the clients that reach existing MCP servers.

Why we built it. MCP has several revisions with different framing: the 2025 revisions with sessions and the stateless 2026-07-28 revision. Keeping the protocol apart from governance lets each evolve without touching the other.

What you get. One handler for every supported revision and both transports; header and body agreement checks; existing MCP servers governed as type: mcp sources without any change to them; bounded outbound HTTP.

Use it when. Always.

The MCP protocol layer. It serves the 2026-07-28 revision (per-request _meta, no sessions) and the 2025-11-25, 2025-06-18 and 2025-03-26 revisions (with caller-bound sessions). It also provides the admin REST API, the downstream MCP clients over Streamable HTTP and stdio that back type: mcp sources, and a bounded HTTP helper used by every outbound call.

Security controls

Admin API

RouteWhoBehaviour
GET /approvalsapprover groupsList pending requests.
GET /approvals/{id}requester or approver groupsInspect one request. Only the requester receives its single-use token.
POST /approvals/{id}/approve, /denyapprover groups, non-delegatedSeparation of duties; journaled before effect; 409 if already decided, 410 if expired.
GET /audit/verifyaudit verifier groups200 verified, 409 broken, 503 unavailable. Fixed journal; file names are withheld.
GET /catalogapprover groupsName, source, class, status, reason and digest of each tool.
POST /catalog/{tool}/acceptapprover groups, non-delegated428 without exactly one Aegis-Definition-Digest; intent journaled first (503 if that fails); 409 unless the tool is quarantined and still has the reviewed digest.
GET /prompts, POST /prompts/{prompt}/acceptapprover groups, non-delegatedSame rules for prompts, when a source offers prompts.

Tests: ContentGovernanceTest, McpServerHandlerTest, ExistingMcpServerProxyTest, AdminApiTest, McpRoundTripTest, TracePropagationTest, BoundedHttpTest.

OBSERVABILITY

aegis-observability-otlp

Dependencies: aegis-engine, aegis-mcpEnabled by tracing.otlp.endpoint

What it is. An optional exporter that sends one OpenTelemetry span per governance decision to an OTLP/HTTP collector.

Why we built it. Operators want governance decisions in the tracing they already run, without adding an SDK to the gateway and without copying sensitive data into a trace store.

What you get. No OpenTelemetry SDK dependency; spans carry names, codes and timings but no caller identity, arguments or results; a bounded queue and a background thread, so a slow or missing collector never slows or changes a call.

Use it when. You run an OTLP collector and want decisions joined to request traces.

An OTLP/HTTP JSON trace exporter with no OpenTelemetry SDK dependency. It observes decisions and exports one SERVER span per decision on a background thread, in batches, through a bounded queue.

KeyDefaultNotes
tracing.otlp.endpointnone (tracing off)Must be a URI and pass egress at startup.
tracing.otlp.headers{}Static headers.
tracing.otlp.tokenEnvnoneEnvironment variable holding a bearer token; must be set.
tracing.otlp.timeoutMs5000Connect and request timeout.
tracing.otlp.serviceNamegateway.nameservice.name resource attribute.
tracing.otlp.maxQueue / batchSize / flushMs2048 / 128 / 2000Queue bound, most spans per POST, idle poll interval (a span is sent as soon as it arrives).

Scope. The exporter is tested against a local HTTP endpoint that reads the OTLP JSON shape. A run against a live OpenTelemetry Collector is planned work.

Tests: OtlpSpanExporterTest.

CONFIGURATION

aegis-config

Dependencies: aegis-engine, aegis-mcp, aegis-observability-otlpSnakeYAML optional (YAML only)

What it is. The builder. It reads one JSON or YAML file and assembles the running gateway: engine, sources, policy, hooks, audit journal, state and the MCP and admin handlers.

Why we built it. Adopting Aegis should mean writing configuration, not Java. Strict loading catches a typo or a missing secret before anything starts, instead of leaving a control silently off.

What you get. Unknown keys, missing secrets and unreachable trust anchors stop startup with the exact path; built-in http and mcp sources; plug-in points for sources, hooks, state stores and secret providers; the signed server catalog checked before any source starts.

Use it when. Always.

Turns one JSON or YAML document into a running gateway: engine, MCP handler, admin API, catalog refresher, metrics, tracer and state. It provides the built-in mcp and declarative http sources, the built-in remote and sql-readonly hooks, OPA policy, static source credentials and RFC 8693 token-exchange credentials, the OpenAPI draft generator, the built-in env, file and vault secret sources, and the ServiceLoader interfaces ToolSourceFactory, GovernanceHookFactory, StateStoreFactory and SecretProviderFactory.

Loader and validation

Top-level keys

KeyDefaultMeaning
gateway.nameaegisName in audit records, serverInfo and tokens.
access.writeGroups[]Groups that may call MUTATE tools at all.
access.destructiveGroupswriteGroupsGroups that may call DESTRUCTIVE tools.
access.approverGroups[]Groups that may decide approvals and accept definitions.
access.auditVerifierGroups[]Groups that may call GET /audit/verify.
approval.keyEnv / keyFilenoneHMAC key of at least 32 bytes; keyEnv wins when both are set. Without a key or approver groups, approval-required calls are denied.
approval.requiredFor[MUTATE, DESTRUCTIVE]Classes needing per-call approval. READ is refused. An explicit empty list turns per-call approval off.
approval.requestTtlSeconds / tokenTtlSeconds1800 / 600Lifetimes of a request and an approval token.
approval.advertiseControlArgumentstrueShow the control arguments on write tools.
vrp.enabled / ttlSecondstrue / 900Dry-run receipts for DESTRUCTIVE calls and their lifetime.
state.typememorymemory, or a provider such as derby-local or postgres.
state.maxEntries1000000Bound for the memory store.
state.settings{}Provider settings; must be empty for memory.
audit.filerequiredJournal path, relative to the configuration file.
audit.fsync / includeArgumentstrue / falseForce each record to disk; record call arguments.

Sources

Key (sources[])DefaultMeaning
idrequired[a-z0-9][a-z0-9_-]{0,63}, unique.
typerequiredmcp, http, or a plugin type.
namePrefix""Prefix for exposed tool names.
timeoutMs30000Backend budget per call.
unlistedToolsEXPOSEEXPOSE or HIDE discovered tools that are not listed under tools.
defaultClassDESTRUCTIVEClass of discovered tools that are not listed.
trust.state / trust.evidenceACTIVE / noneQUARANTINED contributes no callable tool and requires evidence text.
credentials.typenonebearer (tokenEnv), basic (usernameEnv, passwordEnv), header (header, valueEnv): the source's own service credential. token-exchange (tokenEndpoint, clientIdEnv, clientSecretEnv, audience or resource, scope, timeoutMs, checkSubject, discovery): a per-caller token from the identity provider for each call; the token endpoint must pass egress. Caller tokens are never forwarded to a backend.
mcp: url / transport / era / legacyVersion / maxResponseBytesrequired for http / http / AUTO / 2025-11-25 / 4 MiBExisting MCP server over Streamable HTTP or stdio.
mcp: command / env / envFrom / workingDirstdio onlyChild process; envFrom values name environment variables that must be set.
mcp: resources.uriPatterns / prompts.names / completionsoffResources need specific URI globs (* is refused); prompts and completions are opt-in.
http: baseUrl / tools[]requiredDeclarative REST tools: name, description, inputSchema, request (method GET, path, query, body, headers), response (pointer, status check, maxBytes 1 MiB).
tools.<name>.class / resources / dryRun / allowedGroups / actionScopes / timeoutMssee CONFIGURATIONPer-tool classification, typed resources, preview mode (GATEWAY, ARGUMENT, TOOL), visibility, required OAuth scopes and timeout.
settings{}Plugin source settings, validated strictly.

Controls

KeyDefaultMeaning
egress.allowHosts / allowCidrs / schemes[] / [] / [https]Each source host and scheme is added automatically. Non-public answers need an allowed CIDR.
egress.checkArgumentUrlstrueCheck URLs nested in arguments.
policy.rules[]required with opaid, effect (ALLOW, DENY), groups, actors, tools, classes, resources. Any matching DENY wins; otherwise the first matching ALLOW; otherwise deny.
policy.opa.url / timeoutMs / includeArguments / tokenEnvnone / 2000 / false / noneOnly {"result": true} or {"result": {"allow": true}} allows. Responses are bounded to 64 KiB; no redirects.
scopes[][]groups and resources globs.
rateLimits.perCallerPerMinute / perCallerPerToolPerMinute / budgetPerHour0 / 0 / 00 means off. Costs READ 1, MUTATE 5, DESTRUCTIVE 20.
breaker.failureThreshold / openSeconds5 / 30Per-source circuit breaker.
screening.mode / toolDefinitions / contentENFORCEENFORCE, AUDIT or OFF for arguments, definitions, and resources and prompts.
screening.phrases / decodeBase6413 built-in / truePhrase list; Base64 decoding for argument screening (always on for definitions and content).
output.useDefaultRedactions / redact / maxBytestrue / [] / 1 MiBRedaction patterns and output bound.
output.allowBinaryfalsePass binary parts of tool results (image and audio data, any blob) unchanged. When false, such a result is withheld and the call is denied with POLICY_DENIED.
hooks[][]type (remote, sql-readonly, plugin), operations (all when empty), mode, methods, groups, sources, settings.
remote hook settingstimeoutMs 2000, maxResponseBytes 8192url (egress-checked), tokenEnv, phases (BEFORE, AFTER), includeArguments, includeResult. Response cap clamped to 256 to 65536 bytes; allow must be a literal boolean.
sql-readonly settingsmaxChars 8192arguments (required). One statement, a reading first keyword, no writing keyword anywhere; comments and quoted text removed first.
catalog.mode / pins / pinFileTOFU / {} / noneREQUIRE_PINS refuses tools without an operator pin. With serverCatalog the default is REQUIRE_PINS, any other mode is an error and pinFile is refused.
serverCatalog.file / signatureFile / publicKeyFileoff / <file>.sig / noneOffline Ed25519-signed register of which sources[] may start and which tools each may bind. Read once at startup; no admin route reads or replaces it.
serverCatalog.breakGlass.file / signatureFile / publicKeyFileoffIncident order signed with a separate key. It can only quarantine or revoke listed servers, for at most 24 hours; an expired order stops startup.
catalog.acceptNewToolsAfterStart / failOnSourceError / refreshSecondsfalse / true / 0New tools after start are quarantined unless allowed; a failing source stops startup; periodic refresh.
server.*all four revisions, sessions onname, version, versions, legacySessions, allowedOrigins, toolsListTtlMs, instructions, maxRequestBytes 1 MiB, sessionIdleSeconds 1800, maxSessions 10000.
metrics.enabledtruePrometheus decision counters, at most 10000 series.

Operator responsibility. The sql-readonly hook is a keyword and shape guard: a statement that passes may still call a writing function, so pair READ SQL tools with a read-only database credential or classify them MUTATE. Every secret the file names is read through one secrets.source: the environment, one file per name in a mounted directory, or one Vault KV v2 secret read at start-up (validated against OpenBao 2.7.1). Values are not refreshed while the gateway runs.

Tests: GatewayFactoryTest, HttpSourcesAndWiringTest, RemoteHookTest, SqlReadOnlyHookTest, DryRunPreviewToolTest, OpaPolicyTest, SecretProvidersTest, AuditCheckpointAndManifestConfigTest, and, with -Pvault-integration, VaultKvSecretProviderIT.

IDENTITY PERIMETER

aegis-mcp-security

Dependencies: aegis-engine, aegis-mcp, aegis-configJDK cryptography only

What it is. Identity and route admission for the own host: who is calling, and may they reach this route at all.

Why we built it. Governance needs a verified caller. Authenticating before the request body is read keeps unauthenticated traffic cheap to refuse and keeps credentials out of the engine.

What you get. JWT with JWKS, hashed static tokens and SPIFFE over mutual TLS; route groups and OAuth scopes checked before the body; exact-origin CORS; RFC 9728 metadata so MCP clients can find out how to authenticate.

Use it when. You run the own host (aegis-gateway). Inside Knox, Knox does this job.

The identity perimeter of the own host. It parses the host section strictly, authenticates callers with JWT (HS256, or RS256 and ES256 through JWKS), static SHA-256 token digests, or a SPIFFE X.509-SVID the mutual TLS handshake verified, admits route groups and OAuth scopes before the body is read, applies exact-origin CORS, and publishes RFC 9728 protected resource metadata.

Security controls

Host keys

Key (host.)DefaultMeaning
listen.host / port127.0.0.1 / 8080Bind address.
listen.mcpPath / adminPath/mcp / /aegis/v1Route paths.
listen.threads / maxRequestBytes32 / 1 MiBWorker pool and body bound.
tls.keystore / keystorePasswordEnv / keystoreTypenone / required with keystore / PKCS12HTTPS when a keystore is set.
identity.typejwtjwt, static or spiffe; anonymous access is refused.
identity.jwt.issuer / audiencerequiredExpected claims.
identity.jwt.algorithms / hmacSecretEnv / jwksUri[RS256] / none / noneHS256 needs a secret of at least 32 bytes; RS256 and ES256 need a JWKS URI.
identity.jwt.groupsClaim / subjectClaimgroups / subClaim names.
identity.jwt.clockSkewSeconds / jwksTtlSeconds / jwksRefreshCooldownSeconds60 / 3600 / 30Time and cache settings.
identity.static.tokens[]required for statictokenEnv or sha256, actor, groups.
oauth.resource / authorizationServers / scopesSupported / documentation / allowAudienceMismatchoff / required with resource / [] / none / falseRFC 9728 metadata; https, or loopback http for local development.
routes.mcpGroups / adminGroups / mcpScopes / adminScopes[]Empty groups means any authenticated caller; scopes need jwt.
cors.allowedOrigins / allowedMethods / allowedHeaders / exposedHeaders / maxAgeSeconds / allowCredentials[] / POST, DELETE, GET / MCP headers / [] / 600 / falseBrowser access.
stdio.actor / groupsnoneFixed identity for --stdio. It carries no OAuth scopes, so tools with actionScopes are denied.
metrics.path / allowedGroups / requiredScopes/metrics / [] / []Authenticated Prometheus endpoint.

Tests: JwtVerifierTest, ScopeEnforcementTest, ProtectedResourceMetadataTest, OwnServerPerimeterTest, OwnServerSecuritySettingsTest, SpiffeIdentityTest.

EXTENSION

aegis-mcp-guardrails

hooks[].type: project-governanceDependencies: aegis-engine, aegis-config

What it is. An optional hook for project-owned rules: protected resources that nobody may touch, and an evidence reference required on high-impact actions.

Why we built it. Projects often have rules beyond allow and deny, for example that a release action cites its vote thread. A hook keeps such rules out of the sources and out of the engine core.

What you get. Protected resources denied for every caller; a bounded evidence reference required for the tool classes you choose; AUDIT mode to see what it would deny before you enforce it.

Use it when. A project wants evidence attached to high-impact actions.

An optional project-owned governance hook with two jobs: deny any action that touches a protected resource glob, and require a bounded evidence reference argument for configured tool classes. It records a reference; it does not fetch or verify the evidence itself, and it is a project control rather than an ASF policy.

Key (settings.)DefaultMeaning
requireEvidenceFor[]READ, MUTATE or DESTRUCTIVE.
evidenceArgumentevidenceIdIdentifier [A-Za-z][A-Za-z0-9_]{0,63}.
minEvidenceLength81 to 512; the maximum length is 512.
protectedResources[]Resource globs that are always denied.

A protected resource denies with POLICY_DENIED at step 8 for every class. Missing, non-text, too short, too long, ..-bearing or control-character evidence denies with INVALID_INPUT. Engine policy, approval, receipts and audit still apply.

Tests: ProjectGovernanceGuardrailTest.

SOURCE

aegis-source-jdbc

sources[].type: jdbcjava.sql only; ships no driver

What it is. Governed SQL and metadata tools over any JDBC driver.

Why we built it. Many engines expose SQL rather than REST: HiveServer2, Impala, Doris, Druid, Calcite through Avatica, Trino and the Spark Thrift server. One typed source reaches them through their own drivers.

What you get. Metadata through DatabaseMetaData parameters; exactly one read-only statement for the query tool; capped rows and values; credentials by environment name; the operator chooses and supplies the driver.

Use it when. The engine you want to govern has a JDBC driver.

Governed tools over any JDBC driver for SQL-surfaced engines such as HiveServer2, Impala, Doris, Druid, Avatica and Phoenix, Trino and the Spark Thrift server. Tools: jdbc_server_info, jdbc_list_catalogs, jdbc_list_schemas, jdbc_list_tables, jdbc_describe_table, jdbc_run_query, and jdbc_execute_statement when writes are enabled.

Key (settings.)DefaultMeaning
urlrequiredMust start with jdbc:; a rejected value is never echoed.
driverClassJDBC 4 discoveryLoaded at startup; a missing class stops startup.
userEnv / passwordEnvnoneEnvironment variables; must be set when named.
maxRows2001 to 10000.
maxCellChars409616 to 1000000.
loginTimeoutSeconds151 to 600.
allowWritesfalseOffers jdbc_execute_statement.

Operator responsibility. Give the source a read-only database role for READ tools. The database host is configuration, so callers cannot redirect it; transport security follows the driver URL.

Tests: JdbcToolSourceTest against embedded Apache Derby.

SOURCE

aegis-source-zookeeper

sources[].type: zookeeperApache ZooKeeper 3.9.3 client

What it is. Governed tools over the Apache ZooKeeper data tree, through ZooKeeper's own client protocol.

Why we built it. A normal ZooKeeper ensemble serves its data tree over the client protocol, not over REST, so a typed source is the way to reach it.

What you get. Mandatory digest authentication; owner-only znodes; versioned writes and deletes; paths checked by ZooKeeper's own PathUtils; capped data and child lists.

Use it when. You govern znodes, for example coordination data used by HBase, Solr or older Kafka deployments.

Governed tools over the ZooKeeper data tree through ZooKeeper's own client protocol: zookeeper_list_children, zookeeper_stat_node, zookeeper_get_node, zookeeper_create_node, zookeeper_set_data and zookeeper_delete_node.

Key (settings.)DefaultMeaning
connectStringrequiredEnsemble; configuration only.
auth.digestEnvrequiredEnvironment variable holding user:password for digest authentication.
sessionTimeoutMs / connectTimeoutMs15000 / 10000Session timeout; how long a call waits for the session.
maxDataBytes655361 to 1048576.
maxChildren5001 to 100000.

Operator responsibility. Protect the reserved /zookeeper subtree with a policy rule, and configure client TLS through ZooKeeper's own system properties where required.

Tests: ZooKeeperToolSourceTest against a real ZooKeeper server started in-process by curator-test.

SOURCE

aegis-source-a2a

sources[].type: a2aA2A protocol 1.0, JSON-RPC binding; JDK only

What it is. One Agent2Agent (A2A) agent offered as one governed tool.

Why we built it. Agents increasingly call other agents. Treating an A2A agent as a tool puts it under the same identity, policy, approval and audit as every other tool, without a separate A2A front door.

What you get. The call endpoint is pinned to the agent card's origin or to a configured URL and passes the egress check; the agent credential comes from configuration; replies are bounded.

Use it when. An agent should call an A2A 1.0 agent through Aegis.

One Agent2Agent (A2A) agent as one governed tool. Discovery reads the agent card; a call sends one JSON-RPC SendMessage with the text argument as a text part and the optional data argument as a data part, and returns the agent's message or completed task as text. Aegis is an A2A client only.

Key (settings.)DefaultMeaning
cardUrlrequiredThe agent card URL (http or https, no user-info).
endpointUrlnonePins the JSON-RPC URL the card must name; needed only when it is on another origin than the card.
toolNamesource id with _Stable tool name, independent of the card.
maxTextChars / maxResponseBytes / cardTimeoutMs16000 / 1 MiB / 5000Bounds on one message, one reply and reading the card.

Operator responsibility. List the agent's host in egress.allowHosts; put the agent credential in the source's credentials, which is sent on calls only.

Tests: A2aToolSourceTest (card rules, request shape, reply mapping, gateway integration) and A2aAgentFrontDoorsTest against an agent built on the official a2a-sdk 1.2.1, through both front doors.

STATE

aegis-state-derby

state.type: derby-localApache Derby 10.16.1.1, embedded

What it is. Durable governance state for one gateway process, on embedded Apache Derby.

Why we built it. Pending approvals, spent approval tokens and receipts, and rate counters must survive a restart. Derby gives that without installing a database server.

What you get. No server to run; state survives a restart; Derby's database lock keeps a second process out, verified by a test that starts a second JVM.

Use it when. One gateway process needs state that survives restarts.

Durable single-process governance state on embedded Derby: approval and receipt nonces, expiring key and value entries, and fixed-window rate counters. Derby's database lock keeps a second process from opening the same files.

KeyDefaultMeaning
state.settings.pathrequiredDatabase directory; must stay under the configuration directory.

All statements are prepared with parameters; prefix scans escape \, % and _. Each operation is one synchronized transaction that rolls back and fails closed on error. A refused rate acquisition never charges the counter. Shutdown verifies Derby's expected shutdown state so a stale lock is reported.

Tests: DerbyStateStoreTest (restart survival, expiry, single-winner nonce under concurrency, rate windows).

STATE

aegis-state-postgres

state.type: postgresPostgreSQL JDBC 42.7.12

What it is. Shared governance state for several gateway processes, on PostgreSQL.

Why we built it. With two or more replicas, each would otherwise keep its own memory: a spent token could be replayed on another replica and every rate limit would be multiplied by the number of replicas.

What you get. Exactly one replica wins each single-use token; one rate window across all replicas; a pending approval visible from any replica; a namespace that scopes sharing.

Use it when. More than one Aegis process governs the same tools: high availability, Kubernetes replicas, rolling upgrades.

Shared governance state for several gateway processes on PostgreSQL. Unique constraints, INSERT ... ON CONFLICT ... RETURNING, DELETE ... RETURNING and row locks make nonces single-use and rate windows exact across processes. A namespace column scopes sharing.

Key (state.settings.)DefaultMeaning
jdbcUrlrequiredMust start with jdbc:postgresql://; add sslmode parameters for TLS.
usernameEnv / passwordEnvrequiredEnvironment variables; must be set.
namespacerequired1 to 128 letters, digits, dot, underscore or hyphen.
connectTimeoutSeconds101 to 120.

All data statements are parameterized; table names are constants. Errors roll back and fail closed with a generic message. The schema is created idempotently on first use; after that the role needs only SELECT, INSERT, UPDATE and DELETE.

Scope. Nonces, approvals, receipts and rate windows are shared. Catalog pins and circuit breakers remain per process. PostgresStateStoreIT runs only with -Ppostgres-integration and the AEGIS_POSTGRES_URL, AEGIS_POSTGRES_USER and AEGIS_POSTGRES_PASSWORD variables; a retained, recorded-unattested run against a temporary managed PostgreSQL instance is in the evidence record. TwoGatewayProcessesPostgresIT in aegis-gateway starts two gateway JVMs on one namespace against PostgreSQL 17.6: an approval asked on one replica is decided on the other, the replay is refused, and one rate window covers both (evidence).

HOST

aegis-gateway

Main class io.github.vaquarkhan.aegis.gateway.MainShaded -all jar

What it is. The program you run: an MCP endpoint over HTTP(S) and stdio, plus offline commands, in one runnable jar.

Why we built it. A standalone host lets Aegis run anywhere Java 17 runs, without depending on another server product.

What you get. TLS and mutual TLS; health, readiness and metrics routes; stdio for desktop clients; offline commands to verify the audit journal, sign catalogs, write break-glass orders and draft configuration from OpenAPI.

Use it when. You run Aegis on its own server, in a container or on a laptop.

The own host on the JDK's built-in HTTP(S) server, plus a stdio host. It authenticates through aegis-mcp-security and hands every request to the shared MCP handler or admin API; it contains no governance logic. It bundles the Derby and PostgreSQL state providers and the project guardrail.

Command line

ArgumentEffect
--config <file>Serve HTTP(S) with a YAML or JSON configuration.
--stdioServe line-delimited JSON-RPC on stdin and stdout as host.stdio.actor (lines up to 1 MiB).
--verify-audit <file>Verify a journal offline; exit 0 when intact, 1 when broken.
--hash-tokenPrint the SHA-256 of a token read from stdin, for identity.static.tokens[].sha256.
--require-server-catalog <review.pub>With --config: the host trust anchor. The gateway refuses a configuration without serverCatalog or with a different review key. Also AEGIS_REQUIRE_SERVER_CATALOG_KEY or -Daegis.requireServerCatalogKey (absolute path).
--policy-test <aegis.yaml> <cases.json>Evaluate declarative type: http test cases (caller, tool, arguments, expected outcome) without a backend, audit or approval. MCP, plugin and remote OPA sources are refused before discovery; exit 1 when a case does not match.
--server-catalog-create <aegis.yaml> <catalog-reply.json> <servers.json> [prompts-reply.json] [--serial <n>]Write ACTIVE server records with each source's digest, tool pins and optional prompt pins, for review and signing. A serial turns on rollback protection.
--server-catalog-verify <servers.json> <public.pem> <gateway-name>Check a signed server catalog offline.
--break-glass-create <order.json> <gateway-name> <incident> <minutes> <id>=QUARANTINED|REVOKED ... [--serial <n>]Write a containment order (at most 24 hours) for signing with the incident key.
--break-glass-verify <order.json> <public.pem> <gateway-name>Check a signed break-glass order offline.

Routes and controls

Tests: GatewayHostTest (JWT, JWKS rotation, delegation, approval and promotion over HTTP, Derby state, stdio, metrics, tracing), GuardedExchangeTest, MainAndSettingsTest (including audit checkpoints), ProtectedResourceMetadataTest (including the step-up challenge), SignedCatalogManifestFlowTest (the manifest workflow on the running host), ServerCatalogFlowTest (the server catalog, break-glass and trust-anchor workflow), PolicyTestCommandTest, OpenApiDraftCommandTest, SpiffeMutualTlsTest (real mutual TLS with keytool-issued certificates, not SPIRE-issued), and, with -Ppostgres-integration, TwoGatewayProcessesPostgresIT.

HOST

aegis-knox3-extension

Apache Knox 3.0.0, javax namespaceKnox classes in provided scope

What it is. Aegis as a service inside an existing Apache Knox 3.0.0 gateway.

Why we built it. Hadoop deployments often already use Knox as their perimeter. Hosting Aegis there reuses Knox login, identity assertion and route ACLs, while Aegis adds per-tool governance of the MCP body that route rules do not provide.

What you get. No second perimeter to run; the same engine and configuration as the own host; Knox classes supplied by Knox itself; a corrected configuration file is picked up on a later request without redeploying the topology.

Use it when. Knox already fronts the cluster.

An optional Knox service (role AEGIS_MCP). Knox's provider chain supplies TLS, authentication, identity assertion and route ACLs; the extension reads the established Subject and hands MCP and admin requests to an Aegis gateway built from the topology's aegis.config parameter. Aegis never sees the original credential.

Scope. The default-build tests run the real Knox 3.0.0 SPI classes and the real AclsAuthorizationFilter, with servlet objects supplied by the test. Under -Preal-engines the validation suite installs the current knox-bundle jar into a stock Knox 3.0.0 and drives MCP calls through the running gateway; the 2026-10-05 ZooKeeper run is retained as claims-matrix row H10. Knox 3.1.0 moves to the Jakarta namespace, so running there needs a Jakarta build of this extension; that is the planned direction for aligning with Knox 3.1 identity work.

Tests: KnoxExtensionTest, KnoxAclRouteScopeTest.

EXAMPLES

examples

What it is. Runnable examples, adopter profiles with retained real-engine runs, and the opt-in validation harness.

Why we built it. Configuration is easiest to learn from working copies, and every compatibility claim needs a real run behind it.

What you get. Copyable profiles for real engines; retained runs through both front doors; four independent break-glass MCP servers you can start locally.

Use it when. You want to try Aegis or check how a profile behaves against a real engine.

Plugin sources, runnable bundles and opt-in real-engine validation. These are outside the release core.

ModuleWhat it contains
aegis-examplestype: kafka-admin source over the Kafka Admin client (bootstrapServers, clientPropertiesFile, requestTimeoutMs 15000; a dry run of topic creation uses the broker's validate-only mode; each configured bootstrap server is checked by egress on every call as tcp://host:port; Kafka listener addresses advertised after bootstrap need listener configuration and network policy), and the documentation and configuration contract tests.
aegis-spark-connecttype: spark-connect source (host, port 15002, useSsl, tokenEnv requires SSL, userId, maxRows 100, threads 8). Identifiers are validated and quoted; free SQL is length-bounded and meant to be classified DESTRUCTIVE.
aegis-gateway-kafka, aegis-gateway-sparkRunnable shaded bundles of the own host with those sources.
aegis-validation and *-server modulesProfile real-engines: each test drives a real engine through both front doors (own host, and Knox when AEGIS_KNOX_HOME points at Knox 3.0.0).

Test doubles. Production code contains no mocks or stubs. In the default build the Kafka Admin test runs against a real Kafka 3.9.1 KRaft broker started in its own JVM from aegis-validation-kafka-server's classpath, and the adapter contract tests use a local HTTP harness that proves route rendering and governance order, not product compatibility. The other real brokers, catalogs and engines run under -Preal-engines.

END-TO-END MCP GOVERNANCE

Where each baseline control of the governance guideline lives.

The Aegis MCP governance guideline lists seven baseline controls for an MCP capability. It is Aegis project guidance, not ASF policy; ASF policy continues to govern releases, licensing, security reporting and project conduct.

Guideline controlEnforced byOwned by the deployment
3.1 Capability ownership and contractaegis-config: explicit tool class, typed resources, unlisted tools DESTRUCTIVE or hiddenNaming an owner and documenting backend effects
3.2 Identity and delegationaegis-mcp-security (JWT, act chain, scopes, static tokens, SPIFFE X.509-SVIDs over mutual TLS) or Knox via aegis-knox3-extension; source service credentials in aegis-config from secrets.source (environment, mounted files or a Vault KV v2 secret)Identity provider, group lifecycle, certificate issuance and rotation, token exchange
3.3 Semantic authorization and resource scopeaegis-engine steps 1 to 3: exposure, schema, typed resources, scopes, deny-overrides policy, OPAResource taxonomy and policy content
3.4 Approval and safe executionaegis-engine approval and dry-run receipts, separation of duties; durable or shared state through aegis-state-derby or aegis-state-postgresApprover roles and target-specific preview proof
3.5 Capability and source integrityaegis-engine catalog pins and quarantine, aegis-mcp digest-bound acceptance, source trust states, the signed serverCatalog and break-glass containmentInitial source review; REQUIRE_PINS pins or a signed catalog.manifest or serverCatalog, and custody of the review and break-glass private keys
3.6 Data, content and network controlsaegis-engine screening, redaction, output bounds, binary refusal, egress guard; aegis-mcp request bounds; minimal remote-hook data in aegis-configNetwork policy for processes and non-HTTP clients
3.7 Audit, evidence and responseaegis-engine intent-first hash chain and head checkpoints, aegis-gateway --verify-audit with --checkpoints, aegis-mcp GET /audit/verify, metrics and aegis-observability-otlpStorage for the audit.checkpoint file out of the journal writer's reach, retention, alerting, incident response

SCOPE AND ROADMAP

What the modules cover today, and what is planned.

In the code today

Semantic MCP action governance with typed resources, deny-overrides policy and OPA, independent per-call approval, bound dry-run receipts, definition pinning and quarantine, egress checks, screening, intent-first hash-chained audit with head checkpoints, signed catalog manifests, JWT with delegation chains, SPIFFE X.509-SVID identity over mutual TLS, secrets from the environment, mounted files or Vault KV v2, RFC 9728 metadata, and durable single-process or shared PostgreSQL nonce and rate state (proved with two gateway processes). Since 2026-10-03 also: per-caller backend credentials by RFC 8693 token exchange on the own host, A2A agents as governed tools, remote schema references refused, an OpenAPI-to-draft command, reference hook services, and a container image and Helm chart. Since 2026-10-06 also: per-tool actionScopes, a signed server catalog and time-bounded break-glass containment.

Planned work

Token exchange inside Knox, A2A 0.3 cards and card signature checks, a published container image and a cluster-installed chart, SPIRE Workload API integration, a Cedar policy engine, a network export of audit heads, shared catalog pins and breakers, a Jakarta build for Knox 3.1, a live OpenTelemetry Collector run, and process and network containment guidance for plugins and stdio sources.

Read the roadmap and the claims matrix for the evidence behind each statement.