Configuration

Wazuh manager API configuration file

The Wazuh manager API configuration file is located at /var/wazuh-manager/api/configuration/api.yaml on the Wazuh manager. By default, most settings are commented out. To apply a different configuration, uncomment and edit the desired line. The file owner is root:wazuh-manager, with mode 0660. An unknown option or a value of the wrong type stops the Wazuh manager API with error 2000. To check the file before you restart the Wazuh manager, run /var/wazuh-manager/bin/wazuh-manager-apid -t -c /var/wazuh-manager/api/configuration/api.yaml.

The following block is the shipped template of the /var/wazuh-manager/api/configuration/api.yaml configuration file, with every setting commented out. For more information on each of the settings, check the configuration options:

# USE THIS FILE AS A TEMPLATE. UNCOMMENT LINES TO APPLY CUSTOM CONFIGURATION

# host: ['0.0.0.0', '::']
# port: 55000

# Advanced configuration

# https:
#  enabled: yes
#  key: "apid-key.pem"
#  cert: "apid.pem"
#  use_ca: False
#  ca: "root-ca.pem"
#  ssl_ciphers: ""  # Passed to OpenSSL as written (case-sensitive); empty = ECDHE+AESGCM:ECDHE+CHACHA20

# Modify API's intervals (time in seconds)
# intervals:
#   request_timeout: 10

# Logging configuration
# Values for API log level: critical, error, warning, info, debug, debug2 (each level includes the previous levels).
# Values for API log max_size: <value><unit>. Valid units: K (kilobytes), M (megabytes)
# Enabling the API log max_size will disable the time based rotation (on midnight)
# logs:
#  level: "info"
#  format: "plain"
#  max_size:
#    enabled: False
#    size: "1M"

# Cross-origin resource sharing: https://www.starlette.io/middleware/#corsmiddleware
# cors:
#  enabled: no
#  source_route: "*"
#  expose_headers: "*"
#  allow_headers: "*"
#  allow_credentials: no

# Access parameters
# access:
#  max_login_attempts: 50
#  block_time: 300
#  max_request_per_minute: 300
#  max_unauthenticated_request_per_minute: 10

# Drop privileges (Run as wazuh-manager user)
# drop_privileges: yes

# Maximum body size that the API can accept, in bytes (0 -> limitless)
# max_upload_size: 10485760

# Maximum size, in bytes, of the run_as authentication context payload
# (POST /security/user/authenticate/run_as). AD/LDAP/SSO logins with large
# group memberships may need to raise this. Independent of max_upload_size,
# which still bounds the overall request body for every endpoint.
# auth_context_max_payload_size: 65536

# Number of processes dedicated to processing authentication requests.
# authentication_pool_size: 2

# Uploadable Wazuh configuration sections
# upload_configuration:
#   agents:
#     allow_higher_versions:
#       allow: yes
#   indexer:
#     allow: yes

Make sure to restart the Wazuh manager API using the Wazuh manager service after editing the configuration file:

# systemctl restart wazuh-manager

# service wazuh-manager restart

Wazuh manager API security configuration

Security-related settings such as token expiration auth_token_exp_timeout, and RBAC behavior rbac_mode are managed exclusively through the Wazuh manager API, not through a configuration file.

• GET /security/config: View current security configuration

• PUT /security/config: Update security settings

• DELETE /security/config: Reset to default values

The auth_token_exp_timeout defines the duration in seconds before an authentication token expires and requires renewal. The rbac_mode determines the default behavior of the Role-Based Access Control system. It either permits or denies access to any resource that no policy explicitly covers. Refer to the Role-Based Access Control documentation for more details. In a cluster, the configuration applies to the Wazuh manager API on the master node, the only node that runs it.

For more information on each of the settings, see the security configuration options.

# curl -k -X GET "https://<WAZUH_MANAGER_IP_ADDRESS>:55000/security/config?pretty=true" \
     -H "Authorization: Bearer $TOKEN"

{
   "data": {
      "auth_token_exp_timeout": 900,
      "rbac_mode": "white"
   },
   "error": 0
}

# curl -k -X PUT "https://<WAZUH_MANAGER_IP_ADDRESS>:55000/security/config" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"auth_token_exp_timeout": 1800}'

{"message": "Configuration was successfully updated", "error": 0}

# curl -k -X PUT "https://<WAZUH_MANAGER_IP_ADDRESS>:55000/security/config" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"rbac_mode": "black"}'

{"message": "Configuration was successfully updated", "error": 0}

# curl -k -X DELETE "https://<WAZUH_MANAGER_IP_ADDRESS>:55000/security/config?pretty=true" \
     -H "Authorization: Bearer $TOKEN"

{
   "message": "Configuration was successfully updated",
   "error": 0
}

Configuration endpoints

The Wazuh manager API has several endpoints that allow querying its current configuration. To modify the general API configuration, edit the /var/wazuh-manager/api/configuration/api.yaml file as detailed in the Wazuh manager API configuration file section.

SSL certificate

The SSL certificate ensures secure communication between the Wazuh manager API and its clients. The certificate files are in the /etc/wazuh-manager/certs/ directory.

Take the following steps to issue a new certificate for the Wazuh manager API from the Wazuh manager CA:

1. Move the current key and certificate out of the /etc/wazuh-manager/certs directory. Optionally, set the names that the new certificate must cover in the WAZUH_MANAGER_APID_CERT_SANS variable of /etc/wazuh-manager/local.env. Then run the credential resolver to issue a new pair:

   # cd /etc/wazuh-manager/certs
   # mkdir -p /root/apid-certs-backup
   # mv apid-key.pem apid.pem /root/apid-certs-backup/
   # /var/wazuh-manager/bin/wazuh-manager-resolve-credentials --install
   

   The command issues apid.pem and apid-key.pem from the Wazuh manager CA, with the owner and mode that the Wazuh manager requires.

   To use your own certificate instead, place the key and the certificate, followed by any intermediate certificates, directly in /etc/wazuh-manager/certs. Set their owner to root:wazuh-manager and their mode to 0640, and set https.key and https.cert in api.yaml to the filenames. The certificate must chain to the CA in /etc/wazuh-manager/ca/root-ca.pem, must not be a CA certificate, and must include the hostnames of the Wazuh manager as subject alternative names. Do not protect the key with a passphrase. Run /var/wazuh-manager/bin/wazuh-manager-resolve-credentials --check to validate the files. If any check fails, the Wazuh manager does not start.

2. Restart the Wazuh manager to load the new certificate:

   # systemctl restart wazuh-manager