Search Audit Events
Searches Iru (formerly Kandji) audit log events for device-management and administrative activity
Searches your Iru (formerly Kandji) audit log events so the Risotto agent can investigate device-management actions and administrative changes — device locks, enrollments, profile installs, MDM commands, and other tenant-level activity.
Overview
The Iru Search Audit Events tool queries the Iru audit log so an agent can answer "what happened, when, and who did it" questions about your fleet. It's useful for:
- Device-action history: Confirm when a device was locked, wiped, or restarted, and who issued the command
- Enrollment troubleshooting: See enrollment and re-enrollment events for a device
- Profile / library changes: Track configuration-profile installs and removals
- Administrative auditing: Find admin actions and policy changes across the tenant
- Incident investigation: Reconstruct a timeline of MDM activity around a reported issue
How It Works
The tool calls the Iru audit events API (GET /api/v1/audit/events) using your organization's Iru/Kandji credentials. It then:
- Fetches events sorted by occurrence time — newest first by default
- When a
search_queryis provided, filters events case-insensitively across the event type, action, actor email, target name, target serial number, and description/details fields - Paginates to find matches — for a keyword search it fetches up to 5 pages (1,500 events) so matches beyond the first page aren't missed
- Returns up to your requested
limitof matching events as structured JSON
Prerequisites
This tool uses your organization-level Iru/Kandji credentials — the same API token and subdomain you configure for the Iru (Kandji) integration. There is no per-tool configuration to fill in.
Before the tool can return results, you need:
- The Iru (Kandji) integration connected in Risotto under Settings > Integrations > Iru (API token, subdomain, and region). See the Kandji integration guide.
- The
List Audit Eventspermission enabled on that API token (see below). The default device integration only grants device permissions, so this must be added.
Enable the audit-log permission on your API token
The API token used for the integration must be allowed to read audit events. In the Iru/Kandji web console:
- Go to Settings > Access and find the API token you connected to Risotto
- Click Configure (or the token name) to edit its permissions
- Under the Audit Logs category, enable List Audit Events
- Click Save
Configuration Options
Tool configuration (Risotto dashboard)
This tool has no configuration fields. It reads credentials from your organization's Iru/Kandji integration automatically. Just create the tool from the Iru Search Audit Events template and reference it in a runbook.
Search parameters (set by the agent at runtime)
When the agent uses the tool, it can supply these parameters. You don't set them in the dashboard, but your runbook instructions can guide how they're used.
| Parameter | Description |
|---|---|
search_query | Optional text to filter events (matches event type, action, actor, target name/serial, and description). When set, the tool fetches multiple pages to find matches. |
start_date | Start of the time window, ISO format (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ). If omitted, the API uses its default window. |
end_date | End of the time window, ISO format. If omitted, defaults to now. |
limit | Maximum events to return, from 1 to 300. Defaults to 50. |
sort_order | desc for newest first (default) or asc for oldest first. |
Using the Tool in a Runbook
Tools only run when an agent invokes them as part of a runbook. Reference the tool from your runbook instructions with a {tool:<tool-id>} token, where <tool-id> is the unique ID of your configured tool instance.
Example runbook
Title: Investigate a device lock or MDM action
When (Conditions):
An IT admin asks who locked, wiped, or restarted a device, or wants the recent management history for a specific machine.
Then (Instructions):
- Use the {tool:<tool-id>} tool to search the audit log. Set
search_queryto the device's serial number (or the actor's email if investigating a person's actions), and narrow the window withstart_date/end_datewhen the admin gives a timeframe.- Review the returned events for the relevant action (e.g.,
device.lock), noting theoccurred_attimestamp, theactorwho issued it, and the affectedtarget.- Summarize the timeline for the admin in plain language — what happened, when, and who initiated it.
- If no matching events are found in the default window, widen the date range and search again before concluding nothing happened.
Response Format
On success the tool returns a JSON object with a count and the matching events:
{
"event_count": 2,
"search_query": "TEST123456",
"events": [
{
"occurred_at": "2024-01-15T10:30:00.000Z",
"event_type": "device.lock",
"actor": "admin@example.com",
"target": {
"name": "Johns-MacBook-Pro",
"serial_number": "TEST123456"
},
"description": "Device lock command sent",
"event_id": "evt_abc123"
},
{
"occurred_at": "2024-01-14T09:05:00.000Z",
"event_type": "profile.installed",
"actor": "admin@example.com",
"target": {
"name": "Johns-MacBook-Pro",
"serial_number": "TEST123456"
},
"description": "Configuration profile installed"
}
]
}
Each event includes the occurrence timestamp, event type, the actor who performed the action, the target (device name, serial number, device ID, or email when available), and a description. The search_query field echoes the query when one was supplied.
Error Messages
| Message | Cause & resolution |
|---|---|
Iru API token not configured. Set up Iru in Settings > Integrations > Iru. | No API token on the org integration. Connect Iru on Settings > Integrations > Iru. |
Iru subdomain not configured. Set up Iru in Settings > Integrations > Iru. | The integration is missing the subdomain. Re-enter your Iru/Kandji API URL in the integration settings. |
No audit events found matching '{query}'. | The search succeeded but matched nothing. Broaden the keyword or widen the date range. |
No audit events found for the specified criteria. | No events in the requested window. Widen start_date / end_date. |
Troubleshooting
No events found, or permission errors
- Confirm the API token has Audit Logs → List Audit Events enabled (see Enable the audit-log permission). A token with only device permissions cannot read the audit log.
- Widen the time range — by default the API only returns events from its standard window.
- Make sure your
search_querymatches the data in the log (try the device serial number or the actor's email rather than a free-text phrase).
A known recent event isn't in the results
When you supply a search_query, the tool scans up to 1,500 of the most recent events (5 pages) to find matches. If a match is older than that, narrow the search with start_date / end_date so the relevant events fall within the fetched pages.
Connection or authentication failures
These usually point at the integration rather than the tool. Verify the API token, subdomain, and region in Settings > Integrations > Iru, and confirm the token is still active in the Iru/Kandji console. See the Kandji integration troubleshooting guidance.
Security Considerations
- Read-only. The tool only reads audit events; it cannot issue device commands or change any Iru/Kandji configuration.
- Tenant-wide data. Audit events cover the whole fleet and can include actor emails, device serials, and IP-adjacent metadata. Wire this tool into IT-admin runbooks, not general end-user self-service flows.
- Least privilege. The integration token needs only List Audit Events added on top of its device permissions for this tool — avoid granting write or delete permissions it doesn't use.
- Encryption. Risotto encrypts the Iru/Kandji API token at rest, like all integration secrets.
- Auditability. API reads are themselves recorded in the Iru/Kandji API logs (Settings > Access), preserving a trail of automated access.
Related
- Iru (Kandji) Integration — connect the tenant and configure API-token permissions
- Get Device Information — look up a specific device's details
- Get FileVault Key — retrieve a device's FileVault recovery key
- Runbooks — how to wire tools into agent workflows
- Tools — managing tool instances in the dashboard
Additional Resources
- Iru / Kandji API Documentation
- Kandji API token guide
- Kandji API rate limits (10,000 requests/hour per tenant)
Something wrong or missing? Report an issue · View as Markdown