Wazuh

Supported Versions

This integration connects to deployments that expose the Wazuh server REST API and support username-and-password authentication through: POST /security/user/authenticateBefore publishing this section, add the Wazuh versions formally validated by the AirMDR Engineering or Integration team: Supported Wazuh versions: <Add validated version range>

The setup instructions in this guide follow the current Wazuh server API and RBAC interface. Menu names can vary slightly between Wazuh releases.

Authentication

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/TCPUse 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://<wazuh-manager>:55000.

Setup Steps

Create a dedicated Wazuh API user

Sign in to the Wazuh dashboard using an administrator account.
Open the navigation menu.
Navigate to Server management → Security → Users.
Click Create user or Add new user, depending on the Wazuh version.
Enter a dedicated username, for example: airmdr-api.
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.
Save the user.
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.

Create the required API policies

In the Wazuh dashboard, navigate to Server management → Security → Policies.
Click Create policy.
Enter a descriptive policy name, such as airmdr-investigation-read.
Set the policy effect to allow.
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
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:*
Save the policy.
If response skills are required, create a separate policy, for example: airmdr-response-actions.
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.

Create a role and attach the policies

Navigate to Server management → Security → Roles.
Click Create role.
Enter a role name, for example: airmdr-integration.
Attach the airmdr-investigation-read policy.
If response actions are approved, attach the airmdr-response-actions policy.
Save the role.

Assign the role to the API user

Navigate to Server management → Security → Users.
Open the airmdr-api user.
Select the role-assignment option.
Assign the airmdr-integration role.
Save the changes.
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.

Determine the Base URL

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://<WAZUH_MANAGER_HOSTNAME_OR_IP>:<API_PORT>Example: https://wazuh-manager.example.com:55000The 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:

Sample Request

curl -u "<WAZUH_API_USERNAME>:<WAZUH_API_PASSWORD>" \
  -X POST \
  "https://wazuh-manager.example.com:55000/security/user/authenticate?raw=true"

For a self-signed certificate during testing only:

<AccordionGroup>
  <Accordion title='curl -k \  -u "<WAZUH_API_USERNAME>:<WAZUH_API_PASSWORD>" \  -X POST \  "https://wazuh-manager.example.com:55000/security/user/authenticate?raw=true"'>
    curl -k \\

      -u "\<WAZUH\_API\_USERNAME\>:\<WAZUH\_API\_PASSWORD\>" \\

      -X POST \\

      "[https://wazuh-manager.example.com:55000/security/user/authenticate?raw=true](https://wazuh-manager.example.com:55000/security/user/authenticate?raw=true)"
  </Accordion>
</AccordionGroup>

Sample Response

A successful request returns a JWT. The -k option bypasses certificate validation and corresponds conceptually to setting Verify SSL to false.

<AccordionGroup>
  <Accordion title='TOKEN=$(curl -k \  -u "<WAZUH_API_USERNAME>:<WAZUH_API_PASSWORD>" \  -X POST \  "https://wazuh-manager.example.com:55000/security/user/authenticate?raw=true")curl -k \  -X GET \  "https://wazuh-manager.example.com:55000/" \  -H "Authorization: Bearer ${TOKEN}"'>
    TOKEN=\$(curl -k \\

      -u "\<WAZUH\_API\_USERNAME\>:\<WAZUH\_API\_PASSWORD\>" \\

      -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\}"
  </Accordion>
</AccordionGroup>

Configure Wazuh in AirMDR Integrations Dashboard

Navigate to AirMDR, provide the credentials and click Login
Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select ADMIN → Integrations.
Use the search option, enter the keyword “Wazuh”, select the Connections tab, and click + New Connection button.

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.

Expand Advanced Configuration if required. (Optional)

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

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

Agent and Fleet Visibility

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:*`

Investigation, Detection, and Compliance

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` → `::*`

Response and Remediation

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

Platform Operations and Access Governance

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 Integration page.
Select the Skills tab and click on the required listed skills.

Additional Information

🧰 Error Handling

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://<host>: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.

🔄 Monitoring & Logs

Wazuh API logsWazuh server API activity is recorded in: /var/ossec/logs/api.logThe default API log level is info. Supported levels include:

disabled
info
warning
error
debug
debug2

Wazuh supports plain-text and JSON API log formats. Wazuh API logging configurationExample 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.

🛑 Security & Access Best Practices

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

👉 Support & Maintenance

📧 Contact AirMDR Support 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 Flow & Security

Data exchangedDepending 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

Getting Started

AirMDR Detections

Integrations

API Reference

AirMDR Product Suite

Role-based access

Read and investigation permissions

Response permissions

Pre-requisites

Setup Steps

Wazuh Credential Reference Table

Validate Connectivity

Configure Wazuh in AirMDR Integrations Dashboard

Integration Requirements

Required Permissions

Mandatory connection-test permission

Skills provided by this Integration

Additional Information

Recommended logging

✅ Do

❌ Don’t

​Role-based access

​Read and investigation permissions

​Response permissions

​Pre-requisites

​Setup Steps

​Wazuh Credential Reference Table

​Validate Connectivity

​Configure Wazuh in AirMDR Integrations Dashboard

​Integration Requirements

​Required Permissions

​Mandatory connection-test permission

​Skills provided by this Integration

​Additional Information

​Recommended logging

​✅ Do

​❌ Don’t

Role-based access

Read and investigation permissions

Response permissions

Pre-requisites

Setup Steps

Wazuh Credential Reference Table

Validate Connectivity

Configure Wazuh in AirMDR Integrations Dashboard

Integration Requirements

Required Permissions

Mandatory connection-test permission

Skills provided by this Integration

Additional Information

Recommended logging

✅ Do

❌ Don’t