Category: Software Supply Chain

Package Integrity

Simply put

Package integrity refers to the assurance that a software package has not been tampered with, corrupted, or altered from the version its author originally published. In practice, this typically involves verifying cryptographic hashes or digital signatures associated with the package to confirm that what a developer or system downloads is exactly what was intended to be distributed. Strong package integrity controls help protect against supply chain attacks where malicious code could be injected into otherwise trusted software components.

Formal definition

In the context of application security and software supply chains, package integrity encompasses the set of controls, verification mechanisms, and processes used to ensure that a software artifact (library, module, container image, or other distributable unit) has not been modified between its creation by an authorized publisher and its consumption by a downstream system or developer. Core mechanisms typically include cryptographic hash verification (e.g., SHA-256 digests published alongside artifacts), digital signature validation (e.g., GPG signatures, Sigstore-based attestations), and provenance metadata that links an artifact back to a specific build environment and source commit. Package integrity verification may be performed by package managers at install time, by CI/CD pipelines during build processes, or by policy engines in deployment workflows. Limitations include the fact that integrity checks confirm only that the artifact matches what the registry or publisher attests to; they do not detect malicious code that was present in the original source, nor do they guard against compromised maintainer accounts unless combined with additional controls such as multi-factor authentication or build provenance verification. False negatives can occur when registries do not enforce or provide signature verification by default, allowing tampered packages to pass undetected. False positives are relatively uncommon in hash-based checks but may arise in signature verification scenarios involving expired keys, misconfigured trust roots, or key rotation events.

Why it matters

Package integrity is a foundational control in software supply chain security because modern applications are assembled from dozens or hundreds of third-party dependencies, each representing a potential point of compromise. If an attacker can modify a package between its publication and its consumption, whether by tampering with a registry, performing a man-in-the-middle attack on a download, or compromising a build artifact, they can inject malicious code that propagates silently into every downstream system that installs that package. Without robust integrity verification, organizations have no reliable way to distinguish a legitimate artifact from one that has been subtly altered.

The consequences of weak package integrity controls have been demonstrated in real-world incidents. In the 2020 SolarWinds (Sunburst) attack, adversaries injected malicious code into a legitimate software build process, resulting in trojanized updates distributed to thousands of organizations. While that attack also involved build-system compromise beyond simple artifact tampering, it highlighted how supply chain trust assumptions can be exploited when integrity and provenance controls are insufficient. Attacks targeting package registries directly, such as dependency confusion and typosquatting campaigns, further underscore the need for integrity verification at every stage of artifact consumption.

For organizations subject to regulatory or compliance frameworks, package integrity verification is increasingly expected as a baseline control. Ensuring that every consumed artifact matches the cryptographic digest or signature published by its author is a necessary (though not sufficient) step toward a defensible software supply chain. It is important to recognize, however, that integrity checks alone confirm only that the artifact matches what the publisher attests to. They do not detect malicious code present in the original source, nor do they protect against compromised maintainer accounts unless combined with additional controls such as build provenance verification and multi-factor authentication.

Who it's relevant to

Application Security Engineers

AppSec engineers are responsible for ensuring that the components consumed by development teams have not been tampered with. They typically configure and enforce package integrity checks within CI/CD pipelines, evaluate the integrity mechanisms offered by different package ecosystems, and respond to alerts when verification fails.

Software Developers

Developers consume third-party packages daily and are often the first point where integrity verification either succeeds or is bypassed. Understanding how lockfiles, hash pinning, and signature verification work in their package manager of choice is essential for maintaining a trustworthy dependency chain.

DevOps and Platform Engineers

Teams managing build systems, artifact repositories, and deployment pipelines must ensure that integrity checks are enforced consistently across environments. This includes configuring package managers to fail on hash mismatches, maintaining trusted key stores for signature verification, and integrating provenance checks into deployment gates.

Security Architects and Supply Chain Risk Managers

These practitioners design the policies and control frameworks that govern how software artifacts are sourced, verified, and admitted into an organization's software supply chain. They must understand the scope boundaries of integrity verification, recognizing that it addresses artifact tampering but does not substitute for source code review, vulnerability scanning, or maintainer trust evaluation.

Compliance and GRC Teams

Governance, risk, and compliance professionals need to understand package integrity as a control that may be required or recommended by frameworks addressing software supply chain security. They assess whether the organization's integrity verification practices meet applicable regulatory or contractual requirements.

Inside Package Integrity

Cryptographic Hash Digests

Hash values (typically SHA-256 or SHA-512) computed over the exact bytes of a package artifact. Consumers recalculate the digest after download and compare it to the published value to detect accidental corruption or deliberate modification in transit or at rest. Hash verification alone confirms that the artifact matches a known digest but does not authenticate the identity of whoever produced that digest.

Digital Signatures

Cryptographic signatures created with the private key of the package author or build system, allowing consumers to verify both that the artifact has not been altered and that it was produced by a specific, identifiable party. Signature schemes used in package ecosystems include PGP/GPG signatures (e.g., Linux distribution packages), Sigstore keyless signing (used in some container and npm provenance workflows), and per-ecosystem mechanisms. Verification requires access to trusted public keys or certificate transparency logs.

Provenance Attestations

Metadata statements, typically conforming to frameworks such as SLSA (Supply-chain Levels for Software Artifacts) or in-toto, that record how, where, and by whom a package was built. Provenance attestations link an artifact to a specific source revision, build platform, and build configuration. They complement signatures by providing context about the build process rather than just artifact identity.

Lock Files and Pinned Dependencies

Files generated by package managers (e.g., package-lock.json, Pipfile.lock, go.sum) that record the exact versions and expected hash digests of every resolved dependency. Lock files enable reproducible installations and allow the package manager to reject artifacts whose digests do not match the recorded values, providing a practical integrity check at install time.

Software Bill of Materials (SBOM)

A structured inventory (in formats such as CycloneDX or SPDX) listing the components contained within a software package, including their versions, suppliers, and relationships. While an SBOM does not enforce integrity by itself, it provides a reference baseline that downstream consumers can use to verify that the contents of a delivered artifact match the declared composition.

Registry and Transport Security

Controls at the package registry and network layer that protect integrity during distribution. These include TLS for transport encryption, registry-enforced upload authentication (e.g., multi-factor authentication, OIDC-based trusted publisher workflows), and immutability policies that prevent overwriting a published version. These controls reduce the attack surface but do not replace artifact-level cryptographic verification by the consumer.

Common questions

Answers to the questions practitioners most commonly ask about Package Integrity.

Isn't verifying a checksum or hash sufficient to guarantee that a software package is safe to use?

No. Cryptographic hash verification confirms that the artifact you received matches the artifact that was published, but it says nothing about whether the published artifact itself is trustworthy. If an attacker compromises the build pipeline or the maintainer's account and publishes a malicious package, the hash posted alongside it will match perfectly. Hash verification addresses transport-level tampering and mirror corruption, but it does not substitute for provenance verification, signature validation against a trusted identity, or analysis of the package contents. Practitioners should treat hash checks as a necessary but insufficient layer within a broader integrity strategy.

Does signing a package prove that its contents are free of vulnerabilities or malicious code?

No. A valid cryptographic signature confirms the identity of the signer and that the artifact has not been modified since signing. It does not attest to the quality, safety, or vulnerability status of the code inside the package. A legitimately signed package may still contain known vulnerabilities, inadvertent backdoors, or transitive dependencies with security issues. Signature verification should be combined with vulnerability scanning, software composition analysis, and, where feasible, build provenance attestation to form a more comprehensive integrity assessment.

How should teams implement package hash verification in a CI/CD pipeline?

Teams should pin dependencies to exact versions along with their expected cryptographic hashes in a lock file or requirements file, then configure the package installer to refuse any artifact whose computed hash does not match the recorded value. Tools such as pip's --require-hashes flag, npm's package-lock.json integrity fields, and Go's go.sum file provide built-in mechanisms for this. The lock file itself should be committed to version control and reviewed during code review so that any hash change is visible and auditable. Where possible, artifacts should be fetched through an internal registry or proxy that independently verifies hashes against a known-good source before caching.

What role does build provenance attestation play in package integrity, and how does it differ from signing?

Build provenance attestation provides a verifiable record of how, where, and from what source code a package artifact was produced. Frameworks such as SLSA define provenance levels that capture details including the build platform, the source repository commit, and whether the build was hermetic. While signing answers 'who vouched for this artifact,' provenance attestation answers 'what process produced it and from what inputs.' The two are complementary: a signature without provenance may come from a compromised developer workstation, and provenance without a signature could be forged. Combining both gives consumers stronger, though still not absolute, assurance about an artifact's origin.

How can organizations verify integrity for packages sourced from public registries that do not yet support signature verification or provenance?

Organizations can adopt several compensating controls. First, they can mirror or proxy public registries internally and perform hash verification at ingestion time. Second, they can maintain an allowlist of approved packages and versions, restricting what developers may consume. Third, software composition analysis tools can be integrated into CI/CD to flag unexpected changes in package metadata, unexpected new dependencies, or known-malicious packages. Fourth, teams can compare artifacts across multiple independent mirrors to detect tampering on a single source. These measures reduce risk but do not fully replicate the assurance that cryptographic signatures and verified provenance provide, so organizations should advocate for and adopt registry-level integrity features as they become available.

Where does an SBOM fit within a package integrity strategy, and what are its limitations?

A Software Bill of Materials (SBOM) enumerates the components, versions, and typically the supplier information for the software in a given artifact or product. Within an integrity strategy, the SBOM serves as a reference manifest: teams can compare the actual contents of a deployed artifact against its declared SBOM to detect undeclared components or version discrepancies. However, an SBOM is a declarative document and is only as trustworthy as the process that generated it. If the build pipeline is compromised, the SBOM may accurately list malicious components without flagging them as illegitimate. An SBOM also does not, by itself, verify that artifacts have not been tampered with in transit. For these reasons, SBOMs are most effective when they are cryptographically signed, tied to build provenance attestations, and used alongside hash verification and signature validation rather than treated as a standalone integrity control.

Common misconceptions

Downloading a package over HTTPS guarantees its integrity.

HTTPS protects against modification in transit between the registry and the consumer, but it does not protect against a compromised registry, a compromised maintainer account, or a malicious package that was legitimately uploaded. Artifact-level verification using cryptographic hash digests and digital signatures is necessary to detect tampering that occurs before the package enters the transport channel.

If the hash matches, the package is safe to use.

Hash verification confirms that the artifact you received is identical to the artifact whose digest was published, but it says nothing about whether that artifact itself is trustworthy. A malicious maintainer or a compromised build system can produce a package that is internally harmful yet has a perfectly valid hash. Integrity (the artifact has not been altered) is distinct from trustworthiness (the artifact is free of malicious or vulnerable code), and both require separate controls.

Package registries automatically sign every uploaded package on the server side.

Most major package registries do not add a server-side cryptographic signature to uploaded artifacts. Some ecosystems support provenance attestations (for example, npm packages built via GitHub Actions can carry Sigstore-based provenance), but this is opt-in and ecosystem-specific. Other registries, such as PyPI, offer OIDC-based trusted publisher authentication for uploads but do not countersign the artifact itself. Practitioners should verify what integrity evidence their specific registry actually provides rather than assuming universal server-side signing.

Best practices

Always verify cryptographic hash digests of downloaded packages against a trusted, independently obtained reference value, and use lock files with pinned hashes so that your package manager performs this check automatically on every install.

Where the ecosystem supports it, verify digital signatures or provenance attestations on packages before incorporating them into builds. Establish a policy for which signing identities or provenance predicates your organization considers acceptable.

Enforce multi-factor authentication and, where available, OIDC-based trusted publisher mechanisms on all accounts that publish packages to public or internal registries, reducing the risk that a compromised credential leads to tampered uploads.

Integrate a dependency verification step into your CI/CD pipeline that compares resolved dependency hashes and versions against the committed lock file, failing the build if any discrepancy is detected.

Generate and distribute SBOMs alongside released artifacts so that downstream consumers have a declared baseline to audit the composition of the package and detect unexpected component additions or substitutions.

Monitor for known supply chain attack patterns, such as dependency confusion and typosquatting, by configuring package managers to use scoped or namespaced registries, restricting resolution to approved internal sources where feasible, and auditing new or changed transitive dependencies before they enter production builds.