> ## Documentation Index > Fetch the complete documentation index at: https://docs.airmdr.com/llms.txt > Use this file to discover all available pages before exploring further. # Wazuh > The Wazuh integration enables AirMDR to connect to the Wazuh server API to retrieve security, endpoint, configuration, and compliance information. This integration connects to deployments that expose the Wazuh server REST API and support username-and-password authentication through: `POST /security/user/authenticate` Before publishing this section, add the Wazuh versions formally validated by the AirMDR Engineering or Integration team: `Supported Wazuh versions: ` The setup instructions in this guide follow the current Wazuh server API and RBAC interface. Menu names can vary slightly between Wazuh releases. The integration requires: * Wazuh server API username * Wazuh server API password * Wazuh server API Base URL * SSL verification preference AirMDR submits the configured username and password to: `POST /security/user/authenticate` Wazuh returns a JWT that is used as a bearer token for subsequent API requests. ### Role-based access Wazuh RBAC controls access to API endpoints through users, roles, policies, actions, and resources. Wazuh recommends applying least privilege so that a user can access only the endpoints and resources it requires. #### Read and investigation permissions Assign the following actions only when the corresponding AirMDR skills require them: | Permission | Purpose | | ------------------- | ------------------------------------------------------------------------------------------- | | `agent:read` | Retrieve Wazuh agent details, status, configuration, and summaries. | | `syscheck:read` | Retrieve File Integrity Monitoring results and last-scan information. | | `rootcheck:read` | Retrieve rootcheck scan results and status. | | `sca:read` | Retrieve Security Configuration Assessment policies and check results. | | `syscollector:read` | Retrieve hardware, operating system, package, process, port, network, and hotfix inventory. | | `ciscat:read` | Retrieve CIS-CAT assessment results where supported. | | `rules:read` | Retrieve Wazuh rules, rule files, rule groups, and requirements. | | `decoders:read` | Retrieve Wazuh decoders and decoder files. | | `mitre:read` | Retrieve MITRE ATT\&CK tactics, techniques, mitigations, software, and related metadata. | | `group:read` | Retrieve agent-group information, assigned agents, files, and group configuration. | | `cluster:read` | Retrieve Wazuh cluster nodes, health, status, logs, and configuration information. | | `manager:read` | Retrieve Wazuh manager information, status, statistics, configuration, and logs. | The current Wazuh RBAC reference marks CIS-CAT functionality as deprecated from Wazuh 5.0. Include `ciscat:read` only for deployments and skills that still use the corresponding endpoints. #### Response permissions Add the following permissions only when the corresponding AirMDR response skills are enabled: | Permission | Purpose | | -------------------------- | ----------------------------------------------------------- | | `active-response:command` | Run an authorized active-response command on a Wazuh agent. | | `agent:restart` | Restart a Wazuh agent. | | `agent:reconnect` | Request an agent to reconnect to the Wazuh manager. | | `agent:modify_group` | Change the group membership of an agent. | | `group:modify_assignments` | Add or remove agents from Wazuh groups. | | `syscheck:run` | Start a File Integrity Monitoring scan. | | `rootcheck:run` | Start a rootcheck scan. | | `logtest:run` | Test a log entry against Wazuh rules and decoders. | `active-response:command` permits operational actions on monitored endpoints. Assign it only when AirMDR response skills require it and after receiving the appropriate security approval. ### Pre-requisites > > Users must have Administrator access to the **Wazuh** dashboard with sufficient privileges to create an API user. > > > > Ensure that the Wazuh manager and Wazuh server API are operational. > > > > Allow the configured Wazuh API port through applicable firewalls. The default port is `55000/TCP` > > Use a trusted TLS certificate when SSL verification is enabled. > The Wazuh dashboard URL and the Wazuh server API URL are different. AirMDR requires the **Wazuh server API URL**, typically `https://:55000`. ## Setup Steps 1. Sign in to the Wazuh dashboard using an administrator account. 2. Open the navigation menu. 3. Navigate to **Server management** → **Security** → **Users**. 4. Click **Create user** or **Add new user**, depending on the Wazuh version. 5. Enter a dedicated username, for example: `airmdr-api`. 6. Enter and confirm a strong password. Wazuh requires API user passwords to contain between 8 and 64 characters, including uppercase and lowercase letters, a number, and a symbol. 7. Save the user. 8. Securely record the username and password. These values must be entered in AirMDR. Do not use the default `wazuh` or `wazuh-wui` administrative accounts for the AirMDR integration. Create or manage the API user under **Server management → Security**. The **Indexer management → Security → Internal users** area primarily manages dashboard and indexer identities and should not be confused with Wazuh server API RBAC. 1. In the Wazuh dashboard, navigate to **Server management** → **Security** → **Policies**. 2. Click **Create policy**. 3. Enter a descriptive policy name, such as `airmdr-investigation-read`. 4. Set the policy effect to `allow`. 5. Add the read actions required by the AirMDR skills, such as:
`agent:read` `syscheck:read` `rootcheck:read` `sca:read` `syscollector:read` `rules:read` `decoders:read` `mitre:read` `group:read` `cluster:read` `manager:read` 6. Select the Wazuh resources that AirMDR is permitted to access. For access to all applicable agents, groups, and nodes, the corresponding resource definitions can use wildcards such as:
`agent:id:*` `agent:group:*` `group:id:*` `node:id:*` 7. Save the policy. 8. If response skills are required, create a separate policy, for example: `airmdr-response-actions`. 9. Add only the approved response actions to the response policy. Keep investigation permissions and response permissions in separate policies. This makes access reviews and troubleshooting easier. 1. Navigate to **Server management** → **Security** → **Roles**.  2. Click **Create role**. 3. Enter a role name, for example: `airmdr-integration`. 4. Attach the `airmdr-investigation-read` policy. 5. If response actions are approved, attach the `airmdr-response-actions` policy. 6. Save the role. 1. Navigate to **Server management** → **Security** → **Users**. 2. Open the `airmdr-api` user. 3. Select the role-assignment option. 4. Assign the `airmdr-integration` role. 5. Save the changes. 6. Confirm that the user shows the assigned role. Wazuh permissions are endpoint-specific. A successful authentication does not confirm that the user is authorized to run every AirMDR skill. The Base URL is not generated in the Wazuh dashboard. It is constructed from the reachable Wazuh manager API address and configured API port. Use the following format: `https://:` Example: [https://wazuh-manager.example.com:55000](https://wazuh-manager.example.com:55000) The default Wazuh server API port is `55000`. It can be changed `in /var/ossec/api/configuration/api.yaml` ### **Wazuh** Credential Reference Table | AirMDR field | What to enter | Where to get it | | -------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Base URL** | Wazuh server API URL, including the protocol and API port. Example: `https://wazuh-manager.example.com:55000` | Obtain the externally reachable Wazuh manager hostname or IP address and API port from the Wazuh administrator. The default API port is `55000`. | | **Username** | Username of the dedicated Wazuh API user created for AirMDR. Example: `airmdr-api` | Wazuh dashboard → **Server management** → **Security** → **Users** | | **Password** | Password assigned to the dedicated API user | Defined when the API user is created. Store it securely because Wazuh does not display the existing password later. | | **Verify SSL** | Enter `true` to validate the server certificate or `false` to bypass validation | Determine this from the certificate configured for the Wazuh server API. Use `true` when the certificate is trusted by the system making the connection. | ### Validate Connectivity From a system that can reach the Wazuh manager, run: ```json theme={null} curl -u ":" \ -X POST \ "https://wazuh-manager.example.com:55000/security/user/authenticate?raw=true" ``` ```text theme={null} curl -k \\ -u "\:\" \\ -X POST \\ "[https://wazuh-manager.example.com:55000/security/user/authenticate?raw=true](https://wazuh-manager.example.com:55000/security/user/authenticate?raw=true)" ``` A successful request returns a JWT. The `-k` option bypasses certificate validation and corresponds conceptually to setting **Verify SSL** to `false`. ```text theme={null} TOKEN=\$(curl -k \\ -u "\:\" \\ -X POST \\ "[https://wazuh-manager.example.com:55000/security/user/authenticate?raw=true](https://wazuh-manager.example.com:55000/security/user/authenticate?raw=true)") curl -k \\ -X GET \\ "[https://wazuh-manager.example.com:55000/](https://wazuh-manager.example.com:55000/)" \\ -H "Authorization: Bearer \$\{TOKEN\}" ``` ### Configure **Wazuh** in AirMDR Integrations Dashboard 1. Navigate to [AirMDR](https://app.airmdr.com/auth/login), provide the credentials and click **Login** 2. Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select **ADMIN → Integrations**. 3. Use the search option, enter the keyword "**Wazuh**", select the **Connections** tab, and click **+ New Connection** button. 4. Use the following values in the AirMDR integration configuration screen: Use the Wazuh **server API URL**, not the Wazuh dashboard URL. The default Wazuh server API port is `55000`. | AirMDR Field | Value | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Base URL** | Enter the Wazuh server API URL, including the port. Example: `https://wazuh-manager.example.com:55000` | | **Username** | Enter the username of the dedicated Wazuh API user created for AirMDR. Example: `airmdr-api` | | **Password** | Enter the password associated with the Wazuh API user. | | **Verify SSL** | Enter `true` to validate the Wazuh API certificate. Enter `false` only if the API uses an approved self-signed or untrusted certificate. | 1. In **Remote Agent**, select an AirMDR Remote Agent when the Wazuh server API is hosted on a private network or is not directly accessible from AirMDR. Ensure that the selected Remote Agent can reach the configured Wazuh **Base URL** and API port. 2. In **Expiry**, select the date on which AirMDR should treat the stored Wazuh credentials as expired, according to your organisation’s credential-rotation policy. The **Expiry** setting does not rotate or expire the password in Wazuh automatically. After rotating the password in Wazuh, update the connection credentials in AirMDR. 5. Click **Save**. ### Integration Requirements #### Required Permissions Create a dedicated Wazuh API user for AirMDR and assign RBAC policies that include both the required **action** and **resource scope**.
The permission format is: RBAC action → resource
For Example: `agent:read → agent:id:*, agent:group:*` The asterisk (`*`) grants access to all resources of that type. Replace wildcard resources with specific agent, group, node, role, policy, or user IDs when AirMDR requires access to only part of the Wazuh environment. #### Mandatory connection-test permission > **AirMDR validates the connection by calling:** `GET /manager/info`
**Therefore, every AirMDR Wazuh connection requires:** `manager:read → ::*` This permission is required for connection validation even when none of the enabled skills retrieve Wazuh manager information. #### Skills provided by this Integration | Skill ID | Purpose | Required Wazuh Permission | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_wazuh_agents` | Lists Wazuh agents or retrieves specified agents by ID. Supports filtering by status, group, operating system, version, node, IP address, name, registration date, and last check-in. | `agent:read` → `agent:id:*`, `agent:group:*` | | `get_wazuh_agents_summary` | Returns aggregated fleet information, including agent status, operating-system distribution, versions, configuration-sync status, and distinct field combinations. Use it for coverage reporting and fleet health summaries. | `agent:read` → `agent:id:*`, `agent:group:*` | | `get_wazuh_agent_inventory` | Retrieves Syscollector inventory for an endpoint, including processes, ports, packages, hotfixes, operating systems, hardware, network interfaces, addresses, protocols, users, groups, services, and browser extensions. | `syscollector:read` → `agent:id:*`, `agent:group:*` | | `get_wazuh_agent_configuration` | Retrieves the configuration actively used by a Wazuh agent, cluster node, or manager. Use it to verify monitored FIM paths, collected log files, and enabled active-response commands. The required permission depends on the supplied target. | When `agent_id` is set: `agent:read` → `agent:id:*`

When `node_id` is set: `cluster:read` → `node:id:*`

When neither is set: `manager:read` → `*:*:*` | | `get_wazuh_agent_groups` | Lists Wazuh agent groups or retrieves the members, shared configuration, and files associated with a specified group. | `group:read` → `group:id:*` | | Skill ID | Purpose | Required Wazuh Permission | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `get_wazuh_fim_findings` | Retrieves File Integrity Monitoring findings for an endpoint, including changed files, checksums, permissions, ownership, size, and change count. Supports filtering by file, hash, and detection time. | `syscheck:read` → `agent:id:*`, `agent:group:*` | | `get_wazuh_rootcheck_findings` | Retrieves rootcheck findings, including rootkit traces, hidden processes or ports, and insecure system settings detected on an endpoint. | `rootcheck:read` → `agent:id:*`, `agent:group:*` | | `get_wazuh_compliance_results` | Retrieves endpoint compliance results from Security Configuration Assessment. When `source` is set to `ciscat`, the skill retrieves results from the optional CIS-CAT scanner instead. | SCA results: `sca:read` → `agent:id:*`

When `source=ciscat`: `ciscat:read` → `agent:id:*` | | `get_wazuh_rules` | Retrieves Wazuh detection rules, rule files, groups, and requirements. Use it to investigate rule IDs, severity, compliance mappings, and MITRE ATT\&CK coverage. | `rules:read` → `rule:file:*` | | `get_wazuh_decoders` | Retrieves Wazuh decoders, decoder files, and parent decoders. Use it to determine how raw logs are parsed before rule evaluation. | `decoders:read` → `decoder:file:*` | | `get_wazuh_mitre_info` | Retrieves MITRE ATT\&CK techniques, tactics, groups, software, mitigations, references, and metadata from Wazuh. | `mitre:read` → `*:*:*` | | `run_wazuh_logtest` | Processes a raw log through the Wazuh decoder and rule engine. Returns the matched decoder, rule, severity, description, MITRE mapping, and parsed fields for detection testing and troubleshooting. | `logtest:run` → `*:*:*` | | Skill ID | Purpose | Required Wazuh Permission | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `assign_wazuh_agent_group` | Assigns selected agents to an existing group or removes them from a specified group. When `force_single_group` is enabled during assignment, previous group memberships are removed. | `agent:modify_group` → `agent:id:*`

and

`group:modify_assignments` → `group:id:*` | | `restart_wazuh_agents` | Restarts selected Wazuh agents or requests them to reconnect to the manager. Restart applies pending configuration, while reconnect only re-establishes communication. | Restart: `agent:restart` → `agent:id:*`, `agent:group:*`

When `action=reconnect`: `agent:reconnect` → `agent:id:*`, `agent:group:*` | | `run_wazuh_scan` | Starts an on-demand File Integrity Monitoring or rootcheck scan on selected agents. The required permission depends on the selected scan type. | FIM scan: `syscheck:run` → `agent:id:*`, `agent:group:*`

Rootcheck scan: `rootcheck:run` → `agent:id:*`, `agent:group:*` | | `run_wazuh_active_response` | Runs a configured Wazuh active-response command on selected endpoints, such as blocking an IP address, denying a host, or disabling a local account. | `active-response:command` → `agent:id:*`, `agent:group:*` | | Skill ID | Purpose | Required Wazuh Permission | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `get_wazuh_manager_health` | Retrieves Wazuh manager and cluster health information, including version details, daemon status, active configuration, statistics, cluster resources, nodes, agent counts, and ruleset synchronization. | Manager information: `manager:read` → `*:*:*`

Cluster resources or when `node_id` is set: `cluster:read` → `node:id:*` | | `get_wazuh_manager_logs` | Retrieves Wazuh manager or cluster-node logs and log-level summaries. Supports filtering by severity, component, and time range for ingestion and connectivity troubleshooting. | Manager logs: `manager:read` → `*:*:*`

When `node_id` is set: `cluster:read` → `node:id:*` | | `get_wazuh_tasks` | Retrieves the status of asynchronous Wazuh tasks, including agent upgrades, associated agents or nodes, task status, and creation and update times. | `task:status` → `*:*:*` | | `get_wazuh_security_resources` | Retrieves Wazuh API users, roles, policies, and authorization-context rules. Use it to audit API access or troubleshoot authorization failures. | `security:read` → `user:id:*`, `role:id:*`, `policy:id:*`, `rule:id:*` | To view the details of Input Parameters and Output for the respective skills * Go to [AirMDR → Wazuh](https://app.airmdr.com/integrationsv2/d8c04483-591c-46cb-8613-28cb19a7f311/skills?search=wazuh) Integration page. * Select the **Skills** tab and click on the required listed skills. ## Additional Information | Error or symptom | Likely cause | Resolution | | --------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `401 Unauthorized` | Incorrect username or password, disabled user, or failed authentication | Confirm the credentials, reset the API-user password if required, and test the authentication endpoint. | | `403 Forbidden` | The user authenticated successfully but does not have the required RBAC action or resource | Review the AirMDR skill, identify its Wazuh endpoint, and add the corresponding action and resource to the assigned policy. | | Certificate verification failed | Self-signed, expired, mismatched, or untrusted certificate | Install a valid certificate and use `Verify SSL: true`. Use `false` only as an approved exception. | | Connection refused or timed out | Incorrect Base URL, API service unavailable, blocked firewall, or unreachable private address | Confirm the hostname, port, routing, firewall rules, and Wazuh manager status. | | `404 Not Found` | Dashboard URL or incorrect endpoint used instead of the server API Base URL | Use the Wazuh manager API URL, normally `https://:55000`. | | `429 Too Many Requests` | Wazuh API rate limit exceeded | Reduce request frequency and review `max_request_per_minute`. Wazuh documents a default limit of 300 requests per minute. | | Response action fails while read skills work | Response policy is missing or restricted to different agents or groups | Add only the required response permission and confirm the policy resources include the target agent or group. | | Authentication succeeds but no records are returned | RBAC resources exclude the required agents, groups, or nodes | Review resource scopes such as `agent:id:*`, `agent:group:*`, and `node:id:*`. | | Password stops working after rotation | AirMDR still contains the previous password | Update the Wazuh connection in AirMDR and save it again. | **Wazuh API logs** Wazuh server API activity is recorded in: `/var/ossec/logs/api.log` The default API log level is `info`. Supported levels include: ```text theme={null} disabled info warning error debug debug2 ``` Wazuh supports plain-text and JSON API log formats. Wazuh API logging configuration Example API log: `2026/08/19 12:30:10 INFO: airmdr-api 10.10.20.15 "POST /security/user/authenticate" with parameters {"raw": "true"} and body {} done in 0.210s: 200` Example authorized request: `2026/08/19 12:30:11 INFO: airmdr-api 10.10.20.15 "GET /agents" with parameters {} and body {} done in 0.095s: 200` ### Recommended logging * Use `info` for normal operation. * Temporarily use `debug` when investigating an integration issue. * Return to `info` after troubleshooting to reduce unnecessary log volume. * Review repeated `401`, `403`, `429`, and `5xx` responses. * Do not include passwords or JWT values in troubleshooting tickets or shared logs. ### ✅ Do * Create a dedicated Wazuh API user for AirMDR. * Apply least-privilege policies based on enabled skills. * Use a trusted TLS certificate. * Keep **Verify SSL** set to `true` whenever possible. * Restrict the API port to approved AirMDR or Remote Agent source addresses. * Store and rotate the password according to organizational policy. * Monitor authentication, authorization, and response-action events. ### ❌ Don’t * Using the default `wazuh` or `wazuh-wui` account. * Assigning administrator access only to avoid permission errors. * Reusing a personal administrator account. * Disabling SSL verification permanently. * Exposing port `55000` directly to the public internet. * Sharing API credentials or JWTs in documentation, screenshots, tickets, or logs. * Granting response permissions when the integration uses only read operations. * 📧 Contact [**AirMDR Support**](mailto:support@airmdr.com) through your designated support channel. * 🔁 Rotate credentials (dedicated API-user password) regularly. Recommended cadence: As per your internal security policy * 🔄 **Reconnect with AirMDR immediately when secrets are changed.** **Certificate maintenance** * Monitor the Wazuh API certificate expiration date. * Renew the certificate before it expires. * Ensure that the certificate contains the hostname used in the AirMDR Base URL. * Test the integration after certificate or certificate-authority changes. **Permission reviews** * Review the assigned policies periodically. * Remove permissions for disabled AirMDR skills. * Separate read permissions from response permissions. * Review `active-response:command` more frequently because it permits operational actions on endpoints. * Revalidate permissions after Wazuh or AirMDR upgrades. **Data exchanged** Depending on enabled skills and assigned permissions, AirMDR can retrieve: * Wazuh agent information and status * Agent groups and assignments * File Integrity Monitoring results * Rootcheck results * Security Configuration Assessment results * System and software inventory * Wazuh rules and decoders * MITRE ATT\&CK metadata * Wazuh manager and cluster information When response skills are enabled, AirMDR can send authorized action requests to Wazuh, including agent-management commands and scan requests. **Encryption** * Wazuh server API communication uses HTTPS by default. * AirMDR exchanges the configured credentials for a JWT and uses the JWT for subsequent API calls. * The connection password is handled as a secret by AirMDR. * SSL verification should remain enabled whenever a trusted certificate is available. * Wazuh’s certificate files are normally stored under: `/var/ossec/api/configuration/ssl/` **Ports and endpoints** | Direction | Protocol/port | Purpose | | -------------------------------------- | --------------------------------- | ----------------------------------------------------------- | | AirMDR or Remote Agent → Wazuh manager | HTTPS over `55000/TCP` by default | Authentication and Wazuh server API requests | | AirMDR → `/security/user/authenticate` | HTTPS POST | Exchange username and password for a JWT | | AirMDR → Skill-specific endpoints | HTTPS GET, POST, PUT, or DELETE | Retrieve information or perform authorized response actions |