Integrator
Most integrations connect to services the CyberOptix CTEM Platform can reach directly over the internet. The Integrator exists for the ones it cannot: firewalls, switches and routers, load balancers, IPAM, private cloud controllers and container platforms that have no public endpoint.
It runs inside your network, connects outbound to the platform, and collects inventory, topology, NAT and security rules, and configuration from the devices you assign to it. As with every edge component, no inbound connections are required.
Before you start
- Ubuntu Server 24.04, with root or sudo access.
- Outbound HTTPS to your platform's API hostname, and to
docker.ioso the spool container can be pulled. - Network access from this host to each device it will collect from: HTTPS for API-managed devices, SSH for CLI-managed ones.
- Your organization ID from the platform, and the Platform Integrations add-on.
Give the Integrator a read-only account on every device. It never changes device configuration. Device credentials are stored in the platform's vault and sent to the Integrator only for the task that needs them; the Integrator never writes them to disk.
Install
Add the repository. The rm -f first keeps the step re-runnable - gpg --dearmor
prompts before overwriting an existing keyring, and on a re-run nothing is attached to
answer that prompt:
sudo rm -f /usr/share/keyrings/purpleteamsoftware-archive-keyring.gpg
wget -O - https://apt.fury.io/purpleteamsoftware/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/purpleteamsoftware-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/purpleteamsoftware-archive-keyring.gpg] https://apt.purpleteamsoftware.com/ /" | sudo tee /etc/apt/sources.list.d/purpleteamsoftware.list
sudo apt update && sudo apt install cyberoptix.integrator -y
Installation pulls in Docker and brings up the stack defined in
/etc/optix/docker-compose-integrator.yml. As with every edge system, nothing runs on
the host beyond the service itself: the result spool (redis) is a container bound to
loopback. The spool holds results until the platform has acknowledged them, so nothing
collected is lost if the platform is briefly unreachable.
The daemon runs as the unprivileged optix user. It only talks to the spool over
loopback and starts no containers itself, so it is not a member of the docker
group.
Link it to your organization
sudo integrator link --url https://<your-api-hostname>/ --organization_id <your-organization-id>
Your API hostname is specific to your deployment - take it from the platform rather than assuming a pattern, because it differs between brands.
Start the service
sudo systemctl enable --now integrator-daemon.service
One service does everything: it checks in with the platform every 30 seconds, runs the tasks assigned to it, and reports the results back.
Verify
systemctl status --no-pager integrator-daemon docker
docker compose -f /etc/optix/docker-compose-integrator.yml ps
integrator-daemon and docker should both be active (running), and the compose
stack should list redis as up.
It should be active (running).
sudo journalctl -u integrator-daemon.service -f
Then confirm the Integrator appears in the platform under Integrations, and assign it to the device integrations it should collect from.
Device trust
The Integrator verifies every device it connects to:
- HTTPS devices must present a certificate that chains to a trusted authority, or one whose fingerprint is pinned on the integration. Appliances with self-signed certificates are pinned on first connection from the platform.
- SSH devices are trusted on first connection, and their host key is pinned from then on. If a device's key changes, collection stops until someone confirms the change in the platform: a replaced device and an intercepted connection look the same.
- Only modern SSH algorithms are offered unless the integration is set to allow the legacy ones older devices need.
Next
- Integrations - connecting an integration once the Integrator is up
- Troubleshooting - general edge-system diagnosis
- Host hardening - what the package changes on the host, and why the Integrator wants its own