diff --git a/docs/pages/config/contributors.json b/docs/pages/config/contributors.json
index 133c657d..6ab7127f 100644
--- a/docs/pages/config/contributors.json
+++ b/docs/pages/config/contributors.json
@@ -423,7 +423,7 @@
},
"scode2277": {
"slug": "scode2277",
- "name": "scode2277",
+ "name": "Sara Russo",
"avatar": "https://avatars.githubusercontent.com/scode2277",
"github": "https://github.com/scode2277",
"twitter": "https://x.com/emit_sara",
diff --git a/docs/pages/supply-chain/dependency-awareness.mdx b/docs/pages/supply-chain/dependency-awareness.mdx
index 211fbf0b..28a8d35e 100644
--- a/docs/pages/supply-chain/dependency-awareness.mdx
+++ b/docs/pages/supply-chain/dependency-awareness.mdx
@@ -1,9 +1,12 @@
---
title: "Dependency Awareness | Security Alliance"
-description: "Manage external dependencies to prevent vulnerabilities. Use Snyk, Dependabot, MythX, and npm audit to track, update, and monitor libraries for security risks and compliance."
+description: "Manage external dependencies to prevent vulnerabilities. Use version pinning, lockfile verification, vulnerability scanning, and behavioral analysis to secure your project's supply chain."
tags:
- Engineer/Developer
- Security Specialist
+contributors:
+ - role: wrote
+ users: [scode2277]
---
import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } from '../../../components'
@@ -16,46 +19,365 @@ import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } fr
-Dependency awareness is the practice of understanding and managing all the external libraries, frameworks, and
-components that a software project relies on. Dependencies can introduce vulnerabilities and risks, which means it's
-important to keep track of them and ensure they are secure.
+> 🔑 **Key Takeaway:** Every dependency is code you did not write but are fully responsible for. Know exactly what is
+> in your tree, pin versions for anything security-critical, enforce your lockfile in CI, and treat every update as a
+> change that requires review.
-## Importance of Dependency Awareness
+## Fundamentals
-1. **Security Risks**
- - Dependencies can contain vulnerabilities that may be exploited by threat actors.
+### What Is a Dependency?
-2. **Compliance**
- - Ensuring that dependencies comply with licensing and regulatory requirements is essential to avoid legal issues.
+A dependency is any external code your project relies on to build or run. When you add a library to your project, you
+are making a trust decision: you are choosing to run someone else's code as if it were your own, with all the access
+and privileges that implies.
-3. **Maintainability**
- - Understanding dependencies and their impact on the project will help understand if it's possible to update a
- dependency used by your application.
+A modern Web3 project easily accumulates hundreds of dependencies. Most are never reviewed, many are maintained by a
+single developer, and some are actively targeted by attackers. A compromised package propagates to every project that
+depends on it, without any action required from the project owners. For details on specific attacks and how they
+exploited weak dependency practices, see [Supply Chain Threats](/supply-chain/web3-supply-chain-threats).
-## Best Practices for Dependency Awareness
+### Direct and Transitive Dependencies
-1. **Use Dependency Management Tools**
- - Leverage tools that can automatically track and manage dependencies. Examples include:
- - **Web2:**
- - **Snyk:** Monitors and fixes vulnerabilities in dependencies.
- - **Dependabot:** Automatically updates dependencies in GitHub projects.
- - **Solidity:**
- - **Ethlint:** Analyzes and lints Solidity code, including dependencies.
- - **MythX:** Scans for vulnerabilities in smart contract dependencies.
+- **Direct dependencies** are the packages you explicitly add to your project (listed in your `package.json`,
+ `Cargo.toml`, `go.mod`, `requirements.txt`, etc.).
+- **Transitive dependencies** are the dependencies of your dependencies, packages you never chose that get
+ pulled in automatically.
-2. **Regularly Update Dependencies**
- - Regularly update dependencies to the latest secure versions after verifying them.
+In most projects, transitive dependencies vastly outnumber direct ones. A single install command can bring in hundreds of packages you have
+never seen. This matters because:
-3. **Monitor for Vulnerabilities**
- - Continuously monitor dependencies for known vulnerabilities using tools like Snyk, npm audit, and GitHub Security
- Alerts.
+1. **Vulnerabilities propagate silently.** A vulnerability buried deep in your dependency chain still affects your
+ application.
+2. **Attackers target transitive dependencies** precisely because they receive less scrutiny. Compromising a small,
+ deeply nested utility package can affect thousands of downstream projects.
+3. **You are responsible for all of them.** Your users do not care whether a vulnerability was in code you wrote or in
+ a package five levels down your dependency tree.
-4. **Audit Dependencies**
- - Perform regular audits of dependencies to ensure they are necessary and secure. Remove unused or outdated
- dependencies.
+### How Ecosystems Handle Dependency Locking
-5. **Use Trusted Sources**
- - Only use dependencies from trusted and reputable sources. Avoid using unverified or poorly maintained libraries.
+When you declare a dependency like `"my-library": "^1.2.0"`, you are expressing a *range* of acceptable versions, not
+a single one. Without any locking mechanism, every time you or your CI pipeline runs an install command, the package manager
+resolves that range against whatever is currently published and may pick a different version. This means the same
+project can produce different builds on different machines or at different times and if an attacker publishes a
+malicious version within your accepted range, it gets pulled in silently.
+
+**Dependency locking** solves this by recording the exact versions (and often cryptographic checksums) that were
+resolved at a specific point in time. Once locked, every subsequent install reproduces that exact set of dependencies
+rather than re-resolving from scratch. This gives you:
+
+- **Reproducibility:** Every developer and every CI run gets the same dependency tree.
+- **Auditability:** Changes to dependencies show up as diffs in version control, making them reviewable.
+- **Protection against silent substitution:** A newly published malicious version cannot enter your project until
+ someone explicitly updates the lock and that change is reviewed.
+
+Not every language or package manager implements locking the same way. Some use lockfiles, some use checksums or
+vendoring, and some barely address the problem at all. Understanding how your ecosystem works is the first step to
+securing it.
+
+| Ecosystem | Lockfile / Mechanism | What to Know |
+|-----------|---------------------|--------------|
+| **Node.js (npm/pnpm/yarn)** | Three package managers, each with its own lockfile: `package-lock.json` (npm), `pnpm-lock.yaml` (pnpm), `yarn.lock` (yarn v1 and Berry). They are not interchangeable. | Switching package managers means regenerating the lockfile. Pick one and enforce it across the team. See [Lockfile Integrity](#lockfile-integrity) section below for how each one works. |
+| **Rust (Cargo)** | `Cargo.lock` records exact versions and checksums for every dependency. Cargo verifies these checksums automatically against `crates.io` on every build. | For libraries, `Cargo.lock` is often `.gitignore`d because downstream consumers resolve their own versions. For binaries and applications, always commit it. |
+| **Go** | No traditional lockfile. `go.sum` stores cryptographic checksums for every dependency, and the public checksum database (`sum.golang.org`) lets you verify that everyone gets the same code for a given version. The module proxy caches modules so they remain available even if the original source disappears. | Go's approach is verification-first rather than lock-first. `go.mod` declares minimum versions, `go.sum` verifies integrity, and `go mod tidy` is the primary way updates enter the dependency tree. |
+| **Python (pip/Poetry/PDM)** | pip has no built-in lockfile. You either generate a pinned `requirements.txt` with tools like `pip-compile`, or use Poetry (`poetry.lock`) or PDM (`pdm.lock`), which manage their own lockfile formats. | There is no single standard. Multiple competing tools solve this problem differently, and none of them are part of pip itself. Pick one approach for your project and enforce it across the team. |
+| **Java (Maven/Gradle)** | Maven has no lockfile at all and re-resolves versions on every build. Gradle supports lockfiles (`gradle.lockfile`) but requires you to opt in explicitly. Both rely on artifact checksums from the repository for integrity. | The lack of a default lockfile in Maven means two builds of the same project can pull different versions. If you use Maven, consider the [`maven-enforcer-plugin`](https://maven.apache.org/enforcer/maven-enforcer-plugin/) to enforce reproducibility. |
+| **Ruby (Bundler)** | `Gemfile.lock` records exact versions for every gem in the dependency tree. One of the earliest and most mature lockfile implementations across any ecosystem. | Commit it, and use `bundle install --frozen` in CI. |
+| **PHP (Composer)** | `composer.lock` records exact versions for every package. Works the same way as Bundler. | Commit the lockfile, use `composer install --no-update` in CI. |
+| **Solidity (Foundry/Hardhat)** | Foundry pins dependencies to specific git commits via submodules. Each submodule points at an exact SHA, so the version is locked by git itself.
Hardhat uses npm and produces a standard `package-lock.json`. | Mixing both in the same project means managing two entirely different dependency systems. Review submodule updates with the same care as lockfile changes. |
+
+The core principle is the same regardless of ecosystem: **you need a reproducible, verifiable record of exactly what
+code gets pulled into your project**. If your ecosystem provides a lockfile, commit it and enforce it. If it does not,
+look for checksum verification, vendoring, or commit-pinning as alternatives.
+
+## Lockfile Integrity
+
+### Node.js (npm / pnpm / yarn)
+
+The Node.js ecosystem is the most common in Web3 development: frontends, tooling (Hardhat, Foundry's companion
+scripts), and most Web3 libraries (ethers.js, viem, wagmi) all live here. It is also one of the most targeted
+ecosystems for supply chain attacks due to its massive registry, deep dependency trees, and install-time script
+execution.
+
+Each package manager handles installation differently:
+
+- **npm** installs into a flat `node_modules` where all packages can see each other, regardless of which package
+ declared them as a dependency.
+- **pnpm** uses a content-addressable store with symlinks, so packages can only access their declared dependencies.
+ This stricter isolation catches undeclared dependency usage that would silently work under npm.
+- **yarn v1** uses a flat layout like npm. **yarn Berry (v2+)** removes `node_modules` entirely in favor of
+ Plug'n'Play, which maps dependencies directly without a `node_modules` folder.
+
+The lockfile (`pnpm-lock.yaml`, `yarn.lock`, or `package-lock.json`) is what actually determines which versions get
+installed. Without it, the same `package.json` can produce different dependency trees on different machines and at
+different times. An attacker could publish a malicious patch version, and any install without a lockfile would silently
+pick it up.
+
+1. **Always commit your lockfile** to version control.
+2. **Use frozen installs in CI.** This ensures CI installs exactly what is in the lockfile, failing if there is any
+ discrepancy:
+
+ ```bash
+ pnpm install # pnpm uses --frozen-lockfile by default in CI
+ npm ci # npm equivalent of frozen installs
+ yarn install --frozen-lockfile # yarn v1
+ yarn install --immutable # yarn Berry (v2+)
+ ```
+
+ > **Note:** pnpm automatically sets `--frozen-lockfile` to `true` when it detects a CI environment, so you do not
+ > need to pass the flag explicitly. npm and yarn require the explicit flag or command. yarn Berry replaced
+ > `--frozen-lockfile` with `--immutable`.
+3. **Review lockfile changes in PRs.** Treat lockfile modifications with the same scrutiny as source code changes.
+4. **Watch for lockfile-only PRs.** A PR that modifies only the lockfile without a corresponding change to
+ `package.json` is a meaningful signal worth investigating.
+
+### Cross-Ecosystem Reference
+
+The same principles apply beyond Node.js, though the specific commands and mechanisms differ:
+
+- **Rust:** Commit `Cargo.lock` for all binary and application projects. Cargo verifies checksums automatically, but
+ review `Cargo.lock` diffs in PRs the same way you would a Node.js lockfile.
+- **Go:** Commit `go.sum` and run `go mod verify` in CI to confirm that downloaded modules match their recorded
+ checksums. Go's checksum database adds a layer of tamper detection that most ecosystems lack.
+- **Python:** If using Poetry or PDM, commit the lockfile and use `poetry install --no-update` or `pdm install
+ --frozen-lockfile` in CI. If using pip, generate a fully pinned `requirements.txt` (via `pip-compile` or
+ `pip freeze`) and install with `pip install --require-hashes -r requirements.txt` for checksum verification.
+- **Solidity (Foundry):** Since Foundry uses git submodules, pin dependencies to specific commit SHAs rather than
+ branch names. Review submodule updates as carefully as you would lockfile changes. A submodule pointing at `main`
+ is the equivalent of using `"latest"` in npm.
+
+### Install Scripts
+
+npm packages can define lifecycle scripts (`preinstall`, `postinstall`, `prepare`) that run automatically during
+installation. These scripts execute with the same permissions as the user running the install, which means a
+malicious package can run arbitrary code on your machine or CI server the moment you install it, before you ever
+import or use it. This is the primary execution mechanism behind most npm supply chain attacks, including
+[event-stream](https://blog.npmjs.org/post/180565383195/details-about-the-event-stream-incident) and
+[ua-parser-js](/supply-chain/web3-supply-chain-threats#npm-package-compromise).
+
+1. **Audit install scripts before adding new dependencies.** Before installing a package, download it without
+ executing anything (`npm pack `, `pnpm pack `, or `yarn pack `) and inspect its
+ `package.json` for `preinstall`, `postinstall`, or `prepare` entries.
+2. **Disable scripts by default.** All three package managers support disabling lifecycle scripts. Set this in
+ your `.npmrc` (read by both npm and pnpm) or `.yarnrc.yml` (yarn Berry):
+
+ ```bash
+ # .npmrc (npm and pnpm)
+ ignore-scripts=true
+ ```
+
+ ```yaml
+ # .yarnrc.yml (yarn Berry)
+ enableScripts: false
+ ```
+
+3. **Allowlist packages that need scripts.** Some legitimate packages (native modules like `bcrypt`, build tools
+ like `esbuild`) require install scripts to work. Rather than leaving all scripts enabled, keep them disabled
+ globally and explicitly permit only the packages you have reviewed. pnpm supports this through
+ `onlyBuiltDependencies` in `package.json`:
+
+ ```json
+ {
+ "pnpm": {
+ "onlyBuiltDependencies": ["bcrypt", "esbuild"]
+ }
+ }
+ ```
+4. **Never run the install command with elevated privileges.** If a script requires `sudo`, that is a red flag.
+
+## Version Pinning
+
+How you declare a dependency version determines how much control you have over what gets installed. The syntax varies
+by ecosystem, but the concept is universal: the more flexibility you allow, the more trust you place in upstream
+maintainers.
+
+### Node.js (npm / pnpm / yarn)
+
+| Strategy | Example | Risk Level | When to Use |
+|----------|---------|-----------|------------|
+| **Exact version** | `"1.2.3"` | Lowest | Security-critical packages, wallet libraries, production dependencies |
+| **Patch range** | `"~1.2.3"` | Low | General dependencies where you trust patch releases |
+| **Minor range** | `"^1.2.3"` | Medium | Development dependencies, internal tools |
+| **Any version** | `"*"` or `"latest"` | Highest | Never use this in production |
+
+For any package that runs in a user's browser, interacts with a wallet, or handles signing, use exact versions and
+review every update as a deliberate decision. For development dependencies that do not reach production, patch or minor
+ranges are a reasonable tradeoff between security and maintenance overhead. `"*"` and `"latest"` have no place in a
+production dependency manifest.
+
+> **Important:** Even with exact versions in your direct dependencies, transitive dependencies still resolve through
+> semver ranges declared by the packages you depend on. This is why lockfile integrity matters: the lockfile is what
+> actually pins the full tree.
+
+### Cross-Ecosystem Reference
+
+Each ecosystem has its own version range syntax and defaults. The principles are the same: pin tightly for anything
+security-critical, allow ranges only where the tradeoff is justified.
+
+| Ecosystem | How to Pin Exactly | How Flexible Ranges Work |
+|-----------|-------------------|--------------------------|
+| **Rust (Cargo)** | `=1.2.3` | By default, `1.2.3` allows compatible updates within the same major version. Use `=` for strict pinning. |
+| **Python (pip)** | `==1.2.3` | `~=1.2.3` allows patch updates only. Omitting a version specifier accepts anything, so always specify one. |
+| **Go** | Pinned via `go.sum` checksums | Go uses Minimum Version Selection (MVS): it always picks the *oldest* version that satisfies all requirements, not the newest. This is conservative by design but can delay security patches. |
+| **Java (Maven)** | `1.2.3` (exact by default) | Range syntax like `[1.2,1.3)` is available but rarely used. Avoid `LATEST` and `RELEASE` in production. |
+| **Ruby (Bundler)** | `= 1.2.3` | `~> 1.2` is the "pessimistic" operator. It allows patch updates within `1.2.x` but not `1.3.0`. |
+
+### GitHub Actions SHA Pinning
+
+GitHub Actions are themselves a supply chain dependency. When you reference an action by tag
+(`uses: actions/checkout@v4`), the tag owner can move it to point at different code at any time. Pinning to a full
+commit SHA ensures that the action you run today is the same one you reviewed:
+
+```yaml
+# Instead of this (mutable tag):
+- uses: actions/checkout@v4
+
+# Use this (immutable commit SHA):
+- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+```
+
+## Trust and Verification
+
+Lockfiles and version pinning ensure you get the code you expect, but they do not help you decide whether to trust a
+package in the first place. Trust and verification are about evaluating packages *before* they enter your dependency
+tree, and ensuring that the packages you receive were published by who you think they were.
+
+### Package Trust Signals
+
+Before adding a new dependency, evaluate it. No single signal is definitive, but taken together they form a reasonable
+picture of risk:
+
+- **Maintainer activity:** Is the package actively maintained? Are issues addressed? A package with no commits in two
+ years and a pile of open issues may be abandoned, or it may be stable and complete. Context matters.
+- **Maintainer count:** A package maintained by a single developer is a single point of failure. If their account is
+ compromised, so is every project depending on their packages.
+- **Download trends and community adoption:** Very low download counts for a supposedly popular package are a red flag.
+ Compare against known-good alternatives.
+- **Scope and permissions:** Does the package do what it claims and nothing more? A date-formatting library that
+ requests network access should raise questions.
+- **Dependencies of the dependency:** A minimal utility that itself pulls in 50 transitive dependencies introduces risk
+ disproportionate to its value.
+- **Security posture:** Does the project have a security policy (`SECURITY.md`)? Do they use signed releases or
+ provenance attestations? Do they assess known vulnerabilities quickly?
+
+### OIDC and Trusted Publishers
+
+Traditional package publishing relies on long-lived API tokens stored in CI environments. If those tokens are leaked
+or the CI environment is compromised, an attacker can publish malicious versions of your package. OIDC-based Trusted
+Publishers eliminate this risk.
+
+**How it works:** Instead of storing a static npm (or PyPI) access token in your CI secrets, you configure the
+registry to trust your specific CI workflow. When the workflow runs, the CI provider (GitHub Actions, GitLab CI) and
+the registry negotiate a short-lived, cryptographically signed token that is scoped to that specific workflow,
+repository, and environment. The token cannot be extracted or reused.
+
+This approach was pioneered by [PyPI](https://docs.pypi.org/trusted-publishers/) and adopted by npm. If you maintain
+packages, this is one of the most impactful steps you can take:
+
+1. **Configure Trusted Publishers** for your registry to eliminate long-lived tokens from CI.
+2. **Use isolated CI workflows for publishing.** Separate build, verify, and publish into distinct jobs. Only the
+ publish job should hold credentials, and those credentials should be short-lived OIDC tokens.
+3. **Enable provenance attestation.** npm's `--provenance` flag generates a signed record of how and where a package
+ was built and published, allowing consumers to verify the package's origin.
+4. **Require 2FA for all publish actions.** Prefer WebAuthn/passkeys over TOTP where supported. Enable it for the
+ entire scope or organization, not just individual accounts.
+
+> **For consumers:** When evaluating a package, check whether it publishes with provenance. On npmjs.com, packages with
+> provenance display a green checkmark linking to the specific CI workflow that built them. This is a strong trust
+> signal: it means the package was built from a known source repository through a verifiable pipeline.
+
+For an in-depth walkthrough of npm Trusted Publishers and secure publishing workflows, see
+[How to npm and Avoid Getting Rekt](https://blog.theredguild.org/how-to-npm-and-avoid-getting-rekt/) by [The Red Guild](https://theredguild.org/).
+
+### Typosquatting
+
+Typosquatting attacks publish malicious packages with names deliberately close to popular ones, targeting developers
+who mistype a package name during installation.
+
+1. **Double-check package names** before installing. Verify the exact spelling, publisher, and scope (`@org/package`).
+2. **Check download counts and publish history.** Use `npm info ` to inspect locally or look it up on
+ [npmjs.com](https://www.npmjs.com/). Red flags to look for are: very low download counts (for a supposedly popular
+ package), a recent first publish date, no verified publisher, or a name that is one character off from a well-known
+ package.
+3. **Use scoped packages** when available. Scoped names (`@org/package`) are harder to typosquat than unscoped ones.
+4. **Enable lockfile verification** in CI to prevent unexpected package name changes.
+5. **Consider `minimumReleaseAge`** (pnpm) or equivalent policies. Delaying installations of newly published versions
+ by a configurable period gives the community time to detect malicious releases before they reach your project.
+
+## Vulnerability Scanning
+
+Most ecosystems provide built-in or community-standard tools for checking dependencies against known vulnerability
+databases. Run these in CI and fail builds on high or critical findings.
+
+| Ecosystem | Built-in / Standard Tool | Command |
+|-----------|------------------------|---------|
+| **Node.js** | `npm audit` / `pnpm audit` | `pnpm audit --audit-level=high` |
+| **Rust** | `cargo-audit` | `cargo audit` |
+| **Python** | `pip-audit` | `pip-audit -r requirements.txt` |
+| **Go** | `govulncheck` | `govulncheck ./...` |
+| **Ruby** | `bundler-audit` | `bundle audit check --update` |
+| **Java** | OWASP Dependency-Check | Gradle/Maven plugin |
+
+### Cross-Ecosystem Tools
+
+- [Dependabot](https://github.com/dependabot) is a GitHub built-in tool that supports npm, pip, Cargo, Go modules,
+ Maven, Bundler, Composer, and more. It monitors your dependencies for known vulnerabilities, opens security alerts on
+ your repository, and when a fix is available, creates a PR to bump the affected dependency. It can also open PRs for
+ general version updates on a schedule you configure.
+
+- [Snyk](https://snyk.io/) and [Grype](https://github.com/anchore/grype) go beyond single-ecosystem advisory
+ databases, covering transitive dependencies and scanning against multiple vulnerability sources across many languages
+ and package managers.
+
+- [OSV-Scanner](https://google.github.io/osv-scanner/) by Google queries the OSV (Open Source Vulnerabilities)
+ database, which aggregates advisories from multiple ecosystems into a single, consistent format.
+
+> **Important:** None of these methods or tools make you more secure by themselves. They make you *aware* of vulnerabilities and
+> updates. The security value comes from reviewing those updates in depth, especially security patches.
+
+## Ecosystem-Specific Considerations
+
+### Smart Contract Dependencies
+
+Smart contract dependencies carry unique risk because deployed code is immutable. Static analysis, testing strategies,
+and secure coding practices for Solidity are covered in depth in the [Security Testing](/security-testing/overview)
+and [Secure Software Development](/secure-software-development/overview) frameworks. For guidance on auditing
+contracts and their imported libraries, see
+[External Security Reviews for Smart Contracts](/external-security-reviews/smart-contracts/overview).
+
+## Common Pitfalls
+
+1. **Blindly merging dependency update PRs.** Always review what changed, especially across major versions. Check the
+ changelog and release notes before merging.
+2. **Using `*` or `latest` version ranges.** This hands control of your dependency tree to whoever publishes the next
+ version.
+3. **Ignoring transitive dependencies.** Your direct dependencies carry their own dependency trees, and a vulnerability
+ three levels deep still affects your application. Vulnerability scanning tools surface these; running them in CI
+ ensures the full tree is checked on every build.
+4. **Installing from GitHub URLs instead of registries.** `"my-package": "github:user/repo"` bypasses registry
+ integrity checks, removes version pinning, and pulls whatever is at the HEAD of a mutable branch at install time.
+ Use published, versioned registry packages instead.
+5. **Not reviewing changelogs before updating.** Major version bumps can introduce breaking changes or new
+ dependencies. Review before updating.
+6. **Publishing with long-lived tokens.** If you maintain packages, use OIDC Trusted Publishers when possible instead
+ of static tokens stored in CI secrets. Where OIDC is not available, rotate tokens regularly and scope them to the
+ minimum permissions needed. A leaked token means anyone can publish as you.
+7. **Trusting packages without verification.** Download counts and GitHub stars are not security guarantees. Check
+ provenance, maintainer history, and dependency footprint before adding a new package.
+
+## Further Reading
+
+- [npm Security Best Practices](https://docs.npmjs.com/packages-and-modules/securing-your-code): Official npm
+ security documentation
+- [How to npm and Avoid Getting Rekt](https://blog.theredguild.org/how-to-npm-and-avoid-getting-rekt/) by
+ [The Red Guild](https://theredguild.org/): Covers npm Trusted Publishers, provenance, and secure publishing workflows
+- [PyPI Trusted Publishers](https://docs.pypi.org/trusted-publishers/): OIDC-based publishing for PyPI (the model npm
+ adopted)
+- [Dependabot Documentation](https://docs.github.com/en/code-security/dependabot): GitHub's cross-ecosystem
+ dependency update tooling
+- [OSV (Open Source Vulnerabilities)](https://osv.dev/): Aggregated vulnerability database spanning multiple ecosystems
+- [Snyk Vulnerability Database](https://security.snyk.io/): Searchable database of known vulnerabilities
+- [Cargo Security Advisories](https://rustsec.org/): Rust security advisory database and `cargo-audit`
+- [Go Vulnerability Database](https://vuln.go.dev/): Official Go vulnerability tracking and `govulncheck`
---
diff --git a/docs/pages/supply-chain/incident-response-supply-chain.mdx b/docs/pages/supply-chain/incident-response-supply-chain.mdx
new file mode 100644
index 00000000..2ee7dcc7
--- /dev/null
+++ b/docs/pages/supply-chain/incident-response-supply-chain.mdx
@@ -0,0 +1,163 @@
+---
+title: "Supply Chain Incident Response | SEAL"
+description: "Respond to supply chain compromises in Web3 projects. Detect compromised dependencies, assess blast radius, lock affected versions, and coordinate recovery across frontend and smart contracts."
+tags:
+ - Security Specialist
+ - SRE
+ - Engineer/Developer
+contributors:
+ - role: wrote
+ users: [scode2277]
+---
+
+import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } from '../../../components'
+
+
+
+
+# Supply Chain Incident Response
+
+
+
+
+> 🔑 **Key Takeaway:** Supply chain incidents move faster than direct compromises. You do not control the affected
+> code, the fix depends on an external maintainer, and the same attack may be hitting hundreds of other projects
+> simultaneously. Speed and a practiced response plan are what determine your outcome.
+
+When a dependency is compromised, the clock starts before you are aware of it. The Ledger Connect Kit attack in
+2023 ran for several hours before widespread detection, long enough for significant user losses to occur. By the time
+most teams learned about it, the question was no longer whether they were affected but how many of their users had
+already interacted with the malicious version. Supply chain incidents have this character: they originate externally,
+propagate at ecosystem scale, and the window between compromise and discovery is often controlled by the attacker.
+
+For general incident response procedures, see the [Incident Management](/incident-management/overview) framework.
+This page focuses on the aspects unique to supply chain compromises.
+
+## How Supply Chain Incidents Differ
+
+| Aspect | Direct Compromise | Supply Chain Compromise |
+|--------|------------------|------------------------|
+| **Control** | You own the affected code | You depend on an external maintainer |
+| **Detection** | Internal monitoring catches it | Typically discovered externally: community, security researchers, registry alerts |
+| **Fix timeline** | You can patch immediately | You wait for the upstream fix or pin to a safe version |
+| **Blast radius** | Scoped to your systems | May affect every project in the ecosystem using that dependency |
+| **Attribution** | Attacker targeted you specifically | You are collateral in an ecosystem-wide attack |
+
+## Detection Signals
+
+Watch for these indicators that a supply chain compromise may have occurred:
+
+- **Community alerts.** Security advisories, posts from researchers, messages in developer Discord servers are often
+ the first signal.
+- **Unexpected dependency updates.** A package version appears in your lockfile that no one on the team updated.
+- **Behavioral anomalies.** Unexpected network requests from your application, unusual transaction prompts reported
+ by users, or build output that changes between runs without corresponding source changes.
+- **Integrity check failures.** SRI hash mismatches or checksum discrepancies between expected and actual artifacts.
+- **Registry advisories.** npm sends security advisories when a package is flagged, though this can lag behind public
+ disclosure.
+
+## Response Scenarios
+
+### Frontend Dependency Compromise
+
+This is the most common scenario: a compromised npm package serves malicious JavaScript to users through
+your frontend.
+
+- **Deploy a clean frontend immediately.** Revert to the last known good build or rebuild without the compromised
+ dependency.
+- **Invalidate CDN caches.** A cached compromised version will continue to reach users even after you redeploy from
+ clean source.
+- **Warn users.** Post on your official channels that users should not interact with the application until the clean version
+ is confirmed live.
+- **Check for wallet drainer activity.** If the compromise targeted wallet signing flows, check on-chain for
+ unauthorized transactions originating from your application's users during the exposure window.
+
+### Smart Contract Dependency Compromise
+
+If a Solidity library used in your contracts is found to be vulnerable or malicious:
+
+- **Determine if the affected code is deployed.** Check whether the compromised library version was included in any
+ deployed contracts. Library vulnerabilities that were not present in the version you used may not affect you.
+- **Consider pausing.** If your contracts have a pause mechanism and the vulnerability is actively exploitable, pause
+ them while you assess.
+- **Plan migration if needed.** Evaluate whether the vulnerability is actively exploitable
+ with your current configuration and plan a new deployment.
+
+### CI/CD Pipeline Compromise
+
+If the compromised dependency ran during your build process:
+
+- **Assume build secrets are compromised.** Rotate all secrets accessible to the CI environment (API keys, deployment
+ keys, npm tokens).
+- **Audit recent deployments.** Check if any build produced by the compromised CI was deployed to production.
+ Binaries or contracts produced during the compromise window should be considered untrusted.
+- **Review CI logs.** Look for unexpected network calls or file system access during the build.
+- **Rebuild with clean dependencies.** Use `--frozen-lockfile` with a verified lockfile.
+
+## Immediate Response Steps
+
+When a compromise is confirmed or credibly suspected:
+
+### Assess Exposure
+
+- **Check your lockfile.** Is the compromised version present in `pnpm-lock.yaml`, `yarn.lock`, or
+ `package-lock.json`?
+- **Check deployed artifacts.** Was the compromised version included in any build that reached production?
+- **Check CI history.** Did any CI run install the compromised version? If so, CI secrets may have been exposed.
+- **Identify the attack window.** When was the malicious version published, and when did you last install or build?
+
+### Contain the Damage
+
+- **Lock dependencies** to the last known good version. Delete `node_modules` and rebuild from a verified lockfile
+ using `--frozen-lockfile`.
+- **Do not deploy anything** built during the exposure window until the build is clean.
+- **Rotate exposed secrets.** If the compromised package ran during CI, assume that CI environment's secrets (API
+ keys, deployment keys, npm tokens) are exposed and rotate them immediately.
+- **Take down compromised deployments.** If a compromised frontend was served to users, take it offline or deploy a
+ clean version as fast as possible. A few minutes of unavailability is recoverable, continued exposure is not.
+
+### Communicate
+
+- **Notify your team.** Ensure everyone knows not to install or deploy until the situation is resolved.
+- **Notify affected users.** If wallet-interacting code was affected, warn users on your official channels promptly
+ and specifically: tell them what happened, what the risk is, and what action they should take.
+- **Coordinate with the maintainer.** Report the compromise to the package maintainer and to the registry (npm,
+ crates, PyPI).
+
+## Post-Incident Actions
+
+Once the immediate threat is contained:
+
+- **Document the timeline.** When the compromise occurred, when it was detected, how long it was in production, and
+ what the impact was. This serves the retrospective and any user communication that follows.
+- **Strengthen monitoring.** Add the detection signals you missed to your monitoring setup.
+- **Review dependency practices.** Were versions pinned? Were lockfiles committed and verified in
+ CI? Address any gaps the incident exposed.
+- **Update your response playbook.** Incorporate lessons learned so the next response is faster.
+
+## Quick-Reference Checklist
+
+When a supply chain compromise is reported:
+
+- [ ] Is the compromised version in your lockfile?
+- [ ] Was it included in any build that reached production?
+- [ ] Did it run during CI? If so, rotate all CI secrets.
+- [ ] Lock to the last known good version and rebuild from clean state.
+- [ ] Delete `node_modules` / build cache and use `--frozen-lockfile`.
+- [ ] If user-facing: deploy clean version, invalidate CDN caches, notify users.
+- [ ] If wallet-interacting: check for unauthorized on-chain activity during the exposure window.
+- [ ] Rotate any secrets the package could have accessed.
+- [ ] Report to the registry and coordinate with the package maintainer.
+- [ ] Document the incident timeline and run a retrospective.
+
+## Further Reading
+
+- [Incident Management](/incident-management/overview): General incident response procedures and team coordination
+- [Web3 Supply Chain Threats](/supply-chain/web3-supply-chain-threats): Real-world incidents that illustrate the attack patterns described here
+- [Dependency Awareness](/supply-chain/dependency-awareness): Preventive practices like version pinning and lockfile integrity that reduce exposure
+- [DevSecOps](/devsecops/overview): Integrating dependency scanning and build security into CI/CD pipelines
+
+---
+
+
+
diff --git a/docs/pages/supply-chain/index.mdx b/docs/pages/supply-chain/index.mdx
index 1cdafcdc..3576d4b6 100644
--- a/docs/pages/supply-chain/index.mdx
+++ b/docs/pages/supply-chain/index.mdx
@@ -13,4 +13,7 @@ title: "Supply Chain"
- [Supply Chain Security](/supply-chain/overview)
- [Dependency Awareness](/supply-chain/dependency-awareness)
-- [Supply Chain Levels Software Artifacts](/supply-chain/supply-chain-levels-software-artifacts)
+- [Web3 Supply Chain Threats](/supply-chain/web3-supply-chain-threats)
+- [Supply Chain Levels for Software Artifacts](/supply-chain/supply-chain-levels-software-artifacts)
+- [Vendor Risk Management](/supply-chain/vendor-risk-management)
+- [Supply Chain Incident Response](/supply-chain/incident-response-supply-chain)
diff --git a/docs/pages/supply-chain/overview.mdx b/docs/pages/supply-chain/overview.mdx
index a0ab2883..9658a6ac 100644
--- a/docs/pages/supply-chain/overview.mdx
+++ b/docs/pages/supply-chain/overview.mdx
@@ -1,10 +1,13 @@
---
title: "Supply Chain Security | Security Alliance"
-description: "Supply Chain Security Framework: Secure all components, dependencies, and processes in software development and deployment. Protect web application stacks and smart contract external libraries."
+description: "Supply Chain Security Framework: Secure dependencies, frontend delivery, infrastructure providers, and build artifacts in Web3 projects. Prevent supply chain attacks before they reach users."
tags:
- Engineer/Developer
- Security Specialist
- Devops
+contributors:
+ - role: wrote
+ users: [scode2277]
---
import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } from '../../../components'
@@ -17,9 +20,56 @@ import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } fr
-Supply chain security involves managing and securing all the components, dependencies, and processes involved in the
-development, deployment, and maintenance of software. In the context of blockchain and web3 projects, supply chain
-security could for example be parts of the web application stack, or external libraries used by the smart contract.
+> 🔑 **Key Takeaway:** Your software is only as secure as its weakest dependency. Supply chain security means knowing
+> what you depend on, verifying its integrity, and having a plan for when something in your chain is compromised.
+
+Supply chain security covers everything between your source code and your users. In traditional software, that mostly
+means npm packages and third-party libraries. In Web3, the chain is longer and the consequences are more severe:
+frontend code interacts directly with wallets, smart contracts hold real value, and infrastructure providers make
+decisions your contracts rely on. Attackers who understand this do not need to compromise your code directly. They
+target the libraries you import, the CDNs that serve your frontend, the RPC endpoints your app trusts, and the
+contractors your team onboards.
+
+These are not theoretical risks. Attacks targeting npm packages, wallet connector libraries, and compiler toolchains
+have resulted in hundreds of millions of dollars in losses across the Web3 ecosystem.
+
+## What Makes Up a Web3 Supply Chain?
+
+A Web3 project's supply chain includes every external component between your source code and your users:
+
+- **Code dependencies:** npm packages, Solidity libraries, Rust crates, and their transitive dependencies
+- **Frontend delivery:** CDNs, hosting providers, wallet connector libraries, and the scripts served to users' browsers
+- **Build tooling:** Compilers (solc), development frameworks (Hardhat, Foundry), CI/CD pipelines
+- **Infrastructure providers:** RPC nodes, indexers, oracle networks, bridge relayers
+- **Hardware:** Signing devices, hardware wallets, HSMs
+- **Human supply chain:** Contractors, freelancers, open-source contributors
+
+A compromise at any point in this chain can affect your users.
+
+## What This Framework Covers
+
+This framework provides practical guidance for securing each layer of your supply chain:
+
+1. [Dependency Awareness](/supply-chain/dependency-awareness): Manage external packages securely, including version pinning,
+ lockfile integrity, vulnerability scanning, and protection against typosquatting.
+2. [Web3 Supply Chain Threats](/supply-chain/web3-supply-chain-threats): The specific threat vectors that affect Web3
+ projects, from frontend library hijacking to infrastructure compromise and hardware tampering.
+3. [Supply Chain Levels for Software Artifacts](/supply-chain/supply-chain-levels-software-artifacts): Classify your
+ components by risk level and apply proportional controls.
+4. [Vendor Risk Management](/supply-chain/vendor-risk-management): Evaluate and monitor third-party providers including RPC
+ services, oracle networks, security auditors, and contractors.
+5. [Supply Chain Incident Response](/supply-chain/incident-response-supply-chain): What to do when a dependency or
+ provider is compromised, including Web3-specific response scenarios.
+
+## Related Frameworks
+
+Supply chain security intersects with several other areas covered in this project:
+
+- [DevSecOps](/devsecops/overview): Integrating dependency scanning and build security into CI/CD pipelines
+- [DPRK IT Workers](/dprk-it-workers/overview): Mitigating insider threats from the human supply chain
+- [Wallet Security](/wallet-security/overview): Hardware wallet supply chain integrity and key management
+- [External Security Reviews](/external-security-reviews/overview): Selecting and working with security auditors
+- [Incident Management](/incident-management/overview): General incident response procedures
---
diff --git a/docs/pages/supply-chain/supply-chain-levels-software-artifacts.mdx b/docs/pages/supply-chain/supply-chain-levels-software-artifacts.mdx
index 1f46e7c0..2a39ccd5 100644
--- a/docs/pages/supply-chain/supply-chain-levels-software-artifacts.mdx
+++ b/docs/pages/supply-chain/supply-chain-levels-software-artifacts.mdx
@@ -1,9 +1,12 @@
---
-title: "Supply Chain Levels Software Artifacts | SEAL"
-description: "Prioritize security efforts with software artifact risk levels. Classify components as critical, high, moderate, or low risk and apply appropriate security controls to each level."
+title: "Supply Chain Levels for Software Artifacts | SEAL"
+description: "Classify software components by risk level and apply proportional security controls to your dependency tree."
tags:
- Engineer/Developer
- Security Specialist
+contributors:
+ - role: wrote
+ users: [scode2277]
---
import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } from '../../../components'
@@ -16,49 +19,65 @@ import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } fr
-Supply chain levels for software artifacts provide a framework for categorizing and securing software components based
-on their risk levels. This approach helps projects prioritize their security efforts towards software components with
-the highest risk levels.
+> 🔑 **Key Takeaway:** Not every dependency carries the same risk. Apply your strictest controls to components that
+> touch user funds or signing operations, and scale down from there. Applying the same scrutiny to everything means
+> applying it effectively to nothing.
-## Framework for Supply Chain Levels
+Applying uniform security controls across an entire dependency tree is not practical and does not reflect how risk
+actually distributes. A smart contract library that handles value transfers carries fundamentally different risk than
+a test framework or a documentation generator. Classification frameworks exist to make this explicit: identify which
+components carry the most risk, then concentrate your strongest controls there and apply proportionally lighter
+measures to lower-risk artifacts.
-1. **Level 1: Critical Artifacts**
- - These artifacts are essential to the core functionality of the software and pose a high risk if compromised.
- - Examples: Core libraries.
+## Risk Classification Framework
-2. **Level 2: High-Risk Artifacts**
- - Artifacts that are important but not critical. Their compromise could lead to significant security issues.
- - Examples: Middleware, database connectors, oracles, authentication modules.
+### Level 1: Critical Artifacts
-3. **Level 3: Moderate-Risk Artifacts**
- - Artifacts that are used frequently but have a lower risk profile. Their compromise could cause inconvenience but
- not catastrophic failure.
- - Examples: User interface libraries, utility functions, data processing modules.
+Components that directly handle value, signing operations, or core protocol logic. Smart contract libraries (OpenZeppelin Contracts),
+wallet interaction libraries (ethers.js, viem, web3.js), signing and cryptographic modules, and anything that constructs or
+validates transactions.
-4. **Level 4: Low-Risk Artifacts**
- - Artifacts that have minimal impact on security if compromised.
- - Examples: Logging libraries, test utilities.
+Compromise of these components can directly drain funds or allow unauthorized transactions. These warrant the
+highest scrutiny.
-## Best Practices for Securing Supply Chain Levels
+For specific practices, see
+[Dependency Awareness](/supply-chain/dependency-awareness),
+[Security Testing Framework](/security-testing/overview), and
+[External Security Reviews Framework](/external-security-reviews/smart-contracts/overview).
-1. **Critical Artifacts**
- - Implement strict access controls and require code reviews for all changes.
- - Use robust security testing, including static and dynamic analysis.
- - Monitor continuously for vulnerabilities and apply patches promptly.
+### Level 2: High-Risk Artifacts
-2. **High-Risk Artifacts**
- - Enforce strong access controls and conduct regular security assessments.
- - Perform regular updates and vulnerability scans.
- - Implement automated security testing in CI/CD pipelines.
+Components that are important to application function but do not directly handle funds. Authentication and
+authorization modules, API gateway and middleware components, database connectors, and oracle integration code fall
+in this category.
-3. **Moderate-Risk Artifacts**
- - Apply standard security practices, including access controls and regular updates.
- - Use automated tools to scan for vulnerabilities periodically.
- - Ensure that dependencies are from trusted sources.
+Their compromise could enable data exposure, service disruption, or indirect fund loss, but would typically require
+additional exploitation steps. These benefit from regular vulnerability scanning and automated security testing
+in CI.
-4. **Low-Risk Artifacts**
- - Follow basic security hygiene, such as using trusted sources and applying updates.
- - Perform occasional security reviews and audits.
+For dependency management practices, see [Dependency Awareness](/supply-chain/dependency-awareness).
+
+For CI/CD pipeline security, see [DevSecOps](/devsecops/overview).
+
+### Level 3: Moderate-Risk Artifacts
+
+High-usage components with limited blast radius. UI frameworks (React, Vue), general utility libraries (lodash,
+date-fns), data processing modules, and analytics libraries sit in this tier.
+
+Compromise could cause service degradation or facilitate phishing, but not direct fund loss. Standard update
+practices and periodic vulnerability scanning are sufficient.
+
+### Level 4: Low-Risk Artifacts
+
+Components that do not run in production or have no access to sensitive data. Test frameworks (Jest, Mocha), linting
+and formatting tools, documentation generators, and local development utilities belong here.
+
+Basic security hygiene (trusted sources, occasional updates) is sufficient here.
+
+## Further Reading
+
+- [Dependency Awareness](/supply-chain/dependency-awareness): Practical guidance on managing dependencies
+- [Web3 Supply Chain Threats](/supply-chain/web3-supply-chain-threats): Real-world attacks across the supply chain
---
diff --git a/docs/pages/supply-chain/vendor-risk-management.mdx b/docs/pages/supply-chain/vendor-risk-management.mdx
new file mode 100644
index 00000000..e19fa44f
--- /dev/null
+++ b/docs/pages/supply-chain/vendor-risk-management.mdx
@@ -0,0 +1,101 @@
+---
+title: "Vendor Risk Management | SEAL"
+description: "Assess and manage third-party risks in Web3 projects. Understand the categories of vendor risk, monitor providers, and plan for vendor failures."
+tags:
+ - Operations & Strategy
+ - Security Specialist
+ - Engineer/Developer
+contributors:
+ - role: wrote
+ users: [scode2277]
+---
+
+import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } from '../../../components'
+
+
+
+
+# Vendor Risk Management
+
+
+
+
+> 🔑 **Key Takeaway:** Every provider, auditor, and contractor in your stack is a trust decision you are making on
+> behalf of your users. Assess that trust before onboarding, set expectations contractually, and review it regularly.
+
+Web3 projects are built on top of infrastructure and services they do not own. RPC providers relay every transaction.
+Oracle networks feed price data that contracts treat as ground truth. Auditors assess code that holds user funds.
+CDN providers serve the JavaScript that connects users to wallets. Each of these relationships represents a trust
+decision, and most teams make it informally, based on reputation, convenience, or whoever the previous developer used.
+Vendor risk management is the practice of making these trust decisions deliberately rather than by default.
+
+## Categories of Third-Party Risk
+
+### Infrastructure Providers
+
+- **RPC providers:** Every read and write your application makes to the blockchain goes through them. A compromised
+ or misconfigured provider can return manipulated data, and a single-provider dependency means your application goes
+ down when they do.
+- **Indexing services:** Applications that rely on indexed data for displaying balances, transaction history, or
+ contract state are trusting that the index is accurate and up to date. Stale or incorrect results can mislead users
+ or cause faulty transaction construction.
+- **Hosting and CDN:** Your frontend is served through these providers. If compromised, they can inject or modify the
+ JavaScript that users execute in their browsers, including wallet interaction code.
+- **Domain registrars:** Control of your domain means control of where users are directed. An unauthorized transfer
+ or DNS modification can redirect all traffic to a phishing clone. For DNS and hosting hardening, see
+ [Domain & DNS Security Framework](/infrastructure/domain-and-dns-security/overview).
+
+For real-world incidents involving these providers, see [Web3 Supply Chain Threats](/supply-chain/web3-supply-chain-threats).
+
+### Security Service Providers
+
+- **Smart contract auditors:** Audit quality depends on the auditor's domain expertise, methodology, and the time
+ allocated relative to codebase complexity. Choosing the right auditor for your technology stack and protocol type
+ is as important as the audit itself.
+- **Bug bounty platforms:** These sit between your project and the researchers who find vulnerabilities. Poor triage,
+ slow response times, or mishandled disclosures can result in vulnerabilities going unpatched or being disclosed
+ publicly before a fix is ready.
+- **Monitoring services:** Real-time alerting is only useful if it is accurate and actionable. Misconfigured
+ monitoring produces alert fatigue, and missed detections leave exploits undetected during the critical early window.
+
+For guidance on selecting auditors, see [External Security Reviews](/external-security-reviews/overview).
+
+### Human Supply Chain
+
+Contractors, freelancers, and pseudonymous open-source contributors all represent insider risk. In the Web3 industry
+this is not theoretical. The [DPRK IT Workers](/dprk-it-workers/overview) framework documents a specific and
+increasingly common pattern of state-affiliated actors gaining access to projects through legitimate-looking employment.
+Contractor vetting deserves the same rigor as any other vendor assessment.
+
+## Ongoing Monitoring
+
+Vendor assessment is not a one-time event. Security postures change, ownership changes, incidents happen. Reassess
+critical vendors at minimum annually, and quarterly for high-trust relationships. Subscribe to security advisories
+from your key providers and maintain a log of any vendor-related incidents or service degradations. Periodically
+audit the access each vendor holds and revoke anything unnecessary.
+
+For every critical vendor, have an exit plan: know which alternative you would migrate to, how long migration would
+take, and what data or configuration would need to move. Vendor lock-in becomes a critical risk when you need to
+move quickly during an incident.
+
+## Common Pitfalls
+
+- **Assuming "decentralized" means "no vendor risk."** Even decentralized services have operators, maintainers, and
+ infrastructure that can be compromised.
+- **Over-reliance on a single provider.** If your dApp stops working when one RPC provider goes down, you have a
+ single point of failure.
+- **Skipping due diligence for well-known brands.** Reputation and security posture are related but not the same
+ thing. Large providers have been compromised.
+- **No exit strategy.** Vendor lock-in becomes a critical risk when you need to move quickly during an incident.
+
+## Further Reading
+
+- [Web3 Supply Chain Threats](/supply-chain/web3-supply-chain-threats): Real-world incidents involving infrastructure and service providers
+- [External Security Reviews](/external-security-reviews/overview): Selecting and working with security auditors
+- [DPRK IT Workers](/dprk-it-workers/overview): Mitigating insider threats from the human supply chain
+- [Infrastructure](/infrastructure/overview): Infrastructure hardening and DNS security
+
+---
+
+
+
diff --git a/docs/pages/supply-chain/web3-supply-chain-threats.mdx b/docs/pages/supply-chain/web3-supply-chain-threats.mdx
new file mode 100644
index 00000000..1386b5e2
--- /dev/null
+++ b/docs/pages/supply-chain/web3-supply-chain-threats.mdx
@@ -0,0 +1,256 @@
+---
+title: "Web3 Supply Chain Threats | SEAL"
+description: "Identify and mitigate Web3-specific supply chain threats including frontend attacks, smart contract dependency risks, infrastructure compromise, and hardware tampering."
+tags:
+ - Engineer/Developer
+ - Security Specialist
+contributors:
+ - role: wrote
+ users: [scode2277]
+---
+
+import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } from '../../../components'
+
+
+
+
+# Web3 Supply Chain Threats
+
+
+
+
+> 🔑 **Key Takeaway:** Supply chain attacks skip your code entirely. They compromise what your code depends on. A
+> single hijacked npm package, a manipulated compiler, or a spoofed RPC response can result in irreversible fund loss
+> with no exploit of your own contracts required.
+
+This page catalogs the specific threat vectors that target Web3 supply chains, with real incidents for each. For the
+broader context on why supply chain security matters, see the [Overview](/supply-chain/overview).
+
+## Frontend Supply Chain Attacks
+
+The most common attack vector for end users is the JavaScript supply chain. Because wallet interactions happen through
+the browser, any code that runs on your frontend before a user signs a transaction is in a position to manipulate or
+redirect it.
+
+### NPM Package Compromise
+
+Attackers gain control of popular npm packages through account takeovers, social engineering of maintainers, or
+publishing malicious packages with similar names. Once a compromised version is installed, malicious code executes in
+the user's browser.
+
+**Notable incidents:**
+
+- **npm registry attack (2025).** The largest npm supply chain attack to date. Attackers phished a
+ maintainer's credentials via a fake 2FA reset email from `support@npmjs.help` and published malicious versions of
+ 18 packages including `chalk`, `debug`, and `ansi-styles` (2.6 billion combined weekly downloads). The payload
+ hooked `window.ethereum` to intercept wallet calls and overwrote `fetch`/`XMLHttpRequest` to reroute cryptocurrency
+ transactions to attacker-controlled addresses. The compromise was detected
+ and the malicious versions were removed within approximately two hours.
+- **Solana web3.js (2024).** Malicious versions (1.95.6 and 1.95.7) were published to npm containing code that
+ exfiltrated private keys from any developer or user who installed those versions.
+- **ua-parser-js (2021).** A package with over eight million weekly downloads was briefly hijacked to inject a
+ cryptominer and credential stealer into every project that ran `npm install` during the window.
+- **event-stream (2018).** A new maintainer was granted control of a package with over two million weekly downloads,
+ then added a dependency specifically designed to steal keys from Copay Bitcoin wallet users. The attack ran undetected
+ for weeks.
+
+For practices to defend against these attacks, see [Dependency Awareness](/supply-chain/dependency-awareness).
+
+### Wallet Connector Library Hijacking
+
+Wallet connector libraries are a particularly high-value target because they sit at the exact point where user intent
+meets transaction construction.
+
+**Notable incidents:**
+
+- **Ledger Connect Kit (December 2023).** A former employee's npm credentials were used to publish a malicious version
+ of `@ledgerhq/connect-kit`. The injected code rendered a fake wallet connection interface that redirected funds.
+ Every dApp using the library was affected simultaneously. No vulnerability in any smart contract was involved.
+
+For wallet-specific security practices, see the [Wallet Security](/wallet-security/overview) framework.
+
+### CDN and Hosting Compromise
+
+An attacker who compromises your hosting provider or poisons a CDN cache can serve tampered JavaScript to all users
+without touching your repository.
+
+- **DNS hijacking** can redirect users to a phishing clone that looks identical to your dApp but replaces transaction
+ signing with fund redirection.
+- **CDN cache poisoning** can serve malicious scripts even if your origin server is clean.
+
+For DNS hardening, registrar locks, and monitoring, see the [Domain & DNS Security](/infrastructure/domain-and-dns-security/overview) framework.
+
+## Smart Contract Dependency Risks
+
+Smart contracts inherit the risk of every library and tool in their build chain. While upgradeable proxy patterns
+allow post-deployment fixes, they add governance complexity and introduce their own attack surface. In either case,
+a compromised dependency that makes it into a deployment, whether upgradeable or not, has immediate on-chain
+consequences.
+
+### Compiler Tampering
+
+The Solidity compiler itself is a dependency. Different `solc` versions produce different bytecode, and a compromised
+compiler binary could inject behavior that is invisible in source code review. Because developers typically trust the
+compiler implicitly, a tampered binary would affect every contract compiled with it without leaving any trace in the
+source.
+
+**Notable incidents:**
+
+- **Vyper reentrancy bug (2023).** A latent bug in the Vyper compiler (versions 0.2.15, 0.2.16, and 0.3.0) caused
+ reentrancy guards to be incorrectly compiled at the bytecode level, despite appearing correct in source code. The
+ bug had been present for over two years before attackers exploited it to drain approximately $69 million from
+ multiple Curve Finance pools, Alchemix, JPEG'd, and Metronome. The contracts were not poorly written; the compiler
+ produced faulty bytecode from correct source.
+
+### Malicious Libraries and Plugins
+
+Build toolchains in Solidity projects (Hardhat, Foundry) rely on plugins, libraries, and Git-sourced dependencies.
+Each is an entry point. A malicious Hardhat plugin runs during compilation and deployment, meaning it could modify
+bytecode, exfiltrate private keys from the deployer's environment, or alter deployment scripts. Foundry's
+`forge install` pulls directly from Git repositories, so a compromised or mutable branch reference means the code
+you build against today may not be the code you reviewed yesterday.
+
+### Unverified Deployments
+
+Source verification (via [Sourcify](https://sourcify.dev/) or Etherscan) is standard practice, but its absence
+is itself a supply chain risk. Without it, a build-time compromise leaves no detectable trace: the deployed bytecode
+cannot be compared against the reviewed source, and neither users nor auditors have a way to confirm what is actually
+running on-chain.
+
+Even with source verification, the guarantee only holds if the build is reproducible. If two developers compiling the
+same source with the same compiler version produce different bytecode (due to differing compiler settings, optimizer
+runs, or metadata hashes), there is no reliable way to confirm that the verified source matches the deployed contract.
+Deterministic, reproducible builds are a prerequisite for meaningful source verification. Tools like
+[Sourcify's full match](https://docs.sourcify.dev/docs/full-vs-partial-match/) (which requires identical bytecode
+including metadata) and pinned compiler versions in build configs (`solc` version in `foundry.toml` or
+`hardhat.config.js`) help close this gap.
+
+For practices to mitigate these risks, see [DevSecOps](/devsecops/overview),
+[Security Testing](/security-testing/overview), and
+[Dependency Awareness](/supply-chain/dependency-awareness).
+
+## Governance Attacks
+
+Upgradeable smart contracts introduce a supply chain vector that exists entirely on-chain: governance. If a protocol
+uses a proxy pattern where the implementation contract can be swapped through a governance vote or a multisig
+transaction, then compromising the governance process is equivalent to compromising the code itself. The attacker does
+not need to find a bug or tamper with a dependency. They just need enough votes or enough signers.
+
+### Malicious Governance Proposals
+
+An attacker who acquires sufficient voting power (through token purchases, flash loan voting, or social engineering
+of delegates) can submit a proposal that upgrades a proxy to a malicious implementation. If the proposal passes, the
+new implementation runs with the same address and the same state, but with entirely different logic. Users interacting
+with the protocol may not notice anything changed until funds are drained.
+
+**Notable incidents:**
+
+- **Tornado Cash governance takeover (May 2023).** An attacker submitted a proposal that appeared to be a routine
+ update but contained hidden code granting the attacker 1.2 million fake TORN votes. With majority voting power, the
+ attacker gained full control of governance and used it to drain locked TORN tokens from the governance contract.
+- **Beanstalk (April 2022).** An attacker used a flash loan to acquire enough STALK governance tokens to pass a
+ malicious governance proposal in a single transaction. The proposal transferred all protocol assets to the
+ attacker's address, draining approximately $182 million. The attack exploited the fact that governance voting and
+ execution could happen in the same block with no time delay.
+
+## Infrastructure Dependency Risks
+
+Web3 applications depend on external infrastructure that they do not control. A compromised or unreliable provider
+does not need to exploit your code; it just needs to feed it bad data or go offline at the wrong moment.
+
+### RPC Provider Compromise
+
+RPC providers mediate every interaction between your app and the blockchain. A provider that returns manipulated data,
+whether due to compromise, misconfiguration, or deliberate malfeasance, can cause your application to display
+incorrect balances, construct transactions against stale state, or fail silently during high-value operations. A
+single-provider dependency also creates a single point of failure: if it goes down, your application goes dark.
+
+**Notable incidents:**
+
+- **Infura outage (November 2020).** Infura's nodes were running outdated Geth versions when a silently patched
+ consensus bug caused a chain split. MetaMask (which defaults to Infura) stopped working for hours. Binance, Upbit,
+ and other exchanges halted ETH withdrawals. Uniswap, MakerDAO, and Compound were all affected. No funds were stolen,
+ but the incident demonstrated how a single provider dependency can take down large portions of the ecosystem.
+
+### Oracle Manipulation
+
+Oracle networks are a direct and well-documented attack surface. Manipulated oracle data has been the root cause of
+hundreds of millions of dollars in DeFi losses. The typical pattern: an attacker manipulates a spot price on a
+low-liquidity pool, the oracle reports this manipulated price, and a lending protocol accepts it as ground truth,
+enabling the attacker to borrow against inflated collateral or liquidate positions that should not be liquidatable.
+
+Single-source oracles are especially vulnerable. If the only price feed comes from one exchange or one API, the
+attacker only needs to manipulate one data point.
+
+**Notable incidents:**
+
+- **Mango Markets (October 2022).** An attacker pumped MNGO spot price from $0.02 to $0.91 on thin-liquidity markets
+ within ten minutes, then used the inflated collateral to drain $112 million from the protocol's treasury.
+- **Cream Finance (October 2021).** Flash loans totaling over $1.5 billion were used to manipulate the yUSD price
+ oracle, inflating collateral value and draining $130 million in lending assets.
+- **bZx (February 2020).** The first major flash loan oracle attacks. The attacker used flash-loaned ETH to manipulate
+ WBTC and sUSD prices on Uniswap, which bZx used as its sole price oracle. Two attacks within one week, approximately
+ $1 million total.
+
+### Block Explorer API Dependence
+
+Block explorer APIs (Etherscan, Basescan, and their equivalents) are often used to fetch ABIs, verify contract state,
+or display transaction history. These are third-party services with their own availability and integrity risks. An
+application that depends on a block explorer API for security-critical data (e.g. confirming transaction finality)
+is introducing a single point of failure into its trust model.
+
+Beyond availability, the source verification systems that block explorers provide are themselves an imperfect trust
+layer. In 2021, samczsun [demonstrated](https://samczsun.com/hiding-in-plain-sight/) that Etherscan's handling of
+bytecode metadata could be exploited to make verified source code not match the contract's actual behavior. The
+verification page would show clean, reviewed code while the deployed contract did something different. This was not
+a one-off bug. A 2024 academic study (["Abusing the Ethereum Smart Contract Verification Services for Fun and
+Profit"](https://www.ndss-symposium.org/ndss-paper/abusing-the-ethereum-smart-contract-verification-services-for-fun-and-profit/),
+NDSS 2024) systematically tested Etherscan, Sourcify, and Blockscout and found 19 vulnerabilities across the three
+services. 15 were confirmed by the vendors, 10 were fixed, and some remain open. The attacks ranged from metadata
+manipulation to compiler version mismatches that allowed verified source to diverge from deployed bytecode.
+
+The takeaway: a green checkmark on a block explorer means the submitted source compiled to matching bytecode under
+the conditions the verifier tested. It does not guarantee that the source faithfully represents what the contract
+does. Treat verified source as a useful signal, not a security guarantee, and cross-reference against independent
+verification services when the stakes are high.
+
+For a structured approach to evaluating and managing third-party providers, see
+[Vendor Risk Management](/supply-chain/vendor-risk-management). For infrastructure hardening, see the
+[Infrastructure](/infrastructure/overview) framework.
+
+## Hardware Supply Chain
+
+Hardware wallets and signing devices introduce physical supply chain risks. A tampered device can be programmed to
+leak private keys on first use or to sign transactions differently from what is displayed on screen. Devices
+purchased through third-party resellers, second-hand markets, or unofficial channels may have been intercepted and
+modified before reaching the buyer. Firmware updates from unofficial sources carry the same risk: a malicious update
+could extract keys or alter signing behavior while appearing to function normally.
+
+**Notable incidents:**
+
+- **Trezor Safe 3 vulnerability (2025).** Ledger's security research team disclosed that the Trezor
+ Safe 3 is vulnerable to voltage glitching attacks that can allow an attacker with physical access (during
+ manufacturing or transit) to read and modify firmware without leaving detectable signs. No confirmed exploits in the
+ wild, but the disclosure demonstrates that hardware supply chain attacks are practical, not theoretical.
+- **Ledger customer database breach (2020).** An unauthorized party accessed Ledger's e-commerce database via a
+ misconfigured API key. Over 272,000 customers had their names, physical addresses, and phone numbers leaked. No
+ private keys were compromised, but the exposed data fueled targeted phishing campaigns, extortion attempts, and
+ credible physical threats against wallet holders.
+
+For hardware wallet security guidance, see the [Wallet Security](/wallet-security/overview) framework.
+
+## Further Reading
+
+- Review your project's dependency tree with the practices described in
+ [Dependency Awareness](/supply-chain/dependency-awareness)
+- Classify your components by risk level using the
+ [Supply Chain Levels](/supply-chain/supply-chain-levels-software-artifacts) framework
+- Establish a vendor assessment process following the
+ [Vendor Risk Management](/supply-chain/vendor-risk-management) guide
+- Track real-time exploit data and historical incidents on the
+ [DeFiLlama Hacks Dashboard](https://defillama.com/hacks)
+
+---
+
+
+
diff --git a/utils/fetched-tags.json b/utils/fetched-tags.json
index 8c475f51..7b2ed820 100644
--- a/utils/fetched-tags.json
+++ b/utils/fetched-tags.json
@@ -885,6 +885,11 @@
"Engineer/Developer",
"Security Specialist"
],
+ "/supply-chain/incident-response-supply-chain": [
+ "Security Specialist",
+ "SRE",
+ "Engineer/Developer"
+ ],
"/supply-chain/overview": [
"Engineer/Developer",
"Security Specialist",
@@ -894,6 +899,15 @@
"Engineer/Developer",
"Security Specialist"
],
+ "/supply-chain/vendor-risk-management": [
+ "Operations & Strategy",
+ "Security Specialist",
+ "Engineer/Developer"
+ ],
+ "/supply-chain/web3-supply-chain-threats": [
+ "Engineer/Developer",
+ "Security Specialist"
+ ],
"/threat-modeling/create-maintain-threat-models": [
"Engineer/Developer",
"Security Specialist"
diff --git a/vocs.config.tsx b/vocs.config.tsx
index ae34506d..96452f50 100644
--- a/vocs.config.tsx
+++ b/vocs.config.tsx
@@ -328,8 +328,11 @@ const config = {
dev: true,
items: [
{ text: 'Overview', link: '/supply-chain/overview', dev: true },
- { text: 'Dependency Awareness', link: '/supply-chain/dependency-awareness', dev: true },
{ text: 'Supply Chain Levels for Software Artifacts', link: '/supply-chain/supply-chain-levels-software-artifacts', dev: true },
+ { text: 'Dependency Awareness', link: '/supply-chain/dependency-awareness', dev: true },
+ { text: 'Web3 Supply Chain Threats', link: '/supply-chain/web3-supply-chain-threats', dev: true },
+ { text: 'Vendor Risk Management', link: '/supply-chain/vendor-risk-management', dev: true },
+ { text: 'Incident Response', link: '/supply-chain/incident-response-supply-chain', dev: true },
]
},
{