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.
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.
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.
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.
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.
curl $WAZUH_CTRL_URL/wazuh/agents-info
5. Get tasks info
Get statistics for registered tasks within Wazuh Controller App.
curl $WAZUH_CTRL_URL/tasks/info
6. Get notifiers info
Get statistics for registered notifiers within Wazuh Controller App and their readiness/configured states.
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
curl $WAZUH_CTRL_URL/notifiers/test
8. Configure data to synchronize
You can configure which data should be retrieved from SIEMonster webserver.
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
curl $WAZUH_CTRL_URL/configuration/get | jq
10. Update configuration (boolean, number, string)
We can set custom value of any config's primitive type:
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:
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.
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.
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.
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:
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:
curl $WAZUH_CTRL_URL/configuration/set/autoRemoveFoundLogFiles/true
And then trigger logs maintain immediatelly:
curl $WAZUH_CTRL_URL/wazuh/logs-maintain
16. Add/remove log-folder to watch
curl $WAZUH_CTRL_URL/configuration/rotateFolders/add/alerts
curl $WAZUH_CTRL_URL/configuration/rotateFolders/remove/alerts
17. Update full-disk percentage threshold percentage
curl $WAZUH_CTRL_URL/configuration/set/diskFullPercentageThreshold/85.3
18. Update Wazuh disconnected agents threshold percentage
curl $WAZUH_CTRL_URL/configuration/set/disconnectedAgentsPercentageThreshold/70
19. Attach all available report files on logs maintain
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
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:
curl $WAZUH_CTRL_URL/configuration/set/syncNotifiers/false
Then we send configure requests:
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:
curl $WAZUH_CTRL_URL/configuration/set/syncRecipients/false
Then we send configure request:
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
curl $WAZUH_CTRL_URL/configuration/set/wazuhIndexPattern/wazuh-alerts-4-*
24. Disable attaching Wazuh Kibana App's screenshot on failed Wazuh health check
curl $WAZUH_CTRL_URL/notificationEvents/wazuhHealthScreenshotOnFail/disable
25. Disable notification on still full disk even after logs maintain task
curl $WAZUH_CTRL_URL/notificationEvents/diskIsStillFull/disable
26. Manually configure tenant name
First, we need to disable tenants auto-sync feature:
curl $WAZUH_CTRL_URL/configuration/set/syncTenantName/false
Then we send configure request:
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.
|
Wazuh Logs Maintain | no | 15 3 * * * | Run every day at 03:15 AM | Maintain logs.
|
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 | list of enabled/disabled events generated by service and sent via configured destinations (e.g. Slack) |
daemonsAlerting | +wazuh-apid | list of enabled/disabled alerting for daemons |
rotateFolders | alerts | 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) |