How to Configure Mastra SSH Audit Log
You set up a mastra ssh audit log by pairing agent actions with host login records. This setup links every automated task from your Mastra app to a distinct system user. Many engineering teams start by giving a Mastra agent one shared SSH key. That shared key lets the agent run shell tools on remote Linux hosts. When permissions are too broad, the agent can change files or read secrets anywhere. Worse, shared keys make host logs hard to read during a security review. How a native mastra ssh au
Audit Log Integrity + SSH Access Management: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
You set up a mastra ssh audit log by pairing agent actions with host login records. This setup links every automated task from your Mastra app to a distinct system user. Many engineering teams start by giving a Mastra agent one shared SSH key. That shared key lets the agent run shell tools on remote Linux hosts. When permissions are too broad, the agent can change files or read secrets anywhere. Worse, shared keys make host logs hard to read during a security review.
How a native mastra ssh audit log works
Mastra lets teams build AI agents that call external tools and run workflows. Some workflows need to log in to remote servers over SSH to check system state. To track these actions, teams must link the agent run to the host SSH log. On the server side, OpenSSH writes login events to the local system log. If you use raw public keys, the server only logs the target Linux username.
Teams improve this native setup by switching to OpenSSH certificates. Certificate support arrived in OpenSSH 5.4 and uses a simpler format than X.509 certificates. A Certification Authority key signs a public key to make a user or host certificate. Each signed certificate holds a public key, an identity string, principal names, and options. When the Mastra agent logs in, the SSH daemon writes that identity string to the log. You can also set a time limit so the certificate expires after a short window. If you do not set a time limit, the certificate stays valid forever by default.
How to link agent workflows to host logs
To build a clean trail, your team assigns a distinct identity to each Mastra workflow. Before the agent runs a shell task, your setup signs a user certificate for that job. The identity string inside the certificate includes the agent name and the workflow run ID. You also list the allowed principal names so the agent only logs in to specific accounts. When the agent connects to the bastion or target host, the SSH server checks the signature.
The server trusts the Certification Authority key and lets the agent log in. At that exact moment, the SSH daemon writes the certificate identity and key fingerprint into the log. Meanwhile, your Mastra app logs the tool call and the workflow step on its own side. Your team then ships both the host logs and the app logs to a central store. By matching the workflow ID in both places, you see which agent opened which SSH connection.
Audit Log Integrity + SSH Access Management: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
What native SSH logging solves and what it misses
Using OpenSSH certificates solves the problem of shared static keys across your servers. You no longer have to copy public keys to every host for every new agent. You also get a clear record of who or what logged in and when. If an agent key leaks, you can expire the certificate or rotate the signing key.
Still, native SSH logs only record the login check at the start of a session. The SSH daemon decides who logs in, not what individual commands do in flight. Once the shell opens, standard SSH logs do not show the exact commands the agent runs. They also cannot stop a bad command before it drops a file or reads private data. If an agent queries a local tool that outputs emails or card numbers, native logs miss it. Nothing in the basic SSH setup rewrites matched fields like phone numbers or national IDs in results. You know the agent entered the server, but you stay blind to the shell commands inside.
Check SSH commands and file transfers on the host
OpenSSH keys and certificates decide who can log into a Linux host. They do not check what a one-shot command or file transfer does once the session starts. With hoop.dev, you run an open-source SSH server with guardrails on the host. It checks callers with OpenSSH certificates and works with ssh, sftp, scp, and rsync clients.
When a caller runs a one-shot command or moves a file, hoop.dev guardrails check the command or path before it runs. Then hoop.dev data masking masks matched sensitive patterns in downloads and output. Interactive shells carry no guardrails because keystrokes have no statement boundary. Teams can turn interactive shells off and allow only commands and file tasks. The audit trail logs who connected and what was allowed or refused, without storing keystrokes or file bytes. See the source on GitHub.
Frequently asked questions
Why are shared SSH keys bad for a mastra ssh audit log?
A shared key maps every agent and workflow to the same Linux user account. When something breaks, your host logs cannot show which Mastra workflow ran the shell task.
How do OpenSSH certificates improve host login logs?
An OpenSSH certificate carries a custom identity string signed by your Certification Authority key. The remote server writes this identity string into the system log on every login.
Do standard SSH logs capture the output of agent commands?
No, standard SSH logs only track the login event, the user principal, and the key identity. They do not record the shell commands run inside the session or the data returned.
Related guides
In this post