Auditing activity - Documentation

GrantSSH gives teams a timeline of SSH usage across managed servers. The agent on each host reports authentication events to the app — logins, disconnects, sudo commands, and failed login summaries — so you can see who connected, when, and from where without GrantSSH proxying or recording SSH sessions.

For how permissions and keys relate to what you see in the activity log, read Core concepts first. After your first connection, confirm events appear using the verification step in the quick start guide.

How events are collected

The GrantSSH agent watches authentication-related logs on the server — typically via journald — and sends structured events to GrantSSH on a regular sync cycle. The agent does not intercept SSH traffic, terminate sessions, or hold private keys. It only reads what the host already logs and forwards summaries to your team.

Events are stored per server and scoped to your team. They appear in the dashboard after the agent reports them, usually within the same sync window as key updates (roughly 30–120 seconds). If a server is pending or the agent is not checking in, no new events will arrive until the host is active and connected.

Event types

GrantSSH records four event types. Each appears with a label and colour indicator in the app.

Type	Internal name	What it represents
Login	`ssh_login`	A successful SSH authentication to a managed server account.
Disconnect	`ssh_disconnect`	An SSH session ended for a managed account.
Sudo	`sudo`	A `sudo` invocation logged on the host, including the command run.
Failed logins	`failed_login_summary`	A rolled-up summary of failed SSH authentication attempts over a time window.

Recent Login events (within the last five minutes) may show an Active badge in the app, indicating a session that likely started recently. This is a visual hint, not live session tracking.

Team-wide Activity

Open Activity from the main navigation to see events across every server in your team. All team members — owners, managers, and members — can view this page.

The Activity page shows:

Summary counts for logins, disconnects, sudo events, and failed logins — updated to match any filters you apply.
A paginated event list with time, server, event type, server account, and attributed team member when known.
Filters for event type and server, reflected in the page URL so you can bookmark or share a filtered view.

Owners and managers also see recent activity and failed-login highlights on the Dashboard, including a login trend chart over the last two weeks.

Per-server Auth logs

Each managed server has an Auth logs tab (under server management) with the same four event types, scoped to that host only. Owners and managers reach it from a server's sub-navigation after opening the server in the dashboard.

Auth logs show the most recent 100 events for the server and support filtering by event type. Use this view when you are investigating a specific host; use team-wide Activity when you need a cross-fleet picture.

User attribution

When the agent can match an event to a public key stored in GrantSSH, the event is attributed to the team member who owns that key. Attribution uses the key's SHA256 fingerprint reported from the server log.

Attribution works best when:

The connecting user authenticated with a public key that is registered on the team's SSH keys page.
The key was synced to the server account through an active permission — not pasted manually into authorized_keys.
The host log includes a fingerprint GrantSSH can parse.

If no matching key is found, the event still appears with server, account, and timestamp details, but the User column shows empty. Failed login summaries are never attributed to a team member because they represent unsuccessful attempts, often from unknown sources.

Filtering and event details

On Activity, filter by event type and server. Counts at the top of the page respect the active filters. On Auth logs, filter by event type only.

Choose Details on any event in Activity to open a modal with full metadata. Fields vary by event type:

Login and Disconnect — authentication method, remote IP and port, and key fingerprint when available.
Sudo — key fingerprint, target user, command, and optionally working directory and TTY.
Failed logins — attempt count and the time range the summary covers.

What GrantSSH does not capture

Activity visibility is intentionally bounded. GrantSSH does not:

Record interactive shell commands (except sudo invocations the host logs).
Stream or replay terminal sessions.
Proxy SSH connections or require traffic to pass through GrantSSH infrastructure.
Guarantee attribution for keys that were not registered in GrantSSH or for password-based logins without a matching key fingerprint.

For command-level auditing or compliance requirements that need full session transcripts, you will need additional tooling on the host. GrantSSH focuses on who connected, when, and high-signal events like sudo usage.

Using activity in audit workflows

A practical review rhythm combines permissions with activity:

After granting access — confirm a ssh_login event appears for the expected member and server account (see the quick start verification step).
Weekly — skim Activity for unexpected failed login summaries or logins outside business hours on sensitive servers.
On offboarding — revoke permissions first, then confirm no new logins appear for that member's keys. Existing sessions are not terminated automatically when access ends.
During access reviews — correlate active permissions with recent login and sudo events per server account.

For a broader checklist on fleet-wide SSH audits — including authorized_keys hygiene — see How to audit SSH access across your fleet.