Session recording that captures everything except the one command that mattered is worse than no recording, because it hands you false confidence. For AI agents on AWS, the recording has to capture intent and action at the access boundary, scoped to exactly what the agent did, instead of a partial trace scraped from inside the agent after the fact.
This walks through configuring session recording for an AWS agent with least scope as the constraint: record the whole session for the access that happened, and nothing about access that did not.
What recording has to mean at the boundary
CloudTrail tells you an API call occurred and which role made it. That is necessary and not sufficient for an agent. It does not show the sequence of commands inside a session, it does not tie the actions to the specific task that drove them, and it lives in the same account the agent may be able to influence. Session recording at the boundary means the full interaction is captured at the point the agent connects, before anything reaches AWS, by something the agent cannot switch off.
The distinction matters more for agents than for people. A human session is paced by a person typing, and a gap in the record is obvious. An agent runs fast, in a loop, and can issue hundreds of calls in the time a person reads one line. If the recording is partial or sampled, the missing slice is not a single command, it is a burst of them. The recording has to be continuous and complete for the whole session, which is only practical when it happens at the boundary the traffic already flows through.
Configuring least-scope recording
- Put the agent behind an access boundary instead of giving it AWS keys. The agent connects through hoop.dev, a Layer 7 access gateway that sits in front of the AWS-hosted resources it needs and reaches them with its own scoped IAM role.
- Front each resource through a narrowly scoped connection. Recording a session is more useful when the session itself could only ever do a small, named set of things, so scope the gateway's reach to that resource. Least scope and recording reinforce each other.
- Record at the gateway, not in the agent. Because the session runs through hoop.dev, the full command sequence and results are captured on the gateway side, outside the agent process. hoop.dev records each session by design.
- Tie each recording to an identity and a task. The record should answer who and why, not just what, so a later review can reconstruct the decision and not only the API call.
- Store recordings where the agent has no write path. If the agent can reach the store, a compromised agent can tamper with the evidence.
The architectural point is that recording is only trustworthy when it is produced outside the thing being recorded. A log the agent writes about itself is a statement, not evidence. The getting-started docs show how to register the AWS connection, and the learn pages cover how sessions are captured and scoped.
Verifying the recording is complete
Run a real task through the boundary and pull the session recording. Confirm it contains the full command sequence, the identity, and the task context, not just a single API event. Then run a task that touches a scope you did not grant and confirm two things: the access is denied, and the attempt is still recorded. A recording that only captures successful, in-scope actions is missing exactly the events an investigation needs.
Pitfalls
- Recording inside the agent. If the agent generates its own session log, the recording shares the agent's trust boundary and fails the moment the agent is compromised.
- Wide roles behind tight recording. Capturing every action perfectly does not help if the session could do anything. Scope the role so the recording is of a small, defined surface.
- Unprotected storage. A recording the agent can delete or edit is not evidence. Keep the store on the far side of the boundary.
FAQ
Isn't CloudTrail enough for session recording?
CloudTrail is a strong account-level audit source, but it logs API calls, not the full session and the task behind it. Session recording at the boundary captures the interaction and ties it to the agent identity and task.
Does recording slow the agent down?
Recording at the proxy adds little, because the session already passes through the boundary. The cost is the connection hop you were adding anyway to remove standing keys.
hoop.dev is open source. To configure session recording in front of AWS, start with the repository on GitHub.
