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	Azure Artifact Signing (formerly Trusted Signing)
Breeze Viewer	macOS	.app, .dmg	Apple Developer ID + notarization
Breeze Helper	Windows	.exe	Azure Artifact Signing (formerly Trusted Signing)
Breeze Helper	macOS	.app	Apple Developer ID + notarization

---

Windows Code Signing

The Windows Viewer and Helper installers are signed using Azure Artifact Signing (formerly Azure Trusted Signing). The signing happens in the GitHub Actions release workflow.

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 signs each binary with the azure/artifact-signing-action, authenticating via an OIDC federated credential (no stored client secret).

2. Each binary is signed and RFC 3161-timestamped against the Azure Artifact Signing endpoint; the certificates are short-lived and HSM-backed — the private key never exists outside Azure.

3. The workflow verifies every signature with Get-AuthenticodeSignature before upload (tolerating UnknownError, which means “signed, root not yet cached locally”).

4. 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.

Note

Azure Artifact Signing keys are HSM-backed and never exportable, meeting the CA/Browser Forum hardware requirements for publicly trusted code signing. Certificates are short-lived and rotated automatically — there is nothing to renew.

---

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. SmartScreen reputation is built over time. Newly signed binaries from a new publisher may still show a warning until enough users have downloaded and run the binary. Azure Artifact Signing certificates build reputation faster than traditional OV certificates because Microsoft attests the identity validation. 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.