Dependency Audit

ATHELOS depends on hundreds of npm packages. Any one of them could ship a vulnerability. This page covers how to stay on top of it.

The problem

Every dependency is code you didn't write running on your machine. A single compromised or vulnerable package can expose your system.

The supply chain attack surface is real:

• Typosquatting — a malicious package named like a popular one
• Account takeover — a maintainer's npm account compromised
• Malicious updates — a trusted package ships malicious code
• Known CVEs — an old version with a published vulnerability

You can't eliminate the risk. You can manage it.

pnpm audit

pnpm audit checks every installed package against the GitHub Advisory Database and reports known vulnerabilities.

Run it from the repo root:

pnpm audit

Output looks like:

┌─────────────────────┬────────────────────────────────────────┐
│ high                │ Prototype Pollution in lodash          │
├─────────────────────┼────────────────────────────────────────┤
│ Package             │ lodash                                 │
├─────────────────────┼────────────────────────────────────────┤
│ Vulnerable versions │ <4.17.21                               │
├─────────────────────┼────────────────────────────────────────┤
│ Patched versions    │ >=4.17.21                              │
├─────────────────────┼────────────────────────────────────────┤
│ More info           │ https://github.com/advisories/...      │
└─────────────────────┴────────────────────────────────────────┘

Reading the report

Each entry shows:

• Severity — critical, high, moderate, low
• Package — which dependency
• Vulnerable versions — what's affected
• Patched versions — what fixes it
• Advisory link — details on the vulnerability

Focus on critical and high first. Moderate and low can usually wait unless they're reachable in your code.

Fixing vulnerabilities

1. Update the direct dependency

If the vulnerable package is a direct dependency, update it:

pnpm update <package>

This bumps to the latest version within the semver range.

2. Force a resolution

If the vulnerable package is a transitive dependency and the parent hasn't released an update, override it in package.json:

{
  "pnpm": {
    "overrides": {
      "lodash@<4.17.21": "4.17.21"
    }
  }
}

Run pnpm install after.

3. Accept the risk

Sometimes a vulnerability isn't reachable from your code. If:

• The vulnerable function isn't called
• The package is dev-only
• The exploit requires conditions that don't apply

...then you can accept it. Document the decision in a comment or in the repo's security notes.

Automating with Dependabot

GitHub's Dependabot watches your dependencies and opens PRs when updates are available.

Enable it

Create .github/dependabot.yml:

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 10
    groups:
      minor-and-patch:
        patterns:
          - "*"
        update-types:
          - "minor"
          - "patch"
    ignore:
      - dependency-name: "next"
        update-types: ["version-update:semver-major"]

What it does

• Weekly — checks for updates every Monday
• Groups minor/patch — combines small updates into one PR
• Separate major — major versions get their own PR for review
• Ignores major Next.js — because Next.js majors require manual migration

Reviewing Dependabot PRs

Every Dependabot PR:

1. Shows the changelog of the package
2. Runs your CI (if configured)
3. Lists breaking changes for major versions

Review each one. If the changes are minor and CI passes, merge. If they look suspicious, investigate before merging.

Never merge a dependency update blindly. Supply chain attacks happen through updates.

Pinning versions

ATHELOS uses pnpm with a lockfile (pnpm-lock.yaml). The lockfile pins exact versions of every package.

This means:

• pnpm install produces the same node_modules on every machine
• Updates only happen when you run pnpm update or merge a Dependabot PR
• No surprise breakage from a maintainer pushing a new version

Always commit the lockfile. It's the difference between "reproducible" and "hope."

Known good versions

When a package update breaks the build, you have two options:

• Roll back to the previous version until the issue is fixed upstream
• Pin to a working version until upstream stabilizes

Either way, document why in a comment in package.json or in the repo's security notes.

React 19 / Next 15 compatibility

ATHELOS uses React 19 and Next.js 15. Some older packages haven't caught up. When Dependabot proposes a package that requires React 18, ignore it until the package releases a React 19-compatible version.

Watch for peer dependency warnings during pnpm install. They signal incompatibilities before they become failures.

CI integration

If you have GitHub Actions set up, add an audit step:

- name: Audit dependencies
  run: pnpm audit --audit-level=high

This fails the build if a high or critical vulnerability is present. Low and moderate are logged but don't fail.

Running the audit manually

Once a month:

cd /home/kali/soc-solo-os
pnpm audit
pnpm outdated

pnpm audit — vulnerabilities. pnpm outdated — packages with newer versions available.

Review both. Act on what matters.

When to update dependencies

• Security patches — immediately
• Minor versions — weekly or biweekly
• Major versions — when you have time to test thoroughly
• TypeScript / Next.js majors — planned migrations, not reactive

Don't update everything at once. Small, frequent updates are easier to debug than one giant update.

Where to go next

• Scheduled backups — protecting data
• Notifications — alerts on CVEs
• Reference: CLI — the audit script