dependency-supply-chain-security

What this skill does

# Dependency & Supply Chain Security

## The Dependency Risk

Your application includes hundreds of npm packages. Each one is code written by someone else that runs in your application **with full privileges**.

### The Statistics Are Sobering

According to Sonatype's 2024 State of the Software Supply Chain Report:

- **245,000 malicious packages** published to npm (2023)
- **700% increase** in supply chain attacks (vs 2022)
- Average application has **200+ dependencies**
- Each dependency averages **5 transitive dependencies** (dependencies of dependencies)

### Real-World Supply Chain Attacks

**event-stream Incident (2018):**
A popular npm package (2 million downloads/week) was hijacked. The attacker added code that stole cryptocurrency wallet keys. **Thousands of applications were affected** before discovery.

**ua-parser-js Incident (2021):**
Package with 8 million weekly downloads was compromised. Attackers added cryptocurrency mining and password-stealing code.

**colors.js / faker.js Incident (2022):**
Maintainer intentionally corrupted packages in protest. Millions of applications broke. Demonstrated single-point-of-failure risk.

## Our Dependency Security Architecture

### Current Status

- ✅ All dependencies up-to-date
- ✅ Next.js 15.5.4 (latest stable)
- ✅ 0 known vulnerabilities (npm audit)
- ✅ Package-lock.json committed (reproducible builds)

### Why Next.js 15.5.4 Specifically

We updated from 15.3.5 to 15.5.4 to fix **three security vulnerabilities:**
- Cache Key Confusion (moderate)
- Content Injection (moderate)
- SSRF via Middleware Redirects (moderate)

**Keeping frameworks updated is critical.** According to Snyk's research, 80% of vulnerabilities have patches available within days, but **average time to patch is 148 days**.

## Implementation Files

- `scripts/security-check.sh` - Runs npm audit + shows outdated packages
- `package-lock.json` - Locks exact versions (supply chain consistency)

## Running Security Audits

### Basic Audit

```bash
# Check for vulnerabilities
npm audit

# Output shows:
# - Severity (critical, high, moderate, low)
# - Vulnerability description
# - Affected package
# - Recommended fix
```

### Production-Only Audit

```bash
# Only check production dependencies (ignores devDependencies)
npm audit --production
```

**Use this before every production deploy.** Must show: **0 vulnerabilities**

### Automated Security Check Script

```bash
# Run our comprehensive security check
bash scripts/security-check.sh
```

**What it does:**
1. Runs `npm audit` (shows vulnerabilities)
2. Runs `npm outdated` (shows outdated packages)
3. Provides fix commands

**Expected output:**
```
=== Security Audit ===
found 0 vulnerabilities

=== Outdated Packages ===
Package    Current  Wanted  Latest  Location
next       15.5.4   15.5.4  15.5.4  node_modules/next

✓ All packages up to date!
```

## Fixing Vulnerabilities

### Automatic Fixes (Safe)

```bash
# Fix vulnerabilities with patch/minor version updates
npm audit fix
```

**What it does:**
- Updates to latest patch version (e.g., 1.2.3 → 1.2.4)
- Updates to latest minor version (e.g., 1.2.3 → 1.3.0)
- **Safe:** No breaking changes

### Force Fixes (Risky)

```bash
# Fix vulnerabilities with major version updates
npm audit fix --force
```

⚠️ **WARNING:** This can introduce breaking changes!

**What it does:**
- Updates to latest major version (e.g., 1.2.3 → 2.0.0)
- **May break your code** if API changed

**After running --force:**
1. Check what changed: `git diff package.json package-lock.json`
2. Read migration guides for updated packages
3. Run tests: `npm test`
4. Test app manually
5. Commit only if everything works

### Manual Updates

```bash
# Update specific package
npm update package-name

# Update to specific version
npm install [email protected]

# Update all packages to latest (respecting semver)
npm update
```

## Dependency Update Strategy

### Monthly Routine (30 minutes)

```bash
# 1. Check for outdated packages
npm outdated

# 2. Review what's outdated and why
# Check changelogs for major updates

# 3. Update safe packages (patch/minor)
npm update

# 4. Run audit
npm audit

# 5. Fix vulnerabilities
npm audit fix

# 6. Test everything
npm test
npm run build

# 7. Commit if successful
git add package.json package-lock.json
git commit -m "chore: update dependencies"
```

### Before Every Production Deploy

```bash
# Must show 0 vulnerabilities
npm audit --production
```

**If vulnerabilities found:**
1. Run `npm audit fix`
2. Test thoroughly
3. If fix causes issues, investigate package alternatives
4. **Never deploy with known vulnerabilities**

### Major Framework Updates (Quarterly)

When Next.js releases major update (e.g., 15.x → 16.x):

```bash
# 1. Read upgrade guide
# https://nextjs.org/docs/upgrading

# 2. Create new branch
git checkout -b upgrade-nextjs-16

# 3. Update Next.js
npm install next@latest react@latest react-dom@latest

# 4. Follow migration guide
# Update deprecated APIs
# Test all features

# 5. Run full test suite
npm test
npm run build
npm run lint

# 6. Test locally
npm run dev
# Click through all features

# 7. Deploy to staging first
# Test in production-like environment

# 8. If successful, deploy to production
```

## Preventing Supply Chain Attacks

### 1. Package-lock.json (Always Commit)

```bash
# Package-lock.json ensures:
# - Exact versions installed
# - Reproducible builds
# - Detect tampering
```

✅ **DO commit package-lock.json to git**

❌ **DON'T add package-lock.json to .gitignore**

### 2. Verify Package Integrity

```bash
# npm automatically verifies package integrity using
# checksums from package-lock.json

# If integrity check fails:
# Error: integrity checksum failed
```

**This protects against:**
- Tampered packages on npm registry
- Man-in-the-middle attacks during download
- Corrupted packages

### 3. Audit New Packages Before Installing

**Before adding a new package:**

1. **Check npm page:** https://www.npmjs.com/package/PACKAGE_NAME
   - Weekly downloads (popular = more vetted)
   - Last update date (recently maintained?)
   - Number of dependents (widely used?)
   - GitHub stars/issues

2. **Check for typosquatting:**
   - `react` ✅ (correct)
   - `raect` ❌ (typo package - could be malicious)
   - `reacct` ❌ (typo package - could be malicious)

3. **Check package maintainers:**
   - Look for verified maintainers
   - Check GitHub profile
   - Multiple maintainers = better

4. **Check GitHub:**
   - Stars (popularity indicator)
   - Open issues (maintained?)
   - Recent commits
   - Code quality

5. **Run audit after installing:**
   ```bash
   npm install new-package
   npm audit
   ```

### 4. Use npm ci for Clean Installs

```bash
# In CI/CD pipelines, use:
npm ci

# Instead of:
npm install
```

**Why `npm ci`:**
- Installs from package-lock.json exactly
- Fails if package.json and package-lock.json are out of sync
- Removes node_modules before installing
- Faster and more reliable for CI/CD

### 5. Avoid Dangerous Packages

**Never install packages that:**
- Have very low download counts (< 100/week)
- Were just published (wait a few weeks)
- Have suspicious names (typosquatting)
- Request unusual permissions
- Have no source code visible

**Examples of dangerous packages (real incidents):**
- `crossenv` (typo of `cross-env` - was malicious)
- `babelcli` (typo of `babel-cli` - was malicious)
- `mongose` (typo of `mongoose` - was malicious)

## Dependency Confusion Attacks

### What It Is

Attacker publishes malicious package with same name as your internal package. npm might install malicious one instead.

### Real Example

```bash
# Internal package (not on npm)
"@mycompany/auth": "1.0.0"

# Attacker publishes to npm
"@mycompany/auth": "99.0.0"

# npm might install attacker's version!
```

### Prevention

1. **Use scoped packages for internal packages:**
   ```json
   {
     "name": "@mycompany/internal-package"
   }
   ```

2. **Configure npm to only use internal registry for your scope:**