Agent Guide
The OmniSight Agent is a compiled Go service that runs on endpoints and reports network connection metadata to your self-hosted OmniSight server. It does not capture packet payloads, decrypt TLS, perform MITM behavior, or modify traffic.
Supported Agent Paths
| Platform | Architecture | Current customer path |
|---|---|---|
| macOS | arm64 | Public Agent Installer app plus dashboard invite URL |
| macOS | amd64 | Planned customer package; current published macOS runtime targets arm64 |
| Linux | amd64, arm64 | Authenticated CLI/package install for eligible split packages |
| Windows | amd64 | Metrics-capable agent binary; customer installer remains planned |
The self-hosted console's current Deploy Agent workspace creates macOS invite sessions. Linux packages are validated for the controlled CLI path and are gated by entitlement/package policy. Windows no-code install and connection collection are not customer-ready paths yet, but the Windows agent can report aggregate system metrics when packaged and enrolled.
Data Collected
The agent collects connection metadata only:
- timestamp
- event type
- local IP and port
- remote IP and port
- protocol
- direction
- process name
- PID when available
- DNS/domain enrichment when available
- DNS query metadata (query name, query type, response code, answer count) on Linux agents when Protocol Metadata is enabled by an administrator
- endpoint web connection classification for HTTP/S destinations when available
- software inventory metadata for vulnerability matching
- aggregate host metrics: CPU, memory, disk, network byte counters/throughput, best-effort temperature, and boot identity
It does not collect usernames, passwords, request bodies, response bodies, cookies, headers, files, command lines, per-connection tuples, destinations for system metrics, decrypted TLS content, or packet payloads.
Enrollment Model
First-run enrollment uses two credentials:
- A locally generated
agent_token, persisted in the agent config. - A bootstrap credential for first enrollment.
The bootstrap credential can be:
- a short-lived token generated by the Deploy Agent workspace
- a trusted out-of-band
ENROLLMENT_SECRETfor controlled automation
After the first successful heartbeat, the server assigns an agent_id. The agent persists that ID and uses its agent_token for future heartbeat, event, metrics WebSocket, and remote-control communication.
macOS Agent Install Flow
Current primary path:
- In the self-hosted console, go to Agents > Deploy Agent.
- Create a macOS invite for Apple Silicon, Intel, or auto architecture.
- Download the OmniSight Agent Installer app from the public site.
- Paste the invite URL into the app.
- The app claims the manifest from the local server.
- The manifest provides the server URL, bootstrap token, agent artifact URL, and CA PEM.
- The agent starts as a macOS LaunchAgent and enrolls automatically.
The legacy .command launcher is retained only as an explicit troubleshooting fallback. It is not the normal customer path.
Linux Agent Install Flow
Linux packages are installed as a root-managed systemd service.
Default layout:
| Item | Path |
|---|---|
| Binary | /opt/omnisight-agent/bin/omnisight-agent |
| Config | /etc/omnisight-agent/agent.yaml |
| CA certificate | /etc/omnisight-agent/ca-cert.pem when provided |
| Service | /etc/systemd/system/omnisight-agent.service |
| Logs | journalctl -u omnisight-agent.service |
Noninteractive install example:
bashsudo env \
OMNISIGHT_AGENT_NONINTERACTIVE=1 \
OMNISIGHT_AGENT_SERVER_URL="https://SERVER_HOST:52443" \
OMNISIGHT_AGENT_ENROLLMENT_SECRET="BOOTSTRAP_TOKEN_OR_ENROLLMENT_SECRET" \
OMNISIGHT_AGENT_CA_CERT_PATH="/path/to/ca-cert.pem" \
OMNISIGHT_AGENT_NAME="linux-agent-01" \
bash ./install.sh
Optional inputs:
| Variable | Purpose |
|---|---|
OMNISIGHT_AGENT_BINARY | Use an explicit agent binary path |
OMNISIGHT_AGENT_CA_CERT_PATH | Trust a local/LAN server CA certificate file |
OMNISIGHT_AGENT_CA_CERT_PEM | Trust an inline PEM certificate |
OMNISIGHT_AGENT_NAME | Friendly name shown in the console |
OMNISIGHT_AGENT_REMOTE_TERMINAL_USER | Non-root local account used for remote terminal sessions |
Uninstall:
bashsudo bash installers/linux/uninstall-agent.sh
Configuration Reference
The agent config is YAML.
Identity and Connection
| Field | Default | Description |
|---|---|---|
agent_id | empty | Assigned by server on first enrollment |
agent_token | generated | Persistent agent authentication token |
agent_name | empty | Friendly display name |
enrollment_secret | empty | Bootstrap credential; prefer CLI/env for one-time enrollment |
server_url | https://localhost:52443 | Self-hosted server URL |
ca_cert | empty | CA PEM path for self-hosted local/LAN TLS |
Timing and Batching
| Field | Default | Description |
|---|---|---|
heartbeat_interval_seconds | 10 | Heartbeat interval |
collector_interval_seconds | same as heartbeat | Collection interval |
entitlement_revoked_probe_interval_seconds | 300 or heartbeat, whichever is larger | Probe interval after revoked/restricted entitlement states |
batch_size | 100 | Max events per request |
Collector
| Field | Default | Description |
|---|---|---|
event_source | collector | Current supported event source |
collector_enabled | true when event source is collector | Enable connection collection |
collector_emit_mode | snapshot in raw config defaults; installers write delta | Snapshot sends active connections each cycle; delta sends new/lifecycle changes |
collector_debug | false | Verbose collector logging |
Noise Filtering
Filters are enabled by default unless explicitly disabled.
| Field | Default |
|---|---|
collector_filter_enabled | true |
collector_filter_drop_loopback | true |
collector_filter_drop_private_inbound_listeners | true |
collector_filter_drop_private_remote | true |
collector_filter_drop_agent_self_traffic | true |
collector_filter_drop_empty_remote_for_tcp_listener | true |
collector_filter_drop_process_names | [] |
collector_filter_drop_ports | [] |
State Tracking
| Field | Default |
|---|---|
collector_state_enabled | true |
collector_emit_seen_events | false |
collector_seen_emit_interval_seconds | 60 |
collector_close_timeout_seconds | 30 |
collector_state_ttl_seconds | 300 |
collector_state_max_entries | 10000 |
DNS Enrichment
| Field | Default |
|---|---|
dns_enrichment_enabled | true |
dns_lookup_timeout_ms | 300 |
dns_cache_ttl_seconds | 300 |
dns_cache_max_entries | 1000 |
dns_skip_private_ips | true |
Software Inventory
| Field | Default | Description |
|---|---|---|
inventory_enabled | true | Enables periodic software inventory collection |
inventory_interval_seconds | 3600 | Inventory collection interval |
Inventory entries include package/application name, version, vendor when available, source, platform, architecture, and install path when available. They are used for CVE matching; binaries and file contents are not uploaded.
System Metrics
| Field | Default | Description |
|---|---|---|
system_metrics_enabled | true | Enables aggregate host metrics on heartbeat |
system_metrics_ws_enabled | true | Enables the dedicated metrics WebSocket when the server supports it |
System metrics are collected by a shared sampler and sent through /api/ingest/metrics/ws when available. The same latest sample continues to be included in heartbeat as compatibility and fallback. If collection fails, the agent omits the object and heartbeat still succeeds. The server stores the latest metrics snapshot only.
The server can send runtime config frames over the metrics WebSocket to change the metric interval or start a time-limited diagnostic interval. The agent acknowledges the applied interval, skips overlapping collections, and falls back to normal heartbeat delivery if the WebSocket disconnects. Event batches remain REST-based.
Protocol Metadata (DNS, Linux)
| Field | Default | Description |
|---|---|---|
protocol_meta_dns_enabled | false | Enables Linux DNS query metadata collection; the server-pushed per-agent setting is authoritative |
protocol_meta_dns_snaplen | 512 | Bounded capture length for DNS parsing |
DNS protocol metadata is a Linux-only, default-off capability controlled from the Agent Detail page by administrators. The enable state is pushed to the agent over the metrics WebSocket config channel and acknowledged like metric-interval changes.
When enabled, the agent parses bounded DNS traffic in memory and emits dns_query events with query name, query type, response code, and answer count. Repeated identical queries are coalesced to bound event volume. Raw packet bytes are discarded immediately after parsing and are never stored, logged, or transmitted. The setting is inert on macOS and Windows agents.
Platform support:
- macOS: CPU, memory, disk, network byte counters/throughput, boot identity; temperature is usually unavailable without privileged SMC access.
- Linux: CPU, memory, disk, network byte counters/throughput, boot identity, and best-effort thermal sensor values.
- Windows: CPU, memory, disk, network byte counters/throughput, and boot identity; temperature is unavailable in the current native collector.
Remote Access
| Field | Default | Description |
|---|---|---|
remote_access_enabled | installer/server controlled | Enables the remote-control websocket loop |
remote_terminal_enabled | true when remote access is enabled unless explicitly set | Advertises terminal support |
remote_terminal_user | empty | Non-root account to run terminal sessions as when the service runs as root |
remote_desktop_enabled | false | Remote desktop/RDP is Phase 2 |
remote_control_policy | approval_required | Requires approval before interactive sessions |
remote_control_reconnect_seconds | 5 | Websocket reconnect delay |
Remote terminal safety rules:
- Linux services commonly run as root.
- A root-running Linux agent refuses to open a root shell by default.
- Set
remote_terminal_userto a non-root local account such asege. remote_terminal_user: "root"is rejected.- If the process is not root, user switching is not allowed.
Event Types
| Event type | Meaning |
|---|---|
connection_open | Connection first observed |
connection_seen | Active connection re-emitted when seen events are enabled |
connection_close | Tracked connection disappeared after timeout |
dns_query | DNS activity when available on the platform; includes query type, response code, and answer count on Linux agents with Protocol Metadata enabled |
web_http_connection | Endpoint connection to an HTTP destination, normally remote TCP port 80 |
web_https_connection | Endpoint connection to an HTTPS/QUIC destination, normally remote TCP/UDP port 443 |
Web connection events are metadata classifications. The agent does not capture HTTP methods, URLs, headers, cookies, request bodies, response bodies, or decrypted TLS content.
TLS Handling
Agents use HTTPS and validate certificates.
For local/LAN self-hosted certificates, pass the server CA through:
- the macOS invite manifest
OMNISIGHT_AGENT_CA_CERT_PATHOMNISIGHT_AGENT_CA_CERT_PEM- the
ca_certYAML field
Do not use curl -k or agent insecure TLS bypass as normal customer guidance. Those paths are development/support only.
Service Commands
Linux:
bashsudo systemctl status omnisight-agent.service
sudo journalctl -u omnisight-agent.service -f
sudo systemctl restart omnisight-agent.service
macOS LaunchAgent paths are managed by the Agent Installer app. Manual plist editing should be treated as support work, not the primary install path.