npm - High Risk:

• postinstall, preinstall, install scripts execute automatically with full user privileges
• No sandboxing by default
• Widely exploited in recent attacks (Shai-Hulud, multiple other campaigns)
• Scripts can access environment variables, filesystem, network without restriction

pip - Medium-High Risk:

• setup.py executes arbitrary Python code during installation
• Setuptools/distutils hooks (install, develop) run with user privileges
• Newer PEP 517/518 builds still execute build backends
• Slightly lower than npm because Python ecosystem has fewer packages with complex build requirements proportionally

Maven/Gradle - Medium Risk:

• Maven plugins (especially exec-maven-plugin, maven-antrun-plugin) can execute arbitrary code
• Gradle build scripts are executable Groovy/Kotlin code
• Risk mitigated somewhat by enterprise controls and more mature ecosystem practices
• Less frequently targeted than npm/PyPI (smaller attacker ROI)

Go - No Risk:

• Go modules fundamentally don't support install-time scripts
• All code execution happens at compile time, which is more visible
• This design decision eliminates an entire attack class

npm, pip, Maven - Enabled by default:

• All three execute lifecycle/build scripts automatically
• Users must explicitly opt out (--ignore-scripts, --no-build-isolation, etc.)
• This "default unsafe" posture contributes significantly to attack success rates (thus making the ecosystem more attractive for malicious actors)

Go - N/A: No such concept exists

npm, pip, Maven - None:

• Install scripts run with the same privileges as the user running the package manager
• No filesystem isolation, network isolation, or capability restrictions
• Third-party tools (containers, bubblewrap, etc.) required for sandboxing

Go - N/A: No install scripts to sandbox

npm - Yes, mandatory for popular packages:

• 2FA required for packages with >1M weekly downloads
• Hardware key support (FIDO2/WebAuthn)
• Granular token scopes

PyPI - Yes:

• 2FA available for all accounts
• API tokens with scopes
• Increasingly encouraged by ecosystem

Maven - Limited:

• Maven Central uses Sonatype OSSRH
• Basic authentication, 2FA available but not enforced
• Enterprise repositories (Artifactory, Nexus) have better support

Go - Via hosting provider:

• No central registry like npm/PyPI
• Authentication depends on where modules are hosted (GitHub, GitLab, Bitbucket, etc.)
• Most Go modules use GitHub which supports 2FA, hardware keys
• Private modules use git authentication mechanisms

Maven - Yes:

• Central Repository supports GPG-signed artifacts
• Organizations can enforce signature verification
• Not widely adopted but infrastructure exists

Go - Integrity checks only (not signing):

• go.sum provides cryptographic checksums that ensure build reproducibility and detect tampering during transit or in cache
• Critical limitation: Checksums verify what was downloaded matches what was published, but provide no guarantee that who published it was authorized or legitimate
• sum.golang.org module proxy acts as a transparency log, making it harder to serve different content to different users
• Does not prevent supply chain attacks via compromised maintainer accounts (the primary threat vector)

npm - Limited:

• npm 9+ supports package signatures via npm audit signatures
• Not widely adopted; many packages unsigned
• Infrastructure exists but ecosystem adoption is low

pip - No:

• No native package signing support
• Some distributions (Debian, etc.) sign their own Python packages
• PyPI itself doesn't enforce or facilitate signing

npm, pip - Weak:

• First-come-first-served package names
• No verification of ownership/legitimacy
• Enables typosquatting and namespace confusion attacks
• Once you own a name, you own it (barring trademark disputes)

Maven - Strong:

• Group IDs follow reverse domain notation (com.company.project)
• Repository operators can verify domain ownership
• Significantly harder to squat legitimate namespace
• Enterprise repositories can enforce additional controls

Go - Strong:

• Imports use full URLs including domain (github.com/user/repo)
• Domain ownership verification implicit in module system
• Typosquatting requires domain registration
• More resistant to namespace confusion

Go - Excellent:

• go mod graph shows complete dependency graph
• go.sum includes checksums for all transitive dependencies
• Excellent tooling for analyzing dependency trees

Maven - Good:

• mvn dependency:tree provides clear transitive visibility
• Well-established ecosystem tools (dependency-check, etc.)
• pom.xml structure makes relationships explicit

npm, pip - Medium:

• npm ls, pip show work but output can be overwhelming
• Transitive dependencies less visible in manifests
• Requires additional tooling for effective analysis

npm configuration:

# One-time installations
npm ci --ignore-scripts
npm install --ignore-scripts

# Permanent configuration in .npmrc
echo "ignore-scripts=true" >> .npmrc

# Configuration check
npm config get ignore-scripts

WARNING: --ignore-scripts will break packages requiring native compilation like node-sass, sharp, sqlite3, node-gyp, fsevents, canvas, bcrypt, etc.
How to deal with those:

1. Use pnpm v10+ with onlyBuiltDependencies allowlist
2. Build native modules in separate sandboxed step
3. Use pre-built binaries where available

pnpm (recommended):
pnpm v10+ blocks lifecycle scripts by default and requires explicit approval for packages with build steps. This protection can be relaxed by config and may need per-package allows for native modules.

For pnpm v10+

// package.json - allow specific packages to run scripts
{
  "pnpm": {
    "onlyBuiltDependencies": ["esbuild", "puppeteer", "sqlite3"]
  }
}

Interactive approval workflow (pnpm v10+):

pnpm install
pnpm approve-builds           # approve interactively
pnpm approve-builds esbuild   # or per-package
pnpm ignored-builds           # review what's been blocked

Use pnpm approve-builds to curate the allowlist and pnpm ignored-builds to review what’s blocked. .pnpmfile.cjs still works in v10; disable it with --ignore-pnpmfile if you need a fully inert install.

Verification (pnpm v10+):

# List packages with lifecycle scripts in your tree
pnpm list --json --depth Infinity | jq -r '
  .. | objects | select(has("scripts")) | .name + "@" + .version
'

# Verify install works with blocks applied in CI
pnpm install --ignore-scripts --frozen-lockfile

For pnpm v9 and earlier (scripts run by default - manual blocking needed):

# .npmrc
# Block all scripts by default
ignore-scripts=true

Then use .pnpmfile.cjs for allowlist (when some packages need scripts):

// .pnpmfile.cjs
function readPackage(pkg) {
  const allowedPackages = ['esbuild', 'puppeteer', 'node-sass'];
  
  if (!allowedPackages.includes(pkg.name)) {
    // Remove scripts for non-allowed packages
    pkg.scripts = {};
  }
  
  return pkg;
}

module.exports = {
  hooks: {
    readPackage
  }
};

Important: If your project requires pnpm v9 or earlier (pre-v10 behavior), you can restore script execution with:

{
  "pnpm": {
    "neverBuiltDependencies": []
  }
}

⚠️ Not recommended - this disables the security protection.

Verification:

# Check which packages have lifecycle scripts
npm explore <package-name> -- cat package.json | jq '.scripts'

# Audit all dependencies for scripts
# Huge trees can possibly be hard for jq (--depth flag can help)
npm ls --json --depth=3 | jq '.. | .scripts? | select(. != null)'

References:

• npm ignore-scripts documentation
• pnpm security features
• nodejs-security.com best practices

Implementation:

# Use npm ci to enforce lockfile
npm ci

# Generate initial lockfile
npm install --package-lock-only
    
#!! if you generate a lockfile (without installing) using the above command, then any preinstall script enforcing cooldown won't be executed. The generated lockfile could later be blocked in CI due to cooldown enforcement. The cooldown script provided later can be adjusted to check lockfile generated with npm install --package-lock-only to avoid such issue.  

In package.json, use exact versions:

{
  "dependencies": {
    "express": "4.18.2",          // ✓ Exact version
    "lodash": "4.17.21"           // ✓ Exact version
  },
  "devDependencies": {
    "typescript": "5.3.3"         // ✓ Exact version
  }
}

// Avoid these:
{
  "dependencies": {
    "express": "^4.18.0",         // ✗ Allows 4.x.x updates
    "lodash": "~4.17.21",         // ✗ Allows 4.17.x updates
    "axios": "*",                 // ✗ Allows any version
    "react": "latest"             // ✗ Always uses newest
  }
}

CI/CD enforcement:

# GitHub Actions
name: Verify Dependencies
on: [pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Verify lockfile integrity
        run: npm ci
      - name: Check for floating versions (exact JSON)
        run: |
          node -e '
            const fs = require("fs");
            const pj = JSON.parse(fs.readFileSync("package.json","utf8"));
            const bad = [];
            for (const key of ["dependencies","devDependencies","optionalDependencies","peerDependencies"]) {
              if (!pj[key]) continue;
              for (const [name, ver] of Object.entries(pj[key])) {
                if (/^[~^*]|latest$/i.test(ver.trim())) bad.push(`${key}:${name}@${ver}`);
              }
            }
            if (bad.length) {
              console.error("Floating versions detected:\\n" + bad.join("\\n"));
              process.exit(1);
            }
          '
      - name: Ensure lockfile is committed
        run: |
          if ! git ls-files --error-unmatch package-lock.json > /dev/null 2>&1; then
            echo "::error::package-lock.json is not committed to git"
            echo "Lockfiles must be committed to version control for reproducible builds"
            exit 1
          fi

Note on grep logic: Can flag comments/strings. For a bulletproof check, parse JSON in a tiny Node script; This grep is fine for most repos.

Important difference from Yarn:

• npm ci: Enforces lockfile by default (no flag needed)
• yarn: Requires explicit yarn install --frozen-lockfile flag
• pnpm: Uses --frozen-lockfile flag or auto-detects CI environment

References:

• npm ci documentation
• Package-lock.json documentation

pnpm native support:

# .npmrc
# Delay installation of packages published less than 7 days ago
minimum-release-age=10080  # 7 days in minutes (7 * 24 * 60)

Renovate bot configuration:

// renovate.json (JSONC allowed)
{
  "extends": ["config:base"],
  "dependencyDashboard": true,
  "packageRules": [
    {
      "description": "npm default cooldown and PR gating",
      "matchManagers": ["npm"],
      "stabilityDays": 7,
      // Choose ONE of these:
      // "prCreation": "status-success", // wait for CI green, then open PR
      "prCreation": "not-pending"       // open PR once checks aren't pending
    },
    {
      "description": "npm security updates bypass cooldown",
      "matchManagers": ["npm"],
      "matchUpdateTypes": ["security"],
      "stabilityDays": 0
    }
  ]
}

Note: Removing "matchManagers" on either rule makes it global across ecosystems. That’s fine if you want uniform behavior everywhere.

Guardrail: If you enable both minimumReleaseAge and stabilityDays globally, set minimumReleaseAge shorter than stabilityDays (for example, 3d + 4d). If minimumReleaseAge >= stabilityDays on fast-moving deps, Renovate can starve updates entirely.

Understanding Renovate timing options:

Important: Use stabilityDays instead of minimumReleaseAge to avoid blocking frequently-updated packages:

• stabilityDays: Waits X days after a version is published before creating a PR for that specific version

  • Works with frequently-updated packages (will propose older stable version)
  • If package updates daily, Renovate will propose the version from 7 days ago
  • Provides cooldown window while allowing updates to flow through

• minimumReleaseAge: Filters out ALL versions newer than X days

  • !! Can deadlock frequently-updated packages (if package updates daily with 7-day setting, NO version is ever old enough)
  • !! More aggressive but can prevent any updates for active projects

Recommended approach:

// For most projects - use stabilityDays only
{
  "stabilityDays": 7
}

// For high-security environments - use both with careful tuning
{
  "minimumReleaseAge": "3 days",   // Shorter window
  "stabilityDays": 4               // Total: 7 days but avoids deadlock for weekly updates
}

Example scenario:

Package "fastify" releases daily:
- Jan 1: v4.0.0 published
- Jan 2: v4.0.1 published
- Jan 3: v4.0.2 published
...
- Jan 8: v4.0.7 published (latest)

With stabilityDays=7:
- Renovate will propose v4.0.1 (published 7 days ago)
- Updates flow through with appropriate delay

With minimumReleaseAge=7:
- No version is old enough (latest is always <7 days)
- No PRs ever created - deadlock!

Renovate bot configuration:

// renovate.json (JSONC allowed)
{
  "extends": ["config:base"],
  "dependencyDashboard": true,
  "packageRules": [
    {
      "description": "npm default cooldown and PR gating",
      "matchManagers": ["npm"],
      "stabilityDays": 7,
      // Choose ONE of these:
      // "prCreation": "status-success", // wait for CI green, then open PR
      "prCreation": "not-pending"       // open PR once checks aren't pending
    },
    {
      "description": "npm security updates bypass cooldown",
      "matchManagers": ["npm"],
      "matchUpdateTypes": ["security"],
      "stabilityDays": 0
    }
  ]
}

Note: Removing "matchManagers" on either rule makes it global across ecosystems. That's fine if you want uniform behavior everywhere.

Guardrail: If you enable both minimumReleaseAge and stabilityDays globally, set minimumReleaseAge shorter than stabilityDays (for example, 3d + 4d). If minimumReleaseAge >= stabilityDays on fast-moving deps, Renovate can starve updates entirely.

Understanding Renovate timing options:

Important: Use stabilityDays instead of minimumReleaseAge to avoid blocking frequently-updated packages:

• stabilityDays: Waits X days after a version is published before creating a PR for that specific version

  • Works with frequently-updated packages (will propose older stable version)
  • If package updates daily, Renovate will propose the version from 7 days ago
  • Provides cooldown window while allowing updates to flow through

• minimumReleaseAge: Filters out ALL versions newer than X days

  • Can deadlock frequently-updated packages (if package updates daily with 7-day setting, NO version is ever old enough)
  • More aggressive but can prevent any updates for active projects

Recommended approach:

// For most projects - use stabilityDays only
{
  "stabilityDays": 7
}

// For high-security environments - use both with careful tuning
{
  "minimumReleaseAge": "3 days",   // Shorter window
  "stabilityDays": 4               // Total: 7 days but avoids deadlock for weekly updates
}

Example scenario:

Package "fastify" releases daily:
- Jan 1: v4.0.0 published
- Jan 2: v4.0.1 published
- Jan 3: v4.0.2 published
...
- Jan 8: v4.0.7 published (latest)

With stabilityDays=7:
- Renovate will propose v4.0.1 (published 7 days ago)
- Updates flow through with appropriate delay

With minimumReleaseAge=7:
- No version is old enough (latest is always <7 days)
- No PRs ever created - deadlock!

Dependabot configuration:

Dependabot's cooldown feature is generally available as of July 2025 and provides native support for delaying PR creation after new dependency releases are published.

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    
    # Native cooldown support - delays PR creation for new releases
    cooldown:
      default-days: 7              # Base cooldown for all updates
      semver-major-days: 30        # Cooldown for major version updates
      semver-minor-days: 7         # Cooldown for minor version updates
      semver-patch-days: 3         # Cooldown for patch version updates
      
      # Apply to specific dependencies
      include:
        - "*"                      # All dependencies
      exclude:
        - "@types/*"               # Type definitions excluded
        - "eslint*"                # Dev tooling excluded

Key features:

• Cooldown delays PR creation for a specified number of days after a dependency version is published
• Configure different cooldown periods based on semantic version update type (major/minor/patch)
• Use include to apply cooldown to specific dependencies or "*" for all dependencies
• Cooldown days must be between 1 and 90; include/exclude lists support up to 150 items each
• Available for all supported package ecosystems (npm, pip, bundler, composer, cargo, etc.)
• The exclude list always takes precedence over the include list

Critical constraints:

• If semver-major-days, semver-minor-days, or semver-patch-days are not defined, the default-days setting applies
• Cooldown affects both version updates AND security updates to manifest files, unless target-branch is used for non-default branch updates
• If a dependency appears in both include and exclude lists, it is excluded from cooldown

Cooldown behavior:

Dependabot checks for updates according to the defined schedule. When a new version is published, Dependabot skips creating a PR until the cooldown period has elapsed. After the cooldown ends, Dependabot creates a PR for the latest version that is past its cooldown period.

Package "fastify" releases daily:
- Jan 1: v4.0.0 published
- Jan 2: v4.0.1 published
- Jan 3: v4.0.2 published
...
- Jan 8: v4.0.7 published (latest)
- Jan 15: v4.0.14 published (latest)

With cooldown default-days=7:
- Jan 8: No PR created (v4.0.7 is only 1 day old)
- Jan 15: PR created for v4.0.7 (now 7+ days old)
- Jan 22: PR created for v4.0.14 (now 7+ days old)

Result: Updates are delayed but eventually propose the latest version

Basic configuration (all dependencies):

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    cooldown:
      default-days: 7
      # Omitting 'include' applies to all dependencies

Advanced configuration (targeted dependencies with exclusions):

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    
    # Conservative cooldown for most dependencies
    cooldown:
      default-days: 14
      semver-major-days: 30      # Extra caution for breaking changes
      semver-minor-days: 7       # Moderate for feature additions
      semver-patch-days: 3       # Quick turnaround for bug fixes
      include:
        - "*"                    # Apply to all dependencies
      exclude:
        - "@types/*"             # Type definitions can update immediately
        - "eslint*"              # Dev tooling can update immediately
        - "*-security-*"         # Security packages bypass cooldown

Handling security-critical packages:

Since cooldown affects both version and security updates, use the exclude list to exempt packages that should update immediately:

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    cooldown:
      default-days: 7
      include:
        - "*"
      exclude:
        - "@security/*"          # All security-scoped packages

Comparison: Renovate stabilityDays vs Dependabot cooldown:

Both Renovate's stabilityDays and Dependabot's cooldown provide protection against supply-chain attacks by delaying dependency updates, but they differ in their approach:

Renovate stabilityDays: Proposes a version from X days ago. When a package releases daily, Renovate will propose the version published 7 days ago, even if newer versions exist. This ensures you're always installing a version that has aged, but means you may skip intermediate versions.

Dependabot cooldown: Delays proposing the latest version until it is X days old. When a package releases daily, Dependabot waits 7 days after each version's publication before creating a PR. This means you eventually get the latest version, but with a built-in waiting period.

Implications for frequently-updated packages:

Neither approach creates deadlocks with frequently-updated packages. Renovate continuously proposes older versions, while Dependabot queues updates with appropriate delays. Both strategies provide effective protection while maintaining dependency freshness.

Recommendation: For supply-chain security, both tools are effective. Choose based on your preference:

• Renovate's stabilityDays if you prefer always installing battle-tested older versions
• Dependabot's cooldown if you prefer eventual latest versions with a security delay

For high-security environments, consider combining either tool with additional validation checks (such as npm preinstall hooks) to enforce cooldown periods even when lock files are generated manually.

Integration with pnpm minimumReleaseAge:

If using both Dependabot cooldown and pnpm's minimumReleaseAge, ensure they're coordinated:

# .github/dependabot.yml
cooldown:
  default-days: 7

# .npmrc
minimum-release-age=10080  # 7 days in minutes

# Both will enforce 7-day minimum, with pnpm providing
# an additional safeguard during manual installations

Custom solution using npm hooks:

// preinstall-cooldown.js
console.log('Preinstall hook for cooldown triggered');
const { execSync } = require('child_process');
const fs = require('fs');
const path = require('path');

// Configuration
const COOLDOWN_DAYS = 7;
const CACHE_FILE = path.join(process.cwd(), '.npm-cooldown-cache.json');
const CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
const CACHE_MAX_ENTRIES = 1000;

// In-memory cache for current run
const cache = new Map();

// Load persistent cache from disk
function loadPersistentCache() {
  try {
    if (fs.existsSync(CACHE_FILE)) {
      const cacheData = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
      const now = Date.now();
      
      // Filter out expired entries and load valid ones
      let loadedCount = 0;
      for (const [key, entry] of Object.entries(cacheData)) {
        if (now - entry.timestamp < CACHE_MAX_AGE_MS) {
          cache.set(key, entry.result);
          loadedCount++;
        }
      }
      
      if (loadedCount > 0) {
        console.log(`Loaded ${loadedCount} cached results from ${CACHE_FILE}`);
      }
    }
  } catch (error) {
    console.warn(`Failed to load cache from ${CACHE_FILE}: ${error.message}`);
    // Continue without cache - not a fatal error
  }
}

// Save cache to disk
function savePersistentCache() {
  try {
    const cacheData = {};
    const now = Date.now();
    let savedCount = 0;
    
    // Convert Map to object format with timestamps
    // Limit to most recent CACHE_MAX_ENTRIES to prevent unbounded growth
    const entries = Array.from(cache.entries())
      .slice(-CACHE_MAX_ENTRIES);
    
    for (const [key, result] of entries) {
      cacheData[key] = {
        result: result,
        timestamp: now
      };
      savedCount++;
    }
    
    fs.writeFileSync(CACHE_FILE, JSON.stringify(cacheData, null, 2));
    console.log(`Saved ${savedCount} results to cache file`);
  } catch (error) {
    console.warn(`Failed to save cache to ${CACHE_FILE}: ${error.message}`);
    // Non-fatal - cache is optimization, not requirement
  }
}

function resolveVersion(name, spec, lock) {
  console.log(`Resolving version for ${name}@${spec}`);
  let resolvedVersion;
  if (lock) {
    const pkgKey = `node_modules/${name}`;
    resolvedVersion = lock.packages[pkgKey]?.version;
    console.log(`Lockfile version for ${name}: ${resolvedVersion || 'none'}`);
  }

  if (!resolvedVersion) {
    try {
      // Add timeout to prevent hanging
      resolvedVersion = execSync(`npm view ${name}@${spec || 'latest'} version`, {
        timeout: 10000  // 10 second timeout
      }).toString().trim();
      console.log(`Resolved version via npm view: ${resolvedVersion}`);
    } catch (error) {
      throw new Error(`Failed to resolve version for ${name}@${spec}: ${error.message}`);
    }
  }
  return resolvedVersion;
}

function checkPackageAge(name, version) {
  const cacheKey = `${name}@${version}`;
  
  // Check cache first
  if (cache.has(cacheKey)) {
    console.log(`Using cached result for ${cacheKey}`);
    return cache.get(cacheKey);
  }

  console.log(`Checking age for ${name}@${version}`);
  try {
    // Add timeout and retry logic
    let timeOutput;
    const maxRetries = 3;
    
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      try {
        timeOutput = execSync(`npm view ${name}@${version} time --json`, {
          timeout: 10000  // 10 second timeout
        }).toString().trim();
        break;
      } catch (error) {
        if (attempt === maxRetries) {
          console.warn(`WARNING: Failed to check age for ${name}@${version} after ${maxRetries} attempts`);
          console.warn(`Allowing installation - manual review recommended`);
          cache.set(cacheKey, true);
          return true;  // Fail open on network issues
        }
        console.log(`Retry ${attempt}/${maxRetries} for ${name}@${version}`);
        // Simple delay between retries
        execSync(`sleep 1`);
      }
    }

    let timeData;
    try {
      timeData = JSON.parse(timeOutput);
    } catch (parseError) {
      console.warn(`WARNING: Failed to parse time JSON for ${name}@${version}`);
      cache.set(cacheKey, true);
      return true;  // Fail open on parse errors
    }

    let publishDateStr = timeData[version];
    if (!publishDateStr) {
      publishDateStr = timeData.modified;
      console.log(`Version-specific date missing; using modified: ${publishDateStr}`);
    }

    if (!publishDateStr) {
      console.warn(`WARNING: No publish date available for ${name}@${version}`);
      cache.set(cacheKey, true);
      return true;  // Fail open if no date
    }

    const publishDate = new Date(publishDateStr);
    console.log(`Parsed publish date: ${publishDate}`);

    if (isNaN(publishDate.getTime())) {
      console.warn(`WARNING: Invalid publish date for ${name}@${version}: ${publishDateStr}`);
      cache.set(cacheKey, true);
      return true;  // Fail open on invalid date
    }

    const daysSincePublish = (Date.now() - publishDate.getTime()) / (1000 * 60 * 60 * 24);
    console.log(`Days since publish for ${name}@${version}: ${daysSincePublish.toFixed(1)}`);

    if (daysSincePublish < COOLDOWN_DAYS) {
      const result = false;
      cache.set(cacheKey, result);
      throw new Error(
        `Package ${name}@${version} was published ${daysSincePublish.toFixed(1)} days ago. ` +
        `Minimum age: ${COOLDOWN_DAYS} days. Rejecting installation.`
      );
    }

    console.log(`Package ${name}@${version} is ${daysSincePublish.toFixed(1)} days old. Approved.`);
    cache.set(cacheKey, true);
    return true;
  } catch (error) {
    // If we already cached the result, rethrow
    if (cache.has(cacheKey) && !cache.get(cacheKey)) {
      throw error;
    }
    // Otherwise log and fail open
    console.warn(`WARNING: Error checking ${name}@${version}: ${error.message}`);
    cache.set(cacheKey, true);
    return true;
  }
}

function main() {
  console.log('Reading package.json and lockfile');
  const pkgPath = path.join(process.cwd(), 'package.json');
  if (!fs.existsSync(pkgPath)) {
    console.error('package.json not found');
    process.exit(1);
  }
  const pkg = require(pkgPath);

  let lock = null;
  const lockPath = path.join(process.cwd(), 'package-lock.json');
  if (fs.existsSync(lockPath)) {
    lock = require(lockPath);
    console.log('package-lock.json found');
  } else {
    console.log('No package-lock.json found');
  }

  // Load persistent cache at start
  loadPersistentCache();

  // Track checked packages to avoid duplicates
  const checkedPackages = new Set();

  // Check transitive dependencies from package-lock.json
  if (lock && lock.packages) {
    Object.entries(lock.packages).forEach(([pkgKey, pkgData]) => {
      if (pkgKey && pkgData.version) {
        const name = pkgKey.replace(/^node_modules\//, '');
        const version = pkgData.version;
        const cacheKey = `${name}@${version}`;
        if (name && !checkedPackages.has(cacheKey)) {
          console.log(`Checking lockfile package: ${name}@${version}`);
          checkPackageAge(name, version);
          checkedPackages.add(cacheKey);
        }
      }
    });
  }

  // Check top-level dependencies from package.json
  const depTypes = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
  let hasDeps = false;

  depTypes.forEach(type => {
    const deps = pkg[type] || {};
    if (Object.keys(deps).length > 0) {
      hasDeps = true;
    }
    Object.entries(deps).forEach(([name, spec]) => {
      console.log(`Processing ${type}: ${name}@${spec}`);
      if (spec.startsWith('file:') || spec.startsWith('git:') || spec.startsWith('http:') || spec.startsWith('https:')) {
        console.log(`Skipping non-registry package: ${name}@${spec}`);
        return;
      }

      const resolvedVersion = resolveVersion(name, spec, lock);
      const cacheKey = `${name}@${resolvedVersion}`;
      if (!checkedPackages.has(cacheKey)) {
        checkPackageAge(name, resolvedVersion);
        checkedPackages.add(cacheKey);
      } else {
        console.log(`Skipping already checked package: ${name}@${resolvedVersion}`);
      }
    });
  });

  if (!hasDeps && (!lock || !lock.packages || Object.keys(lock.packages).length === 0)) {
    console.log('No dependencies to check. Proceeding.');
  } else {
    console.log('All packages checked. Proceeding with installation.');
  }
  
  // Save cache at end
  savePersistentCache();
}

try {
  console.log('Starting preinstall script');
  main();
} catch (error) {
  console.error(`Error: ${error.message}`);
  // Save cache even on failure (partial results are useful)
  try {
    savePersistentCache();
  } catch (saveError) {
    console.warn(`Failed to save cache on error: ${saveError.message}`);
  }
  
  // Clean up node_modules and package-lock.json on failure
  try {
    const nodeModulesPath = path.join(process.cwd(), 'node_modules');
    const lockPath = path.join(process.cwd(), 'package-lock.json');
    const altLockPath = path.join(process.cwd(), '.package-lock.json');
    
    if (fs.existsSync(nodeModulesPath)) {
      fs.rmSync(nodeModulesPath, { recursive: true, force: true });
      console.log('Cleaned up node_modules due to failure');
    }
    if (fs.existsSync(lockPath)) {
      fs.unlinkSync(lockPath);
      console.log('Cleaned up package-lock.json due to failure');
    }
    if (fs.existsSync(altLockPath)) {
      fs.unlinkSync(altLockPath);
      console.log('Cleaned up .package-lock.json due to failure');
    }
  } catch (cleanupError) {
    console.error(`Cleanup failed: ${cleanupError.message}`);
  }
  process.exit(1);
}

Note for npm hook script:This example can be improved by using variable to handle cooldown value, manage a whitelist, or improve performance. Don't forget to whitelist this preinstall script itself when using --ignore-scripts. Also note that preinstall hooks are not executed when using npm install --package-lock-only; see the Lock Dependencies section for handling that scenario.

References:

• pnpm minimumReleaseAge
• Renovate minimumReleaseAge

Enable 2FA on npm:

# Enable 2FA for authentication and publishing
npm profile enable-2fa auth-and-writes

# Check 2FA status
npm profile get

# Publish with OTP (one-time password)
npm publish --otp=123456

Token management (only if you cannot use OIDC):

# Prefer granular publish-only tokens with short expiry
npm token create --read-only    # for install-only CI
    
# Optional: restrict by source IPs
npm token create --cidr=10.0.0.0/8
npm token list
npm token revoke <token-id>

# Check token information
npm token list --json

CI/CD best practices:

# GitHub Actions with Trusted Publishing (OIDC) - NO TOKEN NEEDED
name: Publish
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write  # Required for OIDC authentication
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'  # Includes npm 10.8.2+ with OIDC support
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish
        # No --provenance flag needed - automatically included with trusted publishing
        # No NODE_AUTH_TOKEN needed - OIDC authentication happens automatically

Setup requirements for Trusted Publishing (one-time configuration):

Configure on npmjs.com:

• Navigate to your package settings at https://www.npmjs.com/package/<your-package>/access
• Click "Configure trusted publisher"
• Select "GitHub Actions"
• Enter:

Repository owner/organization: your-org
Repository name: your-repo
Workflow filename: publish.yml (or your workflow file name)
Environment name: (optional, leave blank if not using GitHub environments)

Ensure npm CLI version:

• Use a recent npm (10.x or newer) for OIDC trusted publishing and provenance; npm 11+ recommended.
• Node.js 20 ships with npm 10.x; Node.js 22 ships with npm 11.x.

Benefits of Trusted Publishing:

• Zero secrets management - no tokens to create, rotate, or secure
• Automatic provenance generation - no --provenance flag needed
• Reduced attack surface - no long-lived credentials to steal
• Cryptographic proof of source and build environment
• Compliance with OpenSSF best practices

Fallback to tokens (if trusted publishing unavailable):
If you cannot use trusted publishing yet, use short-lived tokens:

# Legacy approach with short-lived tokens
name: Publish
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish --provenance
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Token best practices (when tokens are required):

• Create granular access tokens (not classic tokens)
• Scope tokens to specific packages
• Set short expiration (eg ≤90 days)
• Rotate tokens regularly
• Never use tokens for public package publishing if trusted publishing is available

Monitoring account security:

# Check package signatures (npm 9+)
npm audit signatures

# Monitor for unusual activity (require `npm login` and appropriate permissions)
npm access ls-packages
npm access ls-collaborators <package-name>

References:

• npm 2FA documentation
• npm token documentation
• OWASP npm security cheat sheet

Container-based isolation:

# Dedicated install stage with minimal permissions
FROM node:20-alpine AS installer

# Create non-root user
RUN addgroup -g 1001 -S installer && \
    adduser -u 1001 -S installer -G installer

WORKDIR /install

# Copy dependency files only
COPY --chown=installer:installer package*.json ./

# Switch to non-root user
USER installer

# Install with restricted capabilities
RUN npm ci --ignore-scripts --omit=dev

# Production stage
FROM node:20-alpine
WORKDIR /app
COPY --chown=node:node --from=installer /install/node_modules ./node_modules
COPY --chown=node:node . .
USER node
CMD ["node", "server.js"]

Docker with network isolation:

Option 1: Complete offline install (Recommended as no further infrastructure dependency)

# Step 1: Pre-populate cache with network access
docker run --rm \
  -v npm-cache:/root/.npm \
  -v $(pwd):/app \
  -w /app \
  node:20-alpine \
  npm ci --ignore-scripts

# Step 2: Install offline using cached packages (network completely disabled)
docker run --rm \
  --network=none \
  --memory=2g \
  --cpus=2 \
  --pids-limit=100 \
  --security-opt=no-new-privileges \
  -v npm-cache:/root/.npm \
  -v $(pwd):/app \
  -w /app \
  node:20-alpine \
  npm ci --ignore-scripts --prefer-offline --cache /root/.npm

# Verification: Attempt network access (should fail)
docker run --rm --network=none alpine wget -O- https://google.com 2>&1 | grep -q "bad address" && echo "Network isolation verified"

Option 2: Corporate proxy with domain filtering (Practical for enterprises)

# Requires: Corporate HTTP proxy configured with domain allowlist
# Example: proxy.company.intra:8080 allows only registry.npmjs.org

docker run --rm \
  --memory=2g \
  --cpus=2 \
  --pids-limit=100 \
  --security-opt=no-new-privileges \
  -e HTTP_PROXY=http://proxy.company.intra:8080 \
  -e HTTPS_PROXY=http://proxy.company.intra:8080 \
  -e NO_PROXY=localhost,127.0.0.1, internalArtifactRepo \
  -v $(pwd):/app \
  -w /app \
  node:20-alpine \
  npm ci --ignore-scripts

# The corporate proxy handles domain allowlisting
# Configure your proxy to only allow:
# - registry.npmjs.org (npm registry)
# - Objects.githubusercontent.com (GitHub releases, if needed)

# Verification: Test that proxy blocks unauthorized domains
docker run --rm \
  -e HTTP_PROXY=http://proxy.company.intra:8080 \
  -e HTTPS_PROXY=http://proxy.company.intra:8080 \
  alpine wget -O- https://malicious-site.com 2>&1 | grep -q "Forbidden\|403\|blocked" && echo "Proxy filtering verified"

Option 3: Custom Docker network with egress controls (Advanced - requires infrastructure)

# PREREQUISITES: This option requires external infrastructure setup FIRST.
# 
# Docker's --network flag does NOT provide filtering by itself - it simply assigns 
# a network object to the container. The network object itself has no filtering capability.
# 
# You must then apply filtering to this Docker network by configuring one of:
# 1. Corporate HTTP proxy with domain allowlist (equivalent to Option 2 above)
# 2. Firewall rules on Docker host with egress filtering (iptables/nftables) - shown below
# 3. Docker network plugin with built-in egress controls (Calico, Cilium, etc.)
#
# This example shows HOW to use a restricted network once infrastructure exists,
# but is NOT a complete standalone solution.

# Step 1: Create custom network
docker network create restricted

# Step 2: Find the subnet Docker assigned to this network
RESTRICTED_SUBNET=$(docker network inspect restricted -f '{{range .IPAM.Config}}{{.Subnet}}{{end}}')
echo "Restricted network subnet: $RESTRICTED_SUBNET"
# Example output: 172.18.0.0/16

# Step 3: Configure firewall rules on Docker host (must run as root)
# WARNING: This is complex and requires ongoing maintenance.
# IP-based allowlists for CDNs are impractical. Better to use Option 2 (proxy) instead.

# Allow npm registry only (Cloudflare IPs used by npmjs.org)
sudo iptables -I DOCKER-USER -s $RESTRICTED_SUBNET -d 104.16.0.0/12 -p tcp --dport 443 -j ACCEPT
# Block all other HTTPS traffic from this network
sudo iptables -I DOCKER-USER -s $RESTRICTED_SUBNET -p tcp --dport 443 -j REJECT
# Block HTTP as well
sudo iptables -I DOCKER-USER -s $RESTRICTED_SUBNET -p tcp --dport 80 -j REJECT

# Verify rules are installed
sudo iptables -L DOCKER-USER -n -v | grep $RESTRICTED_SUBNET

# Step 4: Use the restricted network
docker run --rm \
  --network=restricted \
  --dns=10.0.0.1 \
  --memory=2g \
  --cpus=2 \
  --pids-limit=100 \
  --security-opt=no-new-privileges \
  -v $(pwd):/app \
  -w /app \
  node:20-alpine \
  npm ci --ignore-scripts

# Verification: Test that restrictions work
echo "Testing restriction (should fail):"
docker run --rm --network=restricted alpine wget -T 5 -O- https://google.com 2>&1 | grep -q "wget: can't connect\|Connection refused\|Network unreachable" && echo "[OK] Network restrictions verified" || echo "[NOK] Restrictions NOT working - check firewall rules"

echo "Testing npm registry access (should succeed):"
docker run --rm --network=restricted alpine wget -T 5 -O- https://registry.npmjs.org/ 2>&1 | grep -q "<!DOCTYPE html>" && echo "[OK] npm registry accessible" || echo "[NOK] npm registry blocked - adjust firewall rules"

# Cleanup (when done testing):
# sudo iptables -D DOCKER-USER -s $RESTRICTED_SUBNET -d 104.16.0.0/12 -p tcp --dport 443 -j ACCEPT
# sudo iptables -D DOCKER-USER -s $RESTRICTED_SUBNET -p tcp --dport 443 -j REJECT
# sudo iptables -D DOCKER-USER -s $RESTRICTED_SUBNET -p tcp --dport 80 -j REJECT
# docker network rm restricted

# IMPORTANT LIMITATIONS:
# - CDN IP ranges change frequently (npm uses Cloudflare)
# - npm registry uses multiple CDN providers in some regions
# - Requires root access to Docker host (not possible in many environments)
# - iptables rules don't persist across reboots (need to save: iptables-save)
# - Rule order matters (DOCKER-USER chain must be before DOCKER-ISOLATION)
#
# RECOMMENDATION: Use Option 2 (corporate proxy) instead for production.
# Proxies allow domain-based filtering and are easier to maintain.

Resource limits explanation:

• --memory=2g: Prevents memory exhaustion attacks
• --cpus=2: Prevents CPU hogging
• --pids-limit=100: Prevents fork bombs
• --security-opt=no-new-privileges: Prevents privilege escalation

npm and node_modules can be memory-intensive due to:

• Deep dependency trees (common: 500-1000 packages)
• Post-install scripts (native compilation)
• Parallel downloads and extraction
• Package deduplication algorithms

Linux namespace isolation with bubblewrap (local development only):

Important limitations:

• Requires USER_NS (user namespaces) capability - NOT available on:
  • GitHub Actions hosted runners
  • Many Docker containers (unless --privileged)
  • Some corporate Linux systems with restricted security policies
• Requires Linux kernel with namespace support (kernel 3.8+)
• Best suited for local development machines with full control

# Install bubblewrap (Debian/Ubuntu)
sudo apt-get install bubblewrap

# Verify user namespace support
if [ ! -w /proc/self/uid_map ]; then
    echo "ERROR: User namespaces not available"
    echo "This system cannot run bubblewrap sandboxing"
    exit 1
fi

# Run npm install in sandbox with network isolation
# Note: --unshare-net creates network namespace but doesn't guarantee isolation on all distros
bwrap \
  --ro-bind /usr /usr \
  --ro-bind /lib /lib \
  --ro-bind /lib64 /lib64 \
  --ro-bind /bin /bin \
  --ro-bind /sbin /sbin \
  --tmpfs /tmp \
  --tmpfs /var \
  --bind "$(pwd)" "$(pwd)" \
  --unshare-all \
  --unshare-net \
  --die-with-parent \
  --new-session \
  --setenv HOME /tmp \
  -- \
  npm ci --ignore-scripts

# For true network isolation, combine with firewall rules or use --unshare-net explicitly
# Some distros allow network access even with --unshare-all

For CI/CD environments, use Docker-based isolation (Options 1-3 above) instead, as it works reliably across all CI platforms including GitHub Actions, GitLab CI, CircleCI, etc.

Alternative for restricted environments:

# Use Docker even on Linux for better CI/CD compatibility
docker run --rm \
  --network=none \
  --memory=2g \
  --cpus=2 \
  --pids-limit=100 \
  --cap-drop=ALL \
  --cap-add=CHOWN \
  --cap-add=SETUID \
  --cap-add=SETGID \
  --security-opt=no-new-privileges \
  -v $(pwd):/app \
  -w /app \
  node:20-alpine \
  npm ci --ignore-scripts --prefer-offline

Capability management:

# Drop all capabilities and add only what's needed
docker run --rm \
  --cap-drop=ALL \
  --cap-add=CHOWN \
  --cap-add=SETUID \
  --cap-add=SETGID \
  --memory=2g \
  --cpus=2 \
  --pids-limit=100 \
  --security-opt=no-new-privileges \
  -v $(pwd):/app \
  -w /app \
  node:20-alpine \
  npm ci --ignore-scripts

Note: Depending on your project, additional capabilities may be needed. Test in your environment and add capabilities incrementally as required.

References:

• Bubblewrap documentation
• Docker security best practices
• Docker resource constraints
• Linux capabilities

Audit and identify unused packages:

# Find unused dependencies
npx depcheck

# Analyze dependency tree
npm ls --all
npm ls --depth=0  # Direct dependencies only

# Find duplicate packages (be sure to use this in a project and don't run this as root...)
npm dedupe

# Analyze bundle size and identify large deps
npx webpack-bundle-analyzer dist/stats.json

Analyze transitive dependencies:

# See what a package will install before installing
npm view <package-name> dependencies peerDependencies

# Explain why a package is installed
npm explain <package-name>

# Find all instances of a package
npm ls <package-name>

Security auditing:

# Run security audit
npm audit

# Audit only production dependencies
npm audit --omit=dev

# Fix vulnerabilities automatically
npm audit fix

# Generate detailed audit report
npm audit --json > audit-report.json

npm-audit - clarification note:
npm-audit only checks known vulnerabilities and doesn’t detect malicious code; it’s complementary to behavioral scanning.

Evaluate package quality before adding:

# Check package metadata
npm view <package-name>

# Prefer inspecting the published tarball for scripts
npm pack <package-name> --silent
tar -xzf <package-name>-<version>.tgz
jq .scripts package/package.json


# Weekly downloads via the public API
# Manual check could be done on npm-stat.com or similar
curl -s https://api.npmjs.org/downloads/point/last-week/<package-name> | jq .downloads


# Check package size
npm view <package-name> dist.unpackedSize

# Optional: lifecycle scripts reported in packument (may be absent or incomplete)
npm view <package-name> scripts

Corporate environment with private registry mirrors note: for air-gapped installs, note that npm view/npm audit must point to the mirror; set registry= and proxy env vars in CI.

References:

• depcheck tool
• npm audit documentation

Automated security scanning:

# OpenSSF Scorecard
npx @ossf/scorecard <repository-url>

# Socket.dev CLI
npx socket-cli report create package.json

# Snyk test
npx snyk test

# Check for known malicious packages
npm audit

Generate SBOM:

# CycloneDX format
npx @cyclonedx/cyclonedx-npm --output-file sbom.json

# SPDX format
npx @spdx/spdx-sbom-generator npm .

# Fail the build if SBOM generation changes between commits
git diff --exit-code -- sbom.json || {
  echo "::error::SBOM drift detected; review dependency changes";
  exit 1;
}

Manual inspection:

# View package details
npm view <package-name>

# Download and inspect package without installing
npm pack <package-name>
tar -xzf <package-name>-<version>.tgz
cd package && cat package.json

# Check package integrity
npm view <package-name> dist.integrity
npm view <package-name> dist.shasum

Verify package signatures: npm audit signatures validates signatures only when the registry and package actually publish them. Treat as additive integrity, not an anti-malware control, and expect partial ecosystem coverage.

npm audit signatures

References:

• OpenSSF Scorecard
• Socket.dev
• npm audit signatures

Runtime monitoring with Falco:

# falco_rules.local.yaml
- rule: Suspicious npm Network Activity
  desc: Detect npm/pnpm making outbound connections to public IPs during install
  condition: >
    proc.name in (npm, pnpm, node, npx) and
    evt.type=connect and
    evt.dir=> and
    fd.l4proto=tcp and
    not fd.rip in (
      "10.0.0.0/8",
      "172.16.0.0/12", 
      "192.168.0.0/16",
      "127.0.0.0/8"
    )
  output: >
    npm process connecting to public IP during package operation
    (command=%proc.cmdline dst=%fd.rip:%fd.rport sport=%fd.lport 
     user=%user.name container=%container.id)
  priority: WARNING
  tags: [network, npm, supply_chain]

- rule: npm Accessing Sensitive Files
  desc: Detect npm/node accessing SSH keys, cloud credentials, or tokens
  condition: >
    proc.name in (npm, pnpm, node, npx) and
    evt.type in (open, openat, openat2) and
    evt.is_open_write=false and
    (fd.name glob "/home/*/.ssh/*" or
     fd.name glob "/root/.ssh/*" or
     fd.name glob "/home/*/.aws/*" or
     fd.name glob "/root/.aws/*" or
     fd.name glob "/home/*/.config/gcloud/*" or
     fd.name glob "/root/.config/gcloud/*" or
     fd.name glob "/home/*/.kube/*" or
     fd.name glob "/root/.kube/*" or
     fd.name glob "/home/*/.docker/config.json" or
     fd.name glob "/root/.docker/config.json" or
     fd.name contains "id_rsa" or
     fd.name contains "id_ecdsa" or
     fd.name contains "id_ed25519")
  output: >
    npm process accessing sensitive credential files
    (file=%fd.name command=%proc.cmdline user=%user.name 
     parent=%proc.pname container=%container.id)
  priority: CRITICAL
  tags: [filesystem, npm, credentials, supply_chain]

- rule: npm Spawning Suspicious Processes
  desc: Detect npm spawning shells or network utilities during installation
  condition: >
    spawned_process and
    proc.pname in (npm, pnpm, node, npx) and
    proc.name in (bash, sh, zsh, curl, wget, nc, netcat, python, python3, perl, ruby)
  output: >
    npm spawned suspicious subprocess during package operation
    (process=%proc.name cmdline=%proc.cmdline parent=%proc.pname 
     user=%user.name container=%container.id)
  priority: WARNING
  tags: [process, npm, supply_chain]

Runtime monitoring with Falco:
Falco network rules use IP addresses, not DNS names. For corporate environments with proxies, adjust rules to allow your specific proxy IPs.

Detection approaches:

1. Public IP detection (recommended for isolated builds): Alert on any non-RFC1918 connections
2. Allowlist approach (for environments with known registries): List allowed destination IPs
3. Proxy-aware (for corporate environments): Permit connections through corporate proxies only

File system monitoring with osquery:

-- Monitor for new files created during npm install
SELECT * FROM file_events 
WHERE path LIKE '/home/%/.ssh/%' 
  AND action = 'CREATED'
  AND time > (SELECT unix_time FROM time) - 300;

-- Monitor for unexpected processes spawned
SELECT * FROM processes
WHERE parent IN (SELECT pid FROM processes WHERE name IN ('npm','pnpm','node'))
  AND name IN ('bash','sh','curl','wget','python');
    
-- Requires filesystem/process eventing enabled (eg --disable_events=false) and FIM tables configured for file_events.

Dependency diff analysis:

# Compare package versions
npm diff <package-name>@1.0.0 <package-name>@1.0.1

# Detailed package comparison
npm pack <package-name>@1.0.0 && tar -xzf package-1.0.0.tgz -C /tmp/old
npm pack <package-name>@1.0.1 && tar -xzf package-1.0.1.tgz -C /tmp/new
diff -r /tmp/old /tmp/new

# Using diffoscope for detailed analysis
diffoscope \
  <(npm pack package@1.0.0 && tar -xf package-1.0.0.tgz) \
  <(npm pack package@1.0.1 && tar -xf package-1.0.1.tgz)

Network monitoring:

# Monitor network connections during install
strace -e trace=connect npm install 2>&1 | grep connect

# Using tcpdump
sudo tcpdump -i any -n 'dst port 443 or dst port 80' &
npm install
sudo pkill tcpdump
    
# Note: strace requires Linux; tcpdump typically needs root or CAP_NET_RAW.

Rollback procedures:

# Quick rollback using git
git show HEAD~1:package-lock.json > package-lock.json
npm ci

# Keep backup of lockfiles
cp package-lock.json package-lock.json.backup.$(date +%Y%m%d)

References:

• Falco rules documentation
• osquery documentation

Challenge: Python's packaging system executes arbitrary code by design during installation. Unlike npm where scripts can be completely disabled, Python has NO reliable way to prevent code execution during package installation:

• setup.py (legacy): Runs arbitrary Python code during source installs
• PEP 517/518 build backends (modern): Still execute build backend code during wheel creation
• Wheel installation: Prefer prebuilt wheels from a trusted index and enforce --only-binary=:all: to avoid executing arbitrary build backends from sdists. This does not eliminate runtime risk (malicious code on import) but prevents build-time execution.
• Fundamental limitation: Code execution is architecturally integrated into Python's package installation process

Mitigation strategy: Since install-time code execution cannot be prevented in Python, defense must focus on other layers (sandboxing, pre-vetting, network isolation, and using pre-built wheels from trusted sources).

Wheel-only fail-closed install:

# Fail closed: wheels only, hashed, no dep resolver drift
PIP_ONLY_BINARY=:all: \
pip install --require-hashes --only-binary=:all: --no-deps -r requirements.txt

# Check if wheels are available before attempting
pip index versions <package-name>

# Best practice: Use wheels from trusted sources (PyPI, private mirror)

Platform Compatibility: --only-binary=:all: will fail if:

• Wheels not available for your platform (ARM, Alpine Linux, Windows on ARM)
• Python version too new (some packages lag behind latest Python releases)
• Package only publishes sdist (source distribution)
• Uncommon architecture/OS combinations (e.g., Alpine on ARM64)

Pre-flight check:

# Test if all packages have wheels available before actual install
pip install --dry-run --only-binary=:all: -r requirements.txt

If this fails, you must either:

1. Build in sandbox and accept source execution risk
2. Find alternative package with wheel support
3. Request wheel from maintainer (file GitHub issue)
4. Build your own wheel in trusted environment and host privately

PEP 517/518 builds:

PEP 517/518 define how pip builds from source (sdists) using a declared backend in pyproject.toml. Building from source executes backend code during the build phase. Prefer prebuilt wheels to avoid build-time execution.

# pyproject.toml (example - this is in the package, not your project)
[build-system]
requires = ["setuptools>=40.8.0", "wheel"]
build-backend = "setuptools.build_meta"

Key point: Even with PEP 517/518, building from source still executes code (the build backend). The only safe approach is to use prebuilt wheels:

# This prevents source builds but will fail if no wheel exists
pip install --only-binary=:all: -r requirements.txt

Better approach - use Poetry or pip-tools with hash verification:

# Poetry (Recommended)
poetry install --no-root

# pip-sync enforces EXACT environment (uninstalls extras)
pip-sync requirements.txt

# If you want to preserve other packages, use pip install instead:
pip install -r requirements.txt --require-hashes  # Generated with pip-compile --generate-hashes

Inspection workflow (when you must install from source):

# Download and inspect package before installing
pip download <package-name> --no-deps
tar -xzf <package-name>-<version>.tar.gz

# For packages with setup.py
cat <package>/setup.py  # Review for suspicious code

# For packages with pyproject.toml
cat <package>/pyproject.toml  # Check build backend
# Note: You'd still need to inspect the build backend code

# Check for suspicious patterns
grep -r "exec\|eval\|compile\|__import__" <package>/
grep -r "requests\|urllib\|http\|socket" <package>/

# Only install if inspection passes
pip install <package-name>

Important limitation: Manual inspection is time-consuming and requires expertise. For production environments, prioritize:

1. Use wheels-only from trusted sources (PyPI, corporate mirror)
2. Sandbox all builds in containers with network isolation
3. Vet packages before adding to requirements
4. Monitor for unexpected behavior after installation

Note: Python ecosystem has weaker controls for install scripts compared to npm. Focus on other layers (sandboxing, pre-vetting) for protection. There is no Python equivalent to npm's --ignore-scripts that provides comprehensive protection.

References:

• PEP 517 - Build system interface
• PEP 518 - Build system dependencies
• pip installation documentation

Understanding Python lockfiles and transitive dependencies:

Unlike requirements.in which only lists your direct dependencies, Python lockfiles (when properly generated with pip-tools or Poetry) include ALL transitive dependencies with exact versions and cryptographic hashes.

# requirements.in - your direct dependencies only
django==4.2.7
requests==2.31.0

# requirements.txt (generated by pip-compile) - ALL dependencies with hashes
django==4.2.7 \
    --hash=sha256:8e0f1c2c2786b5c0e39fe1afce24c926040fad47c8ea8ad30aaf1188df29fc41
sqlparse==0.4.4 \              # ← Transitive dependency of django
    --hash=sha256:5430a4fe2ac7d0f93e66f1efc6e1338a41884b7ddf2a350cedd20ccc4d9d28f3
asgiref==3.7.2 \               # ← Another transitive dependency  
    --hash=sha256:89b2ef2247e3b562a16eef663bc0e2e703ec6468e2fa8a5cd61cd449786d4f6e

Why hashes matter: The --require-hashes flag verifies not just version numbers but the actual content of every package (including transitives), protecting against registry tampering and ensuring you get exactly what you tested.

Important: --require-hashes is all-or-nothing - if even ONE package in your entire dependency tree is missing a hash, the install will fail. This is why you must use pip-compile --generate-hashes rather than manually creating requirements.txt files.
Constraints when enforcing --require-hashes:

• Editable installs (-e .) and most VCS URLs won’t work. Build a wheel in CI (python -m build) and lock that wheel by filename with a hash.
• Consider omitting --allow-unsafe in production to avoid toolchain drift from pinning pip/setuptools/wheel inside app envs. Manage tool versions separately.

Understanding --allow-unsafe:
The --allow-unsafe flag includes pip, setuptools, and wheel in your lockfile:
Use --allow-unsafe when:

• You want fully reproducible environments (same tool versions everywhere)
• Running in containers where toolchain is part of app environment
• Testing requires exact pip/setuptools versions
  Omit --allow-unsafe when:
• You want to keep pip/setuptools/wheel updated independently
• Your app doesn't depend on specific versions of these tools
• You manage toolchain separately (e.g., via Docker base image)

For most applications: Use --allow-unsafe for maximum reproducibility, but understand you'll need to update these packages separately for security patches.

Using requirements.txt with exact, hashed locks (recommended with pip-tools)
Do not generate lockfiles with pip freeze for production; it lacks hashes and captures incidental environment state.

Using pip-tools:

# Install pip-tools
pip install pip-tools

# Create requirements.in with your direct dependencies
cat > requirements.in << EOF
django==4.2.7
requests==2.31.0
celery==5.3.4
EOF

# Generate locked requirements.txt with hashes for ALL dependencies
# IMPORTANT: Use --allow-unsafe to include setuptools, pip, wheel
pip-compile --generate-hashes --allow-unsafe requirements.in

# Install from locked file with hash verification
pip-sync requirements.txt

# Or install with explicit hash verification enforcement
pip install -r requirements.txt --require-hashes

Critical requirements for --require-hashes to work:

• Every package (direct and transitive) MUST have a hash
• All versions MUST be pinned with == (not >=, ~=, or ranges)
• Use pip-compile --generate-hashes to generate the file (manual creation is error-prone)
• Include --allow-unsafe flag to prevent install failures with setuptools/pip/wheel
• Cannot use with editable installs (-e packages)
• Cannot use with VCS/URL dependencies without additional configuration

What happens without hashes:

# This will FAIL if any package is missing a hash:
pip install -r requirements.txt --require-hashes

# Error: "In --require-hashes mode, all requirements must have their 
# versions pinned with ==. These do not: [package list]"

Using Poetry (modern approach):

# Initialize project
poetry init

# Add dependencies (auto-locks in poetry.lock)
poetry add django==4.2.7

# Install from lockfile
poetry install

# Update all dependencies to latest compatible versions
poetry update

# Update specific package only
poetry update django

# Update without modifying existing locked versions (Poetry 2.0+)
poetry lock --no-update

Note on security updates: Poetry does not have a built-in capability o update only packages with known vulnerabilities.

# Option 1: Use pip-audit (run in Poetry environment)
poetry run pip-audit --format json > audit.json

# Extract vulnerable package names (verify jq path matches actual output)
jq -r '.vulnerabilities[].name' audit.json | sort -u | while read pkg; do
    echo "Updating vulnerable package: $pkg"
    poetry update "$pkg"
done

# Or simpler - let pip-audit handle it:
poetry run pip-audit --fix --skip-editable

# Or with dry-run to see what would be fixed
pip-audit --fix --dry-run

# Option 2: Use dependency update services (automated)
# - Dependabot (GitHub) - automatically creates PRs for security updates
# - Renovate - supports Poetry and security-only updates

# Option 3: Manual selective updates
# First identify vulnerable packages
pip-audit

# Then update specific package
poetry update requests  # Update only the requests package
    
**Using Pipenv**:
```bash
# Create Pipfile with locked versions
pipenv install django==4.2.7

# Install from Pipfile.lock
pipenv install --deploy  # Fails if Pipfile.lock is missing/outdated

# Verify integrity (Pipfile vs Pipfile.lock)
pipenv verify

In requirements.txt, use exact versions:

# Good - exact versions
django==4.2.7
requests==2.31.0
celery==5.3.4

# Bad - floating versions
django>=4.2.0  # ✗ Allows any 4.2+ version
requests~=2.31  # ✗ Allows 2.31.x versions
celery  # ✗ Allows any version

CI/CD enforcement:

# GitHub Actions
name: Verify Dependencies
on: [pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      
      - name: Enforce hashed install from lock
        run: |
          python -m venv .venv && . .venv/bin/activate
          pip install --upgrade pip
          pip install -r requirements.txt --require-hashes --only-binary=:all: --no-deps
      
      - name: Check for floating versions
        run: |
          if grep -E '^[a-zA-Z0-9_-]+[>~!]=|^[a-zA-Z0-9_-]+.*\*' requirements.txt; then
            echo "::error::Floating version ranges detected in requirements.txt"
            echo "Only use exact versions with == operator"
            exit 1
          fi
      
      - name: Ensure lockfile is committed
        run: |
          # Check for pip-tools requirements.txt
          if [ -f requirements.in ]; then
            if ! git ls-files --error-unmatch requirements.txt > /dev/null 2>&1; then
              echo "::error::requirements.txt (lockfile) is not committed to git"
              exit 1
            fi
          fi
          # Check for Poetry lock
          if [ -f pyproject.toml ] && grep -q "tool.poetry" pyproject.toml; then
            if ! git ls-files --error-unmatch poetry.lock > /dev/null 2>&1; then
              echo "::error::poetry.lock is not committed to git"
              exit 1
            fi
          fi

References:

• pip-tools documentation
• Poetry documentation
• Pipenv documentation

Challenge: Python ecosystem lacks native cooldown support. Requires custom implementation or registry proxy.

Using private PyPI mirror (devpi):

# Install devpi
pip install devpi-server devpi-client

# Start devpi server
devpi-server --start

# Configure with cooldown filter (custom plugin needed)
# Create devpi_cooldown.py plugin

Custom pre-install validation script:

#!/usr/bin/env python3
# scripts/check_package_age.py

import sys
import json
import urllib.request
import urllib.error
from datetime import datetime, timezone

def check_package_age(package_name, min_age_days=7, version=None):
    """
    Check if a package (or specific version) is older than min_age_days.

    Args:
        package_name (str): Name of the package to check.
        min_age_days (int): Minimum age in days for the package to be allowed.
        version (str, optional): Specific version to check. If None, checks latest version.

    Returns:
        bool: True if package is old enough or metadata is incomplete, False otherwise.

    Note: Relies on PyPI JSON API metadata. Some packages may have
    incomplete metadata or different structures.
    """
    # Track whether we're querying a specific version or latest
    query_specific_version = version is not None
    
    # Construct URL based on whether version is specified
    if query_specific_version:
        url = f"https://pypi.org/pypi/{package_name}/{version}/json"
    else:
        url = f"https://pypi.org/pypi/{package_name}/json"

    try:
        with urllib.request.urlopen(url, timeout=10) as response:
            data = json.loads(response.read())

        # Get version if not specified (use latest)
        if not query_specific_version:
            version = data['info']['version']
        
        # Get release files based on query type
        if query_specific_version:
            # Version-specific query returns 'urls' field
            release_files = data.get('urls', [])
        else:
            # General package query uses 'releases' dict
            if version not in data.get('releases', {}):
                print(f"WARNING: {package_name} version {version} not found in releases metadata")
                return True  # Allow installation if metadata incomplete
            release_files = data['releases'][version]

        # Check if we have release files
        if not release_files:
            print(f"WARNING: {package_name} {version} has no release files in metadata")
            return True  # Allow installation if no files listed

        # Try multiple possible fields for upload time
        upload_time_str = None
        for field in ['upload_time', 'upload_time_iso_8601', 'upload_timestamp']:
            upload_time_str = release_files[0].get(field)
            if upload_time_str:
                break
        
        # If still no upload time, try the package info level
        if not upload_time_str:
            upload_time_str = data.get('info', {}).get('release_date')
        
        if not upload_time_str:
            print(f"WARNING: {package_name} {version} missing upload_time in all known fields")
            return True  # Allow installation if timestamp unavailable

        # Parse date with timezone awareness
        # Handle both formats: "2023-01-15T10:30:00" and "2023-01-15T10:30:00Z"
        try:
            if upload_time_str.endswith('Z'):
                release_date = datetime.fromisoformat(upload_time_str.replace('Z', '+00:00'))
            else:
                # Try parsing with timezone info, fall back to assuming UTC
                try:
                    release_date = datetime.fromisoformat(upload_time_str)
                    if release_date.tzinfo is None:
                        release_date = release_date.replace(tzinfo=timezone.utc)
                except ValueError:
                    # Try alternate format
                    release_date = datetime.strptime(upload_time_str, '%Y-%m-%d %H:%M:%S')
                    release_date = release_date.replace(tzinfo=timezone.utc)
        except (ValueError, AttributeError) as e:
            print(f"WARNING: {package_name} {version} has unparseable date format: {upload_time_str}")
            return True  # Fail open on date parsing errors
        
        now = datetime.now(timezone.utc)
        days_old = (now - release_date).days

        if days_old < min_age_days:
            print(f"BLOCKED: {package_name} version {version} "
                  f"published {days_old} days ago. Minimum: {min_age_days} days.")
            return False

        print(f"ALLOWED: {package_name} {version} published {days_old} days ago")
        return True

    except urllib.error.HTTPError as e:
        if e.code == 404:
            print(f"ERROR: Package {package_name}{f' {version}' if version else ''} not found on PyPI")
        else:
            print(f"ERROR: HTTP {e.code} when checking {package_name}{f' {version}' if version else ''}")
        return False

    except urllib.error.URLError as e:
        print(f"ERROR: Network error checking {package_name}{f' {version}' if version else ''}: {e.reason}")
        # Fail open on network errors to avoid blocking legitimate installs
        print(f"WARNING: Allowing installation due to network error - manual review recommended")
        return True

    except (KeyError, IndexError, ValueError) as e:
        print(f"WARNING: Unexpected PyPI metadata structure for {package_name}{f' {version}' if version else ''}: {e}")
        print(f"Allowing installation due to metadata parsing failure")
        return True  # Fail open to avoid blocking legitimate packages

    except Exception as e:
        print(f"ERROR: Unexpected error checking {package_name}{f' {version}' if version else ''}: {e}")
        print(f"WARNING: Allowing installation - manual review recommended")
        return True  # Fail open on unexpected errors

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: check_package_age.py <package_name> [version] [min_age_days]")
        print()
        print("Arguments:")
        print("  package_name     : Required. Name of the PyPI package")
        print("  version         : Optional. Specific version to check (e.g., '1.2.3')")
        print("  min_age_days    : Optional. Minimum age in days (default: 7)")
        print()
        print("Examples:")
        print("  check_package_age.py requests                    # Check latest version, 7 days")
        print("  check_package_age.py requests 2.31.0             # Check version 2.31.0, 7 days")
        print("  check_package_age.py requests 2.31.0 14          # Check version 2.31.0, 14 days")
        print("  check_package_age.py requests 14                 # Check latest version, 14 days")
        print()
        print("Returns exit code 0 if package is old enough, 1 otherwise.")
        sys.exit(1)

    package = sys.argv[1]
    
    # Parse arguments: handle both "pkg ver days" and "pkg days" formats
    version = None
    min_age = 7  # default
    
    if len(sys.argv) == 2:
        # Just package name: use latest, default min_age
        pass
    elif len(sys.argv) == 3:
        # Two arguments: could be "pkg ver" or "pkg days"
        arg2 = sys.argv[2]
        # If it looks like a version (contains dots or letters), treat as version
        if '.' in arg2 or any(c.isalpha() for c in arg2):
            version = arg2
        else:
            # Otherwise treat as min_age_days
            try:
                min_age = int(arg2)
            except ValueError:
                print(f"ERROR: Cannot parse '{arg2}' as version or days")
                sys.exit(1)
    elif len(sys.argv) >= 4:
        # Three or more arguments: pkg ver days
        version = sys.argv[2]
        try:
            min_age = int(sys.argv[3])
        except ValueError:
            print(f"ERROR: min_age_days must be an integer, got '{sys.argv[3]}'")
            sys.exit(1)

    if not check_package_age(package, min_age, version):
        sys.exit(1)

Limitations and considerations:

PyPI metadata assumptions:

• Script relies on PyPI JSON API structure which may vary between packages
• Some older packages may have incomplete or missing upload_time metadata
• Private PyPI mirrors may have different API structures
• Network timeouts or PyPI outages will cause checks to fail open (allow installation with warning)

Fail-open vs fail-closed behavior:

• Current script fails open (allows installation) when metadata is incomplete or network issues occur
• This prevents blocking legitimate packages due to metadata quirks or temporary network problems
• All fail-open cases log clear warnings for manual review
• For stricter security, change return True to return False in warning cases (not recommended for most environments)

Performance:

• Checks run sequentially (one package at a time)
• Each check makes 1 HTTPS request to PyPI
• For large requirements.txt files (100+ packages), this may take 1-2 minutes
• Consider caching results or running in parallel for better performance

Alternative approaches:

• Use a private PyPI mirror (devpi) with cooldown filtering plugin
• Use registry proxy with time-based filtering
• Cache check results to avoid repeated API calls for same package@version

Integration with requirements:

# Pre-installation check with better error handling
while IFS='==' read -r name ver; do
  # Skip comments and empty lines
  [[ "$name" =~ ^[[:space:]]*# ]] && continue
  [[ -z "$name" ]] && continue
  [[ -z "$ver" ]] && continue
  
  # Run check
  python scripts/check_package_age.py "$name" "$ver" 7 || exit 1
done < <(grep -E '^[a-zA-Z0-9_.-]+==.*' requirements.txt | sed 's/ *#.*//' | tr '==' ' ')

# Then install
pip install -r requirements.txt

Renovate configuration for Python:

// renovate.json
{
  "extends": ["config:base"],
  "dependencyDashboard": true,
  "packageRules": [
    {
      "description": "Python default cooldown and PR gating",
      "matchManagers": ["pip_requirements", "pip_setup", "poetry"],
      "stabilityDays": 7,
      // "prCreation": "status-success",
      "prCreation": "not-pending"
    },
    {
      "description": "Python security updates bypass cooldown",
      "matchManagers": ["pip_requirements", "pip_setup", "poetry"],
      "matchUpdateTypes": ["security"],
      "stabilityDays": 0
    }
  ]
}

Notes:

• See npm section above for detailed explanation of stabilityDays vs minimumReleaseAge. The same principles apply - use stabilityDays to avoid deadlocking frequently-updated Python packages.
• Removing "matchManagers" on either rule makes it global across ecosystems. That’s fine if you want uniform behavior everywhere.

packageRules Note: This configuration keeps the ecosystem-scoped approach. If you want the same behavior for all ecosystems, remove the "matchManagers" line so the rule applies globally. This rule only overrides cooldown for updates Renovate classifies as "security".

References:

• devpi documentation
• PyPI JSON API

Enable 2FA on PyPI:

# Via PyPI web interface: https://pypi.org/manage/account/
# Enable 2FA in Account Settings

# Generate API token (scoped)
# Navigate to: Account Settings > API tokens > Add API token

# Configure pip to use token
cat > ~/.pypirc << EOF
[pypi]
username = __token__
password = pypi-AgEIcHlwaS5vcmc...
EOF

# Secure the file
chmod 600 ~/.pypirc

Token management best practices:

# Create scoped tokens for different purposes
# - Upload-only token for CI/CD
# - Read-only token for private package index

# Store tokens as environment variables
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-AgEIcHlwaS5vcmc...

# Use keyring for secure storage (recommended)
pip install keyring
keyring set https://upload.pypi.org/legacy/ __token__

CI/CD with GitHub Actions:

# .github/workflows/publish.yml
name: Publish to PyPI
on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    environment: release
    permissions:
      id-token: write  # For trusted publishing
      contents: read
    
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Build package
        run: |
          pip install build
          python -m build
      - name: Publish to PyPI (trusted publishing)
        uses: pypa/gh-action-pypi-publish@release/v1
        # No credentials needed with trusted publishing!

Trusted Publishers (one-time on PyPI):
PyPI supports OIDC-based trusted publishing from GitHub Actions, removing need for long-lived tokens.

1. Go to https://pypi.org/manage/project/YOUR-PROJECT/settings/publishing/
2. Add publisher:
   • Choose "GitHub"
   • Repository owner/org: your-org
   • Repository name: your-repo
   • Workflow name: publish.yml
   • Environment name: release (optional but recommended)

This links your PyPI project to your GitHub repository via OIDC.

References:

• PyPI 2FA documentation
• PyPI API tokens
• Trusted Publishers

Container-based isolation:

# Dockerfile for isolated Python installation
FROM python:3.11-slim AS installer

# Create non-root user
RUN useradd -m -u 1001 installer

WORKDIR /install

# Copy requirements only
COPY --chown=installer:installer requirements.txt ./

# Switch to non-root user
USER installer

# Install dependencies
RUN pip install --user --no-cache-dir -r requirements.txt

# Production stage
FROM python:3.11-slim
WORKDIR /app
COPY --from=installer /home/installer/.local /home/app/.local
COPY . .
RUN useradd -m app && chown -R app:app /app
USER app
ENV PATH=/home/app/.local/bin:$PATH
CMD ["python", "app.py"]

Docker with network isolation:

# Step 1: Pre-populate cache with network access
docker run --rm \
  -v pip-cache:/root/.cache/pip \
  -v $(pwd):/app \
  -w /app \
  python:3.11-slim \
  pip download -r requirements.txt --dest /root/.cache/pip

# Step 2: Install without network using cached wheels
docker run --rm \
  --network=none \
  --memory=4g \
  --cpus=4 \
  --pids-limit=100 \
  --security-opt=no-new-privileges \
  -v pip-cache:/root/.cache/pip \
  -v $(pwd):/app \
  -w /app \
  python:3.11-slim \
  pip install -r requirements.txt --no-index --find-links /root/.cache/pip

Using bubblewrap (local development only):

⚠️ Important limitations:

• Requires user namespace capabilities - NOT available on GitHub Actions, most Docker containers
• Only works on Linux systems with namespace support enabled
• Not suitable for CI/CD pipelines - use Docker-based isolation instead

# Install bubblewrap (Debian/Ubuntu)
sudo apt-get install bubblewrap

# Verify support before attempting
if [ ! -w /proc/self/uid_map ]; then
    echo "ERROR: User namespaces not enabled on this system"
    echo "Use Docker-based isolation instead (see above)"
    exit 1
fi

# Run pip in sandbox
bwrap \
  --ro-bind /usr /usr \
  --ro-bind /lib /lib \
  --ro-bind /lib64 /lib64 \
  --ro-bind /bin /bin \
  --tmpfs /tmp \
  --tmpfs /home \
  --bind "$(pwd)" "$(pwd)" \
  --unshare-all \
  --die-with-parent \
  --setenv HOME /tmp \
  --setenv PYTHONUSERBASE /tmp/python \
  pip install -r requirements.txt --user

Recommended for CI/CD and most production environments:

Use Docker-based isolation which works universally:

# Works on all CI/CD platforms including GitHub Actions
docker run --rm \
  --network=none \
  --memory=4g \
  --cpus=4 \
  --pids-limit=100 \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  -v $(pwd):/app \
  -w /app \
  python:3.11-slim \
  sh -c "pip install -r requirements.txt --user"

Resource limit explanations:

• --memory: Prevents memory exhaustion attacks; pip's wheel builds can use 2-3GB per package
• --cpus: Prevents CPU hogging; compilation of C extensions can max out cores
• --pids-limit: Prevents fork bombs; 100 is sufficient for typical pip operations
• --security-opt=no-new-privileges: Prevents privilege escalation

Python-specific considerations:

• setuptools/wheel compilation: Can spike memory to 2-3GB per package with C extensions
• Large package downloads: torch (~800MB), tensorflow (~500MB) need adequate memory
• Parallel builds: pip builds wheels in parallel by default; reduce with --no-build-isolation if hitting limits
• Virtual environments: Add ~100-200MB overhead for venv/virtualenv

Monitoring and adjustment:

# Monitor during installation
docker stats

# Signs you need more resources:
# - MemoryError or "Killed" messages
# - Pip hangs during compilation
# - Installation takes >2x expected time

# Adjust upward by 50% if consistently hitting limits

Virtual environment isolation (basic):

# Create isolated venv
python -m venv --clear venv

# Activate and install
source venv/bin/activate
pip install -r requirements.txt

# Deactivate
deactivate

References:

• Docker Python best practices
• Python venv documentation

Audit unused packages:

# Find unused imports (requires pipreqs)
pip install pipreqs
pipreqs --print ./src

# Compare with requirements.txt
comm -3 <(pipreqs --print ./src | sort) <(cat requirements.txt | sort)

# Remove unused packages
pip uninstall <package-name>

Analyze dependency tree:

# Install pipdeptree
pip install pipdeptree

# View dependency tree
pipdeptree

# Show only top-level packages
pipdeptree --packages <package-name>

# Find circular dependencies
pipdeptree --warn fail

# Show reverse dependencies
pipdeptree --reverse --packages <package-name>

Security auditing:

Python has multiple vulnerability scanners with different trade-offs:

pip-audit (recommended for most users - free/open source):

pip install pip-audit
pip-audit                    # Scan current environment
pip-audit -r requirements.txt # Scan requirements file
pip-audit --fix              # Auto-fix vulnerabilities

• Fully free and open source
• Free for commercial use
• Auto-fix capability built-in

Snyk (commercial with good free tier):

snyk test --file=requirements.txt

• Free tier available for open source
• Excellent IDE integration
• Multi-ecosystem support (not just Python)

**pip-audit - clarification note**:
pip-audit only check known vulnerabilities and don't detect malicious code, which is complementary to behavioral scanning.
    
**Evaluate package quality**:
```python
# scripts/check_package_info.py
import json
import urllib.request

def get_package_info(package_name):
    url = f"https://pypi.org/pypi/{package_name}/json"
    with urllib.request.urlopen(url) as response:
        data = json.loads(response.read())
    
    info = data['info']
    print(f"Package: {info['name']}")
    print(f"Version: {info['version']}")
    print(f"Author: {info['author']}")
    print(f"License: {info['license']}")
    print(f"Home page: {info['home_page']}")
    print(f"Last release: {data['urls'][0]['upload_time']}")
    print(f"Downloads (approx): Check pypistats.org")
    
    # Check for setup.py or build requirements
    if 'requires_dist' in info:
        print(f"Dependencies: {len(info['requires_dist'])}")

get_package_info('requests')

References:

• pip-audit documentation
• pipdeptree

Automated security scanning:

# OpenSSF Scorecard
scorecard --repo=github.com/<org>/<repo>

# Bandit (Python-specific SAST)
pip install bandit
# For JSON output
bandit -r <package-source-dir> -f json -o bandit-report.json

# For readable output with severity filtering
bandit -r <package-source-dir> -lll  # Only show HIGH confidence
bandit -r <package-source-dir> -ll   # Show MEDIUM and HIGH confidence
bandit -r <package-source-dir> -i    # Show only MEDIUM and HIGH severity issues

# pip-audit
pip-audit -r requirements.txt

# Snyk
snyk test --file=requirements.txt

Generate SBOM:

# Using CycloneDX
pip install cyclonedx-bom
cyclonedx-py -r requirements.txt -o sbom.json

# Using SPDX
pip install spdx-tools
# (requires manual configuration)

Manual inspection:

# Download without installing
pip download <package-name> --no-deps

# Extract and inspect
tar -xzf <package-name>-<version>.tar.gz
cd <package-name>-<version>

# Check setup.py for suspicious code
cat setup.py

# Check for binary files or obfuscated code
find . -type f -name "*.so"
find . -type f -exec file {} \; | grep -i "executable"

Verify package integrity:

# Verify package integrity
# Option 1: Use --require-hashes during install (recommended)
pip install -r requirements.txt --require-hashes

# Option 2: Manually compute hash to compare with PyPI
sha256sum <package-name>-<version>.whl

# Option 3: Use pip-audit to verify integrity
pip-audit --require-hashes -r requirements.txt

References:

• Bandit documentation
• pip-audit
• CycloneDX Python

Runtime monitoring with Falco:

- rule: Suspicious pip Network Activity
  desc: Detect pip/python making outbound connections to public IPs during install
  condition: >
    proc.name in (pip, pip3, python, python3, setup.py) and
    evt.type=connect and
    evt.dir=> and
    fd.l4proto=tcp and
    not fd.rip in (
      "10.0.0.0/8",
      "172.16.0.0/12",
      "192.168.0.0/16", 
      "127.0.0.0/8"
    )
  output: >
    pip process connecting to public IP during package installation
    (command=%proc.cmdline dst=%fd.rip:%fd.rport sport=%fd.lport
     user=%user.name container=%container.id)
  priority: CRITICAL
  tags: [network, python, pip, supply_chain]

- rule: pip Accessing Sensitive Files
  desc: Detect pip/python accessing SSH keys, cloud credentials, or tokens
  condition: >
    proc.name in (pip, pip3, python, python3, setup.py) and
    evt.type in (open, openat, openat2) and
    evt.is_open_write=false and
    (fd.name glob "/home/*/.ssh/*" or
     fd.name glob "/root/.ssh/*" or
     fd.name glob "/home/*/.aws/*" or
     fd.name glob "/root/.aws/*" or
     fd.name glob "/home/*/.config/gcloud/*" or
     fd.name glob "/root/.config/gcloud/*" or
     fd.name glob "/home/*/.kube/*" or
     fd.name glob "/root/.kube/*" or
     fd.name glob "/home/*/.docker/config.json" or
     fd.name glob "/root/.docker/config.json" or
     fd.name contains "id_rsa" or
     fd.name contains "id_ecdsa" or
     fd.name contains "id_ed25519")
  output: >
    pip process accessing sensitive credential files
    (file=%fd.name command=%proc.cmdline user=%user.name
     parent=%proc.pname container=%container.id)
  priority: CRITICAL
  tags: [filesystem, python, pip, credentials, supply_chain]

- rule: pip Spawning Suspicious Processes
  desc: Detect pip/setup.py spawning shells or network utilities during installation
  condition: >
    spawned_process and
    proc.pname in (pip, pip3, python, python3, setup.py) and
    proc.name in (bash, sh, zsh, curl, wget, nc, netcat, perl, ruby, gcc, cc, make)
  output: >
    pip spawned suspicious subprocess during package installation
    (process=%proc.name cmdline=%proc.cmdline parent=%proc.pname
     user=%user.name container=%container.id)
  priority: WARNING
  tags: [process, python, pip, supply_chain]

# =============================================================================
# Optional: Corporate Environment Adjustments
# =============================================================================
# If using corporate proxies, modify network rules to allow proxy IPs:
#
# - macro: corporate_proxy
#   condition: fd.rip in ("10.0.1.100", "10.0.1.101")
#
# Then update network rules:
#   condition: >
#     ... and
#     not corporate_proxy
#
# =============================================================================
# Notes for Production Use
# =============================================================================
# 1. Test rules in audit mode first (priority: NOTICE instead of WARNING/CRITICAL)
# 2. Tune file paths based on your actual user home directories
# 3. Add exceptions for legitimate build tools if needed
# 4. For CI/CD: Add container.id or k8s pod filters to reduce noise
# 5. Consider using fd.rip instead of fd.sip for destination IPs

Runtime monitoring with Falco:
Falco network rules use IP addresses, not DNS names. For corporate environments with proxies, adjust rules to allow your specific proxy IPs.

Detection approaches:

1. Public IP detection (recommended for isolated builds): Alert on any non-RFC1918 connections
2. Allowlist approach (for environments with known registries): List allowed destination IPs
3. Proxy-aware (for corporate environments): Permit connections through corporate proxies only

Monitor setup.py execution:

# Monitor pip install process
strace -f -e trace=open,openat,connect \
  pip install <package-name> 2>&1 | grep -E '\.ssh|\.aws|\.config'

# Monitor network during install
sudo tcpdump -i any -n 'host not pypi.org and host not files.pythonhosted.org' &
pip install <package-name>
sudo pkill tcpdump

Dependency diff:

# Compare requirements files
diff requirements.txt.old requirements.txt

# Using pip-diff (custom script)
pip freeze > current.txt
# After changes
pip freeze > new.txt
diff current.txt new.txt

Rollback procedures:

# Rollback using git
git show HEAD~1:requirements.txt > requirements.txt
pip install -r requirements.txt --force-reinstall

# Keep backups
cp requirements.txt requirements.txt.backup.$(date +%Y%m%d)

References:

• Falco documentation
• Python security best practices

Maven - Restrict dangerous plugins:

<!-- pom.xml -->
<build>
  <pluginManagement>
    <plugins>
      <!-- Enforce explicit plugin versions everywhere -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-enforcer-plugin</artifactId>
        <version>3.4.1</version>
        <executions>
          <execution>
            <id>enforce-plugin-versions</id>
            <goals><goal>enforce</goal></goals>
            <configuration>
              <rules>
                <requirePluginVersions>
                  <banLatest>true</banLatest>
                  <banRelease>true</banRelease>
                </requirePluginVersions>
              </rules>
            </configuration>
          </execution>
        </executions>
      </plugin>
      <!-- Corporate: define only approved plugins here (whitelist). 
           Omit exec-maven-plugin and maven-antrun-plugin to discourage use. -->
    </plugins>
  </pluginManagement>
</build>

Warning: Banning exec-maven-plugin may break builds that legitimately need to execute code (e.g., code generation, native compilation). Maintain an allowlist of approved use cases.

Gradle - Disable exec tasks:

// build.gradle
import org.gradle.api.tasks.Exec
import org.gradle.api.tasks.JavaExec

def allowed = ['buildNative', 'compileProto'] as Set

tasks.withType(Exec).configureEach {
    enabled = name in allowed
}
tasks.withType(JavaExec).configureEach {
    enabled = name in allowed
}

Gradle Kotlin DSL:

// build.gradle.kts
import org.gradle.api.tasks.Exec
import org.gradle.api.tasks.JavaExec

val allowed = setOf("buildNative", "compileProto")

tasks.withType<Exec>().configureEach {
    enabled = name in allowed
}
tasks.withType<JavaExec>().configureEach {
    enabled = name in allowed
}

Note: Scope this to CI ‘verify’ jobs first; it will break builds that legitimately spawn tools.

Maven settings.xml - Block repositories with executable plugins:

<!-- ~/.m2/settings.xml -->
<settings>
  <mirrors>
    <mirror>
      <id>corporate-maven</id>
      <mirrorOf>*</mirrorOf>
      <url>https://maven.company.com/repository</url>
    </mirror>
  </mirrors>
  <!-- Tip: control dangerous plugins via repository manager policy 
       (block/strip artifacts) and require plugin versions via Enforcer. -->
</settings>

References:

• Maven Enforcer Plugin
• Gradle Task Configuration

Maven - Control direct AND transitive dependencies:

Maven's transitive dependency resolution can introduce vulnerable versions even when your direct dependencies are pinned. Use dependencyManagement to control transitive versions.

<!-- pom.xml -->
<dependencies>
  <!-- Direct dependencies with exact versions -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.1.5</version>
  </dependency>
  
  <dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.15.3</version>
  </dependency>
  
  <!-- Bad - version ranges (avoid these) -->
  <!-- <version>[1.0,2.0)</version> -->
  <!-- <version>LATEST</version> -->
  <!-- <version>RELEASE</version> -->
</dependencies>

<!-- Lock transitive dependency versions -->
<dependencyManagement>
  <dependencies>
    <!-- Override transitive versions explicitly -->
    <!-- Example: spring-boot-starter-web pulls in jackson-core -->
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-core</artifactId>
      <version>2.15.3</version>
    </dependency>
    
    <!-- Example: Control commons-codec version across all dependencies -->
    <dependency>
      <groupId>commons-codec</groupId>
      <artifactId>commons-codec</artifactId>
      <version>1.16.0</version>
    </dependency>
    
    <!-- Example: Override vulnerable transitive dependency -->
    <dependency>
      <groupId>org.yaml</groupId>
      <artifactId>snakeyaml</artifactId>
      <version>2.0</version>
    </dependency>
  </dependencies>
</dependencyManagement>

How this works:

• <dependencies> section: Your direct dependencies with exact versions
• <dependencyManagement> section: Overrides versions for transitive dependencies
• Maven will use the version specified in dependencyManagement even if a direct dependency requests a different version

Identifying which transitives to lock:

# View full dependency tree including transitives
mvn dependency:tree

# Find which version of a transitive is actually resolved
mvn dependency:tree -Dverbose -Dincludes=commons-codec:commons-codec

# Example output shows transitive path:
# [INFO] com.example:myapp:jar:1.0.0
# [INFO] \- org.springframework.boot:spring-boot-starter-web:jar:3.1.5
# [INFO]    \- commons-codec:commons-codec:jar:1.15 (version from transitive)

Maven - Dependency snapshot for verification (Maven 3.8+):

Critical Limitation: Maven does NOT have an enforced lockfile mechanism
like npm/pip/go.

The dependency:list command creates a snapshot for MANUAL COMPARISON ONLY.
Maven WILL NOT fail builds if versions change.

This means:

• Two developers can build "same" code with different dependency versions
• Production builds may differ from testing
• No guarantee of reproducible builds

Workarounds (choose at least 2):

1. Switch to Gradle which has real locking
2. Use corporate repository manager to freeze versions
3. Implement CI check that fails on dependency:tree diff
4. Use exact versions + Maven Enforcer + dependencyManagement

The following creates a text snapshot for manual verification:

# Generate dependency snapshot (for audit/comparison purposes)
mvn dependency:list -DoutputFile=dependencies.lock

# Verify dependencies haven't changed (manual check)
mvn dependency:list -DoutputFile=dependencies-check.lock
diff dependencies.lock dependencies-check.lock

# This is a verification tool, not an enforcement mechanism
# Actual version locking happens via dependencyManagement in pom.xml

Limitation: This snapshot is not automatically enforced by Maven. Teams must rely on dependencyManagement for actual version control and use this snapshot for audit trails and change detection.

CI enforcement example (implementing workaround #3):

# .github/workflows/verify-dependencies.yml
name: Verify Dependency Tree
on: [pull_request]

jobs:
  check-dependencies:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Need history to compare
      
      - uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'
      
      - name: Generate dependency tree for current branch
        run: |
          mvn dependency:tree -DoutputFile=dependency-tree-current.txt -DoutputType=text
      
      - name: Generate dependency tree for base branch
        run: |
          git checkout ${{ github.base_ref }}
          mvn dependency:tree -DoutputFile=dependency-tree-base.txt -DoutputType=text
          git checkout -
      
      - name: Compare dependency trees
        run: |
          if ! diff -u dependency-tree-base.txt dependency-tree-current.txt > dependency-diff.txt; then
            echo "::error::Dependency tree has changed!"
            echo ""
            echo "Dependency changes detected:"
            cat dependency-diff.txt
            echo ""
            echo "If these changes are intentional, document them in the PR description."
            echo "Otherwise, check for version drift or unexpected dependency resolution changes."
            exit 1
          fi
          echo "✓ Dependency tree unchanged"
      
      - name: Upload diff on failure
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: dependency-diff
          path: dependency-diff.txt

This CI check will fail if dependency resolution changes between base branch and PR,
catching version drift that Maven's lack of lockfile would otherwise allow silently.

Gradle - Use dependency locking:

// build.gradle
dependencyLocking {
    lockAllConfigurations()
}

// Generate lock files
// Run: ./gradlew dependencies --write-locks

// Commit gradle.lockfile to version control

Gradle Kotlin DSL:

// build.gradle.kts
dependencyLocking {
    lockAllConfigurations()
}

// Strict mode - fail on missing locks
configurations.all {
    resolutionStrategy.activateDependencyLocking()
}

Verify in CI/CD:

# GitHub Actions
name: Verify Dependencies
on: [pull_request]
jobs:
  verify-maven:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'

      - name: Verify no SNAPSHOT or dynamic versions
        shell: bash
        run: |
          set -euo pipefail
          
          echo "==> Checking for dynamic/SNAPSHOT versions in POMs..."
          
          # Phase 1: Quick check of POM XML directly (fast-fail for obvious issues)
          mapfile -t POMS < <(git ls-files '**/pom.xml')
          bad=false
          
          for pom in "${POMS[@]}"; do
            # Remove XML comments to avoid false positives
            cleaned="$(sed -e 's/<!--[^-]*-[^-]*->//g' "$pom")"
            
            if grep -Eq '<version>.*(LATEST|RELEASE).*</version>' <<< "$cleaned" \
              || grep -Eq '<version>\s*[\(\[].*[\)\]]\s*</version>' <<< "$cleaned" \
              || grep -Eq '<version>.*SNAPSHOT.*</version>' <<< "$cleaned"
            then
              echo "::error file=$pom::Dynamic or SNAPSHOT versions detected in POM XML"
              bad=true
            fi
          done
          
          if [[ "$bad" == true ]]; then
            echo "::error::Direct SNAPSHOT/dynamic versions found in POM files"
            echo "Use exact, non-SNAPSHOT versions only."
            exit 1
          fi
          
          echo "✓ Direct POM check passed"
          
          # Phase 2: Check effective POM (catches property-based versions)
          echo "==> Generating effective POM to check resolved versions..."
          
          # Generate effective POM (resolves all properties)
          if ! mvn help:effective-pom -Doutput=target/effective-pom.xml -B -q; then
            echo "::warning::Could not generate effective POM for deep validation"
            echo "Proceeding with direct POM validation only"
            exit 0
          fi
          
          # Check effective POM for SNAPSHOTs
          if grep -Eq '<version>.*SNAPSHOT.*</version>' target/effective-pom.xml; then
            echo "::error::SNAPSHOT versions detected in effective POM (may be from properties)"
            echo ""
            echo "SNAPSHOT versions found:"
            grep -E '<version>.*SNAPSHOT.*</version>' target/effective-pom.xml | head -10
            echo ""
            echo "This indicates SNAPSHOT versions defined via properties or parent POMs."
            echo "Run locally: mvn help:effective-pom | grep SNAPSHOT"
            exit 1
          fi
          
          # Check for dynamic version ranges in effective POM
          if grep -Eq '<version>\s*[\(\[].*[\)\]]\s*</version>' target/effective-pom.xml; then
            echo "::error::Dynamic version ranges detected in effective POM"
            echo ""
            echo "Dynamic ranges found:"
            grep -E '<version>\s*[\(\[].*[\)\]]\s*</version>' target/effective-pom.xml | head -10
            echo ""
            echo "Use exact versions instead of ranges like [1.0,2.0) or (,1.0]"
            exit 1
          fi
          
          # Check for LATEST/RELEASE in effective POM
          if grep -Eq '<version>.*(LATEST|RELEASE).*</version>' target/effective-pom.xml; then
            echo "::error::LATEST or RELEASE keywords detected in effective POM"
            echo ""
            echo "Dynamic keywords found:"
            grep -E '<version>.*(LATEST|RELEASE).*</version>' target/effective-pom.xml | head -10
            echo ""
            echo "Use exact version numbers instead of LATEST or RELEASE"
            exit 1
          fi
          
          echo "✓ Effective POM check passed"
          echo "✓ All dependency versions are pinned correctly"

      - name: Forbid risky Maven plugins via POM scan
        shell: bash
        run: |
          set -euo pipefail
          mapfile -t POMS < <(git ls-files '**/pom.xml')
          banned='org.codehaus.mojo:exec-maven-plugin|org.apache.maven.plugins:maven-antrun-plugin'
          hit=false
          for pom in "${POMS[@]}"; do
            cleaned="$(sed -e 's/<!--[^-]*-[^-]*->//g' "$pom")"
            if grep -Eq "$banned" <<< "$cleaned"; then
              echo "::error file=$pom::Forbidden Maven plugin referenced (exec-maven-plugin or maven-antrun-plugin)"
              hit=true
            fi
          done
          [[ "$hit" == true ]] && exit 1

      - name: Verify dependencies (structure/conflicts)
        run: mvn -B dependency:tree -Dverbose -DfailOnWarning

  verify-gradle:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'

      - name: Enforce checksum verification against committed metadata
        run: ./gradlew --verify-metadata resolveDependencies

      - name: Ensure verification metadata committed
        run: |
          if ! git ls-files --error-unmatch gradle/verification-metadata.xml >/dev/null 2>&1; then
            echo "::error::gradle/verification-metadata.xml is not committed"
            exit 1
          fi

      - name: Check if verification metadata is current
        run: |
          ./gradlew --write-verification-metadata sha256 dependencies
          if ! git diff --exit-code gradle/verification-metadata.xml; then
            echo "::error::gradle/verification-metadata.xml is out of date"
            echo "Run './gradlew --write-verification-metadata sha256 dependencies' locally and commit changes"
            exit 1
          fi

      - name: Ensure Gradle lockfile is committed
        run: |
          if ! git ls-files --error-unmatch gradle.lockfile >/dev/null 2>&1; then
            echo "::error::gradle.lockfile is not committed to git"
            echo "Run './gradlew dependencies --write-locks' and commit the lockfile"
            exit 1
          fi