shellgraph

Collector API

The HTTP API that the collector uses. Use it to write a different collector.

Authentication

Each request has the header Authorization: Bearer <collector token>. Create tokens in the UI (Collector tokens).

An error response has a status code that is not 2xx and the body {"error": "<message>"}.

Endpoints

GET /api/collector/whoami

Tests the token.

{"name": "jump-host-01"}

GET /api/collector/environments

[{"id": 1, "name": "Production"}]

GET /api/collector/environments/{id}/vlans

[{"id": 3, "name": "app-10", "cidr": "10.0.10.0/24"}]

GET /api/collector/vlans/{id}/config

The configuration of the VLAN. The response contains the decrypted private key. The server logs each request.

{
  "id": 3,
  "environment_id": 1,
  "name": "app-10",
  "cidr": "10.0.10.0/24",
  "ssh_port": 22,
  "excluded_ips": ["10.0.10.1"],
  "username": "shellgraph",
  "private_key": "-----BEGIN OPENSSH PRIVATE KEY-----\n...",
  "passphrase": "",
  "use_sudo": true,
  "known_host_keys": {"10.0.10.12": "SHA256:..."}
}

known_host_keys has the stored host key fingerprints of the addresses in the CIDR. A collector must not collect a host when its fingerprint is different. The result status is then hostkey_changed.

POST /api/collector/vlans/{id}/reports

Sends the report of a complete scan. See Report format.

Headers: Content-Type: application/json, Content-Encoding: gzip (optional).

{"scan_id": 7, "map_url": "https://shellgraph.example.net/environments/1/map"}

The server rejects the report with status 400 when:

  • The schema version is not known.
  • The vlan_id in the report is not the id in the path.
  • The CIDR in the report is not the current CIDR of the VLAN.
  • The report is larger than 64 MiB after decompression.