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: API Port is reachable Apid is running DB is running Remoted is running Token obtaining Disconnected agents percentage Cluster is running (for cluster-mode) 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: Remove very old logs Auto-remove found .log files (if enabled) Cleanup .log/.json files until disk is free Find and compress uncompressed logs Remove old empty folders Check and notify if found .log files (if enabled) 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)