Aegis Gateway 2.0

Claims matrix

This is the release-evidence index for Aegis 2.0. A product claim needs an implementation anchor, an assertion anchor and a result classification. It is deliberately stricter than “a test exists.” A contract route harness can prove configuration rendering and governance flow; it cannot certify a third-party product release. A converter tested against an embedded Apache engine can prove converter behavior; it cannot certify every database or client implementation.

Status vocabulary

Status Meaning
verified-current The named command has a retained immutable artifact bound to the reviewed candidate commit/tree and target.
verified-historical A preserved earlier run exists, but the current working tree has not repeated it.
recorded The run is documented in this repository. The release-candidate repeat is on the roadmap.
implemented-contract Code and governance flow are tested against a contract or protocol harness, not a target product.
implemented-pending The source/configuration exists but no adequate target execution has happened.
not shipped The capability is intentionally absent or remains on the roadmap.

Core control plane

ID Claim Implementation and assertion Evidence target Status Revalidate when
C01 Every governed call follows the fixed control order and fails closed when a required control cannot run. GovernanceEngine; GovernanceEngineTest and ControlsTest deterministic engine tests recorded chain, deny-code or SPI change
C02 Approval and destructive-run receipts bind to the caller, the full action binding (gateway, tool, class, source, resources, argument digest, pinned definition digest) and one-time state; the requester (under any NFKC or case spelling) and delegated callers cannot approve; approval decisions are journaled before a token is issued. Promotion is at-most-once: consumed approval or receipt nonces remain consumed when later intent journaling fails, and no backend call occurs. ApprovalService, VrpService, Action.binding; GovernanceEngineTest, SeparationOfDutiesTest deterministic engine tests recorded approval, receipt, binding or state-store change
C03 A TOOL preview uses the actual READ preview tool, not the destructive tool being validated. GatewayFactory.SourceBuild; DryRunPreviewToolTest converter-shaped test source recorded source binding or dry-run parser change
C04 Input and output controls inspect nested data, with bounded parsing and redaction. SchemaValidator, ValueWalker, OutputGuard; engine tests deterministic engine tests recorded JSON, screen or output-control change
C05 Egress checks inspect declared and embedded HTTP(S) targets, classify DNS answers, and bound outbound reads. EgressGuard, BoundedHttp; ControlsTest deterministic engine tests recorded egress or HTTP-client change
C06 Audit intent is written before backend execution and records form a locally verifiable hash chain. If intent journaling fails after at-most-once control consumption, no credential lookup or backend execution occurs. HashChainFileAuditSink; audit and engine tests local file system recorded audit format or store change
C07 Resources, prompts and completion traverse governance as read operations when enabled. ContentGovernor; content tests deterministic engine tests recorded MCP/content operation change
C08 OTLP span export is bounded, asynchronous, carries no identity, arguments or results, and cannot slow or change a governed call. OtlpSpanExporter; OtlpSpanExporterTest local collector test endpoint that asserts the OTLP/JSON document shape implemented-contract exporter or span attribute change
C09 A valid JWT without a route’s required OAuth scope is refused with 403 insufficient_scope, and published OAuth URLs are https or loopback only. OwnServerPerimeter, JwtVerifier.verifyWithScopes, ProtectedResourceMetadata; ScopeEnforcementTest, ProtectedResourceMetadataTest (both modules) deterministic tests and the JDK HTTP server recorded perimeter, identity or OAuth metadata change
C10 Per-tool actionScopes require exact, case-sensitive verified OAuth scopes at step 2, before resource scopes, policy, approval, credentials or the backend; missing scopes deny SCOPE_DENIED naming them; the requirement is part of the approval and receipt binding; identities without OAuth grants (static, SPIFFE, stdio, Knox) are denied scoped tools. GovernanceEngine, Action.binding, CallerIdentity.scopes, JwtVerifier, GatewayFactory; GovernanceEngineTest.missingActionScopeDeniesBeforeCredentialsOrBackendAndFullGrantProceeds, GatewayFactoryTest.actionScopesAreTrustedToolRequirementsAndDenyBeforeBackendAccess, SeparationOfDutiesTest.tokensFromAnotherGatewaySharingTheKeyAreRejected, JwtVerifierTest, ScopeEnforcementTest deterministic tests recorded scope parsing, identity, binding or control-order change

Source and adapter evidence

ID Claim Implementation and assertion Evidence target Status Revalidate when
S01 The shipped inventory includes seven named shared reference profiles, one separate teaching template, and 27 deployable adapter configurations with 123 tools. shared and adapter YAML configs; AdapterConfigsTest; DocumentationClaimsTest parsed configurations and layout contracts recorded any shared profile, adapter config or tool change
S02 The shipped comparison surface has 165 tools: 152 successors of the 0.1 inventory, ten Apache Burr (incubating) tools, two Kafka Admin reads, and one Superset chart read. No shipped tool is less guarded. Arrow, Beam, Hudi, Kudu, and Ozone are on the roadmap. Coverage01VsTwoTest frozen 0.1 inventory and 2.0 YAML recorded any config or 0.1 inventory change
S03 JDBC metadata/query behavior and result bounds work against actual Apache software. aegis-source-jdbc; JdbcToolSourceTest Apache Derby 10.16.1.1 recorded JDBC source change
S04 ZooKeeper data-tree operations, optimistic versions, binary handling and path rules work against actual Apache software. aegis-source-zookeeper; ZooKeeperToolSourceTest ZooKeeper 3.9.3 through Curator TestingServer recorded ZooKeeper source change
S05 Configured ZooKeeper AdminServer command names exist in ZooKeeper’s own command registry. ZooKeeperAdminCommandsTest ZooKeeper Commands registry recorded ZooKeeper admin config change
S06 A working-tree run was reported for Flink source governance against a real local Flink 1.20.1 MiniCluster; no candidate-bound artifact is retained. RealFlinkTest Flink 1.20.1 MiniCluster recorded Flink source, Flink version or config change
S07 Working-tree runs were reported for Spark read-source governance and Spark Connect source governance against local Spark 4.0.1 runtimes; Spark standalone submission/kill was not exercised. RealSparkTest, RealSparkConnectServerTest Spark 4.0.1 driver UI; Spark Connect 4.0.1 local server recorded Spark, Spark Connect or source/config change
S08 Iceberg catalog governance worked against an official REST catalog server in retained historical two-door runs. IcebergFrontDoorsTest (own host at 2026-10-04T23:40:55Z, Knox at 2026-10-04T23:41:50Z), RealIcebergRestCatalogTest Iceberg 1.10.1 RESTCatalogServer verified-historical any later source/config change
S09 Kafka Admin and Connect governance worked against a broker and worker in retained historical two-door runs. KafkaFrontDoorsTest (own host at 2026-10-05T01:28:15Z, Knox at 2026-10-05T01:29:32Z), ExampleConfigsTest.kafkaConnectAndAdminClient Kafka 3.9.1 KRaft and Connect verified-historical any later source/config change
S10 HTTP adapter configs are parsed, routed and governed, and target-version compatibility needs a retained real-engine run for each target. AdapterConfigsTest contract route harness implemented-contract target engine real run
S11 Arrow, Beam, Hudi, Kudu, and Ozone are planned typed sources and are not part of this release. absence from the adopters/configurations/adapters/<adopter>/ profile directories; Coverage01VsTwoTest.UNIMPLEMENTED_ENGINES source inspection and executable verdict accounting not shipped a real source for any of the five

Hosts and integrations

ID Claim Implementation and assertion Evidence target Status Revalidate when
H01 The own-server host authenticates JWTs and governs a real local HTTP request. GatewayHostTest local JDK HTTP server and local JWKS fixture recorded host or identity change
H02 The Knox extension maps a Knox Subject and governs a proxied MCP call. KnoxExtensionTest Knox 3.0.0 API plus handler-independent test MCP server recorded Knox extension or Knox version change
H03 A Knox 3.0.0 cold-install transcript is retained for the stock gateway, demo LDAP, and AclsAuthz. docs/evidence/knox-3.0.0-cold-install/ stock Knox 3.0.0 and a test MCP backend recorded before any release or Knox claim broadening
H09 A preserved source comparison found no packaged Knox classes at its 2026-09-29 revisions; the current packaging boundary remains a separate executable assertion. KnoxPackagingBoundaryTest; tools/provenance/compare_knox_source.py historical knox-source-comparison.json; current POMs, production source, and built jars verified-historical host packaging, extension import or Knox baseline change
H04 Iceberg REST integration used the published Iceberg REST Catalog protocol, not a private endpoint model, in the retained 2026-10-04 UTC run. iceberg.yaml, IcebergFrontDoorsTest, RealIcebergRestCatalogTest Apache Iceberg REST Catalog API verified-historical Iceberg config or catalog version change

Rules for changing this file

  1. Add or update a row whenever an externally visible capability, count or compatibility claim changes.
  2. Change verified-current to verified-historical after any relevant code/configuration change until the exact target run repeats.
  3. Preserve the command output or raw transcript under docs/evidence/ before promoting a row to verified-current. The evidence must bind the exact candidate commit and tree, include a SHA-256 manifest, and retain or content-address the selected Surefire/reactor output.
  4. A test double must be identified, never implied away. A source route, a deterministic response and a real product response are different evidence classes.
  5. Update each referenced documentation sentence in the same change. DocumentationClaimsTest guards the inventory arithmetic; this matrix is the review surface for the remaining qualitative claims.

MCP security additions

ID Claim Implementation and assertion Evidence target Status Revalidate when
H05 Own-server route groups reject an identity before its MCP/admin body is buffered or dispatched. OwnServerSecuritySettings (host.routes), OwnServerPerimeter, AegisServer.serve; OwnServerPerimeterTest.routeAdmissionUsesIdentityAndRouteGroupBeforeAnyBodyIsNeeded, GatewayHostTest.ownHostRouteGroupsAndCorsRunBeforeMcpDispatch local JDK HTTP server recorded perimeter or host binding change
H06 Browser preflight uses exact origins and cannot advertise an origin the common MCP handler rejects. OwnServerSecuritySettings (host.cors), OwnServerPerimeter.preflight, AegisServer.preflight; OwnServerPerimeterTest.corsPolicyUsesExactOriginsAndHeaderNormalization, GatewayHostTest.corsPreflightCannotAdvertiseAnOriginTheMcpHandlerRejects local JDK HTTP server recorded CORS or origin-check change
H07 Own-server OAuth protected-resource metadata follows RFC 9728 and is bound to the JWT audience unless explicitly escaped. ProtectedResourceMetadata, OwnServerSecuritySettings (host.oauth); ProtectedResourceMetadataTest (both modules), OwnServerSecuritySettingsTest.oauthMetadataRequiresAudienceBindingUnlessExplicitlyEscaped local JDK HTTP server recorded OAuth metadata or identity change
H10 In the retained 2026-10-05 run, the dated knox-bundle jar loaded in a stock Apache Knox 3.0.0 gateway process and governed MCP calls end to end: Knox demo-LDAP authentication and AclsAuthz admitted the route, Aegis denied a reader’s destructive call, required an independent approval and a dry-run receipt, executed the approved delete on a real ZooKeeper 3.9.3 server, and refused the replay; both audit journals verified. ZooKeeperFrontDoorsTest (OWN_HOST and KNOX); retained run, knox-bundle SHA-256 0726C4CE71D23856F8FE9A58BE2C80E7FC7E4AE740ED70E8ECC8CBFB2617B780 stock Knox 3.0.0 (bin/gateway.jar) with the bundle in ext/, real ZooKeeper 3.9.3, 2026-10-05 verified-historical any extension, bundle, Knox version or candidate change
H08 The Knox bundle contains the Aegis engine, MCP, OTLP, configuration and PostgreSQL state modules, the PostgreSQL driver and the extension, and no Knox, servlet, JAX-RS, Jersey, Jackson or SnakeYAML class. aegis-knox3-extension/pom.xml shade include list; KnoxPackagingBoundaryTest.builtHostsShareAegisGovernanceButNotHostImplementations reads the built knox-bundle jar built jar in the default reactor recorded shade list or dependency change
S12 derby-local persists durable local governance state for one process, with exact nonce and rate semantics. aegis-state-derby, StateStoreFactory; DerbyStateStoreTest, GatewayHostTest.derbyLocalStateProviderIsDiscoveredByTheOwnServer Apache Derby 10.16.1.1 embedded recorded state store or Derby version change
S13 A quarantined MCP/HTTP/plugin source contributes no callable tool and must identify its evidence reference. sources[].trust, GatewayFactory.SourceBuild.bind; GatewayFactoryTest.sourceTrustQuarantineHidesEveryToolUntilOperatorConfigActivatesTheSource deterministic configuration test recorded source binding change
S14 In the historical 2026-10-08 managed PostgreSQL run, two PostgreSQL providers reportedly shared nonce/rate state, and persistence, expiration, escaped scans, invalid rate requests, environment-named credentials, and signed serial high-water rollback protection behaved as described. The engine version was not retained, and the run is not candidate or active-active certification. PostgresStateStoreIT; PostgreSQL validation evidence temporary managed PostgreSQL instance, deleted after the run; no immutable raw artifact retained recorded state provider, PostgreSQL version, candidate release, or deployment topology change
S15 In the historical 2026-10-03 run, two gateway processes using one postgres namespace reportedly shared approvals, single-use approval and receipt nonces, signed serial high-water state, and rate windows. The run did not cover replication, failover, or a release candidate. TwoGatewayProcessesPostgresIT; two-gateway evidence two Main JVMs, real PostgreSQL 17.6 on loopback; no immutable raw artifact retained recorded state provider, approval or rate code, PostgreSQL version, or candidate release change
S16 With audit.checkpoint the journal exports its head on a record count, a timer, open and close; it refuses to reopen a journal that is shorter than or different at the last exported head without exporting anything, and --verify-audit --checkpoints reports truncation and regeneration that the chain alone accepts. HashChainFileAuditSink, AuditCheckpointVerifier, Main; AuditCheckpointTest, MainAndSettingsTest.auditCheckpointsAreWrittenFromConfigAndCheckedFromTheCommandLine, AuditCheckpointAndManifestConfigTest deterministic file tests recorded audit sink, checkpoint format or CLI change
S17 A signed catalog.manifest (Ed25519, verified before parsing) activates exactly its pinned tools in REQUIRE_PINS; a changed definition is quarantined, an edited manifest, another key or another gateway name stops start-up, and a conflicting inline pin is refused. The gateway jar generates keys, creates a manifest from a reviewed GET /aegis/v1/catalog reply, signs and verifies. SignedCatalogManifest, GatewayFactory, CatalogManifestCommands; SignedCatalogManifestTest, SignedCatalogManifestFlowTest (real own host), AuditCheckpointAndManifestConfigTest JDK Ed25519; real own host on loopback recorded manifest format, signature algorithm or pin semantics change
S18 Historical 2026-10-03 OpenBao and 2026-10-05 Vault runs reportedly showed strict secret replacement and fail-closed KV v2 behavior. Neither run retained immutable raw output; Vault namespaces and server TLS were not exercised. FileSecretProvider, VaultKvSecretProvider, SecretProviderFactory; SecretProvidersTest, VaultKvSecretProviderIT; OpenBao evidence real OpenBao 2.7.1 and Vault 1.17.6 dev servers on loopback recorded provider code, KV API or OpenBao/Vault version change
H12 File-based SPIFFE identity tests exercise real JDK TLS with keytool-issued certificates: mapped URI SANs authenticate, while missing, untrusted, ambiguous, wrong-domain, and unmapped certificates fail. They do not exercise SPIRE Workload API issuance. SpiffeIdentity, OwnServerSecuritySettings, AegisServer; SpiffeMutualTlsTest (real TLS), SpiffeIdentityTest JDK TLS with keytool-issued certificates, not SPIRE-issued certificates recorded identity, TLS host or SVID rule change
S20 The kafka-admin source creates, describes, lists and deletes topics on a real Kafka 3.9.1 KRaft broker in the default build; a dry run is the broker’s own validateOnly check, creates nothing, and an impossible replication factor is refused by the broker. KafkaAdminToolSource; ExampleConfigsTest.kafkaConnectAndAdminClient with RealKafkaBroker real broker in its own JVM from aegis-validation-kafka-server recorded Kafka version or kafka-admin source change
G01 hooks[].type: project-governance enforces evidence references for configured high-impact actions and denies protected resources. ProjectGovernanceGuardrail; ProjectGovernanceGuardrailTest, and ApacheProjectGovernanceProfileTest for the profile build and tool visibility deterministic hook tests; profile built in a temporary directory recorded guardrail setting, hook or profile change
S21 The historical own-host Keycloak run reportedly gave each caller a per-user RFC 8693 backend token with no inbound-token forwarding, fallback, or token journaling. Current stricter token parsing postdates that run. Knox does not bind the required verified subject token and fails closed. TokenExchangeCredentialsTest; examples/adopters/token-exchange/keycloak_e2e.py (evidence) Keycloak 26.8.0 standard token exchange, own host; no immutable raw run artifact retained recorded credential provider, host binding or Keycloak version change
S22 The a2a source offers an A2A 1.0 agent as one governed tool, applies the source credential, and enforces the card endpoint origin rule. A2aToolSourceTest; A2aAgentFrontDoorsTest agent on the official a2a-sdk 1.2.1, own host and Knox 3.0.0 recorded a2a source, A2A protocol or SDK version change
S23 --openapi-draft produces a configuration that loads, with every tool DESTRUCTIVE and a deny-all policy, from the published Iceberg 1.10.1 REST document; a reviewed tool reaches the real catalog with the document’s schema enforced. OpenApiDraftTest, OpenApiDraftCommandTest, OpenApiDraftIcebergTest Iceberg 1.10.1 RESTCatalogServer recorded generator or schema validator change
S24 A remote schema $ref is never fetched and denies the call; local $refs are enforced and cycles are bounded. SchemaRefTest deterministic recorded schema validator change
S25 Optional serverCatalog: an offline Ed25519-signed register, verified before parsing, decides at startup which configured sources start. Unlisted or changed (source-digest mismatch) sources stop start-up; QUARANTINED or REVOKED sources are never constructed or discovered; only pinned tools are bound; pinning becomes signed-only (an inline or manifest pin the catalog does not carry stops start-up). A break-glass order under a separate key can only reduce capability by quarantining or revoking named sources for at most 24 hours, and an expired order refuses start-up. The gateway jar generates, signs and verifies both files offline. No admin route exists for either. Deterministic tests and the reported four-engine two-door runs are recorded; their target output exists only under ignored target/ paths, and Spark Connect was not run with a catalog. Key custody remains the operator’s. Signed serial rollback protection depends on the configured atomic state-store high-water mark; unnumbered same-key files remain signature-only. SignedServerCatalog, BreakGlassContainment, CatalogIntegrity, GatewayFactory, ServerCatalogCommands; SignedServerCatalogTest, ServerCatalogConfigTest, ServerCatalogFlowTest (real own host), AdminApiTest.noRouteRegistersABackendAtRunTime JDK Ed25519; real own host on loopback; real Flink 1.20.1, Iceberg 1.10.1, Spark 4.0.1 and Kafka 3.9.1 through the own host and stock Knox 3.0.0 (FlinkFrontDoorsTest, IcebergFrontDoorsTest, SparkFrontDoorsTest, KafkaFrontDoorsTest, run) recorded catalog or order format, source digest, pin or acceptance semantics change
G02 The reference PII, secrets and change-window hooks refuse before the backend sees the call, withhold a result carrying a card number, and a stopped hook makes the gateway deny. adopters/hooks/test_hooks.py; adopters/hooks/e2e_gateway.py gateway jar as a process, CPython http.server backend recorded hook contract or hook service change
G03 Security properties S1-S31 that have deterministic tests have a documented focused-suite plan; the product threat model documents assets, DFD, STRIDE by zone, TM01-TM10, and residual risk. The reported 2026-10-05 result is not bound to this review candidate by immutable raw evidence, so it is not current verification. SECURITY.md, THREAT-MODEL.md; focused suite and per-class catalogue in SECURITY-VALIDATION.md reported JDK 17.0.7 Maven surefire run, 227 selected tests, 0 reported failures (2026-10-05) recorded any S1-S31 control, host perimeter, approval, egress, audit or identity change; promote only with candidate-bound raw evidence
H11 The Helm chart renders valid Kubernetes 1.33 manifests, refuses unsafe values, and its rendered configuration starts the gateway with the StatefulSet’s own arguments. charts/aegis/ci/start_rendered.py; helm lint, kubeconform Helm 4.3.0, kubeconform 0.8.0; no cluster recorded chart or Dockerfile change