Wazuh REST API v2
Wazuh is the leading open-source SIEM, XDR, and security monitoring platform. Its REST API (v2, introduced in Wazuh 4.x) is a full-featured management and query interface running on the Wazuh manager node (default port 55000, HTTPS). The API covers five primary domains: security alerts (query, filter, aggregate by rule, severity, agent, time window), agent management (inventory, status, OS details, installed packages, network interfaces), rule and decoder management (read, add, enable/disable rules), compliance reporting (PCI-DSS, CIS, GDPR, HIPAA, NIST 800-53), and cluster management (node status, health, configuration). Authentication uses JWT tokens obtained by POST /security/user/authenticate with username/password (default expiry: 900 seconds / 15 minutes). Wazuh's query API supports rich filtering using q= parameter syntax (field:operator:value with AND/OR logic), enabling complex alert correlation queries. Security agents use the Wazuh API to build automated threat detection, SOC alert triage, incident investigation, compliance posture reporting, and response automation workflows without requiring direct Wazuh dashboard access.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
HTTPS is used for the Wazuh API by default but with self-signed certificates — organizations must replace with proper CA-signed certs for production. JWT-based auth with configurable TTL. RBAC system provides fine-grained per-resource, per-method access control. Create dedicated read-only API users for agent automation. Wazuh handles highly sensitive security telemetry (alerts, agent inventory, vulnerability data) — API access must be strictly controlled. Python SDK (Wazuh API Python package) available. Wazuh is GPL v2 with active community security review. API port (55000) should be firewall-restricted to known agent IPs only.
⚡ Reliability
Best When
A security operations team runs Wazuh for endpoint monitoring and needs to build automated SOC workflows — alert triage, compliance reporting, threat hunting, or incident response playbooks — without the cost of commercial SIEM platforms like Splunk or Microsoft Sentinel.
Avoid When
You use a different SIEM, need real-time event streaming via API (not polling), or require a fully managed cloud SIEM with no self-hosted infrastructure.
Use Cases
- • Querying security alerts by rule ID, severity, and time window to feed automated SOC triage workflows
- • Correlating alerts across multiple endpoints by agent group or OS type for incident investigation
- • Fetching agent vulnerability inventory to identify exposed endpoints before patching
- • Generating PCI-DSS and CIS compliance posture reports automatically on a schedule
- • Monitoring Wazuh agent health and connectivity status for infrastructure assurance workflows
- • Querying file integrity monitoring (FIM) events to detect unauthorized file changes across the fleet
- • Extracting MITRE ATT&CK technique mappings from alerts for threat intelligence enrichment workflows
Not For
- • Teams not running Wazuh — the API only surfaces data from Wazuh-monitored endpoints
- • Real-time streaming alert consumption — the API is pull-based; use Wazuh's Kafka/Logstash integration for streaming
- • Splunk, Elastic SIEM, or Microsoft Sentinel environments — use their respective APIs
- • Organizations requiring a vendor-supported cloud SIEM SLA — consider Wazuh Cloud or alternatives like Elastic SIEM
Interface
Authentication
JWT-based authentication: POST /security/user/authenticate with username/password returns a JWT token in the 'token' response field. Include in subsequent requests as Authorization: Bearer <token>. Default JWT TTL is 900 seconds (15 minutes) — configurable in /var/ossec/api/configuration/api.yaml. Wazuh 4.3+ supports API keys (long-lived tokens) for agent/automation use. RBAC (role-based access control) introduced in Wazuh 4.0 — roles grant fine-grained access to API resources (agents:read, rules:read, alerts:read, etc.). For agents, create a dedicated Wazuh user with a custom role that grants only the API endpoints the agent needs. The default 'wazuh-wui' user (used by the Wazuh dashboard) has full access and should NOT be used for agent automation. SSL/TLS is configured on the Wazuh manager API — use the Wazuh-generated CA cert or your own PKI; by default, self-signed certs require certificate verification to be disabled.
Pricing
Self-hosted Wazuh is completely free with no commercial license required. Wazuh Cloud is a managed SaaS offering that removes the operational burden. The Wazuh community is large and active — strong open-source support without a commercial contract.
Agent Metadata
Known Gotchas
- ⚠ JWT tokens expire after 900 seconds (15 minutes) by default — agents making long-running bulk queries must proactively refresh tokens; token expiry mid-workflow returns 401 with 'Expired signature' which must be caught and re-authenticated; implement token refresh 60 seconds before expiry to avoid gaps
- ⚠ Alert query results are indexed in Wazuh's internal Elasticsearch/OpenSearch store — queries against large time windows (>24 hours) can take 30-120 seconds and may trigger the API's request timeout (default 10 seconds); agents must configure timeout and use narrower time windows with pagination for bulk alert extraction
- ⚠ The q= filter parameter uses a custom syntax (field:operator:value) that differs from SQL, Lucene, and FQL — operators include =, !=, <, >, ~(contains), operators must be URL-encoded, and compound conditions use AND/OR logic; agents generating dynamic queries must validate q= syntax before submission
- ⚠ Wazuh API is only available on the Wazuh manager node — in clustered deployments (master + worker nodes), API calls go to the master and are forwarded to workers; agents querying a worker node directly will receive connection errors
- ⚠ Self-signed TLS certificates are used by default — agents must either pass the Wazuh CA certificate for verification or set verify=False (insecure) in HTTPS clients; production deployments should replace with organization CA certs
- ⚠ API rate limiting is configurable but not enforced by default — the default configuration has no rate limits; if a rate limit is configured by the admin, agents receive 429 with a remediation message specifying the limit; agents must check the /security/config endpoint to discover the current rate limit setting
- ⚠ Wazuh API RBAC permissions are defined per HTTP method and resource — a role with 'agents:read' allows GET /agents but not PUT /agents/{id}/restart; agent developers must map every API call their agent makes to the correct RBAC permission to avoid privilege creep or insufficient access errors
- ⚠ Alert query results are limited to 100,000 entries per paginated window — extracting all alerts for a high-traffic environment requires careful time windowing and offset pagination; the total_affected_items field in the response indicates total matches, not the number returned in the current page
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for Wazuh REST API v2.
Scores are editorial opinions as of 2026-03-06.