# Search Audit Events

Searches Iru (formerly Kandji) audit log events for device-management and administrative activity

Searches your **Iru (formerly Kandji)** [audit log events](https://api-docs.kandji.io/) so the Risotto agent can investigate device-management actions and administrative changes — device locks, enrollments, profile installs, MDM commands, and other tenant-level activity.

> **Note:** **Iru is the new name for Kandji.** The product, API (`*.api.kandji.io`), and
> dashboard integration are the same — you may still see "Kandji" in some URLs
> and labels. This tool reads from the same Iru/Kandji tenant you connect under
> [Settings > Integrations > Iru](https://www.tryrisotto.com/docs/integrations/device-management/iru).

> **Note:** This tool is **read-only** and returns **tenant-wide** audit data for IT
> investigation. It is not scoped to a single requestor, so it's intended for
> IT-admin workflows rather than end-user self-service.

## 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:

1. Fetches events sorted by occurrence time — **newest first** by default
2. When a `search_query` is provided, filters events **case-insensitively** across the event type, action, actor email, target name, target serial number, and description/details fields
3. 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
4. Returns up to your requested `limit` of matching events as structured JSON

> **Tip:** Narrow searches with a date range (`start_date` / `end_date`) and a specific
> keyword (a serial number or actor email) rather than relying on a broad query
> — it's faster and avoids hitting the page cap before finding what you need.

## Prerequisites

This tool uses your **organization-level Iru/Kandji credentials** — the same API token and subdomain you configure for the [Iru (Kandji) integration](https://www.tryrisotto.com/docs/integrations/device-management/iru). There is **no per-tool configuration** to fill in.

Before the tool can return results, you need:

1. **The Iru (Kandji) integration connected** in Risotto under **Settings > Integrations > Iru** (API token, subdomain, and region). See the [Kandji integration guide](https://www.tryrisotto.com/docs/integrations/device-management/iru).
2. **The `List Audit Events` permission** 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:

1. Go to **Settings > Access** and find the API token you connected to Risotto
2. Click **Configure** (or the token name) to edit its permissions
3. Under the **Audit Logs** category, enable **List Audit Events**
4. Click **Save**

> **Note:** If you connected Risotto only for device lookups (Device List / Get Device
> Details), the token will **not** have audit access yet. Add **List Audit
> Events** to the existing token rather than creating a new one, so you don't
> have to reconnect the integration.

## 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.                                                                                                        |

> **Note:** All parameters are optional. With no `search_query`, the tool returns the most
> recent events for the time window (a single page). Provide a `search_query` to
> filter for specific activity.

## Using the Tool in a Runbook

Tools only run when an agent invokes them as part of a [runbook](https://www.tryrisotto.com/docs/dashboard/runbooks). 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.

> **Tip:** You don't type the ID by hand. Use the tool picker in the runbook editor to
> insert the reference, and the dashboard fills in the correct
> {tool:\<tool-id>} token for you.

### 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):**

> 1. Use the {tool:\<tool-id>} tool to search the audit log. Set `search_query` to the device's serial number (or the actor's email if investigating a person's actions), and narrow the window with `start_date` / `end_date` when the admin gives a timeframe.
> 2. Review the returned events for the relevant action (e.g., `device.lock`), noting the `occurred_at` timestamp, the `actor` who issued it, and the affected `target`.
> 3. Summarize the timeline for the admin in plain language — what happened, when, and who initiated it.
> 4. 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:

```json
{
  "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](#enable-the-audit-log-permission-on-your-api-token)). 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_query` matches 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](https://www.tryrisotto.com/docs/integrations/device-management/iru) 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](https://www.tryrisotto.com/docs/integrations/device-management/iru) — connect the tenant and configure API-token permissions
- [Get Device Information](https://www.tryrisotto.com/docs/integrations/tools/kandji/get_device_information) — look up a specific device's details
- [Get FileVault Key](https://www.tryrisotto.com/docs/integrations/tools/kandji/get_filevault_key) — retrieve a device's FileVault recovery key
- [Runbooks](https://www.tryrisotto.com/docs/dashboard/runbooks) — how to wire tools into agent workflows
- [Tools](https://www.tryrisotto.com/docs/dashboard/tools) — managing tool instances in the dashboard

## Additional Resources

- [Iru / Kandji API Documentation](https://api-docs.kandji.io/)
- [Kandji API token guide](https://support.kandji.io/kb/kandji-api)
- [Kandji API rate limits](https://support.kandji.io/kb/kandji-api) (10,000 requests/hour per tenant)

Source: https://www.tryrisotto.com/docs/integrations/tools/kandji/search_audit_events
