Report format · ShellGraph

The report that the collector sends to the server after a scan. The collector and the server follow this page.

The collector and the server each have a copy of the report types. If you change the format, change this page and the example first.

Transport

Method and path: POST /api/collector/vlans/{id}/reports
Headers: Authorization: Bearer <collector token>, Content-Type: application/json, Content-Encoding: gzip
Body: one JSON object, compressed with gzip.
Maximum size after decompression: 64 MiB.

Versions

`schema_version`	Status
1	Current

The server rejects a report with a schema version that it does not know. The error message tells which program to upgrade.

Top-level object

Field	Type	Description
`schema_version`	integer	Format version. Current value: `1`.
`collector_version`	string	Version of the collector that made the report.
`vlan_id`	integer	ID of the VLAN on the server.
`cidr`	string	CIDR that the collector scanned. The server rejects the report if this is not the current CIDR of the VLAN.
`started_at`	string	Start time of the scan, RFC 3339, UTC.
`finished_at`	string	End time of the scan, RFC 3339, UTC.
`results`	array of Result	One item for each IP that the collector scanned.

The report always contains the complete VLAN. The collector does not send a report for a scan that stopped before the end.

Result

Field	Type	Description
`ip`	string	IP address that the collector scanned.
`status`	string	One of the values in the table below.
`message`	string	Error text. Only for `auth_failed`, `hostkey_changed` and `error`. Optional.
`hostkey_fp`	string	SHA-256 fingerprint of the SSH host key (`SHA256:...`). Present when the SSH handshake started. Optional.
`host`	Host	Collected data. Only for `ok` and `partial`.

Status	Meaning	Server action
`no_ssh`	No answer on the SSH port.	The host leaves this VLAN. A host with no VLAN left is deleted.
`auth_failed`	The SSH server refused the credential.	The host keeps its data and becomes `stale`.
`hostkey_changed`	The host key is not the key that the server knows.	The host keeps its data and becomes `stale`.
`error`	Other failure (timeout, script error).	The host keeps its data and becomes `stale`.
`ok`	Complete collection.	The server replaces the data of the host.
`partial`	Collection without `sudo`. Some sockets have no process.	The server replaces the data of the host and marks it `partial`.

Host

Field	Type	Description
`machine_id`	string	Content of `/etc/machine-id`. Can be empty.
`hostname`	string	Output of `hostname -f`.
`os`	string	`PRETTY_NAME` from `/etc/os-release`. Can be empty.
`addresses`	array of Address	All IP addresses of the host, and the IP addresses of its containers.
`services`	array of Service	Services that the collector found.

The server finds a known host with the pair (machine_id, hostname).

Address

Field	Type	Description
`ip`	string	IP address, without prefix length.
`interface`	string	Interface name. For a container address: `container:<name>`.
`scope`	string	`global`: a routable address of the host. `local`: loopback or a bridge interface (`docker0`, `br-`, `cni`, `virbr`, `podman`, `veth*`). `container`: an address of a container network namespace.

Only global addresses identify a host for other hosts. The same local or container address can exist on many hosts.

Service

Field	Type	Description
`key`	string	Stable key of the service in the host. See the formats below.
`name`	string	Name to show.
`kind`	string	`systemd`, `process`, `container` or `unknown`.
`listens`	array of Listen	Ports where the service listens.
`observations`	array of Observation	Connections of the service.

Key formats:

Kind	Key	Name
`container`	`container:<container name>`	container name
`systemd`	`unit:<unit name>`	unit name
`process`	`proc:<comm>:<hash>`	`comm`
`unknown`	`port:<port>` for a listen without a process, `unknown` for other sockets	`unknown:<port>` or `unknown`

<hash> is the first 8 hexadecimal characters of the SHA-256 of the process command line, after the collector removes all digits. The command line itself is never in the report, because it can contain passwords.

Listen

Field	Type	Description
`proto`	string	`tcp`.
`ip`	string	Bind address. `0.0.0.0` or `::` for all addresses. For a container, the container address.
`port`	integer	Port.

A container port that is published on the host has one more Listen with the host bind address and the host port.

Observation

Field	Type	Description
`direction`	string	`outbound`: the service calls the remote side. `inbound`: the remote side calls the service.
`local_ip`	string	Local address.
`local_port`	integer	Local port for `inbound`. `0` for `outbound` (the ephemeral port is removed).
`remote_ip`	string	Remote address.
`remote_port`	integer	Remote port for `outbound`. `0` for `inbound`.
`samples`	integer	Number of samples in the scan that found this connection.
`target_service`	string	Only for `outbound` to the same host: the `key` of the service that listens. Optional.

The collector does not report:

inbound connections from an address of the same host. The outbound side gives the same information.
Connections between two processes of the same service.
The SSH session of the collector.

Example

Download report-v1.json: a complete report of version 1.