Many teams assume that once a Kubernetes pod runs an agent, the audit trail is automatically complete. In reality, the presence of nested agents often leaves critical commands invisible to logging systems.
When a pod launches an internal helper, such as a sidecar that spawns a database client, the outer agent records only the initial handshake. The helper’s subsequent queries, file reads, or remote calls bypass the outer logger entirely. Even if the organization enforces strict identity provisioning through OIDC tokens and assigns least‑privilege roles, the request still reaches the target service directly, without any intermediate enforcement point that can observe or control the inner activity.
This gap means that the audit trail lacks the granularity needed to answer questions such as: Who executed the destructive SQL statement? Which service account triggered the privileged API call? Without a unified observation point, post‑mortem investigations become guesswork, and compliance evidence is incomplete.
To close the visibility gap, the connection must be forced through a dedicated gateway that sits between the nested agents and the target resource. The gateway becomes the sole place where policy can be evaluated, commands can be blocked, and responses can be masked. It also provides a single source of truth for the audit trail, independent of any individual pod or sidecar.
Explore the hoop.dev source code and contribute on GitHub to see how the gateway captures every interaction.
hoop.dev is a Layer 7 gateway that proxies traffic for databases, Kubernetes exec, SSH, and other supported protocols. By placing hoop.dev in the data path, every byte that flows between any agent, nested or not, and the backend is inspected, recorded, and optionally transformed.
How hoop.dev captures a complete audit trail for nested agents
When a pod’s outer agent initiates a connection, hoop.dev authenticates the request using the organization’s OIDC identity provider. The request is then handed to the gateway, which forwards it to the target. If the outer agent spawns a nested client, that client inherits the same network route, so its traffic also passes through hoop.dev. Because hoop.dev is the only conduit, it records each command and response, producing a replay‑able session log that reflects the full interaction chain.
hoop.dev’s session recording is the source of the audit trail. It stores timestamps, user identifiers, and the exact payloads exchanged. Because the gateway controls the flow, it can also apply inline masking to hide sensitive fields before they reach logs, ensuring compliance without sacrificing forensic detail.
Practical steps to get reliable audit trails with nested agents
- Deploy the hoop.dev gateway using the official Docker Compose quick‑start or a Kubernetes manifest. The deployment includes a network‑resident agent that runs alongside your workloads.
- Register each Kubernetes resource (pods, sidecars, or services) as a connection in hoop.dev, supplying the necessary host, port, and credential information. The gateway holds the credentials; the agents never see them.
- Configure OIDC authentication so that every request carries a verified token. hoop.dev reads group membership to enforce just‑in‑time access and to tag audit records with the correct identity.
- Enable session recording and inline masking in the gateway’s policy configuration. This ensures that every nested interaction is captured and that any sensitive data is redacted before storage.
- Reference the getting‑started guide for detailed deployment steps, and explore the learn section for deeper explanations of masking and approval workflows.
Once deployed, any nested agent that attempts to communicate with a database, Kubernetes API, or SSH endpoint will be forced through hoop.dev. The resulting audit trail will include a reliable record of every command, regardless of how many layers of agents were involved.
FAQ
Does hoop.dev require changes to my application code?
No. hoop.dev works with standard client tools (psql, kubectl, ssh, etc.). The only change is directing traffic to the gateway’s address, which can be done via environment variables or service discovery.
Can I still use my existing OIDC provider?
Yes. hoop.dev is an OIDC relying party, so it validates tokens issued by any compliant provider such as Okta, Azure AD, or Google Workspace.
What happens if a nested agent bypasses the network route?
If traffic does not traverse hoop.dev, the audit trail will miss that activity. Enforcing network policies that route all pod egress through the gateway eliminates this risk.
