# MITRE ATLAS Mapping

Aquaman maps to **MITRE ATLAS v5.4.0 (Adversarial Threat Landscape for Artificial-Intelligence Systems)** — a stable, machine-readable catalog of adversary techniques widely cited in audit reports. The 2026 ATLAS updates added agent-focused techniques; the one most directly in aquaman's lane is **AML.T0098 (AI Agent Tool Credential Harvesting)**, mapped below.

Below: each ATLAS technique aquaman addresses, the aquaman feature that mitigates it, and the runnable test that proves the mitigation holds.

Run all ATLAS conformance tests with `vitest run test/compliance/atlas/` (or just `npm test`, which runs the whole suite). The opt-in loopback listener (Hermes path, v0.13.0+) is a network-reachable surface and is covered separately in [`test/compliance/loopback-listener.test.ts`](https://github.com/tech4242/aquaman/blob/main/test/compliance/loopback-listener.test.ts). The Hermes Python plugin — a credential-free status layer that performs no isolation itself — is conformance-tested in [`packages/hermes/tests/test_compliance.py`](https://github.com/tech4242/aquaman/blob/main/packages/hermes/tests/test_compliance.py) for the controls applicable to it (it is verified to never *undermine* the proxy's isolation, not to enforce it).

| Technique | Title | Aquaman mitigation | Test |
|---|---|---|---|
| **AML.T0055** | Unsecured Credentials | Credentials live in a vault backend (Keychain, 1Password, HashiCorp Vault, KeePassXC, encrypted-file, systemd-creds, Bitwarden, Keeper). The agent process never sees them — only a sentinel base-URL and a placeholder `aquaman-proxy-managed` marker. The proxy strips placeholder + injects the real credential before forwarding upstream. Post-tool-output redactor catches secrets that might leak into transcripts. The same guarantees hold on the opt-in loopback listener (Hermes path) — token-gated instead of socket-file-gated, placeholder stripped, real key injected only on the upstream leg. | [`t0055-unsecured-credentials.test.ts`](https://github.com/tech4242/aquaman/blob/main/test/compliance/atlas/t0055-unsecured-credentials.test.ts), [`loopback-listener.test.ts`](https://github.com/tech4242/aquaman/blob/main/test/compliance/loopback-listener.test.ts) |
| **AML.T0012** | Valid Accounts | Even with valid credentials injected, request-level policy enforcement (method + path deny rules per service) blocks privileged paths *before* credentials are injected. Hash-chained audit log records every denied request with tamper-evident chain. Denied requests never reach the upstream provider. | [`test/compliance/atlas/t0012-valid-accounts.test.ts`](https://github.com/tech4242/aquaman/blob/main/test/compliance/atlas/t0012-valid-accounts.test.ts) |
| **AML.T0062** | Exfiltration via AI Agent Tool Invocation | Same policy engine + audit log. An agent that tries to exfiltrate via a sanctioned tool call (e.g., `Authorization`-bearing `curl`) is intercepted by the proxy, evaluated against policy, and either denied (403) or logged. Header-stripping in the HTTP interceptor removes `Authorization` + `X-API-Key` from outgoing requests before routing — so even if the agent presets them, they're scrubbed before egress. | [`test/compliance/atlas/t0062-exfiltration-via-tool.test.ts`](https://github.com/tech4242/aquaman/blob/main/test/compliance/atlas/t0062-exfiltration-via-tool.test.ts) |
| **AML.T0090** | OS Credential Dumping (Process credential access) | Credentials never reside in the agent's process address space. They live in a separate proxy process accessed via Unix Domain Socket (`chmod 0o600`). Even RCE in the agent cannot dump credentials from the agent's own memory because they were never there. The broker endpoint (v0.12.0+) materializes credentials per tool call and the consumer scrubs them after the indicated TTL. On the Hermes path the agent host only ever holds the loopback *token* as its api_key — never the real credential — so dumping the host process yields nothing usable. | [`t0090-os-credential-dumping.test.ts`](https://github.com/tech4242/aquaman/blob/main/test/compliance/atlas/t0090-os-credential-dumping.test.ts), [`loopback-listener.test.ts`](https://github.com/tech4242/aquaman/blob/main/test/compliance/loopback-listener.test.ts) |
| **AML.T0098** | AI Agent Tool Credential Harvesting (added ATLAS 2026 / v5.4.0) | An agent uses its tools (file reads, shell) to harvest credentials and surface them. Layered defense: (1) nothing to harvest — credentials never enter the agent process (see T0090); (2) per-tool-call broker materialization with a TTL instead of a long-lived export; (3) the post-tool-output redactor scrubs both secret-shaped strings and the verbatim injected values before they can reach a transcript. The `aquaman-coder` PreToolUse hook additionally blocks reads of `.env*`, `*.pem`, `id_rsa`, `.aws/credentials`, `.ssh/*`. The Hermes `aquaman_status` tool/command is itself an agent-callable surface; it is conformance-tested to never surface the loopback token or any key value (it lists only non-secret metadata). | [`t0098-credential-harvesting.test.ts`](https://github.com/tech4242/aquaman/blob/main/test/compliance/atlas/t0098-credential-harvesting.test.ts), [`hermes/tests/test_compliance.py`](https://github.com/tech4242/aquaman/blob/main/packages/hermes/tests/test_compliance.py) |

## What this is not

- Not an official ATLAS certification (ATLAS is a catalog, not a conformance program).
- Not a complete defense against the techniques — see "Limits" below.

## Limits

- **AML.T0055:** Vault backends themselves can be compromised. Aquaman shifts the trust boundary from agent process → vault; it doesn't eliminate it.
- **AML.T0012:** Policy rules are operator-defined. A misconfigured allow-everything policy leaves the path open. `aquaman doctor` validates the policy config but cannot validate intent.
- **AML.T0062:** Header-stripping covers `Authorization` and `X-API-Key`. Other auth schemes (cookies, custom headers, query-string-embedded tokens) flow through untouched and rely on the policy engine.
- **AML.T0090:** The broker endpoint materializes credentials in the agent shell's env for the duration of the tool call. That's still a non-zero window where the credential exists outside the proxy. The consumer's responsibility is to scrub after.
- **AML.T0098:** The redactor is pattern- and value-based. A secret the agent transforms (base64, splits across lines, re-encodes) before surfacing it can evade pattern matching; the verbatim-value scrub only covers values aquaman itself injected. Layer 1 (isolation) is the real mitigation — redaction is defense-in-depth, not a guarantee.
- **Hermes loopback path:** the listener binds to `127.0.0.1` and is token-gated, but it is reachable by *any* local process (unlike the `0o600` UDS, which is user-restricted by the filesystem). The per-install token in `~/.hermes/.env` is the access boundary — protect that file. The `aquaman-hermes` Python plugin enforces none of this: it is a credential-free status/health layer, and the conformance tests assert only that it does not undermine the proxy's isolation.
- **Credential cache (v0.13.1+):** for backends with per-access cost (1Password, Bitwarden, Vault) the daemon holds fetched values in its own memory for a bounded TTL (default 15 min, configurable to 0) instead of per-request only. This extends *residency duration inside the already-trusted proxy process*; it does not change what the agent process can reach (T0055/T0090 hold unchanged), is never persisted, and is invalidated on writes. Verified in [`test/compliance/cache-residency.test.ts`](https://github.com/tech4242/aquaman/blob/main/test/compliance/cache-residency.test.ts).

## References

- ATLAS Matrix: https://atlas.mitre.org/
- ATLAS Technique IDs cited above are stable across v5.x releases.
- For a machine-readable evidence report keyed by technique ID, run `vitest run test/compliance/atlas/ --reporter=json`.
