Skip to main content
Skip table of contents

XDR controller API

For resiliency and automation, SIEMonster created the Wazuh controller api application. This application includes self-healing characteristics as well as some maintenance functions. Please find relevant information below for interacting with the API. To access it you need to drop into a shell on the wazuh container for the relevant tenant using the command listed.

CODE
kubectl -n tenant1 exec -it tenant1-wazuh-0 bash

NOTE: The above is based on the assumption that that the tenant being addressed is tenant1

Wazuh controller use cases and examples

Trigger immediate wazuh health check

Sending request will force the App to start Wazuh health check right now.

CODE
curl $WAZUH_CTRL_URL/wazuh/health-check?pretty
2. Trigger immediate wazuh logs maintain

Sending request will force the App to start logs maintain task right now.

CODE
curl $WAZUH_CTRL_URL/wazuh/logs-maintain
3. Trigger immediate synchronization with siemonster webserver

Wazuh Controller App will retrieve notificators (Slack, Mailgun, SMTP) settings, tenant name, email recipients, etc from SIEMonster Webserver and update its persistent config.

CODE
curl $WAZUH_CTRL_URL/sync
4. Get Wazuh agents info

Retrieve agents info from Wazuh. Controller App will automatically authenticate by obtaining token to get access to Wazuh API.

CODE
curl $WAZUH_CTRL_URL/wazuh/agents-info
5. Get tasks info

Get statistics for registered tasks within Wazuh Controller App.

CODE
curl $WAZUH_CTRL_URL/tasks/info
6. Get notifiers info

Get statistics for registered notifiers within Wazuh Controller App and their readiness/configured states.

CODE
curl $WAZUH_CTRL_URL/notifiers/info
7. Test configured notifiers

Broadcast test message to all ready and configured notifiers. If something goes wrong, error with details will be returned

CODE
curl $WAZUH_CTRL_URL/notifiers/test
8. Configure data to synchronize

You can configure which data should be retrieved from SIEMonster webserver.

CODE
curl $WAZUH_CTRL_URL/configuration/set/syncNotifiers/true
curl $WAZUH_CTRL_URL/configuration/set/syncRecipients/true
curl $WAZUH_CTRL_URL/configuration/set/syncTenantName/true
9. Get current configuration

Request will return current stored in RAM configuration, synced with file /var/ossec/etc/wazuh-controller.json

CODE
curl $WAZUH_CTRL_URL/configuration/get | jq
10. Update configuration (boolean, number, string)

We can set custom value of any config's primitive type:

CODE
curl $WAZUH_CTRL_URL/configuration/set/syncNotifiers/true
curl $WAZUH_CTRL_URL/configuration/set/cleanupIgnoreDays/14
curl $WAZUH_CTRL_URL/configuration/set/kibanaHost/kibana:5602

To update complex fields notificationEvents, rotateFolders, emailRecipients, use these API-routes:

CODE
curl $WAZUH_CTRL_URL/notificationEvents/diskIsStillFull/enable
curl $WAZUH_CTRL_URL/notificationEvents/diskIsStillFull/disable
curl $WAZUH_CTRL_URL/configuration/rotateFolders/add/alerts
curl $WAZUH_CTRL_URL/configuration/rotateFolders/remove/alerts
curl $WAZUH_CTRL_URL/configuration/emailRecipients/add/ilia@siemonster.com
curl $WAZUH_CTRL_URL/configuration/emailRecipients/remove/test@siemonster.com
11. Disable notifications module globally

You can turn off notifications globally.

CODE
curl $WAZUH_CTRL_URL/configuration/set/notificationsEnabled/false
12. Disable event notification

There's a pretty huge list of available events, generated by the App. You can configure every event separately.

CODE
curl $WAZUH_CTRL_URL/notificationEvents/restartingWazuh/disable
curl $WAZUH_CTRL_URL/notificationEvents/checkWazuhLogs/enable
13. Enable dry-mode

In this mode log files won't be touched when logs maintain task is performed.

CODE
curl $WAZUH_CTRL_URL/configuration/set/dryMode/true
14. Disable notification of found .log files

Notification about found .log files could be noisy. To disable it use request below:

CODE
curl $WAZUH_CTRL_URL/notificationEvents/foundLogFiles/disable
15. Enable autoremoving of .log files

If you don't want to delete .log files manually, you can enable related option:

CODE
curl $WAZUH_CTRL_URL/configuration/set/autoRemoveFoundLogFiles/true

And then trigger logs maintain immediatelly:

CODE
curl $WAZUH_CTRL_URL/wazuh/logs-maintain
16. Add/remove log-folder to watch
CODE
curl $WAZUH_CTRL_URL/configuration/rotateFolders/add/alerts
curl $WAZUH_CTRL_URL/configuration/rotateFolders/remove/alerts
17. Update full-disk percentage threshold percentage
CODE
curl $WAZUH_CTRL_URL/configuration/set/diskFullPercentageThreshold/85.3
18. Update Wazuh disconnected agents threshold percentage
CODE
curl $WAZUH_CTRL_URL/configuration/set/disconnectedAgentsPercentageThreshold/70
19. Attach all available report files on logs maintain
CODE
curl $WAZUH_CTRL_URL/notificationEvents/statReport/enable
curl $WAZUH_CTRL_URL/notificationEvents/logReport/enable
curl $WAZUH_CTRL_URL/notificationEvents/debugReport/enable
curl $WAZUH_CTRL_URL/notificationEvents/eventsReport/enable
20. Do not attach report files in notifications
CODE
curl $WAZUH_CTRL_URL/notificationEvents/statReport/disable
curl $WAZUH_CTRL_URL/notificationEvents/logReport/disable
curl $WAZUH_CTRL_URL/notificationEvents/debugReport/disable
curl $WAZUH_CTRL_URL/notificationEvents/eventsReport/disable
21. Manually configure Slack without syncing

First, we need to disable notifiers auto-sync feature:

CODE
curl $WAZUH_CTRL_URL/configuration/set/syncNotifiers/false

Then we send configure requests:

CODE
curl $WAZUH_CTRL_URL/configuration/set/slackEnabled/true
curl $WAZUH_CTRL_URL/configuration/set/slackToken/xoxp-12345-...
curl $WAZUH_CTRL_URL/configuration/set/slackChannel/demoalerting2
22. Manually configure recipients for email notification

First, we need to disable recipients auto-sync feature:

CODE
curl $WAZUH_CTRL_URL/configuration/set/syncRecipients/false

Then we send configure request:

CODE
curl $WAZUH_CTRL_URL/configuration/emailRecipients/add/ilia@siemonster.com
curl $WAZUH_CTRL_URL/configuration/emailRecipients/remove/test@siemonster.com
23. Set custom Wazuh index pattern to work with
CODE
curl $WAZUH_CTRL_URL/configuration/set/wazuhIndexPattern/wazuh-alerts-4-*
24. Disable attaching Wazuh Kibana App's screenshot on failed Wazuh health check
CODE
curl $WAZUH_CTRL_URL/notificationEvents/wazuhHealthScreenshotOnFail/disable
25. Disable notification on still full disk even after logs maintain task
CODE
curl $WAZUH_CTRL_URL/notificationEvents/diskIsStillFull/disable
26. Manually configure tenant name

First, we need to disable tenants auto-sync feature:

CODE
curl $WAZUH_CTRL_URL/configuration/set/syncTenantName/false

Then we send configure request:

CODE
curl $WAZUH_CTRL_URL/configuration/set/tenantName/customTenantName

Tasks Running by App

Task Name

Run at Start

Cron Value

Human-Readable

Comment

Wazuh Health

no

*/15 * * * *

Run every 15 minutes

Make sure that Wazuh service is healthy, otherwise restart it.
List of checks:

  1. API Port is reachable

  2. Apid is running

  3. DB is running

  4. Remoted is running

  5. Token obtaining

  6. Disconnected agents percentage

  7. Cluster is running (for cluster-mode)

  8. Scrape Wazuh Kibana App's page and make sure that it's loading

Wazuh Logs Maintain

no

15 3 * * *

Run every day at 03:15 AM

Maintain logs.
List of tasks:

  1. Remove very old logs

  2. Auto-remove found .log files (if enabled)

  3. Cleanup .log/.json files until disk is free

  4. Find and compress uncompressed logs

  5. Remove old empty folders

  6. Check and notify if found .log files (if enabled)

  7. Check if disk is not full after performing all tasks, otherwise send notification if enabled

Wazuh Scheduled Restart

no

38 */24 * * *

Run at minute 38 past every 24th hour

Scheduled wazuh restart.

Sync Notifiers

yes

*/10 * * * *

Run every 10 minutes

Retrieve configuration of Slack/SMTP/Mailgun destinations from SIEMonster webserver. Task could be disabled by related config-value.

SCA-check

yes

17 9 * * *

Run every day at 9.17am

Update SCA-check status.

Kibana Index Pattern

yes

-

-

Check existence of required index-pattern. If it doesn't exist, then open Wazuh Kibana App to trigger index-pattern creation.

Environment Variables

Name

Is Required

Default Value

Description

ES_URL

yes

Elasticsearch URL with credentials

KIBANA_HOST

yes

Kibana's Hostname

WAZUH_API_USER

yes

Username for Wazuh API

WAZUH_API_PWD

yes

Password for Wazuh API

WAZUH_API_HOSTNAME

no

localhost

Hostname for Wazuh API

WAZUH_CTRL_BASIC_USERNAME

no

si3monster

Basic-Auth Username for service's API

WAZUH_CTRL_BASIC_PASSWORD

no

a1b2c3d4

Basic-Auth Password for service's API

SIEMONSTER_URL

no

SIEMonster webserver's url, e.g. http://siemonster:3000

SIEMONSTER_JWT_SECRET

no

JWT to interact with SIEMonster webserver

SVC_CRON_DELAY_SEC

no

600

Delay before start all CRON-jobs on server start

SVC_WAIT_TIMEOUT_SEC

no

900

Timeout for waiting functions

SVC_WAIT_INTERVAL_SEC

no

15

Sleep interval between waiting steps

APP_HTTPS

no

false

Run service either in HTTP/HTTPS mode

DEBUG_WS_ENDPOINT

no

Debug browser's endpoint

DEBUG_BROWSER

no

false

Open Browser in non-headless mode

DEBUG_ADD_CONSOLE_LOG

no

false

Print in server console browser's console log

API

Service runs on port 4000. Available methods are GET/POST. Current API-version prefix is /api/v1/
For convenience ENV-variable WAZUH_CTRL_URL is available, so you can interact with API in such way: curl $WAZUH_CTRL_URL/configuration/get?pretty

Endpoint

Auth Required

Description

/sync

yes

retrieve configuration (notifiers, tenant name, email recipients) from SIEMonster server

/configuration/get

yes

get all persistent configuration keys

/configuration/get/:key

yes

get configuration value for specified key

/configuration/set/:key/:unfilteredValue

yes

set specified value for specified key (string, number, boolean data types only)

/configuration/emailRecipients/add/:email

yes

add email to recipients list

/configuration/emailRecipients/remove/:email

yes

remove email from recipients list

/configuration/notificationEvents/:eventName/enable

yes

enable notification event

/configuration/notificationEvents/:eventName/disable

yes

disable notification event

/configuration/daemonsAlerting/:daemonName/enable

yes

enable alerting for daemon

/configuration/daemonsAlerting/:daemonName/disable

yes

disable alerting for daemon

/configuration/rotateFolders/add/:folderName

yes

enable scanning logs folder

/configuration/rotateFolders/remove/:folderName

yes

disable scanning logs folder

/wazuh/health-check

yes

trigger immediately Wazuh health check without waiting related CRON-tick

/wazuh/logs-maintain

yes

trigger immediately Wazuh logs maintain without waiting related CRON-tick

/wazuh/sca-check

yes

trigger immediately SCA check task

/wazuh/kibana-index-check

yes

trigger immediately Wazuh Kibana index check task

/wazuh/stat

yes

form statistics

/wazuh/agents-info

yes

form agents info

/wazuh/cluster/agents

yes

get cluster agents info

/wazuh/cluster/health

yes

get cluster health info

/wazuh/cluster/nodes

yes

get cluster nodes info

/wazuh/cluster/nodes/all

yes

get all registered nodes

/wazuh/cluster/nodes/unregister/:nodeName

yes

unregister node by specified name

/wazuh/build

yes

Wazuh version and revision

/wazuh/status

yes

ossec-control status

/wazuh/disk-info

yes

disk info

/backup/do

yes

run backup task

/backup/list

yes

list available backups

/backup/info/:backupId

yes

list backup info

/backup/delete/:backupId

yes

delete specified backup

/tasks/info

yes

info of tasks and their state (health-check, logs-maintain, etc)

/notifiers/info

yes

info about existing notifiers

/notifiers/test

yes

broadcast test message for all configured notifiers

/getSettings

no

return public settings

/metrics

no

Prometheus metrics

/metrics/refresh

no

Generate Prometheus metrics immediately

/ping

no

ping-pong

/about

no

print information about service

/healthz

no

return OK (for Kubernetes health-checks)

Persistent Configuration

Configuration file is located at path: /var/ossec/etc/wazuh-controller.json

Name

Default Value (on config init)

Description

dryMode

false

when enabled log files are not modifying when performing related logs-repairment tasks

tenantName

env TENANT_NAME

additional prefix in notifications

wazuhIndexPatternCheckFeatureEnabled

true

Enable index pattern auto-creation feature

wazuhHealthCheckFeatureEnabled

true

Enable Wazuh health check feature

wazuhLogsMaintainFeatureEnabled

true

Enable Wazuh logs maintain feature

notificationsEnabled

true

Enable notifications module globally

syncNotifiers

true

Sync notification settings from SIEMonster webserver (SIEMONSTER_URL/SIEMONSTER_JWT_SECRET envs are required)

syncRecipients

true

Sync notifications recipients settings from SIEMonster webserver (SIEMONSTER_URL/SIEMONSTER_JWT_SECRET envs are required)

syncTenantName

true

Sync tenant name from SIEMonster webserver (SIEMONSTER_URL/SIEMONSTER_JWT_SECRET envs are required)

emailRecipients

[]

emails list of notifications recipients

slackEnabled

false

enable/disable Slack destination

slackToken

token for Slack destination

slackChannel

channel for Slack destination

mailgunEnabled

false

enable/disable Mailgun integration

mailgunApiKey

API key for Mailgun destination

mailgunDomain

domain for Mailgun destination

mailgunFromAddress

from-address for Mailgun destination

smtpEnabled

enable/disable SMTP destination

smtpHost

host for SMTP destination

smtpPort

port for SMTP destination

smtpSecure

secure flag for SMTP destination

smtpIgnoreTLS

ignore-tls flag for SMTP destination

smtpUser

user for SMTP destination

smtpPassword

password for SMTP destination

smtpSender

sender for SMTP destination

kibanaHost

required env KIBANA_HOST

host of Kibana to interact with

wazuhIndexPattern

wazuh-alerts-*

wazuh's index pattern

notificationEvents

+restartingWazuh
+restartingWazuhResult
+wazuhHealthLocked
+wazuhLogsMaintainLocked
+checkWazuhLogs
+wazuhHealthScreenshotOnFail
+noRemovableLogsLeft
+diskIsStillFull
+monthsShortCheckFailed
+foundLogFiles
-statReport
-logReport
-debugReport
-eventsReport
+forcedLogsMaintainAfterHealthChecks
+exOnRemoveOldFile
+exOnRemoveDiskFullDayFile
+exOnRemoveDiskFullDayFileItem
+exOnCompressDayFile
+exOnSyncFailed

list of enabled/disabled events generated by service and sent via configured destinations (e.g. Slack)

daemonsAlerting

+wazuh-apid
+wazuh-db
+wazuh-clusterd
+wazuh-remoted
+wazuh-modulesd
+wazuh-monitord
+wazuh-logcollector
+wazuh-syscheckd
-wazuh-analysisd
-wazuh-maild
+wazuh-execd
+wazuh-authd
-wazuh-agentlessd
-wazuh-integratord
-wazuh-dbd
-wazuh-csyslogd

list of enabled/disabled alerting for daemons

rotateFolders

alerts
api
archives
cluster
firewall
ossec

list of folders in Wazuh's logs path, which are observed for maintain (deleting, compress, etc)

cleanupIgnoreDays

7

number of ignore last days of logs when cleaning up logs to fix full disk

protectionIgnoreDays

2

number of ignore last days of logs which are totally ignored for any files manipulations

uncompressIgnoreDays

2

number of ignore last days of logs when check uncompressed logs

findLogFilesIgnoreDays

2

number of ignore last days of logs when searching *.log files

oldEmptyFoldersIgnoreMonths

90

number of ignore last days when searching empty log folders

oldLogsEdgeDays

365

number of ignore last days of logs when removing very old logs

maxCleanupFilesPerTick

1000

maximum number of cleanup files per logs tick

autoRemoveFoundLogFiles

false

find and auto-remove *.log files

diskFullPercentageThreshold

85.0

percentage threshold of filled space when we consider that disk is full

disconnectedAgentsPercentageThreshold

75.0

percentage threshold of disconnected Wazuh agents when we consider that Wazuh should be restarted

healthCheckFailsThresholdCount

3

number of failed scheduled wazuh health checks in a row to trigger immediate logs maintain task

forceUnlockLogsMaintainJobInSeconds

2700

logs maintain task timeout in seconds (45 minutes by default)

forceUnlockWazuhHealthJobInSeconds

600

wazuh health task timeout in seconds (10 minutes by default)

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.