netmiko.query_audit_trail
Audit past SSH connections and command executions on network devices. Filter by device, tool, outcome, or event to trace who ran what and why.
Instructions
Read the audit trail: what this server was asked to do, and what happened.
Answers questions about PAST activity — "everything done on SW-CORE-01", "the last 6 netmiko actions", "which commands were refused this week", "who touched that switch and with which credential". It reads the audit records only; it never opens a connection and never returns device output.
Every argument is a filter, combined with AND. Leave one empty to not filter on it. Translate what the user asked into these arguments — do not ask for everything and sift through it.
The audit trail rotates daily and this reads the rotated files too, but only
what is still on disk. files_scanned and oldest_available in the response
say how far back the answer actually reaches: if the period the user asked
about is older than that, say so instead of reporting "nothing happened".
matched is how many records satisfied the filters; returned is how many
came back in this call. When they differ, the response is one page — never
report returned as a total.
Calling this tool writes a tool_invocation record of its own — reading the
trail is itself auditable — but those records are hidden from the results by
default, so "the last 6 actions" is about the network and not about your own
questions. audit_queries_hidden says how many were left out.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tool | No | Full tool name, e.g. 'netmiko.send_show_command'. | |
| event | No | Record type. One of command_attempt (a command was validated), connection_outcome (an SSH attempt finished), tool_invocation (a tool that touches no device was called), credential_resolution (which credential was used). | |
| limit | No | Maximum records to return. Defaults to 50, capped at 500. | |
| order | No | 'desc' (newest first, the default) or 'asc'. | desc |
| since | No | ISO 8601 date or datetime, UTC. '2026-08-17' means from midnight. | |
| until | No | ISO 8601 date or datetime, UTC. | |
| device | No | Exact inventory device name, as netmiko.list_devices returns it. | |
| reason | No | Why a command was allowed or refused, e.g. DENY_MATCH, NO_ALLOW_MATCH. | |
| outcome | No | How an execution ended, e.g. SUCCESS, AUTH_FAILURE, TIMEOUT. Only connection_outcome records carry it. | |
| verdict | No | ALLOWED or DENIED. Only command_attempt records carry it. | |
| summary_by | No | Return counts instead of records, grouped by one of device, tool, outcome, verdict, event, day. Counts are exact over every matching record, not over one page. Use it for "how many" questions so a count does not cost hundreds of records. Combine it with an `event` filter to avoid a large '(absent)' bucket: records of one type do not carry the fields of another. | |
| correlation_id | No | Ties the validation, the credential and the outcome of one single attempt together. Use it to reconstruct what happened in one case. | |
| command_contains | No | Case-insensitive substring of the command, e.g. 'running-config'. | |
| include_audit_queries | No | Include this tool's own invocations. Defaults to False. Set it to True only when the question is about who read the audit trail. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |