Skip to main content
Version: 0.4 · current

Store a credential for the collector

How-to guideReviewed October 11, 2026
Applies to:Excubius 0.4Roles: Entity admin
PlansFree · Core · Pro · EnterpriseDeploymentSelf-hosted

A credential is the read-only login the collector uses to reach a system: a SQL login, a Windows account, an SSH key or an Azure service principal. You store it once on an entity, and every resource of that entity and below can use it. This guide shows how to add one, which kind to choose, the connection options of each kind and how a resource finds the credential it uses.

Before you begin​

  • You need the Entity admin role on the entity that will own the credential.
  • The login exists on the monitored system with read-only permissions. For SQL Server, see Prerequisites for availability groups; for every platform, see Permissions.
  • Store the credential as high in the entity tree as it is valid. A SQL login used on every server of Ciguapa Inc. belongs on Ciguapa Inc., not on each environment.

Choose the kind​

KindUserSecretUse it for
SQL login (sql_login)SQL loginPasswordSQL Server instances and availability groups; their discovered databases and linked servers use the instance's. Also the Reporting Services execution log
Windows account (windows)Account (DOMAIN\user)PasswordWindows hosts over WinRM; report servers and web endpoints with Windows authentication (NTLM)
HTTP user and password (http_basic)UserPasswordWeb endpoints and report servers with Basic authentication; the Wazuh checks
Bearer token (token)—TokenWeb endpoints with bearer authentication
SSH key (ssh_key)UserPrivate keyLinux hosts
SSH password (ssh_password)UserPasswordLinux hosts
Azure service principal (azure_sp)Client idClient secretAzure posture checks and Entra ID identity checks, for a tenant the server's managed identity cannot reach

Windows-integrated authentication to SQL Server is not supported: the collector runs in a Linux container without a Kerberos ticket. Use a SQL login, which needs the instance to accept SQL Server authentication (mixed mode).

Add a credential​

  1. Open Settings › Credentials and choose the entity in the entity picker, for example Ciguapa Inc..
  2. Select Add credential.
  3. Enter a Name you will recognise, such as sql-monitoring, and choose the Kind. The kind cannot change later.
  4. Check the Entity: resources of this entity and below can use the credential.
  5. Enter the user and the secret. The labels follow the kind, for example SQL login and Password, or Client id and Client secret.
  6. Under Connection options, set what the kind needs. See the next section.
  7. Select Create.

The credential appears in the list with the secret marked stored, how many resources use it and when it was last used.

Connection options​

KindOptionValuesEffect
SQL loginencryptyes (default), no, strictEncrypts the connection. strict uses TDS 8 and needs SQL Server 2022 or later
SQL logintrust_server_certificatetrue (default), falseMost instances use self-signed certificates. Set false once the instance has a certificate the collector trusts
SQL loginhost_name_in_certificateA host nameThe name to validate when it differs from the host, for example through a listener or an alias
SQL loginapplication_intentReadOnly (default), ReadWriteReadWrite only changes routing, so per-database checks include the availability databases of a primary that refuses read-intent connections. The login still has no write permission
Windows accountauthkerberos (default), negotiate, ntlmHow WinRM authenticates. The collector image has no Kerberos configuration, so choose negotiate or ntlm
SSH key, SSH passwordknown_hostsOpenSSH known_hosts lines, one per linePins the host keys the collector accepts
Azure service principaltenant_idThe Entra tenant IDThe tenant of the app registration

Some options are set through the API only, in the credential's attributes:

KindOptionEffect
Azure service principalsubscriptionsLimits Azure posture checks to these subscriptions. Without it, AZURE_SUBSCRIPTION_IDS applies, or else every subscription the identity can read
HTTP user and passwordverify_tlsfalse accepts an untrusted certificate on the Wazuh indexer and manager. Default true

Option names never hold secrets: the API refuses an option whose name contains pass, secret, token, private or pwd. Put secrets in the secret field.

How the secret is protected​

  • The secret is write-only. It is encrypted with the installation's data key (EXCUBIUS_DATA_KEY) and never shown again, on any screen or through the API, which only says whether one is stored.
  • To change it, edit the credential and enter a new one. Leave the field empty to keep the stored secret, or select Remove the stored secret to clear it.
  • The collector receives the secret over the internal network, keeps it in memory only and never logs it.
  • Keep EXCUBIUS_DATA_KEY with the backup of the .env file. Without it the stored secrets cannot be decrypted, and checks fail with the error kind config until you enter them again.

Which credential a resource uses​

A resource looks for a credential in this order and takes the first one whose kind suits the check:

  1. The check's own credential, when one is set.
  2. The resource's credential.
  3. The credential of the nearest parent resource. An availability group or a database discovered under an instance uses the instance's SQL login.

For example, the execution log check of a report server is a T-SQL check. When the report server resource holds a Windows account for its portal, the check uses the SQL login of the instance above it, or a SQL login you set on that one check.

To set a credential on one check, use the API: PATCH /api/v1/resources/{id}/checks/{check_id} with credential_id. Pointing a resource or a check at a credential needs the Entity admin role on the entity that owns the credential.

Edit or delete a credential​

  • Edit changes the name, the user, the secret and the options. The kind stays.
  • Delete works only when nothing uses the credential. Change the resources and checks that use it first.
  • Deleting an entity also deletes the credentials it owns.

The list shows, for each credential, how many resources and checks use it and when a successful check last used it.