Skip to main content

Supply-chain trust: verified binaries

A core promise of AtherOps is that a tampered or corrupt collector binary is never executed on your host. This is enforced by a signed version manifest and a SHA-256 check that happens before anything runs.

The manifest is the source of truth​

The version manifest lists, per tool and per os/arch, the download URL and the expected SHA-256. Both the installer and the running agent consume the same manifest.

Verify before execute​

Whenever a binary is downloaded (at install time or during a remote upgrade):

  1. The artifact is downloaded to a temporary file (never the final path).
  2. Its SHA-256 is computed and compared to the manifest value.
  3. On a mismatch, the file is deleted and nothing is installed, extracted, or run. The installer exits with code 2; the agent keeps running its current, already-verified collector.
  4. Only a binary that passed the check is made runnable.

You see this on a clean install:

[atherops] Verifying sha256…
[atherops] OK  sha256 matches             otelcol-contrib-linux_amd64

And on a mismatch (installer):

[atherops] ERROR  sha256 MISMATCH — otelcol-contrib-linux_amd64
          expected : e3b0c44298fc1c149afb...
          got      : 9f86d081884c7d659a2f...

  INSTALL ABORTED. The downloaded file does not match the manifest checksum.
  The file has been removed. No binary was installed and no service was started.

During a remote upgrade the agent logs instead:

level=error msg="collector upgrade aborted: sha256 mismatch"

Versioned, rollback-friendly layout​

Collector binaries install under a versioned directory with a stable current symlink:

/var/lib/atherops/otelcol/
  0.102.0/otelcol-contrib
  0.103.0/otelcol-contrib
  current -> 0.103.0

You can see exactly which version is on disk, and the symlink is repointed atomically when a new version is activated.

What a mismatch means​

A SHA-256 mismatch is either a corrupt/partial download or a tampering event (MITM / CDN compromise). The safe behavior (abort and run nothing) is the same either way. Retry once; if it persists, treat it as a security incident and contact security@atherops.com. Never run the binary manually.

See also​