Investigate errors without a log platform
Use ssh_logs_search with file: app.log, query: timeout, levels: [ERROR], from: -15m and maxLines: 20. File names must already be selected in the connection.
APIs & logs · MCP Firewall integration
Expose selected log files to AI. Keep shell access out of scope.
Use GateRook’s MCP Firewall to read text and JSON Lines on an SSH server through dedicated log tools. Select exact files, verify the host key, and let GateRook translate bounded read and search requests into validated server commands. These tools do not expose an arbitrary shell.
Connection in GateRook
stage-server-logs
SSH log files
stage / QA- Connector type
- SSH log files
- Host / port / user
- app.stage.internal / 22 / logreader
- Authentication
- Private key file
- Private key file
- ~/.ssh/stage-logreader
The security boundary
Your AI requests a tool. GateRook checks its mode and policy, requires approval when configured, and resolves credentials locally before an allowed call runs.
Understand the request flowAsk your AI
List the selected application logs on the staging server before investigating an error.
ssh_logs_list · arguments
{
"connection": "stage-server-logs"
}Example result
{
"root": "/var/log/orders",
"files": [
{
"file": "app.log",
"size": 1048576
},
{
"file": "worker.log",
"size": 262144
}
],
"truncated": false
}Sample configuration and output, not a live connection. Replace example values with your environment. Tool names here are connector names; the endpoint may expose a connection-specific name.
Useful access. Explicit control.
What you can do with SSH log files and AI
Inspect the end of a file
Call ssh_logs_read with file: app.log, tail: true and maxLines: 100. This reads a bounded snapshot; it does not open a live subscription.
Follow the evidence across pages
When scanComplete is false, repeat the same filters and limits, passing the returned nextCursor as cursor. Check warnings and diagnosticCountsComplete before treating an empty page as evidence that no matching events exist.
From service to MCP Firewall
How to connect SSH log files
GateRook must be running on a computer that can reach your service. Open Connections, choose Add connection, and select SSH log files. Give the connection a name and environment.
New to GateRook? Start with the full setup guide.Prepare a restricted log account
Give the account read access only to the relevant logs. The server needs SFTP, a POSIX shell, GNU or BSD head, tail, grep and stat, plus awk, cat, od and wc.
Connect and verify the server
Choose SSH log files, enter the host, port and user, and select password or local private-key authentication. Use Test connection and verify the server fingerprint before trusting it.
Select the files explicitly
Browse remote folders over SFTP, choose the root folder and select individual files. Configure text or JSON Lines parsing if needed, then test read access to the selected files.
Choose the endpoint and tool modes
Add the tested connection to an endpoint. In Tools & policies, enable only the tools needed for the task. Start with Read only where supported; use Approval for any selected mutation and leave other tools Off. A connection alone does not grant an AI client access.
Connect your AI and verify the first call
In Clients, choose your AI app and endpoint, review the connection details, and connect. Try this guide’s example in Playground before asking your AI. Open Activity to inspect the tool, target, decision and returned result. The getting started guide covers this shared flow.
Connection settings
Configure SSH log files in GateRook
These are example values for the connection form. Enter credentials into GateRook’s secret fields, not into an AI prompt. Requirements and alternatives are noted per field.
| Setting | Example | How to use it |
|---|---|---|
Connector type | SSH log files | A dedicated read-only connector, separate from SSH runbooks. |
Host / port / user | app.stage.internal / 22 / logreader | The account needs SFTP, SSH command execution and read access to the selected files. Connect from a machine with the required VPN or network access. |
Authentication | Private key file | Choose a local private-key file or password authentication. SSH policies may restrict the method; production defaults to private-key access. |
Private key file | ~/.ssh/stage-logreader | Use an absolute path or ~/ path. The key is read locally for authentication and is never uploaded. Enter an optional passphrase in GateRook. |
Host key | Verify the server fingerprint | Test connection and verify an unfamiliar fingerprint through a trusted channel before accepting it. Known-hosts entries can also be supplied. |
Remote log folder | /var/log/orders | Choose an absolute remote folder. Selecting the folder alone does not expose its contents. |
Allowed log files | app.log, worker.log | Select 1 to 500 exact paths relative to the folder. Files with new names, including rotated files, must be selected explicitly. |
Log format / time zone | auto / UTC | Auto detects JSON objects per line or text. Set the time zone for timestamps without an offset; optional JSON field names and timestamp patterns control parsing. |
Know what you expose
SSH log files tools and access boundaries
The connector defines available operations. GateRook’s MCP Firewall enforces endpoint modes and connection policies before an AI client can use them.
| Tool | Purpose | Access behavior |
|---|---|---|
ssh_logs_list | List selected root-relative file names and sizes. Optional query, matchMode and caseSensitive filter names without reading their contents. | Read only; endpoint Approval can require a decision before a read. |
ssh_logs_read | Read one allowed file. Use tail and maxLines for recent records, or startLine/endLine for an inclusive physical line range. | Read only; file selection and output limits apply. |
ssh_logs_search | Search one, several or all selected files by literal text, RE2 regex, levels and event time. Use maxLines to bound results; pass the returned nextCursor as cursor to continue. | Read only; no AI-supplied shell command. |
Before you enable access
- Only explicitly selected regular files are eligible. Symbolic links, nonregular files and files with multiple hard links are rejected. New or rotated names are not automatically included.
- GateRook builds read-only commands from validated parameters. These tools cannot accept arbitrary shell commands, edit logs or execute saved SSH runbooks.
- Each physical UTF-8 line is one record. JSON Lines requires one object per line; stack-trace continuation lines do not automatically inherit timestamps. Compressed archives are not supported.
- Time filters apply to parsed event timestamps, not file modification time. Records without a usable timestamp or level do not match an explicit filter for that field.
- Source scanning, returned lines, response size and execution time are bounded separately. Use maxLines for a small answer; keep scanBytes unset unless you intentionally want a smaller scan budget.
- Cursor continuation checks the file snapshot. Rotation, truncation or detected changes can invalidate it; later appends do not extend the snapshot. Start a new query to inspect new records.
- GateRook does not create a persistent log-file copy. Returned records still go to the AI client, and Activity retains bounded, masked call previews under your retention policy.
GateRook stores local connection secrets encrypted and resolves them for connectors. Allowed tool results are returned to your AI client and may be processed by its provider. Scope the data you expose as well as the actions you allow.
Practical answers
SSH log files connection questions
Use Test connection to isolate service access problems. Use Playground and Activity to inspect endpoint permissions and tool calls.
How is this different from the SSH connector?
SSH runs saved runbooks with typed parameters. SSH log files exposes only file listing, reading and searching, using an explicit file selection and GateRook-generated read commands.
Can I use a local private key or Vault SSH CA?
This connector accepts a local private-key file, with an optional passphrase, or a password when the SSH policy allows it. Vault SSH CA is a feature of the separate SSH runbook connector.
Why does a healthy connection fail when reading one file?
Automatic health checks verify SSH, SFTP and the root folder. Test connection checks every selected file. Rotation or permission changes can make an individual file unavailable after either check; review the file selection and permissions.
Can I search more than one file?
Yes. Pass files with exact selected names, or omit both file and files to search the configured selection. file and files are mutually exclusive. Results follow file and byte order, not a global sort by timestamp.
Does a zero-match page mean there are no errors?
Not necessarily. If scanComplete is false, pass the returned nextCursor as cursor with the same filters and limits. Review warnings, skipped or unparsed records and diagnosticCountsComplete. A bounded or partially parsed scan is not proof that every source record was examined.
Keep exploring
Extend control across your stack
SSH
Control AI access to SSH with GateRook. Verify host keys, use predefined runbooks and review rendered commands before approving server changes.
Loki
Control AI access to Loki logs with GateRook. Configure tenant and source scope, keep credentials local and bound LogQL results and time ranges.
AWS CloudWatch Logs
Control CloudWatch Logs access through GateRook. Restrict regions and log groups, keep AWS credentials local and bound queries and returned results.
Your MCP Firewall. Your access rules.
Control AI access to SSH log files.
Start with read-only access. Approve changes. Inspect the audit trail.