tacogips/supply-chain-secure-install

Supply Chain Secure Install

This skill provides comprehensive defense-in-depth guidelines for safe package installation with Bun, based on lessons learned from the Shai-Hulud 1.0 (September 2025) and Shai-Hulud 2.0 (November 2025) npm supply chain attacks.

When to Apply

Apply these guidelines when:

• Installing new dependencies (bun add)
• Updating existing dependencies (bun update)
• Setting up CI/CD pipelines that install packages
• Auditing current project dependency security posture
• Reviewing pull requests that modify package.json or lockfiles

Threat Model: Shai-Hulud Attack Vectors

The Shai-Hulud attacks exploited:

| Attack Vector | Description | Countermeasure | |--------------|-------------|----------------| | Lifecycle scripts | preinstall/postinstall scripts execute malicious code on bun install | Bun blocks by default; use trustedDependencies allowlist | | Freshly published packages | Compromised packages published and consumed within hours | minimumReleaseAge in bunfig.toml | | Token theft from .npmrc | Malware reads _authToken from .npmrc files | Never store tokens in project .npmrc; use env vars | | Typosquatting | Fake packages with similar names | Manual review before adding dependencies | | Dependency confusion | Public package replaces private one | Scoped packages + registry configuration | | BYOR (Bring Your Own Runtime) | Attacker installs Bun as evasion technique | Not applicable to Bun projects (already using Bun) |

Lifecycle Script Blocking (Bun Default Behavior)

Bun's most important security advantage over npm/yarn: lifecycle scripts (preinstall, postinstall, prepare) are blocked by default for all third-party packages.

This is the PRIMARY defense against Shai-Hulud. The attack chain depends entirely on preinstall scripts executing setup_bun.js automatically during bun install. With Bun's default behavior, this execution is blocked.

How It Works

| Package Manager | Default Behavior | Shai-Hulud Risk | |----------------|-----------------|-----------------| | npm | ALL lifecycle scripts execute automatically | HIGH - attack succeeds | | yarn | ALL lifecycle scripts execute automatically | HIGH - attack succeeds | | pnpm 10+ | lifecycle scripts disabled by default | LOW - blocked | | Bun | lifecycle scripts blocked by default | LOW - blocked |

In Bun, only packages explicitly listed in trustedDependencies in package.json are allowed to run lifecycle scripts. All other packages' scripts are silently skipped.

What Gets Blocked

// In a compromised package's package.json:
{
  "scripts": {
    "preinstall": "node setup_bun.js",     // BLOCKED by Bun
    "postinstall": "node malicious.js",    // BLOCKED by Bun
    "install": "node compromise.js"        // BLOCKED by Bun
  }
}

Comparison with npm --ignore-scripts

# npm requires explicit flag (easy to forget)
npm install --ignore-scripts

# pnpm 10+ disables by default, but respects .npmrc
# WARNING: Shai-Hulud could manipulate .npmrc to re-enable scripts

# Bun: blocked by default, CANNOT be re-enabled via .npmrc
# Only trustedDependencies allowlist enables scripts
bun install  # Scripts already blocked, no flag needed

IMPORTANT: Bun does NOT respect .npmrc's ignore-scripts setting. This is actually a security advantage -- attackers cannot re-enable scripts by manipulating .npmrc.

Cooldown Period (minimumReleaseAge)

The second critical defense: minimumReleaseAge prevents installation of freshly published package versions.

Why this matters: Shai-Hulud 1.0 (September 2025) was detected in 2.5 hours, and 2.0 (November 2025) in 12 hours. A cooldown period of even 1 day would have completely blocked both attacks.

How it works: When minimumReleaseAge is configured, Bun checks the publish timestamp of each package version. If a version was published more recently than the configured threshold, Bun refuses to install it and falls back to the most recent version that satisfies the age requirement.

bunfig.toml Hardening

Required Configuration

Every project MUST have a bunfig.toml with these security settings:

[install]
# Pin exact versions - no semver ranges
exact = true

# Generate text lockfile for reviewable git diffs
saveTextLockfile = true

# CRITICAL: Minimum age before a package version can be installed
# 259200 = 3 days (Shai-Hulud 1.0 was detected in 2.5 hours)
# 604800 = 7 days (recommended for production projects)
minimumReleaseAge = 259200

# NOTE: Bun blocks lifecycle scripts by default (secure by design)
# Use "trustedDependencies" in package.json to allowlist specific packages

minimumReleaseAge Reference

| Value | Duration | Use Case | |-------|----------|----------| | 86400 | 1 day | Fast-moving development, acceptable risk | | 259200 | 3 days | Standard projects (DEFAULT) | | 604800 | 7 days | Production/commercial projects (RECOMMENDED) | | 1209600 | 14 days | High-security environments |

minimumReleaseAge Exclusions

For packages that require faster updates (e.g., type definitions), use minimumReleaseAgeExcludes in bunfig.toml:

[install]
minimumReleaseAge = 604800

# Packages excluded from release age requirement
minimumReleaseAgeExcludes = [
  "@types/bun",
  "@types/node",
  "typescript"
]

WARNING: Keep the exclusion list minimal. Each exclusion is a potential attack surface.

trustedDependencies Management

Bun blocks lifecycle scripts by default. Only packages listed in trustedDependencies in package.json can run install scripts.

Rules

1. Default to empty array: Start with "trustedDependencies": []
2. Add only when necessary: Only add packages that genuinely need lifecycle scripts
3. Document the reason: Add a comment explaining why each package is trusted
4. Review periodically: Audit the list on a regular cadence

Common Packages Requiring Trust

{
  "trustedDependencies": [
    "esbuild",
    "@swc/core",
    "sharp",
    "better-sqlite3",
    "playwright"
  ]
}

Verification Before Trust

Before adding a package to trustedDependencies:

1. Check the package source: Review the postinstall script on npm/GitHub
2. Check maintenance status: Active maintainers, recent commits, no ownership transfers
3. Check download count: Established packages with high download counts are lower risk
4. Check with Socket.dev: Use npx socket-npm info <package> if available

Lockfile Security

Mandatory Practices

1. Always commit lockfiles: Both bun.lockb (binary) and bun.lock (text) must be in git
2. Review lockfile changes: Text lockfile diffs show exactly what changed
3. Use bun install --frozen-lockfile in CI: Prevents unexpected dependency resolution

CI Pipeline Example

- name: Install dependencies
  run: bun install --frozen-lockfile

Lockfile Integrity Checks

# Verify lockfile is up-to-date without modifying it
bun install --frozen-lockfile

# If this fails, the lockfile is out of sync with package.json
# Developer must run `bun install` locally and commit the updated lockfile

Pre-Install Dependency Review

Before Adding a New Package

Run these checks before bun add <package>:

# 1. Check package info on npm
bun pm info <package>

# 2. Check for known vulnerabilities
bun audit

# 3. Review the package on npm website
# Check: maintainers, last publish date, weekly downloads, dependencies count

# 4. Check for typosquatting
# Verify the exact package name matches the official one
# Common tricks: lodash vs 1odash, express vs expresss

Red Flags During Review

| Red Flag | Risk | |----------|------| | Published less than 7 days ago | Potentially compromised freshly published package | | Single maintainer | Higher risk of account compromise | | Very few downloads | Potential typosquatting | | Excessive dependencies | Larger attack surface | | Recent ownership change | Possible account takeover | | No source repository linked | Cannot verify code matches published package | | preinstall / postinstall scripts | Arbitrary code execution during install | | Minified/obfuscated code in npm package | Hiding malicious behavior |

CI/CD Pipeline Security

Secure Installation in CI

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read  # Minimal permissions
    steps:
      - uses: actions/checkout@<SHA>
        with:
          persist-credentials: false

      - uses: oven-sh/setup-bun@<SHA>
        with:
          bun-version: latest

      # CRITICAL: frozen lockfile prevents supply chain manipulation
      - name: Install dependencies
        run: bun install --frozen-lockfile

      # Run audit after install
      - name: Security audit
        run: bun audit

Environment Variable Protection in CI

# NEVER expose npm tokens as environment variables accessible to all steps
# Use step-level env only where needed

# BAD
env:
  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

# GOOD - only expose to the step that needs it
steps:
  - name: Publish
    env:
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
    run: bun publish

.npmrc Security

Project-Level .npmrc

The project .npmrc should NEVER contain auth tokens:

# .npmrc - safe settings only
registry=https://registry.npmjs.org/
# Do NOT put _authToken here

.gitignore

Ensure .npmrc with tokens is never committed:

# User-level .npmrc may contain tokens
.npmrc.local

Token Storage

| Environment | Where to Store Tokens | |------------|----------------------| | Local development | ~/.npmrc (user home, NOT project) | | CI/CD | Environment variables / secrets manager | | Docker | Build args or runtime secrets |

Periodic Audit Checklist

Run these checks regularly (weekly or per-sprint):

# 1. Check for known vulnerabilities
bun audit

# 2. Check for outdated packages
bun outdated

# 3. Verify lockfile integrity
bun install --frozen-lockfile

# 4. Review trustedDependencies list
# Ensure each entry is still necessary

CI/CD Environment Hardening

Shai-Hulud 2.0 detects CI/CD environments by checking for specific environment variables (GITHUB_ACTIONS, BUILDKITE, PROJECT_ID, CODEBUILD_BUILD_NUMBER, CIRCLE_SHA1). When detected, it runs in foreground mode for maximum credential extraction during the build window.

GitHub Actions Hardening

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 15  # Prevent long-running malicious processes
    permissions:
      contents: read  # MINIMUM permissions
      # Do NOT add: actions: write, administration, workflows
    steps:
      - uses: actions/checkout@<SHA>  # Always pin to SHA
        with:
          persist-credentials: false  # Prevent token leakage

      - uses: oven-sh/setup-bun@<SHA>  # Pin to SHA
        with:
          bun-version: latest

      # CRITICAL: frozen lockfile in CI
      - name: Install dependencies
        run: bun install --frozen-lockfile

      # Audit after install
      - name: Security audit
        run: bun audit

      # Tests and build
      - name: Test
        run: bun test
      - name: Build
        run: bun run build

CI Environment Variable Protection

# BAD: Global env exposes tokens to ALL steps (including compromised dependencies)
env:
  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
  AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}

# GOOD: Step-level env exposes tokens ONLY to the step that needs them
steps:
  - name: Install (no secrets needed)
    run: bun install --frozen-lockfile
    # NO env: block - compromised dependency cannot access secrets

  - name: Deploy (needs secrets)
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
    run: bun run deploy

Restrict Network Egress in CI

# Use GitHub Actions network restrictions (if available)
# Or use a custom container with restricted networking

jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: your-org/restricted-build-image
      # Container with iptables rules blocking non-essential outbound

Prevent Workflow Injection

Shai-Hulud creates discussion.yaml and add-linter-workflow-* branches:

# Branch protection rules (via GitHub settings):
# - Require PR reviews before merging
# - Require status checks
# - Restrict push to main branch
# - Require signed commits

# In workflow: only trigger on trusted events
on:
  push:
    branches: [main]  # NOT on all branches
  pull_request:
    branches: [main]  # NOT pull_request_target

Monitor for Unauthorized Workflow Changes

# In CI: verify no unexpected workflows were added
git diff origin/main -- .github/workflows/
# Fail the build if unexpected workflow files appear

Emergency Response: Suspected Compromise

If you suspect a dependency has been compromised:

1. Do NOT run bun install on the affected project
2. Check the specific package version against known compromised lists
3. Review bun.lock (text) for unexpected version changes
4. Rotate ALL tokens (npm, GitHub, cloud providers) if lifecycle scripts were executed
5. Report the issue to npm security and the package maintainers
6. Pin to a known-good version in package.json with exact version

References

• Bun bunfig.toml documentation
• Shai-Hulud 2.0 - Trend Micro Analysis
• PostHog Shai-Hulud Post-Mortem
• Datadog Shai-Hulud 2.0 Analysis
• Socket.dev - Package Security