Code Signing

All Breeze release binaries — the agent, the native viewer, and the Helper tray app — are code-signed to establish authenticity and prevent tampering warnings from operating system gatekeepers and endpoint security tools.

---

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 signs the following artifacts:

Artifact	Platform	Format	Signing Method
Breeze Agent	Windows	.exe, .msi	Azure Artifact Signing (formerly Trusted Signing)
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

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

How it works

1. The release workflow rebuilds the resource-stamped Windows binaries (agent, backup, watchdog, user-helper) and signs each 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 MSI installer is built from the signed binaries with the WiX CLI, then signed as a separate step.

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

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

WiX MSI Packaging

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 signed agent binary, configures the Windows service, and sets appropriate file permissions. The MSI itself is then signed as a separate step.

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"

# Expected: Status = Valid, SignerCertificate shows LanternOps

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.