DEVELOPER GUIDE
Use Aegis to govern your project, or change Aegis itself.
Sections 1 to 4 are for teams putting Aegis in front of an engine. Sections 5 to 9 are for people who extend it. The fastest hands-on start is a project tutorial: each one comes from a kept real run through both front doors.
1. BUILD AND RUN
One Maven build, one runnable jar.
JDK 17 or newer and Maven 3.9 or newer. The default build reaches no external network. Besides embedded Apache Derby and Apache ZooKeeper, it starts one engine process: a Kafka 3.9.1 broker on loopback for the Kafka Admin test.
mvn -B clean install # all modules, tests, license headers, coverage gates
mvn -B -Preal-engines clean install # adds the real-engine validation modules
java -jar aegis-gateway/target/aegis-gateway-2.0.0-SNAPSHOT-all.jar --config my-aegis.yaml
java -jar aegis-gateway/target/aegis-gateway-2.0.0-SNAPSHOT-all.jar --config my-aegis.yaml --stdio
java -jar aegis-gateway/target/aegis-gateway-2.0.0-SNAPSHOT-all.jar --verify-audit audit/aegis.jsonl
java -jar aegis-gateway/target/aegis-gateway-2.0.0-SNAPSHOT-all.jar --verify-audit audit/aegis.jsonl --checkpoints anchor/heads.jsonl
echo -n "$TOKEN" | java -jar aegis-gateway/target/aegis-gateway-2.0.0-SNAPSHOT-all.jar --hash-token
$env:TOKEN | java -jar aegis-gateway/target/aegis-gateway-2.0.0-SNAPSHOT-all.jar --hash-token # PowerShell
java -jar aegis-gateway/target/aegis-gateway-2.0.0-SNAPSHOT-all.jar --openapi-draft openapi.yaml draft.yaml --source-id orders --base-url https://orders.internal.example
docker build -t aegis-gateway:2.0.0-SNAPSHOT . # non-root image; plugins go in /opt/aegis/plugins
helm install aegis charts/aegis -f my-values.yaml # StatefulSet, one audit journal volume per replica
For a Spark Connect source use examples/aegis-gateway-spark/target/aegis-gateway-spark-2.0.0-SNAPSHOT-all.jar, and for the Kafka Admin source examples/aegis-gateway-kafka/target/; the commands are the same. Exit codes of the command-line modes: 0 success, 1 broken audit chain or manifest, 2 usage error. A configuration error stops start-up with a message that names the key.
2. WRITE A CONFIGURATION
Start from the closest profile; unknown keys stop start-up.
Shared profiles live in adopters/configurations/<name>/<name>.yaml (Spark, Spark Connect, Flink, Iceberg, Kafka, an A2A agent, an existing MCP server, and the teaching template template/TEMPLATE.yaml), and 25 adapter profiles in adopters/configurations/adapters/. The minimum file has sources, policy, audit.file and a host section. Every key is in the configuration reference.
| Step | Why |
|---|---|
Classify every tool with class | An unclassified tool is DESTRUCTIVE; MUTATE and DESTRUCTIVE need an independent per-call approval, and DESTRUCTIVE also a fresh dry-run receipt. |
Name the resources each tool touches (resources: [{type, pointer}]) | Policy rules and scopes match typed resources, not raw arguments. |
Give destructive tools a real preview (dryRun) | The backend's validate-only flag (ARGUMENT) or a read tool (TOOL) shows the approver the actual target. |
List every backend host in egress | Every HTTP destination, including URLs inside arguments, plus Kafka bootstrap and Spark Connect endpoints is checked. Kafka listener addresses advertised after bootstrap need Kafka listener configuration and network policy. |
| Test policy changes in CI | --policy-test <aegis.yaml> <cases.json> evaluates declarative type: http cases without backend, audit or approval. MCP and plugin sources are refused before discovery, and a remote OPA PDP is refused; it exits 1 when a case does not match. |
| Start a REST API from its OpenAPI document | --openapi-draft writes every operation as a DESTRUCTIVE tool with a deny-all policy and lists what it could not express; classify, trim and write policy before use. |
| Give the backend each user, not one account | credentials: {type: token-exchange, tokenEndpoint, clientIdEnv, clientSecretEnv, audience} exchanges the caller's verified JWT per call (RFC 8693). Own host with JWT identity only; no fallback. |
Pick a secrets.source | env (default), file (a mounted directory) or vault (one KV v2 secret). The names in the file stay the same. |
Use catalog.mode: REQUIRE_PINS with signed pins | A catalog.manifest signed off the gateway host decides which tool definitions may run. |
Add audit.checkpoint | Exports the journal head to storage the journal writer cannot rewrite, so truncation and regeneration are detected. |
3. CONNECT A CLIENT OR IDE
Streamable HTTP, stdio, or through Knox.
- Own host, HTTP.
POST http://host:8080/mcpwithAuthorization: Bearer <token>. 2026-07-28 clients sendMCP-Protocol-Version,Mcp-MethodandMcp-Nameheaders that must match the body; 2025 clients callinitializeand use theMcp-Session-Idthey receive. - Own host, mutual TLS. With
host.tls.clientAuth: requirethe client presents a certificate from theclientCaFilebundle; withidentity.type: spiffethat certificate is an X.509-SVID mapped to a caller. - stdio. Run the jar with
--stdio; the caller ishost.stdio. - Knox.
https://<knox>/gateway/<topology>/aegis-mcp/v1/mcp; Knox authenticates and checks the route ACL, Aegis governs the call. - Controls go in
params._meta:io.github.vaquarkhan.aegis/dryRun,.../approvalToken,.../dryRunReceipt, and optionally a W3Ctraceparent. - Decisions come back in
result._meta["io.github.vaquarkhan.aegis/decision"]for tools, and as JSON-RPC error -32010 with the deny code for resources, prompts and completion.
Generated IDE files differ by client. VS Code includes separate own-host mcp.json and Knox mcp.knox.json variants. Kiro uses one mcp.json with own host enabled and the Knox entry present but disabled. Cursor's generated mcp.json is own-host only. The token supplied to the selected own-host entry decides who the assistant is to Aegis.
4. OPERATE
Approvals, definitions, audit and health.
| Task | How |
|---|---|
| Decide or inspect an approval | Approvers list pending requests with GET /aegis/v1/approvals and decide with POST /aegis/v1/approvals/{id}/approve or /deny. The requester or an approver may inspect one request with GET /aegis/v1/approvals/{id}, but only the requester receives the single-use token. A requester cannot approve their own request. |
| Accept a changed definition | GET /aegis/v1/catalog, then POST /aegis/v1/catalog/{tool}/accept with exactly one Aegis-Definition-Digest header copied from the reviewed entry. Signed and configured pins cannot be overridden this way. |
| Sign the catalog | --manifest-keygen <private.pem> <public.pem>, --manifest-create <catalog-reply.json> <manifest.json> <gateway-name>, --manifest-sign <manifest.json> <private.pem>, --manifest-verify <manifest.json> <public.pem> <gateway-name>. Keep the private key off the gateway host. |
| Sign the server catalog | --server-catalog-create <aegis.yaml> <catalog-reply.json> <servers.json>, review it, --manifest-sign <servers.json> <review.key>, --server-catalog-verify <servers.json> <review.pub> <gateway-name>, then set serverCatalog. Only listed sources start; changes apply on restart. Add --serial <n> to refuse older catalogs once this one is accepted, and start the gateway with --require-server-catalog <review.pub> so the configuration cannot drop the catalog. |
| Contain a server in an incident | With a separate incident key: --break-glass-create <order.json> <gateway-name> <incident> <minutes> <id>=QUARANTINED|REVOKED, --manifest-sign, --break-glass-verify, set serverCatalog.breakGlass and restart. At most 24 hours; an expired order stops startup. Walk-through: examples/break-glass-mcp-servers/ in the repository. |
| Check the journal | --verify-audit <journal>, or with --checkpoints <file> to also check every exported head. GET /aegis/v1/audit/verify answers verified: true|false to access.auditVerifierGroups. |
| Probe and measure | /healthz; /readyz answers 503 until at least one tool is active; /metrics in Prometheus text, authenticated like /mcp. |
5. WHERE TO CHANGE WHAT
Governance lives in the engine; everything else carries it.
| You want to | Change | Do not |
|---|---|---|
| add a control to every call | aegis-engine (GovernanceEngine, control/) or a GovernanceHook plugin | put governance in a source or a front door |
| support a backend with a Java client | a module with a ToolSourceFactory (see examples/aegis-spark-connect) | add its client to engine, mcp or config |
| support a REST backend | a configuration file with type: http | write Java |
| change protocol handling | aegis-mcp (McpServerHandler, HttpMcpClient, StdioMcpClient) | trust a header that disagrees with the body |
| add a configuration key | GatewayFactory, CONFIGURATION.md and a test | accept unknown keys |
| change own-host identity, OAuth metadata, routes or CORS | aegis-mcp-security (OwnServerSecuritySettings, OwnServerPerimeter, JwtVerifier, SpiffeIdentity) | put transport code there; aegis-gateway owns the JDK HTTP binding |
| add a state or secret provider | a module with a StateStoreFactory (see aegis-state-derby) or a SecretProviderFactory | weaken the atomic StateStore contract, or skip the egress check |
| change trace export | aegis-observability-otlp | let an exporter block or change a decision |
| change Knox integration | aegis-knox3-extension only | bundle Knox, Jersey, Jackson or servlet classes |
6. EXTENSION POINTS
ServiceLoader interfaces and in-process seams.
| Interface | Selected by | Contract |
|---|---|---|
config.spi.ToolSourceFactory | sources[].type | Contributes tool descriptors and executors only. GatewayFactory invokes create(id, settings, context). The default three-argument method delegates to the required two-argument method for compatibility; override the context-aware method when the source needs host services such as context.env(). |
config.spi.GovernanceHookFactory | hooks[].type | Builds a GovernanceHook: deny before a call, rewrite or withhold after it. |
config.spi.StateStoreFactory | state.type | Durable or shared state; must keep the atomic put-if-absent, take and rate semantics. |
config.spi.SecretProviderFactory | secrets.source | Returns name to value, null for unknown names; receives the egress check and must use it for every destination. |
engine.spi.CredentialProvider | embedding host (BuildContext) | Backend credentials per source, resolved at execution time, never before. Built in: static credentials and RFC 8693 token exchange, which reads the verified caller token from engine.spi.SubjectToken for the duration of the request only. |
engine.spi.PolicyDecisionPoint | built in: rules and OPA | Allow or deny with a reason; all configured PDPs must allow. |
engine.spi.DecisionListener | embedding host | Observes decisions (metrics, tracing); cannot change them. |
Register a factory in META-INF/services/io.github.vaquarkhan.aegis.config.spi.<Interface>. Built-in names (mcp, http, memory, env, file, vault) always select the built-in implementation, and a hook factory that claims a built-in hook name stops start-up.
7. WRITE A SOURCE PLUGIN
Capability only: descriptors and executors.
public final class MyEngineToolSourceFactory implements ToolSourceFactory {
@Override public String type() { return "my-engine"; }
@Override public ToolSource create(String id, ConfigNode s) {
// Compatibility path for direct callers without a BuildContext.
return create(id, s, System::getenv);
}
@Override public ToolSource create(String id, ConfigNode s, BuildContext context) {
// GatewayFactory calls this overload.
return create(id, s, context.env());
}
private ToolSource create(String id, ConfigNode s, Function<String, String> env) {
String host = s.requiredString("host"); // read every key you support;
int port = (int) s.integer("port", 9000); // unknown keys fail startup
String tokenEnv = s.requiredString("tokenEnv");
String token = env.apply(tokenEnv); // resolve named secrets through the host
if (token == null || token.isBlank()) {
throw new ConfigException(s.path() + ".tokenEnv names an unset or empty variable");
}
return new MyEngineToolSource(id, host, port, token);
}
}
- Classification, resources, groups and previews come from the operator's
tools:section, never from the source. ToolSource.configuredEndpointsreports the endpoints the plugin connects to from its configuration (for exampletcp://broker:9092), so their hosts join the egress allow list, andToolExecutor.egressTargetsreturns the same endpoints so the egress guard checks them and every DNS answer on each call.- Use
ExecutionContext.credentials()and forwardExecutionContext.traceparent()when the protocol carries metadata; honourtimeoutMillis(). - Caller mistakes are a
ToolResultwithisError: true; outages are anExecutionExceptionand count towards the circuit breaker. - Never build a query by concatenating an argument; validate identifiers and quote them.
aegis-source-a2ais a small worked example with no dependencies beyond the Aegis modules: card discovery, an origin rule for the endpoint, bounded HTTP and reply mapping.- Return
truefromdispatchesByUpstreamName()only if one executor serves several tools byupstreamToolName(); that enables dry-run modeTOOL.
8. WRITE A GOVERNANCE HOOK
In another process, or in-process.
Without Java: configure hooks: [{type: remote, settings: {url: ...}}] and answer {"allow": true|false} over HTTP; the URL passes the egress check at start-up. In-process: implement GovernanceHook and ship a GovernanceHookFactory (aegis-mcp-guardrails is a worked example). For the remote path, adopters/hooks has three reference services in Python's standard library (PII guard, secrets guard, change window) with unit tests and a live run against the gateway jar.
before(Context)may deny withPOLICY_DENIED,INVALID_INPUTorPROMPT_INJECTION.afterTool(Context, ToolResult)andafterContent(Context, Map)may rewrite or withhold a result; throwHookDenied(code, reason)to withhold with a reason that reaches the audit record.- Operators narrow a hook with
operations,methods,groupsandsources, and chooseENFORCEorAUDIT. InENFORCEa hook that throws denies.
9. TESTS AND EVIDENCE
A behavior change comes with a test that fails without it.
| Build | What runs | Needs |
|---|---|---|
| default | Every module's unit and integration tests, RAT, per-module JaCoCo floors, the Kafka Admin test against a real KRaft broker, the SPIFFE test over real mutual TLS | JDK and Maven |
-Preal-engines | Real engines through the own host and, with AEGIS_KNOX_HOME, a stock Knox 3.0.0 | Engine-specific variables listed in each example README |
-Ppostgres-integration | PostgresStateStoreIT, TwoGatewayProcessesPostgresIT | AEGIS_POSTGRES_URL, _USER, _PASSWORD |
-Pvault-integration | VaultKvSecretProviderIT | AEGIS_VAULT_ADDR, AEGIS_VAULT_TOKEN |
adopters/hooks scripts | python -m unittest test_hooks; python e2e_gateway.py --jar ...-all.jar against the running gateway (CI runs both) | Python 3 and the built jar |
charts/aegis/ci | helm lint, helm template with kubeconform, start_rendered.py; CI also builds and starts the image | Helm, kubeconform, Python with PyYAML |
-Prelease | The default build plus release checks and a CycloneDX SBOM | JDK and Maven |
Rule. A test whose real target is not configured reports skipped, never passed. Protocol fixtures (TestMcpServer) and the adapter contract harness prove protocol and route behavior, not compatibility with a named product. What each run established is in VALIDATION and the claims matrix.
10. TUTORIALS
One per project with a kept real run.
The tutorial index lists the deep-dive tutorials (Spark and Iceberg, Spark and Spark Connect, Iceberg, Kafka, Flink) and one IDE-ready tutorial per verified project, built by tools/build-project-tutorials.py from that project's kept two-door run. Twenty-seven generated tutorials cover the Keep-verified engines, including Airflow, CouchDB, Doris, Druid, Hadoop, HBase, Hive, NiFi, Pinot, Ranger, Storm, and Superset. Projects with a configuration but no real run (Atlas, Cassandra, Impala, Paimon) have no tutorial; they are on the future roadmap.
Security reviewers should start with the HTML security guide (threat zones, TM01 to TM10, OWASP MCP handling, S1 to S31, and dated control-suite records with their attestation status) before reading THREAT-MODEL and SECURITY.
11. CONVENTIONS
From AGENTS.md.
- Fail closed: if a control cannot decide, deny.
- Reuse the stable deny codes in
DENY-CODES.md; new ones need review. - Apache License 2.0 header on every file that can carry one (RAT runs in the build).
- Keep the engine, mcp and config modules free of third-party runtime dependencies.
- Humans commit; agents propose. Disclose AI assistance in the pull request.