Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

WhatYouShip

Know what you ship. Know what you install.

WhatYouShip is an open-source release artifact linter. It analyzes the software package that users actually receive — not the source tree or build configuration.

It can inspect, lint, and compare directory, DMG, MSI, NSIS installer, Inno Setup installer, and ZIP releases.

Quick start

Inspect a release:

whatyouship inspect release.msi

Lint it:

whatyouship lint release.msi

Compare two releases:

whatyouship compare previous.msi release.msi

Use the previous release as a baseline so that existing findings do not hide new regressions:

whatyouship lint release.msi --baseline previous.msi

Save a report:

whatyouship lint release.msi --baseline previous.msi -o lint.json

Use WhatYouShip as a CI release gate:

whatyouship lint release.msi --baseline previous.msi --fail-on error

For available commands and options:

whatyouship --help
whatyouship inspect --help
whatyouship lint --help
whatyouship compare --help
whatyouship cache --help

What it looks for

WhatYouShip analyzes the final release rather than assumptions made by the build system.

Current checks and comparisons include:

  • suspicious build artifacts accidentally included in a release;
  • unsigned executables and libraries;
  • untrusted signers and invalid artifact signatures where platform verification is available;
  • inconsistent MSI installation scope;
  • DMG releases without an embedded software license agreement;
  • unsigned, untrusted, or invalid DMG container signatures;
  • malformed macOS application bundles;
  • missing required Mach-O libraries expected inside an application bundle;
  • release Mach-O binaries with debugger attachment enabled;
  • added, removed, and changed files between releases;
  • binary architecture changes;
  • executable/library kind changes;
  • file and product version changes;
  • signature and signer changes between releases.

For recognized PE binaries, WhatYouShip extracts architecture, binary kind, version metadata, and signature information. For thin and universal Mach-O binaries, it reports all target architectures, the binary kind, and whether every architecture slice has an ad hoc or certificate signature. It also reads the macOS deployment target, dynamic library dependencies, and runtime search paths from Mach-O load commands. Embedded signatures also expose the Hardened Runtime flag and XML entitlements. lint treats an enabled com.apple.security.get-task-allow entitlement as an error. Cryptographic validity of Mach-O signatures is not currently checked.

For macOS application bundles in directories, ZIP archives, and DMG images, WhatYouShip reads XML and binary Contents/Info.plist files without using macOS APIs. inspect reports the bundle identifier, name, versions, main executable, minimum system version, and package type. lint checks required metadata, the main executable, and consistency between LSMinimumSystemVersion and the executable deployment target, while compare reports bundle and binary metadata changes. Bundle validation resolves @executable_path, @loader_path, and @rpath references and reports required libraries that should be present inside the application bundle but are missing.

Commands

inspect

Shows what is actually present in a release artifact.

whatyouship inspect release.zip

For recognized binaries, the report includes metadata such as architecture, executable or library kind, versions, and signature information.

lint

Runs release rules and reports findings.

whatyouship lint release.msi

A product-specific TOML configuration can change rule settings. Download or adapt examples/whatyouship.toml, then pass its local path:

whatyouship lint release.msi --config whatyouship.toml

Baseline linting

A previous release can be used as the baseline:

whatyouship lint release.msi --baseline previous.msi

Findings are classified as:

  • new — present only in the new release;
  • existing — present in both releases;
  • resolved — present only in the baseline.

This makes it possible to concentrate on regressions without losing track of known issues.

compare

Compares the actual contents of two releases:

whatyouship compare previous.msi release.msi

In addition to added, removed, changed, and unchanged files, WhatYouShip reports semantic binary and application bundle changes such as version, architecture, signature, bundle identifier, and minimum system version changes.

cache

Shows or removes persistent artifact cache data:

whatyouship cache info
whatyouship cache clear --format zip

See Cache for persistent cache behavior and removal options.

Supported artifacts

Artifact Inspect Lint Compare
Directory Yes Yes Yes
DMG Yes Yes Yes
MSI Yes Yes Yes
NSIS EXE Yes Yes Yes
Inno Setup EXE Yes Yes Yes
ZIP Yes Yes Yes

MSI extraction and static MSI analysis are platform-independent.

On Windows, the signature of the MSI package itself is verified using the system Authenticode API. Signature status distinguishes unsigned, valid and trusted, signed but untrusted, and cryptographically invalid artifacts. Package signature verification is currently unsupported on Linux and macOS.

ZIP releases use the same file and binary analysis as ordinary directories.

On macOS, DMG releases use the system hdiutil command. WhatYouShip mounts a single-volume image read-only at a private mount point, analyzes its regular files and symbolic links, and detaches it after inspection. It also reports whether the original image embeds a software license agreement; its absence is an error by default. An image with an agreement is converted to a normalized DMG without accepting the agreement on the user's behalf, then mounted read-only. The normalized image is temporary by default and is stored persistently only with --cache.

On Linux and Windows, DMG releases require 7z or 7zz from 7-Zip in PATH. WhatYouShip supports single-volume images whose HFS or APFS filesystem is recognized by 7-Zip and analyzes the extracted regular files. Embedded software license agreement metadata is unavailable through this backend, so lint does not report the agreement as present or absent. Encrypted and multi-volume images are not supported. Symbolic links are reported with their stored targets and whether they point outside the artifact, without being materialized or followed. Extended attributes, alternate streams, and resource forks are not represented.

DMG container signatures are inspected independently from their files on every platform. WhatYouShip always detects unsigned images, verifies CodeDirectory content and trailer digests, and reports the Team ID and presence of a stapled notarization ticket. If rcodesign is available in PATH, it also verifies the CMS signature and reports the signer and timestamp. A signature with valid digests and CMS cryptography that does not chain to an Apple root is reported as untrusted. Current Gatekeeper policy and online notarization status are not evaluated.

NSIS installers require 7z or 7zz from 7-Zip to be available in PATH. WhatYouShip inspects the extracted payload; extracted paths are not an exact simulation of runtime installation paths. On Windows, the outer installer's Authenticode signature is checked separately from signatures of binaries in its payload.

Inno Setup installers require innoextract to be available in PATH. Their extracted layout is a payload representation, not an exact simulation of runtime installation paths. On Windows, the outer installer's Authenticode signature is checked separately from signatures of binaries in its payload.

MSI installation scope

WhatYouShip statically analyzes MSI installation scope and distinguishes:

  • per-user;
  • per-machine;
  • dual-purpose;
  • ambiguous.

The inconsistent-installation-scope rule reports concrete conflicts between the declared installation context and component resources.

WhatYouShip also reports installation-scope changes when comparing MSI releases.

Because this is static analysis, runtime conditions and installer choices cannot always be resolved in advance.

Reports

Use -o or --output to write a report to a file. The extension selects the format.

whatyouship inspect release.zip -o inspect.json
whatyouship lint release.zip -o lint.csv
whatyouship compare previous.zip release.zip -o compare.txt

Supported formats:

Format Inspect Lint Compare
.txt Yes Yes Yes
.json Yes Yes Yes
.csv Yes Yes No

Without --output, commands print text to stdout.

JSON reports contain structured data and include schema_version, tool_version, and the report type.

CI and exit codes

lint can be used directly as a release gate.

whatyouship lint release.msi --fail-on error

Available thresholds:

--fail-on error
--fail-on warning
--fail-on never

The default is --fail-on error.

Exit codes:

  • 0 — the release passes the selected threshold;
  • 1 — lint findings reach the selected threshold;
  • 2 — WhatYouShip cannot complete the operation because of an input, configuration, or tool error.

With --baseline, only new findings affect the lint exit code.

For example:

whatyouship lint release.msi --baseline previous.msi --fail-on error -o lint.json

Cache

By default, WhatYouShip extracts artifacts into a temporary cache that is removed when the command finishes. Pass --cache to inspect, lint, or compare to reuse and populate the persistent cache between commands.

WhatYouShip keeps persistent user data under:

~/.whatyouship/

Persistently cached artifacts are keyed by SHA-256:

~/.whatyouship/cache/msi/v1/
~/.whatyouship/cache/nsis/v1/
~/.whatyouship/cache/inno/v1/
~/.whatyouship/cache/zip/v1/
~/.whatyouship/cache/dmg/v1/
~/.whatyouship/cache/dmg-7zip/v2/

The persistent cache avoids repeated extraction of the same artifact. Binary metadata and lint analysis are performed again on each run.

Inspect persistent cache usage with:

whatyouship cache info

Cache information includes completed entries, interrupted temporary entries, logical file size, and the cache layouts present for each artifact format.

Clear the complete persistent cache or selected artifact formats with:

whatyouship cache clear --all
whatyouship cache clear --format zip
whatyouship cache clear --format dmg --format msi

The target is mandatory, so cache removal cannot accidentally default to the complete cache. Supported format names are msi, nsis, inno, zip, and dmg. Clearing dmg removes both native and 7-Zip DMG cache layouts.

Do not run cache clear concurrently with inspect, lint, or compare using --cache. Cache removal is not coordinated with active cache readers.

On macOS, DMGs without an embedded agreement are inspected directly from a temporary read-only mount. Images with an agreement are converted to a normalized image that preserves the contained filesystem for inspection. With --cache, that image is stored by the original image's SHA-256 under dmg/v1. On Linux and Windows, --cache stores the regular-file tree and symbolic-link metadata extracted by 7-Zip separately under dmg-7zip/v2.

The cache hash identifies artifact content; it is not a signature or authenticity check.

On Windows, ~ refers to the user's profile directory.

Metadata

Release files for whatyouship 0.1.0b2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for whatyouship 0.1.0b2
File Size Uploaded Provenance Actions
whatyouship-0.1.0b2.tar.gz 69.7 kB Without provenance Details for whatyouship-0.1.0b2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for whatyouship 0.1.0b2
File Interpreter ABI Platform Actions
whatyouship-0.1.0b2-py3-none-any.whl Python 3 none any Details for whatyouship-0.1.0b2-py3-none-any.whl

Total release size: 160.4 kB

Release files / whatyouship-0.1.0b2.tar.gz

Download URL whatyouship-0.1.0b2.tar.gz
Size 69.7 kB
Tags Source
SHA-256 checksum
How to use checksums
78d0df7498019ce4d62eaf2e6a8ca918e9b786e2717d2b0b01459bdd42d043b4
BLAKE2b-256 checksum
How to use checksums
10b2e0538692c02373a044989f37265d820ea66fd0d24d56ed15019ee8d8d73e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / whatyouship-0.1.0b2-py3-none-any.whl

Download URL whatyouship-0.1.0b2-py3-none-any.whl
Size 90.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
01225721f7123fba0ff19d809c4a384aded052bf0d808ef29e0520fb093b4ceb
BLAKE2b-256 checksum
How to use checksums
d0c9d8abd576a8c88c1733dd682433a0dc9813844eb19d2de20a36e119882e11
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for whatyouship 0.1.0b2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page