Vulnerability Disclosure and Security Updates

How to report a security issue in Circuit Breaker, what happens next, and which versions receive security fixes.

The canonical machine-readable copy is SECURITY.md in the repository root — that is the file GitHub surfaces on the Security tab. This page is the same policy, published where operators read documentation, with the operational detail that does not belong in a root file.

Reporting a vulnerability

Report privately through GitHub Security Advisories:

Report a vulnerability →

Please do not open a public issue for a security report. A public issue is a disclosure, and it starts a race between the fix and everyone who reads it.

What to include

The more of this you can supply, the faster the assessment:

Item How to get it
Affected version cb version
Deployment mode Native or mono — the two that ship. See deployment modes
Install method Quick install, Proxmox LXC, Docker Compose, single Docker container, or from source
Reproduction steps Ideally the smallest sequence that shows the issue
Impact What an attacker gains, and from what starting position
Whether authentication is required Reachable anonymously, or only as a signed-in user of some role

Redact secrets from anything you attach. cb doctor output prints connection targets and environment-derived paths; application logs are redacted by a global filter but your own reproduction notes are not.

What to expect

Stage Target
Acknowledgement 3 business days
Initial assessment 10 business days
Fix or mitigation plan for a confirmed high-impact issue 30 days

This is a self-hosted project maintained by a small team. Those are targets we aim for, not a contractual SLA. Reporters are credited in the release notes unless they ask not to be.

Scope

In scope

  • The server: API, workers and the bundled web UI.
  • cb-agent, its enrollment and its wire protocol.
  • The installers and packaging.
  • The published container images.

Out of scope

Not accepted Why
Findings that require an already-compromised host or database Root on the host owns the vault key by definition. The threat model states this as an assumption, not an oversight.
Denial of service by resource exhaustion on a deployment the reporter controls Self-hosted software will always exhaust if you ask it to.
Missing hardening headers with no demonstrated impact The headers actually set are listed in Deployment & Security; a report needs an exploit path, not a scanner row.
Exposing the deployment directly to the internet Unsupported for 1.0.0. A finding that depends on it is a finding about an unsupported configuration.
A deployment mode the support contract lists as unsupported Same reasoning: an unsupported mode is out of scope for a fix, not merely undocumented.

The threat model is the honest starting point for a report. Its residual risk register lists what we already know is not closed — a report naming one of those rows tells us nothing new, but a report showing that a listed residual is worse than stated is very much wanted.

Security update policy

Supported versions

Version Security fixes
1.0.x, including release candidates Yes
Anything below 1.0 No — upgrade to the 1.0 line

Security fixes land on the current 1.0 line only. There is no backport branch for 0.x.

The full support boundary — platforms, architectures, deployment modes, browsers — is the 1.0.0 support contract. A mode listed there as unsupported is also out of scope for a security fix.

How a fix reaches you

  1. The fix lands on the 1.0 line and a release is published.
  2. Release notes name the issue and credit the reporter.
  3. Your instance's daily release check shows an administrator a banner — unless you turned it off, which is a supported choice. If you did, watch the releases page yourself.
  4. Upgrade with the procedure for your install mode: Upgrading.

Nothing is downloaded or installed automatically. The release check compares versions and shows a banner; it never applies anything.

Emergency removals

The compatibility policy's deprecation stages normally require a deprecated behaviour to survive at least one minor release after announcement. That window has one exception: the security owner may approve immediate removal when continued support creates unacceptable risk. When that happens, the release notes name the break explicitly.

CB_API_TOKEN is the current example of the ordinary path — it is rejected at runtime, logs a removal warning at startup, and CB_LEGACY_AUTH exists only as a temporary rollback.

Verifying what you install

Every release ships:

  • SBOMs in CycloneDX and SPDX, generated with syft.
  • A SHA256SUMS file.
  • A cosign keyless signature on the container image, with its SBOM attached to the image.

GPG detached signatures — over the artifacts and over SHA256SUMS — are produced only when the release workflow has a signing key available. A release published without one carries checksums and cosign signatures but no .asc files, and its SHA256SUMS does not cover the SBOM files. Check for the .asc files on the release before relying on a GPG signature.

Step-by-step verification: Security verification checklist.