Code Signing

Breeze release binaries are code-signed to establish authenticity and prevent tampering warnings from operating system gatekeepers and endpoint security tools — with one deliberate exception: as of v0.105.0, the Windows agent artifacts in the public release are published unsigned, as self-host edition signing inputs, so self-hosters can sign them under their own certificate (see Sign Your Own Agent Packages). All macOS artifacts, and the Windows Viewer and Helper installers, remain signed by Breeze.

---

Why Code Signing Matters

Unsigned binaries trigger security warnings on both Windows and macOS that block installation or execution. For an RMM agent that needs to run silently and with elevated privileges, code signing is essential:

Platform	Without Signing	With Signing
Windows	SmartScreen blocks execution; AV products flag as suspicious; Group Policy may reject unsigned MSIs	Trusted publisher; silent installation works; SmartScreen passes
macOS	Gatekeeper quarantines the binary; users must manually override in System Settings; notarization fails	Gatekeeper passes; notarization succeeds; MDM deployment works

---

Signed Artifacts

The CI/CD release pipeline produces the following artifacts:

Artifact	Platform	Format	Signing Method
Breeze Agent	Windows	.exe, .msi	Unsigned in the public release (self-host edition signing inputs — sign them yourself, see below)
Breeze Agent	macOS	.pkg, binary	Apple Developer ID + notarization
Breeze Viewer	Windows	.exe, .msi	LanternOps Authenticode (Azure Artifact Signing or SSL.com eSigner)
Breeze Viewer	macOS	.app, .dmg	Apple Developer ID + notarization
Breeze Helper	Windows	.exe	LanternOps Authenticode (Azure Artifact Signing or SSL.com eSigner)
Breeze Helper	macOS	.app	Apple Developer ID + notarization

---

Windows Code Signing

The Windows Viewer and Helper installers are Authenticode-signed by LanternOps in the GitHub Actions release workflow. The release operator can use Azure Artifact Signing or SSL.com eSigner; both paths are timestamped and must pass the same publisher verification before an artifact is uploaded.

The Windows agent artifacts (.exe binaries and breeze-agent.msi) are no longer Authenticode-signed by the public pipeline — they are published unsigned as the exact pre-signing build outputs, so a deployment can sign them under its own certificate. An unsigned agent MSI will trip SmartScreen unless you sign it; see Sign Your Own Agent Packages for the supported signing path.

How it works (Viewer and Helper)

1. The release workflow selects exactly one configured Windows signing provider and fails if the provider value is invalid.

2. Azure authenticates with a short-lived OIDC token. SSL.com eSigner authenticates with credentials scoped to the tag’s signing environment. The two providers run in separate jobs, so the SSL.com job never receives Azure’s OIDC permission.

3. The SSL.com path stages its signing toolchain from a checksum-verified archive before any credential is used, rather than letting the signing action fetch it unverified at run time.

4. The selected provider Authenticode-signs and RFC 3161-timestamps the Viewer and Helper installers.

5. Both providers verify through the same script before upload: signature status, signer certificate, RFC 3161 timestamp, certificate validity window, and that the publisher is LanternOps. The SSL.com path additionally requires the exact configured SHA-256 certificate thumbprint; Azure does not pin one, because its certificates are short-lived and rotate automatically.

6. Signed artifacts are uploaded to the GitHub release together with a signed release manifest.

WiX MSI Packaging and Editions

The Windows agent MSI is built with the WiX CLI (v7; the breeze.wxs authoring schema is the v4 namespace — the two version numbers are unrelated). The MSI bundles the agent binary, configures the Windows service, and sets appropriate file permissions.

The MSI carries a per-edition product identity: the public release builds the self-host edition (“Breeze Agent (Self-Hosted)”, with its own UpgradeCode), distinct from the hosted edition used by Breeze’s SaaS. The two editions refuse to install over each other on the same machine — the installer blocks with “A different edition of the Breeze Agent is already installed.” See the MSI product identity appendix for details, and Self-Host Migration for moving a fleet between editions.

Caution

Verify the publisher as LanternOps when installing Viewer or Helper packages. Public Agent packages remain unsigned by design so self-hosters can sign them with their own certificate; see Sign Your Own Agent Packages.

Operators: SSL.com secrets are per-environment

The SSL.com path reads SSLCOM_USERNAME, SSLCOM_PASSWORD, SSLCOM_CREDENTIAL_ID, SSLCOM_TOTP_SECRET, SSLCOM_CERT_SHA256 and SSLCOM_ENVIRONMENT_LABEL. These must be added to the signing-production and signing-prerelease GitHub Environments individually, not to the repository.

SSLCOM_CERT_SHA256 also accepts a comma-separated allowlist. Put the incoming thumbprint alongside the outgoing one ahead of a certificate renewal, then drop the old entry once the changeover is done — otherwise renewal becomes a release-day edit made after the signing steps have already run and consumed eSigner quota.

Only the first four are credentials. SSLCOM_CERT_SHA256 is a public certificate hash and SSLCOM_ENVIRONMENT_LABEL is just the environment’s own name; they are kept as secrets so they sit alongside the credentials they describe.

Nothing in the workflow differs between a stable and a prerelease tag except which environment supplies the credentials, so repository-level secrets would sign prereleases with the production certificate. SSLCOM_ENVIRONMENT_LABEL guards against that: set it to the environment’s own name (signing-production or signing-prerelease) and putting all six at the repository level will fail one of the two environments loudly instead of signing silently.

It is a safety net for the common mistake, not a proof. Scoping only the label per environment while leaving the credentials at repository level would still pass, so place all six deliberately.

---

macOS Code Signing & Notarization

macOS binaries are signed with an Apple Developer ID Application certificate and then submitted to Apple’s notarization service.

How it works

1. The release workflow builds the macOS universal binaries (arm64 + amd64).

2. Each binary is signed with codesign using the Developer ID certificate from the CI keychain.

3. The signed binary is packaged into a .pkg or .app bundle.

4. The package is submitted to Apple’s notarization service via notarytool.

5. The workflow waits for notarization to complete (timeout: 30 minutes).

6. Once notarized, the package is stapled with stapler so it can be verified offline.

Caution

Notarization can take several minutes. The release workflow uses a 30-minute timeout to accommodate Apple’s processing queue. If notarization fails with UnknownError, the workflow retries — this status code sometimes appears transiently with newly provisioned certificates.

Gatekeeper Verification

End users can verify that a downloaded binary passes Gatekeeper:

spctl --assess --verbose /path/to/breeze-agent
# Expected: accepted, source=Notarized Developer ID

---

Signing Your Own Packages (Self-Hosted)

Self-hosted deployments sign the official agent packages with their own certificates — per release, never per download, so SmartScreen and Gatekeeper reputation accrues on a stable hash. See Sign Your Own Agent Packages.

---

Verifying Signatures

Windows

# Check digital signature on a binary
Get-AuthenticodeSignature "C:\Program Files\Breeze\breeze-agent.exe"

# Viewer/Helper installs: Status = Valid, SignerCertificate shows LanternOps.
# Agent installed from the public (unsigned) release: Status = NotSigned — expected.
# Agent installed from your own signing repo: SignerCertificate shows YOUR certificate.

macOS

# Verify code signature
codesign --verify --deep --strict /usr/local/bin/breeze-agent

# Check notarization
spctl --assess --verbose /usr/local/bin/breeze-agent

---

Troubleshooting

Windows SmartScreen still warns after signing. Breeze’s own Viewer and Helper installers moved to an SSL.com OV certificate in v0.107.0. SmartScreen reputation is earned per certificate and does not transfer, so early v0.107.0 downloads may show Windows protected your PC even though the signature is valid and the publisher still reads LanternOps – confirm with Get-AuthenticodeSignature, then choose More info → Run anyway. SmartScreen reputation is built over time. Newly signed binaries using any newly introduced certificate may still show a warning until enough users have downloaded and run the binary. If the warning persists, verify the signature with Get-AuthenticodeSignature to confirm the binary is properly signed. Self-hosters should see Sign Your Own Agent Packages for guidance on establishing their own signing identity.

macOS notarization timeout. Apple’s notarization service can be slow during peak times. The workflow allows up to 30 minutes. If it times out, re-run the release workflow — the binary does not need to be rebuilt, only re-submitted.

“Developer cannot be verified” on macOS. The binary was not notarized, or the stapled ticket is missing. Re-download the binary from the official release page. If installing via MDM, ensure the MDM profile allows the Developer ID. Users can temporarily override Gatekeeper via System Settings → Privacy & Security but this should not be necessary for properly signed releases.

Antivirus flags the agent after signing. Some endpoint security products flag new binaries regardless of signature status. See Antivirus Exceptions for recommended exclusions per platform.