Learn Wazuh - API, Authentication, and Security Best Practices

#Introduction

In episode 14, we built the distributed Wazuh architecture: indexer cluster, manager cluster, and dashboard. A large architecture brings consequences: the more entry points, the more needs securing. One of the most often forgotten entry points is the API.

The Wazuh API is the automation gateway. The dashboard talks to the API, tooling talks to the API, and SOAR integrations talk to the API. If the API is exposed without proper authentication, our entire stack could be taken over by someone else.

In episode 15, we'll discuss the Wazuh API from two sides. First, its function: main endpoints, Swagger UI, and the Python SDK. Second, its security: RBAC, single sign-on, TLS, and password hardening.

#Getting to Know the Wazuh API

The Wazuh API is a RESTful interface running on port 55000 over HTTPS. All management operations can be done through the API: listing agents, running active response, triggering SCA scans, up to managing rules.

Every request requires a JWT token. The token is obtained by calling the login endpoint with user credentials. The simplest example uses curl.

TOKEN=$(curl -s -u wazuh-wui:SecretWUI \
  -k https://10.0.1.11:55000/security/user/authenticate)

curl -k -X GET https://10.0.1.11:55000/agents \
  -H "Authorization: Bearer $TOKEN"

#Main Endpoints

A few endpoints most frequently used in automation:

• /agents: agent list, status, and details.
• /security: user, role, and RBAC policy management.
• /vulnerability: vulnerability scan results per agent.
• /syscheck: file integrity monitoring results.
• /sca: security configuration assessment results.
• /active-response: trigger prevention actions on agents.

To add a new agent via the API, we can call the enrollment endpoint. This is what the dashboard uses when showing install commands for new agents.

{
  "data": {
    "id": "014",
    "key": "MDE1NmViOWQxMW...",
    "name": "web-server-01"
  }
}

#Swagger UI

Every Wazuh installation ships interactive API documentation as Swagger UI. Open https://10.0.1.11:55000 in a browser, then log in with an API user. You'll see all endpoints, parameters, and example responses that can be tried directly.

Swagger UI is very helpful when learning. You can see the correct request shape for an endpoint, then replicate that shape in your automation scripts. This significantly speeds up integration development.

#The Python SDK

For programming languages, Wazuh provides an official Python SDK. The package named wazuh SDK wraps the API so we don't have to write curl over and over.

Installing the Wazuh SDKExample of using the SDK to list agents

pip install wazuh

from wazuh.core import client
 
client = client.Wazuh(host="10.0.1.11", user="wazuh-wui", password="SecretWUI")
agents = client.api_request("/agents")
for agent in agents["data"]["affected_items"]:
    print(agent["name"], agent["status"])

This SDK uses the same API, so anything possible in the dashboard is possible in code. That's the foundation for SOAR and automation integration.

#Role-Based Access Control

The Wazuh API implements RBAC. Users don't get full access directly; instead they go through roles that contain policies. Each policy defines the allowed resources and actions.

• User: the identity used to log in.
• Role: a collection of policies, attached to a user.
• Policy: permission rules, e.g., allowed to read agents but not delete them.

By default there are two built-in roles: administrator with full access, and read-only. For special needs, create new roles with strict policies. An example policy for a user who may only read agent status:

{
  "actions": ["agent:read"],
  "resources": ["agent:id:*"]
}

Apply the principle of least privilege: give the minimum access needed for the task. Service accounts for automation should also be limited, not using an administrator account.

#Single Sign-On

Local user passwords are hard to manage as teams grow. The solution is single sign-on. The Wazuh Dashboard supports SAML and OpenID Connect, so login can be handed off to an identity provider like Keycloak or Authelia.

With SSO, user management is centralized in one place. Users who leave the team can have their access revoked immediately, and policies like MFA can be applied uniformly. Integration with Keycloak or Authelia in Wazuh is done by filling in the provider's metadata in the dashboard configuration.

#TLS Between Components

All internal Wazuh communication must go over TLS. There are several paths that must be secured.

• Agent to manager: we'll discuss this deeper via mTLS in episode 16.
• Manager to indexer: Filebeat uses HTTPS with the indexer certificate.
• Dashboard to indexer: HTTPS with the same certificate.
• Browser to dashboard: ideally behind a reverse proxy with TLS.

Internal certificates are usually self-signed from the Wazuh CA. What matters isn't who issued them, but consistency: one same CA trusted by all components.

#Password Hardening

Passwords are the last line of defense that's most often ignored. A few steps we apply:

• Change all default passwords right after installation.
• Use long random passwords, not easily guessable phrases.
• Enable rate limiting on the API to slow brute force.
• Rotate API passwords regularly, especially service accounts.
• Never store passwords in code or in committed configuration files.

curl -k -u wazuh-wui:SecretWUI \
  -X PUT https://10.0.1.11:55000/security/users/1/password \
  -H "Content-Type: application/json" \
  -d '{"password":"NewStr0ngP@ss!"}'

#Integration with SOAR and Automation

The API and SDK open the door to integration with SOAR tools like TheHive or Shuffle. A typical flow: a Wazuh alert triggers a webhook, the SOAR creates a ticket, then runs a playbook that calls back to the Wazuh API to fetch context or run active response.

A simple example using Wazuh's built-in webhook to forward alerts to Shuffle:

<integration>
  <name>shuffle</name>
  <hook_url>https://shuffle.example.com/api/v1/webhooks/...</hook_url>
  <alert_format>json</alert_format>
</integration>

With this pattern, incident response is no longer manual. Playbooks can disable agents, trigger scans, or call threat intel automatically.

#Conclusion

In episode 15, we covered the Wazuh API and its security. We got to know the main endpoints, Swagger UI for interactive documentation, and the wazuh Python SDK for automation. Then we strengthened access with RBAC, single sign-on via SAML and OpenID Connect, TLS between components, and password hardening.

Key takeaways:

• The Wazuh API runs on port 55000 and uses JWT tokens.
• Swagger UI is available directly at the API address for interactive documentation.
• The wazuh Python SDK wraps the API for automation and SOAR.
• RBAC separates users, roles, and policies with the principle of least privilege.
• SSO with Keycloak or Authelia centralizes dashboard authentication.
• TLS and password rotation are mandatory for all paths and accounts.

The API is secure, but there's one communication path that's most often underrated: agent to manager. In episode 16, we'll cover encryption, X.509 certificates, and secure agent communication in depth. See you there!