Security & Hardening

electron-builder aims to be secure-by-default across the whole release pipeline — from how updates are verified, to how your app's contents are integrity-checked, to how artifacts are signed and published. This page is a map of those controls; each section links out to the detailed guide rather than repeating it.

v27 tightened several defaults

Several security-relevant defaults changed in v27 — auto-update web installers, update-metadata format, and explicit publishing. If you are upgrading, read this page alongside the v27 Breaking Changes.

Update security (electron-updater)

Signed update manifests (required by default). The latest*.yml update metadata is Ed25519-signed at publish time and verified by electron-updater — before any download — against a public key embedded in the app. Verification fails closed on unsigned or tampered manifests. Publishing a build that emits update metadata fails unless a signing key resolves; updateManifest: false is the only opt-out and warns on every build. Unlike the sha2-only metadata grace period below, this one is enforced in v27. See Signed Update Manifests.
Web-installer payloads are disabled by default. AppUpdater.disableWebInstaller now defaults to true. NSIS web installers (the small installer that downloads its full payload at install time from a manifest-supplied URL) are no longer loaded unless you opt in, because that payload may not undergo signature verification. A web-installer update is rejected with ERR_UPDATER_WEB_INSTALLER_DISABLED — at download (including an update cached by a previous launch), before an install on next launch, and at install time. Installs made by an nsis-web installer built with electron-builder v27+ opt in automatically (via the resources/package-type marker); set autoUpdater.disableWebInstaller = false yourself only for web-installer installs without that marker (built before v27, or with a custom script) or when switching an app from nsis to nsis-web. Cached web updates are re-verified against the freshly fetched manifest, and the nsis-web installer verifies the package electron-updater passes to it against the packages built with it (see Web Installer). Signed update manifests cover the web package's path, SHA-512 and size, so don't set updateManifest: false for nsis-web apps.
Update credentials stay on the feed's origin. The credential headers from requestHeaders / addAuthHeader (headers such as Authorization, the same set that is removed on a cross-origin redirect) and the query string of the feed URL are only sent to the update feed's origin. A download on another origin, including the same host on another port or over http instead of https, is requested without them. See Auto Update.
Linux package signatures. AppUpdater.allowUnverifiedLinuxPackages (default true) preserves historical behavior, since electron-builder does not sign Linux packages itself. Set it to false to enforce GPG signature checks when installing .deb / .rpm auto-updates on package managers that support verification.
Modern, verified update metadata. Generated latest*.yml targets the files[] format and the default electronUpdaterCompatibility is now >=2.16. Update metadata validated only by the legacy SHA-256 sha2 checksum is deprecated.
Windows update signature verification. On Windows, downloaded NSIS updates are Authenticode-verified before they are applied. win.verifyUpdateCodeSignature (default true) embeds your signing publisherName into app-update.yml, and electron-updater checks each downloaded update against the certificate subject. Supply an array of publisherName values when rotating certificates so updates signed by either the old or new certificate still verify. Verification fails closed: an update is rejected when app-update.yml has no publisherName, and a build that would write such an app-update.yml fails; win.verifyUpdateCodeSignature: false is the only opt-out (see the v27 migration guide).

sha2-only metadata is rejected in v28

v27 is a grace period for sha2-only update metadata. In v28, it is rejected. Confirm your updates use modern files[] metadata before upgrading to v28.

Package integrity

Two independent mechanisms protect the code inside your packaged app:

ASAR integrity. When your app is packaged into an app.asar archive (the default), electron-builder embeds integrity hashes so Electron can detect a tampered or swapped archive at runtime. It is on by default; asar.disableIntegrity: true disables it (not recommended). See the ASAR options for the v27 config shape. On macOS the hashes are stored in Info.plist, so with Electron 41 and later electron-builder also embeds a digest of them into the Electron Framework binary, which the code signature covers: with the enableEmbeddedAsarIntegrityValidation fuse (see below), the hashes can't be changed to match a modified archive either. The digest is embedded by default; mac.asarIntegrityDigest: false turns it off.
Electron Fuses. Fuses are "magic bits" flipped at package time — before code signing — that disable risky Electron features for the entire app (e.g. runAsNode, enableNodeCliInspectArguments, enableNodeOptionsEnvironmentVariable). Pairing enableEmbeddedAsarIntegrityValidation with onlyLoadAppFromAsar binds the app to its verified ASAR. Because the bits are flipped before signing, the OS (Gatekeeper / App Locker) is responsible for ensuring they can't be flipped back.

See also: Adding Electron Fuses

Files from the build machine

Only the build configuration is trusted, not the files it packages. Files reached through symlinks must resolve inside the workspace or the package-manager store, copies and the files electron-builder writes stay inside the output directory by real path, and Windows archives and installers refuse a symlink that leaves the app. Intended links can be allowed with fileOptions.allowExternalLinks; writes through a symlink are always refused.

See also: Symbolic links

Code signing & notarization

Signing proves your app's identity and lets the OS confirm it hasn't been tampered with since it was signed. On macOS, notarization is additionally required for Gatekeeper when distributing outside the Mac App Store. electron-builder discovers signing credentials from the environment and signs automatically when they are present.

macOS signing (Developer ID, mac.sign) — macOS Signing
Windows signing — signtool, HSM, PKCS#11, and Azure Trusted Signing via the win.sign discriminated union — Windows Signing
Apple notarization — Notarization

See also: Code Signing overview

Safe publishing

v27 removed implicit --publish. Earlier versions could auto-publish based on the presence of CI tag environment variables, git tags, or npm lifecycle events — which risked accidentally exposing secrets or shipping unfinished releases. v27 never publishes unless you ask it to: pass --publish <always|onTag|onTagOrDraft|never> explicitly in your release scripts, or set the publish option in your configuration.

electron-builder --publish always   # explicit — required in v27

Update feed ownership

When a GitHub or Bitbucket publish configuration omits owner/repo, electron-builder fills them in from the repository info (package.json repository, CI environment variables, then .git/config). The result becomes the publish/update destination and, for auto-update-capable targets, is written to app-update.yml inside the packaged app, so it is the update feed every installed copy keeps using — long after the build machine is gone. A build reports the repository it resolved to and the source it came from (info level for package.json repository, warn level for CI environment variables or .git/config), so read that line and confirm it is correct:

• update feed inferred from repository info; it will be used as the publish/update destination
  (written to app-update.yml in auto-update-capable targets) - specify it explicitly to be sure
  it stays under your control  reason=owner and repo not specified in the publish configuration
  source=.git/config provider=github owner=my-org repo=my-app

That name has to stay yours. GitHub frees an owner or repository name for re-registration as soon as it is renamed, transferred or deleted, and whoever claims it next can publish a release that installed copies of your app will download and run. Set owner and repo explicitly rather than relying on detection, and do not retire the namespace while builds are still in the field.

See also: GitHub repository detection

Toolset integrity

The external build toolsets electron-builder downloads (NSIS, winCodeSign, AppImage, Wine, FPM, …) are checksum-verified after download and cached, so a corrupted or substituted bundle is rejected. When you supply a custom toolset from a remote url, a checksum is required; a local file:// directory is used as-is and needs no checksum.

{
  "build": {
    "toolsets": {
      "nsis": {
        "url": "https://example.com/my-nsis-bundle.tar.gz",
        "checksum": "sha256:abc123…"
      }
    }
  }
}

See also: Toolsets · Custom toolset bundles

Update security (electron-updater)​

Package integrity​

Files from the build machine​

Code signing & notarization​

Safe publishing​

Update feed ownership​

Toolset integrity​