How the collector works
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
- 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.
- 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.
- 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.
- 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.
| Transport | Reaches | Port | Credential kind | Status |
|---|---|---|---|---|
| T-SQL (Microsoft ODBC Driver 18) | SQL Server instances, availability groups, linked servers, the Reporting Services execution log | 1433 or the instance's port; UDP 1434 for named instances without a fixed port | SQL login | Supported |
| HTTP(S) | Web endpoints, Reporting Services portals, TLS certificates, domain expiry (RDAP) | 443, 80 | None, Windows account (NTLM), HTTP user and password, Bearer token | Supported |
| DNS | Name resolution of endpoints and availability group listeners, with the server's resolver | 53 | None | Supported |
| Azure Resource Graph | Cloud posture checks, Defender for Cloud assessments, Azure Update Manager, Service Health | 443 | The server's managed identity, or an Azure service principal | Supported |
| Microsoft Graph | Entra ID identity checks | 443 | The server's managed identity, or an Azure service principal | Supported |
| Wazuh | The Wazuh indexer and, optionally, the manager API | The URLs you set | HTTP user and password | Supported when Wazuh is switched on |
| WinRM | Windows host checks, Active Directory checks | 5986 (HTTPS) | Windows account | Experimental |
| SSH | Linux host checks | 22, or the host's ssh_port | SSH key, SSH password | Experimental |
| PostgreSQL | PostgreSQL module checks | 5432 | SQL login | Not available yet: the checks are added but stay Unknown |
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
| Module | Collected through | What you provide |
|---|---|---|
| SQL Server, availability groups, SQL Server security | T-SQL | A read-only SQL login on every instance and replica |
| Windows | WinRM (experimental), or New Relic and NinjaOne | A Windows account in three local read groups, or a source |
| Linux | SSH (experimental), or New Relic and NinjaOne | A non-root user with a key, or a source |
| PostgreSQL | Not available yet natively; Azure flexible servers through Azure Monitor | A role with pg_monitor, ready for when collection arrives |
| Azure, Azure Data Factory | The Azure Monitor source | Reader and Monitoring Reader, plus a read-only Data Factory role |
| Synthetic checks | HTTP, DNS, T-SQL | Credentials only for protected endpoints and report servers |
| Expiry | Azure Monitor, HTTP (RDAP), T-SQL, WinRM | Key Vault and Microsoft Graph read permissions |
| Updates | Vendor feeds read by the API, plus inventory checks | Outbound HTTPS from the server to the feeds |
| Identity security | Microsoft Graph, WinRM | Read-only Graph application permissions |
| Cloud security | Resource Graph, Defender for Cloud, Wazuh | Reader and Security Reader; a read-only Wazuh user |
| New Relic, NinjaOne | Their source | A 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.
| To | Port | For |
|---|---|---|
| Every SQL Server instance, replica, listener name and listener IP | The SQL port, 1433 by default | SQL Server modules, availability groups, synthetic SQL round trips |
| Named instances without a fixed port | UDP 1434 | SQL Server Browser |
| Web endpoints and Reporting Services portals | 443, 80 | Synthetic checks, TLS certificates |
| The DNS resolver of the server | 53 | Name resolution checks |
data.iana.org and the registries' RDAP servers | 443 | Domain expiry |
| Windows hosts | 5986 | WinRM (experimental) |
| Linux hosts | 22 | SSH (experimental) |
management.azure.com, graph.microsoft.com, your key vaults (*.vault.azure.net), and login.microsoftonline.com when you use a service principal | 443 | Azure Monitor source, Azure posture and identity checks |
api.newrelic.com or api.eu.newrelic.com | 443 | New Relic source |
app.ninjarmm.com, or eu., oc. or ca.ninjarmm.com | 443 | NinjaOne source |
| The Wazuh indexer and manager | Their ports | Wazuh |
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
| Limit | Value |
|---|---|
| Checks running at once | 32 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 timeout | 10 s · 30 s (catalog parameters timeout_seconds, query_timeout_seconds) |
| Rows read per query | 1,000 |
| Longest a single check may run | 120 s |
| Results kept while the API cannot be reached | 10,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:
SELECTon dynamic management views, catalog views,msdbbackup and job tables and the report server'sExecutionLog3;sys.sp_readerrorloginto a table variable;sp_testlinkedserverfor linked servers. - HTTP: only
GETandHEAD. - Azure and Wazuh: reads, plus the few
POSTrequests 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.