Dependency Review

Every dependency added to a project expands its attack surface.

architectureenforced by 1 rule

Context

Every dependency added to a project expands its attack surface. Supply chain attacks — where a malicious actor compromises an npm package — are increasingly common. Packages with postinstall scripts can execute arbitrary code during installation. New dependencies should be reviewed for necessity, maintenance status, and security posture before being added.

Decision

New dependencies must be reviewed before being added to the project. The review should consider whether the dependency is necessary, well-maintained, and free of known vulnerabilities. As an automated baseline, we flag packages with postinstall scripts since those can execute arbitrary code at install time. This is a warning-level rule.

Review new dependencies for necessity — can the functionality be implemented in a few lines?
Check the package's maintenance status, download count, and known vulnerabilities.
Be cautious of packages with lifecycle scripts (postinstall, preinstall).

Do's and Don'ts

Do

Review new dependencies in a dedicated PR comment.
Check https://socket.dev or npm audit for known vulnerabilities.
Prefer well-maintained packages with active security response.
Pin dependency versions or use a lockfile.

Don't

Add dependencies without team review.
Ignore postinstall scripts that download or execute external code.
Add large frameworks when a small utility would suffice.
Skip npm audit or equivalent checks in CI.

Consequences

Positive

Reduces exposure to supply chain attacks.
Keeps the dependency tree lean and maintainable.
Team awareness of what third-party code runs in the project.

Negative

Adding a new dependency requires an extra review step.
Some legitimate packages use postinstall for native compilation.

Enforcement rules

adrs/SEC-003-dependency-review.rules.ts

/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "dependency-review": {
      description:
        "Flag dependencies with postinstall scripts as potential supply chain risks",
      severity: "warning",
      async check(ctx) {
        const pkg = await ctx.readJSON("package.json");
        if (!pkg || typeof pkg !== "object") return;

        const pkgData = pkg as PackageJson;
        const allDeps: Record<string, string> = {
          ...(pkgData.dependencies ?? {}),
          ...(pkgData.devDependencies ?? {}),
        };

        // Check if any dependency's own package.json has lifecycle scripts
        // For now, check the project's own package.json for risky patterns
        const scripts = (pkgData as { scripts?: Record<string, string> })
          .scripts;
        if (scripts) {
          if (scripts.postinstall) {
            ctx.report.warning({
              message:
                "This project has a `postinstall` script — ensure it does not execute untrusted code.",
              file: "package.json",
              fix: "Review the postinstall script and remove it if it is not essential.",
            });
          }
          if (scripts.preinstall) {
            ctx.report.warning({
              message:
                "This project has a `preinstall` script — ensure it does not execute untrusted code.",
              file: "package.json",
              fix: "Review the preinstall script and remove it if it is not essential.",
            });
          }
        }

        // Flag if there are many dependencies (potential bloat)
        const depCount = Object.keys(allDeps).length;
        if (depCount > 100) {
          ctx.report.warning({
            message: `Project has ${depCount} dependencies — consider auditing for unnecessary packages.`,
            file: "package.json",
            fix: "Run `npm audit` and review whether all dependencies are necessary.",
          });
        }
      },
    },
  },
} satisfies RuleSet;