Reading a session's acts in the Audit tab

An agent worked in a session and you want to review what it did: the files read, the files modified, the commands run, the developer’s decisions. This page describes what the log contains, how the console’s Audit tab presents a session’s acts, how to revoke a session, and what the log lets you establish.

What the log contains

Logs are kept by the gateway services, not by the workstation. They have five properties (security white paper V3, section 7.1):

• they are append-only, and a deletion is itself logged;
• each entry contains the digest of the previous one: a modification breaks the chain and is detected, including when it comes from an administrator;
• each event is timestamped and carries the identity from your directory, the project, the repository, the model and the result;
• they are exported to your SIEM in a structured format, following a documented event schema;
• content is absent by default: neither the requests nor the code appear there, and you can enable their retention, with separate encryption and a separate retention period.

Seven event categories are always logged (security white paper V3, section 7.2):

Category	What is logged
Authentication and sessions	opening, closing, failure, revocation
Developer instruction	event, user, project; the text optionally
Files read and modified	list of the files involved; the content optionally
Actions proposed by the agent	action type, tool, command, model used
Human decisions	approval, refusal, stop, with timestamp and identity
Sandbox executions	command, return code, duration; the output optionally
Policy changes	old and new value, author

A detected secret is not logged in clear text.

The Audit tab presents the acts of sessions: the agent’s actions, the decision taken for each one and its result. For each act, it shows the tool, the target (a path or a command, cut at 160 characters), the decision, who took it, the result, the reason (300 characters at most) and the instant. It shows neither the content of a file nor the conversation.

Opening the tab

Open the console’s Audit tab. Reading acts requires the auditor role, which reads logs and policies read-only (security white paper V3, section 6.1); another role sees the tab and the error message described below. See Opening the administration console.

The screen has two panels: Sessions on the left, the timeline of the selected session on the right. It reloads every 10 seconds; the line “Updated HH:MM:SS · refreshes every 10 s” gives the time of the last read, and the Refresh now button reads again without waiting. The most recent session opens by itself; a session you have selected stays selected from one reload to the next.

With no act received, the sessions panel displays “No act has been remitted to this gateway yet.”. If the console cannot read the acts, the cause is written above the panels, after “Could not read the acts: ”.

Selecting a session

The Sessions panel lists 100 sessions at most, from the most recent activity to the oldest. It has no filter: you read one session at a time, by clicking its card.

Each card carries:

• the day (Today, Yesterday, or the date in abbreviated form) and the times of the first and last act, then the age of the last one (“just now”, “12 min ago”, “3 h ago”, “2 d ago”);
• the person the acts are attributed to: the identity from your directory (security white paper V3, section 7.1);
• the surface (“terminal” or “editor”) and the session’s duration;
• the number of acts received for the session, session frame included, and, if there are any, the number of refused acts and the number of failures;
• the session and workstation identifiers, abbreviated to eight characters. The full identifier appears on hover.

Reading the timeline

The right-hand panel is titled with the person, the day and the times of the session. Its subtitle names the surface and repeats the two identifiers.

At the top, four figures: actions (the tool calls, without the session frame), approved by the developer, refused, failed.

Below the figures, the collapsible How this session was set up card describes the session frame: Mode, the session’s mode; Permission rules, the number of rules in the policy in force; Tools available, the number of tools the policy left to the agent, with their list.

The list of acts reads from the most recent to the oldest: the act the agent has just taken is at the top, the session’s first one at the bottom. Each line carries the time to the second, the action spelled out, the decision, the result, then the target. The tool’s actual name appears when hovering over the action. When a reason exists, it is written under the line, after “Why: ”.

Action displayed	Tools
Read a file	Read
Wrote a file	Write
Edited a file	Edit, MultiEdit
Ran a command	Bash
Switched branch	SwitchBranch
Listed a directory	List, LS
Searched the code	Search, Grep, Glob
Delegated to a sub-agent	Task
the tool’s name	any other tool

The decision and the result are labels. A colored border distinguishes refused lines and failed lines from granted and successful lines.

Label	What it says
auto-approved	the policy let it through without asking: action freely allowed
approved by the developer	the developer was consulted and said yes
refused by the developer	the developer was consulted and said no; nothing ran
refused by the rules	the policy refused without asking
done	the tool ran and succeeded
failed	the tool ran and did not succeed; the reason is under the line
not run	the tool did not run
stopped by the revocation	the command was running when the session was revoked, and was stopped

The i button at the top of the timeline, described as “What the labels mean”, opens a legend for these labels.

Revoking a session

Revoking a session stops the agent in that session, and in that one only. The person keeps their other sessions and can open a new one. A revocation is final: a revoked session cannot be resumed, duplicated or restored.

From the tab

The Revoke this session button is at the top of the selected session’s timeline, next to a reason field. The reason is optional; it is kept for the audit and is not shown to the developer. With no reason, the revocation carries “revoked from the console”. The button opens a confirmation that describes the effect; Cancel writes nothing.

The button is displayed only if the signed-in person can revoke, and only on a session still in force. Revocation requires the sessions:revoquer permission, which the administrator holds; the auditor, who reads this tab, sees the state of sessions and does not have the button (security white paper V3, sections 4.5 and 6.1).

Once the session is revoked:

• its card carries the revoked label in the Sessions panel;
• its timeline carries a “Session revoked by …” line, in its place in time, with the time, the author and the reason after “Why: ”;
• the session’s sub-agents are revoked with it; their timeline says so and names the revoked session;
• the act appears in the administration act log, with its author and the session concerned.

Revoking an already revoked session changes nothing: the original act is kept.

Through the operations command

The gateway carries a command that revokes a session by its full identifier, the one the tab displays on hover. The author is mandatory; the reason is optional.

node dist/identity/revokeAgentSession.js <session> <auteur> "motif"

What the developer sees

The terminal asks the gateway for the state of its session every 5 seconds. When the session is revoked:

• the turn in progress is interrupted, and a command already launched is stopped along with the processes it launched: a stop signal, then a forced stop after 3 seconds. It is logged as a failure, with its stop by the revocation as the reason, and the tab displays it as stopped by the revocation;
• the session’s sandbox is destroyed, and uncommitted writes are discarded (security white paper V3, section 4.5);
• no action the agent requests afterwards is executed, and the developer is not asked to authorize it;
• the terminal displays once: “This session was revoked by your organization’s administration at HH:MM. The agent will not act in it any more. Your other sessions are not affected: start a new one with lemni.”, followed by the session identifier and an invitation to contact the administrator;
• if the developer writes again in this session, their message is not sent to the agent and the terminal reminds them in one line: “This session is revoked since HH:MM: your message was not sent to the agent. Start a new session with lemni.”;
• in non-interactive mode, this text goes to the error output and the program exits with code 1;
• resuming or duplicating this session is refused with the same text. Duplicating a session is also refused when the workstation cannot ask the gateway for its state;
• the revocation is recorded in the log.

The gateway also refuses model calls made on behalf of a revoked session, with a 403 response carrying the code agent-session-revoked.

When the workstation cannot reach the gateway

A workstation that no longer gets a response from the gateway continues for 5 minutes from the last response received. Beyond that, the agent stops acting and the terminal says so: “The agent stopped acting: this workstation could not verify … This is not a revocation, and nothing is lost: the agent acts again as soon as the gateway answers.” As soon as the gateway answers, the agent acts again. This is not a revocation: nothing is recorded in the tab.

The gateway is updated before the workstations. A terminal that queries an older gateway, without the session state route, gets no response and stops acting after the same 5 minutes.

What revocation does not cover

Revoking a session cuts off neither the person nor their other sessions. Revoking a user is a separate act, also performed from the console (security white paper V3, section 4.5).

What the log lets you establish

The log lets you reconstruct a session: who authenticated, what instruction was given, which files were read, what the agent proposed, what the developer decided, what was executed and which policy was in force. It establishes which proposal was accepted, and by whom (security white paper V3, section 7.2).

The Audit tab shows the agent’s acts and the decisions taken. Three things are read elsewhere:

• the log’s integrity. It rests on the chaining of digests: each entry seals the previous one (security white paper V3, section 7.1);
• authentication events and policy changes. They are logged with their author and are read in the exported logs (security white paper V3, section 7.2);
• operation over time. The exported events feed the rules of your security operations center, in your SIEM (security white paper V3, section 7.3).

The console reads the acts through GET /api/audit/agent-acts, which returns the sessions, and GET /api/audit/agent-acts?session=<id>, which returns a session’s acts in increasing order of rank. The inversion from most recent to oldest is done by the screen; rank remains the reference order. The rights for these routes are in Reference: the administration console.