Skip to main content
Version: 0.4 · current

How the collector works

ConceptReviewed October 11, 2026
Applies to:Excubius 0.4Roles: Entity admin, Installer (Linux administrator)
PlansFree · Core · Pro · EnterpriseDeploymentSelf-hosted

The collector is the part of Excubius that reaches your systems. It runs the checks of the catalog over read-only connections, reads the sources you add, and sends raw results to the API, which evaluates them, raises alerts and notifies. This article explains how it works, which transports it uses, what each module needs, which network paths to open and what it never does.

How a check runs​

  1. Every 30 seconds the collector asks the API what to run: the check definitions from the catalog, the resources they target and the credentials they use. When nothing changed, the answer is empty and costs almost nothing.
  2. It runs each check on its interval over the transport the catalog names, such as T-SQL for a SQL Server instance or HTTP for a web endpoint.
  3. It sends the raw results to the API in batches. The API compares them with the effective thresholds, opens and resolves alerts and notifies the right channels.
  4. Every 10 seconds it picks up one-off jobs, such as Test connection, Discover and the Test and Sync now of a source. Every 60 seconds it reports a heartbeat, which the Sources zone of the Overview shows.

The collector runs inside the Excubius server, next to the API. It receives only its own token and settings; it never sees the database password or the key that encrypts stored secrets. Credentials reach it over the internal network, stay in memory and are never logged.

Transports​

A transport is the way the collector talks to one kind of system. Each one only reads.

TransportReachesPortCredential kindStatus
T-SQL (Microsoft ODBC Driver 18)SQL Server instances, availability groups, linked servers, the Reporting Services execution log1433 or the instance's port; UDP 1434 for named instances without a fixed portSQL loginSupported
HTTP(S)Web endpoints, Reporting Services portals, TLS certificates, domain expiry (RDAP)443, 80None, Windows account (NTLM), HTTP user and password, Bearer tokenSupported
DNSName resolution of endpoints and availability group listeners, with the server's resolver53NoneSupported
Azure Resource GraphCloud posture checks, Defender for Cloud assessments, Azure Update Manager, Service Health443The server's managed identity, or an Azure service principalSupported
Microsoft GraphEntra ID identity checks443The server's managed identity, or an Azure service principalSupported
WazuhThe Wazuh indexer and, optionally, the manager APIThe URLs you setHTTP user and passwordSupported when Wazuh is switched on
WinRMWindows host checks, Active Directory checks5986 (HTTPS)Windows accountExperimental
SSHLinux host checks22, or the host's ssh_portSSH key, SSH passwordExperimental
PostgreSQLPostgreSQL module checks5432SQL loginNot available yet: the checks are added but stay Unknown
warning

The WinRM and SSH transports exist and their checks are added to Windows and Linux hosts, but they have not been validated against real hosts yet. For those hosts, use NinjaOne, New Relic or Azure Monitor as a source until a release marks them as supported.

Sources are read by the collector too, over HTTPS (443), each with its own adapter: New Relic through NerdGraph, NinjaOne through its public API, and Azure Monitor through Azure Resource Manager, Resource Graph, Azure Monitor, Data Factory, Key Vault and Microsoft Graph. See Sources.

By default the collector offers every transport whose libraries are present in its image. EXCUBIUS_COLLECTOR_TRANSPORTS narrows that list; see Environment variables.

What each module needs​

ModuleCollected throughWhat you provide
SQL Server, availability groups, SQL Server securityT-SQLA read-only SQL login on every instance and replica
WindowsWinRM (experimental), or New Relic and NinjaOneA Windows account in three local read groups, or a source
LinuxSSH (experimental), or New Relic and NinjaOneA non-root user with a key, or a source
PostgreSQLNot available yet natively; Azure flexible servers through Azure MonitorA role with pg_monitor, ready for when collection arrives
Azure, Azure Data FactoryThe Azure Monitor sourceReader and Monitoring Reader, plus a read-only Data Factory role
Synthetic checksHTTP, DNS, T-SQLCredentials only for protected endpoints and report servers
ExpiryAzure Monitor, HTTP (RDAP), T-SQL, WinRMKey Vault and Microsoft Graph read permissions
UpdatesVendor feeds read by the API, plus inventory checksOutbound HTTPS from the server to the feeds
Identity securityMicrosoft Graph, WinRMRead-only Graph application permissions
Cloud securityResource Graph, Defender for Cloud, WazuhReader and Security Reader; a read-only Wazuh user
New Relic, NinjaOneTheir sourceA read-only key or API client

Every permission in one place: Permissions.

Network paths​

Every connection starts at the Excubius server. Nothing connects to the collector.

ToPortFor
Every SQL Server instance, replica, listener name and listener IPThe SQL port, 1433 by defaultSQL Server modules, availability groups, synthetic SQL round trips
Named instances without a fixed portUDP 1434SQL Server Browser
Web endpoints and Reporting Services portals443, 80Synthetic checks, TLS certificates
The DNS resolver of the server53Name resolution checks
data.iana.org and the registries' RDAP servers443Domain expiry
Windows hosts5986WinRM (experimental)
Linux hosts22SSH (experimental)
management.azure.com, graph.microsoft.com, your key vaults (*.vault.azure.net), and login.microsoftonline.com when you use a service principal443Azure Monitor source, Azure posture and identity checks
api.newrelic.com or api.eu.newrelic.com443New Relic source
app.ninjarmm.com, or eu., oc. or ca.ninjarmm.com443NinjaOne source
The Wazuh indexer and managerTheir portsWazuh

The API, not the collector, fetches the update feeds and talks to Slack and Jira; see Environment variables. Webhooks from sources arrive at the server's public address on 443 and go to the API, never to the collector.

Limits and timeouts​

LimitValue
Checks running at once32 in all; per transport: T-SQL 8, HTTP and DNS 16, SSH 8, WinRM 4, Resource Graph 4, Defender, Microsoft Graph and Wazuh 2
SQL Server login timeout · query timeout10 s · 30 s (catalog parameters timeout_seconds, query_timeout_seconds)
Rows read per query1,000
Longest a single check may run120 s
Results kept while the API cannot be reached10,000; the oldest are dropped first

SQL Server sessions carry the application name monitoring-collector, so the database administrators can recognise them in sys.dm_exec_sessions.

What the collector never does​

The collector is read-only by provisioning and by code. It never installs, updates, restarts or stops anything, never writes data, registry or configuration, never kills a session and never runs a remediation. A check that would need a write is rejected when it is reviewed for the catalog.

What it does send:

  • SQL Server: SELECT on dynamic management views, catalog views, msdb backup and job tables and the report server's ExecutionLog3; sys.sp_readerrorlog into a table variable; sp_testlinkedserver for linked servers.
  • HTTP: only GET and HEAD.
  • Azure and Wazuh: reads, plus the few POST requests that are queries, such as a Resource Graph query, a Data Factory run query or a Wazuh _search. Anything else is refused in code.
  • WinRM and SSH: the PowerShell and shell commands written in the catalog, which only read.

The exact query of every check is in the catalog and in the API at GET /api/v1/catalog/checks/{id}.

Agents for optional sources​

Excubius installs nothing on the systems it monitors. The agents of optional sources, such as Wazuh, are deployed by your own tooling, for example NinjaOne or your configuration management.

Next steps​