From bfc0a09163c4712c5d00eed82d066394f223a20b Mon Sep 17 00:00:00 2001 From: Sara Russo Date: Fri, 7 Aug 2026 18:04:03 +0200 Subject: [PATCH 1/2] Standardization sweep on supply-chain framework --- .../supply-chain/dependency-awareness.mdx | 50 +++++++++---------- .../incident-response-supply-chain.mdx | 36 ++++++------- docs/pages/supply-chain/overview.mdx | 31 ++++++------ ...supply-chain-levels-software-artifacts.mdx | 20 ++++---- .../supply-chain/vendor-risk-management.mdx | 18 +++---- .../web3-supply-chain-threats.mdx | 46 ++++++++--------- 6 files changed, 100 insertions(+), 101 deletions(-) diff --git a/docs/pages/supply-chain/dependency-awareness.mdx b/docs/pages/supply-chain/dependency-awareness.mdx index d7eaf3578..dec493d9e 100644 --- a/docs/pages/supply-chain/dependency-awareness.mdx +++ b/docs/pages/supply-chain/dependency-awareness.mdx @@ -1,6 +1,6 @@ --- title: "Dependency Awareness | Security Alliance" -description: "Manage external dependencies to prevent vulnerabilities. Use version pinning, lockfile verification, vulnerability scanning, and behavioral analysis to secure your project's supply chain." +description: "Manage external dependencies with version pinning, lockfile enforcement in CI, vulnerability scanning, and package trust signals that keep malicious code out." tags: - Engineer/Developer - Security Specialist @@ -16,13 +16,13 @@ import { TagList, AttributionList, ContributeFooter } from '../../../components' -> 🔑 **Key Takeaway:** Every dependency is code you did not write but are fully responsible for. Know exactly what is +> 🔑 **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. ## Fundamentals -### What Is a Dependency? +### What is a dependency? 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 @@ -33,7 +33,7 @@ single developer, and some are actively targeted by attackers. A compromised pac 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). -### Direct and Transitive Dependencies +### Direct and transitive dependencies - **Direct dependencies** are the packages you explicitly add to your project (listed in your `package.json`, `Cargo.toml`, `go.mod`, `requirements.txt`, etc.). @@ -50,7 +50,7 @@ of packages you have never seen. This matters because: 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. -### How Ecosystems Handle Dependency Locking +### How ecosystems handle dependency locking 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 @@ -71,9 +71,9 @@ Not every language or package manager implements locking the same way. Some use 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 | +| 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. | +| **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. | @@ -86,11 +86,11 @@ The core principle is the same regardless of ecosystem: **you need a reproducibl 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 +## Lockfile integrity ### Node.js (npm / pnpm / yarn) -The Node.js ecosystem is the most common in Web3 development: frontends, tooling (Hardhat, Foundry's companion +The Node.js ecosystem is the most common in Web3 development: front ends, 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. @@ -127,7 +127,7 @@ pick it up. 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 +### Cross-ecosystem reference The same principles apply beyond Node.js, though the specific commands and mechanisms differ: @@ -142,7 +142,7 @@ The same principles apply beyond Node.js, though the specific commands and mecha 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 +### 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 @@ -183,7 +183,7 @@ import or use it. This is the primary execution mechanism behind most npm supply 4. **Never run the install command with elevated privileges.** If a script requires `sudo`, that is a red flag. -## Version Pinning +## 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 @@ -191,7 +191,7 @@ maintainers. ### Node.js (npm / pnpm / yarn) -| Strategy | Example | Risk Level | When to Use | +| 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 | @@ -207,12 +207,12 @@ production dependency manifest. > 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 +### 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 | +| 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. | @@ -220,7 +220,7 @@ security-critical, allow ranges only where the tradeoff is justified. | **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 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 @@ -234,13 +234,13 @@ commit SHA ensures that the action you run today is the same one you reviewed: - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 ``` -## Trust and Verification +## 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 +### 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: @@ -302,12 +302,12 @@ who mistype a package name during installation. 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 +## 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 | +| Ecosystem | Built-in / standard tool | Command | | --------- | ---------------------- | ------- | | **Node.js** | `npm audit` / `pnpm audit` | `pnpm audit --audit-level=high` | | **Rust** | `cargo-audit` | `cargo audit` | @@ -316,7 +316,7 @@ databases. Run these in CI and fail builds on high or critical findings. | **Ruby** | `bundler-audit` | `bundle audit check --update` | | **Java** | OWASP Dependency-Check | Gradle/Maven plugin | -### Cross-Ecosystem Tools +### 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 @@ -334,9 +334,9 @@ databases. Run these in CI and fail builds on high or critical findings. > vulnerabilities and updates. The security value comes from reviewing those updates in depth, especially security > patches. -## Ecosystem-Specific Considerations +## Ecosystem-specific considerations -### Smart Contract Dependencies +### 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) @@ -344,7 +344,7 @@ and [Secure Software Development](/secure-software-development/overview) framewo contracts and their imported libraries, see [External Security Reviews for Smart Contracts](/external-security-reviews/smart-contracts/overview). -## Common Pitfalls +## Common pitfalls 1. **Blindly merging dependency update PRs.** Always review what changed, especially across major versions. Check the changelog and release notes before merging. @@ -364,7 +364,7 @@ contracts and their imported libraries, see 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 +## Further reading - [npm Security Best Practices](https://docs.npmjs.com/packages-and-modules/securing-your-code): Official npm security documentation diff --git a/docs/pages/supply-chain/incident-response-supply-chain.mdx b/docs/pages/supply-chain/incident-response-supply-chain.mdx index 6aff5ad74..f6b5ddebe 100644 --- a/docs/pages/supply-chain/incident-response-supply-chain.mdx +++ b/docs/pages/supply-chain/incident-response-supply-chain.mdx @@ -1,6 +1,6 @@ --- 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." +description: "Respond to a compromised dependency or provider: assess exposure, contain the damage, rotate build secrets, and coordinate recovery across front end and contracts." tags: - Security Specialist - SRE @@ -17,7 +17,7 @@ import { TagList, AttributionList, ContributeFooter, Checklist } from '../../../ -> 🔑 **Key Takeaway:** Supply chain incidents move faster than direct compromises. You do not control the affected +> 🔑 **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. @@ -30,9 +30,9 @@ propagate at ecosystem scale, and the window between compromise and discovery is 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 +## How supply chain incidents differ -| Aspect | Direct Compromise | Supply Chain Compromise | +| 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 | @@ -40,7 +40,7 @@ This page focuses on the aspects unique to supply chain compromises. | **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 +## Detection signals Watch for these indicators that a supply chain compromise may have occurred: @@ -53,14 +53,14 @@ Watch for these indicators that a supply chain compromise may have occurred: - **Registry advisories.** npm sends security advisories when a package is flagged, though this can lag behind public disclosure. -## Response Scenarios +## Response scenarios -### Frontend Dependency Compromise +### Front-end dependency compromise This is the most common scenario: a compromised npm package serves malicious JavaScript to users through -your frontend. +your front end. -- **Deploy a clean frontend immediately.** Revert to the last known good build or rebuild without the compromised +- **Deploy a clean front end 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. @@ -69,7 +69,7 @@ your frontend. - **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 +### Smart contract dependency compromise If a Solidity library used in your contracts is found to be vulnerable or malicious: @@ -80,7 +80,7 @@ If a Solidity library used in your contracts is found to be vulnerable or malici - **Plan migration if needed.** Evaluate whether the vulnerability is actively exploitable with your current configuration and plan a new deployment. -### CI/CD Pipeline Compromise +### CI/CD pipeline compromise If the compromised dependency ran during your build process: @@ -91,11 +91,11 @@ If the compromised dependency ran during your build process: - **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 +## Immediate response steps When a compromise is confirmed or credibly suspected: -### Assess Exposure +### Assess exposure - **Check your lockfile.** Is the compromised version present in `pnpm-lock.yaml`, `yarn.lock`, or `package-lock.json`? @@ -103,14 +103,14 @@ When a compromise is confirmed or credibly suspected: - **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 +### 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 +- **Take down compromised deployments.** If a compromised front end 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 @@ -121,7 +121,7 @@ When a compromise is confirmed or credibly suspected: - **Coordinate with the maintainer.** Report the compromise to the package maintainer and to the registry (npm, crates, PyPI). -## Post-Incident Actions +## Post-incident actions Once the immediate threat is contained: @@ -132,7 +132,7 @@ Once the immediate threat is contained: CI? Address any gaps the incident exposed. - **Update your response playbook.** Incorporate lessons learned so the next response is faster. -## Quick-Reference Checklist +## Quick-reference checklist When a supply chain compromise is reported: @@ -149,7 +149,7 @@ When a supply chain compromise is reported: - [ ] Document the incident timeline and run a retrospective. -## Further Reading +## 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 diff --git a/docs/pages/supply-chain/overview.mdx b/docs/pages/supply-chain/overview.mdx index c7b6ede4b..1c51de9f8 100644 --- a/docs/pages/supply-chain/overview.mdx +++ b/docs/pages/supply-chain/overview.mdx @@ -1,6 +1,6 @@ --- title: "Supply Chain Security | Security Alliance" -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." +description: "Secure the dependencies, front-end delivery, infrastructure providers, and build artifacts that sit between your source code and your users in Web3." tags: - Engineer/Developer - Security Specialist @@ -17,25 +17,25 @@ import { TagList, AttributionList, ContributeFooter } from '../../../components' -> 🔑 **Key Takeaway:** Your software is only as secure as its weakest dependency. Supply chain security means knowing +> 🔑 **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 +front-end 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 +target the libraries you import, the CDNs that serve your front end, 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? +## 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 +- **Front-end 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 @@ -43,23 +43,22 @@ A Web3 project's supply chain includes every external component between your sou A compromise at any point in this chain can affect your users. -## What This Framework Covers +## 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 +1. [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. +2. [Dependency Awareness](/supply-chain/dependency-awareness): Manage external packages securely, including version + pinning, lockfile integrity, vulnerability scanning, and protection against typosquatting. +3. [Web3 Supply Chain Threats](/supply-chain/web3-supply-chain-threats): The specific threat vectors that affect Web3 + projects, from front-end library hijacking to infrastructure compromise and hardware tampering. +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 +## Related frameworks Supply chain security intersects with several other areas covered in this project: 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 4e3f5593e..bece81a28 100644 --- a/docs/pages/supply-chain/supply-chain-levels-software-artifacts.mdx +++ b/docs/pages/supply-chain/supply-chain-levels-software-artifacts.mdx @@ -1,6 +1,6 @@ --- title: "Supply Chain Levels for Software Artifacts | SEAL" -description: "Classify software components by risk level and apply proportional security controls to your dependency tree." +description: "Classify software components by risk level, from value-handling libraries down to local build tooling, and apply proportional controls across your dependency tree." tags: - Engineer/Developer - Security Specialist @@ -16,7 +16,7 @@ import { TagList, AttributionList, ContributeFooter } from '../../../components' -> 🔑 **Key Takeaway:** Not every dependency carries the same risk. Apply your strictest controls to components that +> 🔑 **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. @@ -26,9 +26,9 @@ a test framework or a documentation generator. Classification frameworks exist t components carry the most risk, then concentrate your strongest controls there and apply proportionally lighter measures to lower-risk artifacts. -## Risk Classification Framework +## Risk classification framework -### Level 1: Critical Artifacts +### Level 1: critical artifacts 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, @@ -43,7 +43,7 @@ For specific practices, see [Security Testing Framework](/security-testing/overview), and [External Security Reviews Framework](/external-security-reviews/smart-contracts/overview). -### Level 2: High-Risk Artifacts +### Level 2: high-risk artifacts 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 @@ -57,25 +57,25 @@ For dependency management practices, see [Dependency Awareness](/supply-chain/de For CI/CD pipeline security, see [DevSecOps](/devsecops/overview). -### Level 3: Moderate-Risk Artifacts +### 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. -User-facing frontend dependencies that influence wallet connection, transaction construction, signing flows, or -security-critical UI should be treated as high-risk or critical, even if they are "just frontend libraries". +User-facing front-end dependencies that influence wallet connection, transaction construction, signing flows, or +security-critical UI should be treated as high-risk or critical, even if they are "just front-end libraries". 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 +### 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 +## 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 index da2348eb3..db6595e3f 100644 --- a/docs/pages/supply-chain/vendor-risk-management.mdx +++ b/docs/pages/supply-chain/vendor-risk-management.mdx @@ -17,7 +17,7 @@ import { TagList, AttributionList, ContributeFooter } from '../../../components' -> 🔑 **Key Takeaway:** Every provider, auditor, and contractor in your stack is a trust decision you are making on +> 🔑 **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. @@ -26,9 +26,9 @@ CDN providers serve the JavaScript that connects users to wallets. Each of these 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 +## Categories of third-party risk -### Infrastructure Providers +### 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 @@ -36,7 +36,7 @@ Vendor risk management is the practice of making these trust decisions deliberat - **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 +- **Hosting and CDN:** Your front end 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 @@ -44,7 +44,7 @@ Vendor risk management is the practice of making these trust decisions deliberat For real-world incidents involving these providers, see [Web3 Supply Chain Threats](/supply-chain/web3-supply-chain-threats). -### Security Service Providers +### 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 @@ -57,14 +57,14 @@ For real-world incidents involving these providers, see [Web3 Supply Chain Threa For guidance on selecting auditors, see [External Security Reviews](/external-security-reviews/overview). -### Human Supply Chain +### 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 +## Ongoing monitoring Vendor assessment is not a one-time event. Security postures change, ownership changes, and incidents happen. Reassess vendors periodically based on criticality, e.g., at a minimum annually, and quarterly for high-trust relationships. @@ -75,7 +75,7 @@ For every critical vendor, have an exit plan: know which alternative you would m 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 +## Common pitfalls - **Assuming "decentralized" means "no vendor risk."** Even decentralized services have operators, maintainers, and infrastructure that can be compromised. @@ -85,7 +85,7 @@ move quickly during an incident. 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 +## Further reading - [Web3 Supply Chain Threats](/supply-chain/web3-supply-chain-threats): Real-world incidents involving infrastructure and service providers diff --git a/docs/pages/supply-chain/web3-supply-chain-threats.mdx b/docs/pages/supply-chain/web3-supply-chain-threats.mdx index bd87d7cfc..8cfb55c9f 100644 --- a/docs/pages/supply-chain/web3-supply-chain-threats.mdx +++ b/docs/pages/supply-chain/web3-supply-chain-threats.mdx @@ -1,6 +1,6 @@ --- 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." +description: "Web3-specific supply-chain threats with real incidents: front-end and wallet connector attacks, compiler tampering, governance takeovers, RPC and oracle abuse." tags: - Engineer/Developer - Security Specialist @@ -18,20 +18,20 @@ import { TagList, AttributionList, ContributeFooter } from '../../../components' -> 🔑 **Key Takeaway:** Supply chain attacks skip your code entirely. They compromise what your code depends on. A +> 🔑 **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 +## Front-end 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 +the browser, any code that runs on your front end before a user signs a transaction is in a position to manipulate or redirect it. -### NPM Package Compromise +### 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 @@ -58,7 +58,7 @@ For practices to defend against these attacks, see [Dependency Awareness](/suppl For runtime integrity verification using Subresource Integrity and Content Security Policy, see [Third-Party Script Security](/front-end-web-app/third-party-script-security). -### Wallet Connector Library Hijacking +### 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. @@ -74,7 +74,7 @@ For wallet-specific security practices, see the [Wallet Security](/wallet-securi For browser-level controls that would have blocked execution of the tampered library, see [Third-Party Script Security](/front-end-web-app/third-party-script-security). -### CDN and Hosting Compromise +### 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. @@ -90,14 +90,14 @@ For browser-level defenses against CDN and hosting compromise, including Content Subresource Integrity, and self-hosting strategies, see [Third-Party Script Security](/front-end-web-app/third-party-script-security). -## Smart Contract Dependency Risks +## 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 +### 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 @@ -112,7 +112,7 @@ source. 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 +### 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 @@ -120,7 +120,7 @@ bytecode, exfiltrate private keys from the deployer's environment, or alter depl `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 +### 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 @@ -139,7 +139,7 @@ For practices to mitigate these risks, see [DevSecOps](/devsecops/overview), [Security Testing](/security-testing/overview), and [Dependency Awareness](/supply-chain/dependency-awareness). -## Governance Attacks +## 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 @@ -148,7 +148,7 @@ not need to find a bug or tamper with a dependency. They just need enough votes In upgradeable systems, governance is effectively part of the code delivery path. -### Malicious Governance Proposals +### 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 @@ -165,26 +165,26 @@ with the protocol may not notice anything changed until funds are drained. 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 +## 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 provider compromise RPC providers mediate every interaction between your app and the blockchain. The risk has two distinct shapes. A single-RPC dependency exposes you to both, and the integrity case is far harder to detect because nothing looks broken from the outside. 1. **Availability:** a provider goes down and your application goes dark. -2. **Integrity:** a provider returns data that looks valid but isn't — manipulated balances, forged transaction - receipts, stale state — and downstream systems act on it without realizing. +2. **Integrity:** a provider returns data that looks valid but is not, such as manipulated balances, forged + transaction receipts, or stale state, and downstream systems act on it without realizing. Running nodes internally is a possible path to reduce reliance on third parties, but it requires significant resources and a strong security posture to do well. -Availability is addressed by reliable monitoring and automatic failover across independently operated providers — when -one degrades or drops, traffic shifts without manual intervention. +Availability is addressed by reliable monitoring and automatic failover across independently operated providers. +When one degrades or drops, traffic shifts without manual intervention. Integrity is harder. The base defense is cross-validation, applied at increasing strictness: @@ -209,7 +209,7 @@ Integrity is harder. The base defense is cross-validation, applied at increasing 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 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 @@ -229,7 +229,7 @@ attacker only needs to manipulate one data point. 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 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 @@ -255,7 +255,7 @@ 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 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 @@ -276,7 +276,7 @@ could extract keys or alter signing behavior while appearing to function normall For hardware wallet security guidance, see the [Wallet Security](/wallet-security/overview) framework. -## Further Reading +## Further reading - Review your project's dependency tree with the practices described in [Dependency Awareness](/supply-chain/dependency-awareness) From 51ce4d8dbd5515c924f6803b75b52d6e74b163b1 Mon Sep 17 00:00:00 2001 From: Sara Russo Date: Fri, 7 Aug 2026 18:25:54 +0200 Subject: [PATCH 2/2] standardize overview page + add citations + populate wordlist for cspell --- docs/pages/supply-chain/overview.mdx | 17 ++++++- .../web3-supply-chain-threats.mdx | 51 ++++++++++++------- wordlist.txt | 2 + 3 files changed, 51 insertions(+), 19 deletions(-) diff --git a/docs/pages/supply-chain/overview.mdx b/docs/pages/supply-chain/overview.mdx index 1c51de9f8..47b22cb24 100644 --- a/docs/pages/supply-chain/overview.mdx +++ b/docs/pages/supply-chain/overview.mdx @@ -28,7 +28,8 @@ target the libraries you import, the CDNs that serve your front end, the RPC end 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. +have resulted in hundreds of millions of dollars in losses across the Web3 ecosystem, documented case by case in +[Web3 Supply Chain Threats](/supply-chain/web3-supply-chain-threats). ## What makes up a Web3 supply chain? @@ -43,6 +44,10 @@ A Web3 project's supply chain includes every external component between your sou A compromise at any point in this chain can affect your users. +This framework concentrates on the code, delivery, tooling, and provider layers. Hardware integrity is covered in +depth by [Wallet Security](/wallet-security/overview), and the human supply chain by +[DPRK IT Workers](/dprk-it-workers/overview). + ## What this framework covers This framework provides practical guidance for securing each layer of your supply chain: @@ -68,6 +73,16 @@ Supply chain security intersects with several other areas covered in this projec - [External Security Reviews](/external-security-reviews/overview): Selecting and working with security auditors - [Incident Management](/incident-management/overview): General incident response procedures +## Further reading + +- [SLSA](https://slsa.dev/): Build integrity framework defining provenance and hardening levels for build platforms. + Note that SLSA levels describe build assurance, not the artifact criticality tiers used in + [Supply Chain Levels for Software Artifacts](/supply-chain/supply-chain-levels-software-artifacts). +- [NIST SP 800-218, Secure Software Development Framework](https://csrc.nist.gov/pubs/sp/800/218/final): Practices for + producing software with fewer vulnerabilities, including third-party component controls +- [OpenSSF](https://openssf.org/): Working groups and tooling for open source supply chain security, including + Scorecard and Sigstore + --- diff --git a/docs/pages/supply-chain/web3-supply-chain-threats.mdx b/docs/pages/supply-chain/web3-supply-chain-threats.mdx index 8cfb55c9f..ddcaea3ee 100644 --- a/docs/pages/supply-chain/web3-supply-chain-threats.mdx +++ b/docs/pages/supply-chain/web3-supply-chain-threats.mdx @@ -44,9 +44,11 @@ the user's browser. 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. + and the malicious versions were removed within approximately two hours. See + [Wiz's breakdown of the impact and scope](https://www.wiz.io/blog/widespread-npm-supply-chain-attack-breaking-down-impact-scope-across-debug-chalk). - **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. + exfiltrated private keys from any developer or user who installed those versions. See the + [project security advisory](https://github.com/solana-labs/solana-web3.js/security/advisories/GHSA-jcxm-7wvp-g6p5). - **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, @@ -68,6 +70,7 @@ meets transaction construction. - **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. + See [Ledger's incident statement](https://www.ledger.com/blog/a-letter-from-ledger-chairman-ceo-pascal-gauthier-regarding-ledger-connect-kit-exploit). For wallet-specific security practices, see the [Wallet Security](/wallet-security/overview) framework. @@ -110,7 +113,8 @@ source. 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. + produced faulty bytecode from correct source. See the + [LlamaRisk pool reentrancy postmortem](https://hackmd.io/@LlamaRisk/BJzSKHNjn). ### Malicious libraries and plugins @@ -160,10 +164,12 @@ with the protocol may not notice anything changed until funds are drained. - **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. + See [CoinDesk's report on the vote fraud](https://www.coindesk.com/tech/2023/05/21/attacker-takes-over-tornado-cash-dao-with-vote-fraud-token-slumps-40). - **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. + execution could happen in the same block with no time delay. See + [Veridise's analysis of the flash loan governance vulnerability](https://veridise.com/blog/audit-insights/flash_loan_governance_vulnerability_beanstalk_182m/). ## Infrastructure dependency risks @@ -203,11 +209,13 @@ Integrity is harder. The base defense is cross-validation, applied at increasing rsETH. LayerZero's DVN was configured to cross-check across multiple RPCs, but attackers compromised two op-geth nodes and caused the healthy endpoints to be unreachable, forcing the DVN onto the poisoned ones. The incident illustrates that RPC integrity, not just availability, is part of the security boundary for any system that derives - state from off-chain calls. + state from off-chain calls. See + [LayerZero Labs' incident report](https://layerzero.network/blog/layerzero-labs-kelpdao-incident-report). - **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. + but the incident demonstrated how a single provider dependency can take down large portions of the ecosystem. See + [CoinDesk's report](https://www.coindesk.com/tech/2020/11/11/ethereum-service-providers-scramble-to-update-software-after-unannounced-hard-fork). ### Oracle manipulation @@ -221,13 +229,17 @@ 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. +- **Mango Markets (October 2022).** An attacker pumped the MNGO spot price across the thin-liquidity markets feeding + Mango's oracle, then used the inflated collateral value to withdraw over $110 million from the protocol. The + [CFTC charged the trader](https://www.cftc.gov/PressRoom/PressReleases/8647-23) in its first enforcement action + for oracle manipulation. - **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. + oracle, inflating collateral value and draining $130 million in lending assets. See + [Halborn's breakdown of the hack](https://www.halborn.com/blog/post/explained-the-cream-finance-hack-october-2021). - **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. + $1 million total. See samczsun's + [analysis of the undercollateralized loans](https://samczsun.com/taking-undercollateralized-loans-for-fun-and-for-profit/). ### Block explorer API dependence @@ -265,14 +277,17 @@ could extract keys or alter signing behavior while appearing to function normall **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. +- **Trezor Safe 3 vulnerability (2025).** Ledger's Donjon research team demonstrated that voltage glitching can + bypass the Safe 3 authenticity and firmware hash checks, so an attacker with full physical access (during + manufacturing or transit) could load modified firmware that the device still reports as genuine. No private key or + PIN extraction was demonstrated, and the Safe 5 uses a more resilient microcontroller, but the disclosure shows + that hardware supply chain attacks are practical rather than theoretical. See + [Trezor's disclosure of the Donjon evaluation](https://trezor.io/vulnerability/donjon-s-trezor-safe-3-evaluation). +- **Ledger customer database breach (2020).** An unauthorized party accessed Ledger's e-commerce and marketing + database through a third party's API key. Roughly 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. See + [Ledger's statement on the breach](https://www.ledger.com/addressing-the-july-2020-e-commerce-and-marketing-data-breach). For hardware wallet security guidance, see the [Wallet Security](/wallet-security/overview) framework. diff --git a/wordlist.txt b/wordlist.txt index 08ece144f..1fa27eb67 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -33,6 +33,7 @@ CCIP CCPA CCSS Certora +CFTC cicd CIS CISA @@ -375,6 +376,7 @@ UUPS Valimail VDI Vercel +Veridise verifiability verifiably viem