@aikidosec/safe-chain 1.4.0 → 1.4.2

package/README.md

@@ -152,23 +152,36 @@ iex (iwr "https://github.com/AikidoSec/safe-chain/releases/latest/download/unins
 
 ## Logging
 
-You can control the output from Aikido Safe Chain using the `--safe-chain-logging` flag:
+You can control the output from Aikido Safe Chain using the `--safe-chain-logging` flag or the `SAFE_CHAIN_LOGGING` environment variable.
 
-- `--safe-chain-logging=silent` - Suppresses all Aikido Safe Chain output except when malware is blocked. The package manager output is written to stdout as normal, and Safe Chain only writes a short message if it has blocked malware and causes the process to exit.
+### Configuration Options
+
+You can set the logging level through multiple sources (in order of priority):
+
+1. **CLI Argument** (highest priority):
+
+   - `--safe-chain-logging=silent` - Suppresses all Aikido Safe Chain output except when malware is blocked. The package manager output is written to stdout as normal, and Safe Chain only writes a short message if it has blocked malware and causes the process to exit.
+
+     ```shell
+     npm install express --safe-chain-logging=silent
+     ```
 
-  Example usage:
+   - `--safe-chain-logging=verbose` - Enables detailed diagnostic output from Aikido Safe Chain. Useful for troubleshooting issues or understanding what Safe Chain is doing behind the scenes.
 
-  ```shell
-  npm install express --safe-chain-logging=silent
-  ```
+     ```shell
+     npm install express --safe-chain-logging=verbose
+     ```
 
-- `--safe-chain-logging=verbose` - Enables detailed diagnostic output from Aikido Safe Chain. Useful for troubleshooting issues or understanding what Safe Chain is doing behind the scenes.
+2. **Environment Variable**:
+
+   ```shell
+   export SAFE_CHAIN_LOGGING=verbose
+   npm install express
+   ```
 
-  Example usage:
+   Valid values: `silent`, `normal`, `verbose`
 
-  ```shell
-  npm install express --safe-chain-logging=verbose
-  ```
+   This is useful for setting a default logging level for all package manager commands in your terminal session or CI/CD environment.
 
 ## Minimum Package Age
 
@@ -199,6 +212,22 @@ You can set the minimum package age through multiple sources (in order of priori
    }
    ```
 
+### Excluding Packages
+
+Exclude trusted packages from minimum age filtering via environment variable or config file (both are merged). Use `@scope/*` to trust all packages from an organization:
+
+```shell
+export SAFE_CHAIN_NPM_MINIMUM_PACKAGE_AGE_EXCLUSIONS="@aikidosec/*"
+```
+
+```json
+{
+  "npm": {
+    "minimumPackageAgeExclusions": ["@aikidosec/*"]
+  }
+}
+```
+
 ## Custom Registries
 
 Configure Safe Chain to scan packages from custom or private registries.
@@ -258,6 +287,7 @@ iex "& { $(iwr 'https://github.com/AikidoSec/safe-chain/releases/latest/download
 - ✅ **Azure Pipelines**
 - ✅ **CircleCI**
 - ✅ **Jenkins**
+- ✅ **Bitbucket Pipelines**
 
 ## GitHub Actions Example
 
@@ -347,6 +377,21 @@ pipeline {
 }
 ```
 
+## Bitbucket Pipelines Example
+
+```yaml
+image: node:22
+
+steps:
+  - step:
+      name: Install
+      script:
+        - npm install -g @aikidosec/safe-chain
+        - safe-chain setup-ci
+        - export PATH=~/.safe-chain/shims:$PATH
+        - npm ci
+```
+
 After setup, all subsequent package manager commands in your CI pipeline will automatically be protected by Aikido Safe Chain's malware detection.
 
 # Troubleshooting

package/docs/troubleshooting.md

@@ -44,20 +44,72 @@ pip3 install safe-chain-pi-test
 
 These test packages are flagged as malware and should be blocked by Safe Chain.
 
+**If the test package installs successfully instead of being blocked**, see [Malware Not Being Blocked](#malware-not-being-blocked) below.
+
 ### Logging Options
 
-Use logging flags to get more information:
+Use logging flags or environment variables to get more information:
 
 ```bash
 # Verbose mode - detailed diagnostic output for troubleshooting
 npm install express --safe-chain-logging=verbose
 
+# Or set it globally for all commands in your session
+export SAFE_CHAIN_LOGGING=verbose
+npm install express
+
 # Silent mode - suppress all output except malware blocking
 npm install express --safe-chain-logging=silent
 ```
 
 ## Common Issues
 
+### Malware Not Being Blocked
+
+**Symptom:** Test malware packages (like `safe-chain-test`) install successfully when they should be blocked
+
+**Most Common Cause:** The package is cached in your package manager's local store
+
+Safe-chain blocks malicious packages by intercepting network requests to package registries using its proxy.
+
+When a package is already cached locally, the package manager skips downloading it from the registry, which bypasses the proxy.
+
+**Resolution Steps:**
+
+1. **Clear your package manager's cache:**
+
+   ```bash
+   # For npm
+   npm cache clean --force
+
+   # For pnpm
+   pnpm store prune
+
+   # For yarn (classic)
+   yarn cache clean
+
+   # For yarn (berry/v2+)
+   yarn cache clean --all
+
+   # For bun
+   bun pm cache rm
+   ```
+
+   > **⚠️ Warning:** Cache clearing is safe but will remove all cached packages. Subsequent installations will need to re-download packages. In CI/CD environments or monorepos, this may affect build times.
+
+2. **Clean local installation artifacts:**
+
+   ```bash
+   # Remove node_modules if you want a completely fresh install
+   rm -rf node_modules
+   ```
+
+3. **Re-test malware blocking:**
+
+   ```bash
+   npm install safe-chain-test    # Should be blocked
+   ```
+
 ### Shell Aliases Not Working After Installation
 
 **Symptom:** Running `npm` shows regular npm instead of safe-chain wrapped version
@@ -229,11 +281,16 @@ rm -rf ~/.safe-chain
 
 ### Enable Verbose Logging
 
-Get detailed diagnostic output:
+Get detailed diagnostic output using a CLI flag or environment variable:
 
 ```bash
+# Using CLI flag
 npm install express --safe-chain-logging=verbose
 pip install requests --safe-chain-logging=verbose
+
+# Using environment variable (applies to all commands)
+export SAFE_CHAIN_LOGGING=verbose
+npm install express
 ```
 
 ### Report Issues
@@ -246,4 +303,4 @@ If you encounter problems:
    - Shell type and version
    - `safe-chain --version` output
    - Output from verification commands
-   - Verbose logs of the failing command
+   - Verbose logs of the failing command (add the `--safe-chain-logging=verbose` argument)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikidosec/safe-chain",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "scripts": {
     "test": "node --test --experimental-test-module-mocks 'src/**/*.spec.js'",
     "test:watch": "node --test --watch --experimental-test-module-mocks 'src/**/*.spec.js'",

package/src/api/aikido.js

@@ -1,5 +1,10 @@
 import fetch from "make-fetch-happen";
-import { getEcoSystem, ECOSYSTEM_JS, ECOSYSTEM_PY } from "../config/settings.js";
+import {
+  getEcoSystem,
+  ECOSYSTEM_JS,
+  ECOSYSTEM_PY,
+} from "../config/settings.js";
+import { ui } from "../environment/userInteraction.js";
 
 const malwareDatabaseUrls = {
   [ECOSYSTEM_JS]: "https://malware-list.aikido.dev/malware_predictions.json",
@@ -17,38 +22,91 @@ const malwareDatabaseUrls = {
  * @returns {Promise<{malwareDatabase: MalwarePackage[], version: string | undefined}>}
  */
 export async function fetchMalwareDatabase() {
-  const ecosystem = getEcoSystem();
-  const malwareDatabaseUrl = malwareDatabaseUrls[/** @type {keyof typeof malwareDatabaseUrls} */ (ecosystem)];
-  const response = await fetch(malwareDatabaseUrl);
-  if (!response.ok) {
-    throw new Error(`Error fetching ${ecosystem} malware database: ${response.statusText}`);
-  }
+  const numberOfAttempts = 4;
 
-  try {
-    let malwareDatabase = await response.json();
-    return {
-      malwareDatabase: malwareDatabase,
-      version: response.headers.get("etag") || undefined,
-    };
-  } catch (/** @type {any} */ error) {
-    throw new Error(`Error parsing malware database: ${error.message}`);
-  }
+  return retry(async () => {
+    const ecosystem = getEcoSystem();
+    const malwareDatabaseUrl =
+      malwareDatabaseUrls[
+        /** @type {keyof typeof malwareDatabaseUrls} */ (ecosystem)
+      ];
+    const response = await fetch(malwareDatabaseUrl);
+    if (!response.ok) {
+      throw new Error(
+        `Error fetching ${ecosystem} malware database: ${response.statusText}`
+      );
+    }
+
+    try {
+      let malwareDatabase = await response.json();
+      return {
+        malwareDatabase: malwareDatabase,
+        version: response.headers.get("etag") || undefined,
+      };
+    } catch (/** @type {any} */ error) {
+      throw new Error(`Error parsing malware database: ${error.message}`);
+    }
+  }, numberOfAttempts);
 }
 
 /**
  * @returns {Promise<string | undefined>}
  */
 export async function fetchMalwareDatabaseVersion() {
-  const ecosystem = getEcoSystem();
-  const malwareDatabaseUrl = malwareDatabaseUrls[/** @type {keyof typeof malwareDatabaseUrls} */ (ecosystem)];
-  const response = await fetch(malwareDatabaseUrl, {
-    method: "HEAD",
-  });
-
-  if (!response.ok) {
-    throw new Error(
-      `Error fetching ${ecosystem} malware database version: ${response.statusText}`
-    );
+  const numberOfAttempts = 4;
+
+  return retry(async () => {
+    const ecosystem = getEcoSystem();
+    const malwareDatabaseUrl =
+      malwareDatabaseUrls[
+        /** @type {keyof typeof malwareDatabaseUrls} */ (ecosystem)
+      ];
+    const response = await fetch(malwareDatabaseUrl, {
+      method: "HEAD",
+    });
+
+    if (!response.ok) {
+      throw new Error(
+        `Error fetching ${ecosystem} malware database version: ${response.statusText}`
+      );
+    }
+    return response.headers.get("etag") || undefined;
+  }, numberOfAttempts);
+}
+
+/**
+ * Retries an asynchronous function multiple times until it succeeds or exhausts all attempts.
+ *
+ * @template T
+ * @param {() => Promise<T>} func - The asynchronous function to retry
+ * @param {number} attempts - The number of attempts
+ * @returns {Promise<T>} The return value of the function if successful
+ * @throws {Error} The last error encountered if all retry attempts fail
+ */
+async function retry(func, attempts) {
+  let lastError;
+
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await func();
+    } catch (error) {
+      ui.writeVerbose(
+        "An error occurred while trying to download the Aikido Malware database",
+        error
+      );
+      lastError = error;
+    }
+
+    if (i < attempts - 1) {
+      // When this is not the last try, back-off exponentially:
+      //  1st attempt - 500ms delay
+      //  2nd attempt - 1000ms delay
+      //  3rd attempt - 2000ms delay
+      //  4th attempt - 4000ms delay
+      //  ...
+      await new Promise((resolve) => setTimeout(resolve, Math.pow(2, i) * 500));
+    }
   }
-  return response.headers.get("etag") || undefined;
+
+  throw lastError;
 }

package/src/config/configFile.js

@@ -16,6 +16,7 @@ import { getEcoSystem } from "./settings.js";
  * @typedef {Object} SafeChainRegistryConfiguration
  * We cannot trust the input and should add the necessary validations.
  * @property {unknown | string[]} customRegistries
+ * @property {unknown | string[]} minimumPackageAgeExclusions
  */
 
 /**
@@ -127,6 +128,27 @@ export function getPipCustomRegistries() {
   return customRegistries.filter((item) => typeof item === "string");
 }
 
+/**
+ * Gets the minimum package age exclusions from the config file
+ * @returns {string[]}
+ */
+export function getNpmMinimumPackageAgeExclusions() {
+  const config = readConfigFile();
+
+  if (!config || !config.npm) {
+    return [];
+  }
+
+  const npmConfig = /** @type {SafeChainRegistryConfiguration} */ (config.npm);
+  const exclusions = npmConfig.minimumPackageAgeExclusions;
+
+  if (!Array.isArray(exclusions)) {
+    return [];
+  }
+
+  return exclusions.filter((item) => typeof item === "string");
+}
+
 /**
  * @param {import("../api/aikido.js").MalwarePackage[]} data
  * @param {string | number} version

package/src/config/environmentVariables.js

@@ -25,3 +25,22 @@ export function getNpmCustomRegistries() {
 export function getPipCustomRegistries() {
   return process.env.SAFE_CHAIN_PIP_CUSTOM_REGISTRIES;
 }
+
+/**
+ * Gets the logging level from environment variable
+ * Valid values: "silent", "normal", "verbose"
+ * @returns {string | undefined}
+ */
+export function getLoggingLevel() {
+  return process.env.SAFE_CHAIN_LOGGING;
+}
+
+/**
+ * Gets the minimum package age exclusions from environment variable
+ * Expected format: comma-separated list of package names
+ * Example: "react,@aikidosec/safe-chain,lodash"
+ * @returns {string | undefined}
+ */
+export function getNpmMinimumPackageAgeExclusions() {
+  return process.env.SAFE_CHAIN_NPM_MINIMUM_PACKAGE_AGE_EXCLUSIONS;
+}

package/src/config/settings.js

@@ -7,14 +7,20 @@ export const LOGGING_NORMAL = "normal";
 export const LOGGING_VERBOSE = "verbose";
 
 export function getLoggingLevel() {
-  const level = cliArguments.getLoggingLevel();
-
-  if (level === LOGGING_SILENT) {
-    return LOGGING_SILENT;
+  // Priority 1: CLI argument
+  const cliLevel = cliArguments.getLoggingLevel();
+  if (cliLevel === LOGGING_SILENT || cliLevel === LOGGING_VERBOSE) {
+    return cliLevel;
+  }
+  if (cliLevel) {
+    // CLI arg was set but invalid, default to normal for backwards compatibility.
+    return LOGGING_NORMAL;
   }
 
-  if (level === LOGGING_VERBOSE) {
-    return LOGGING_VERBOSE;
+  // Priority 2: Environment variable
+  const envLevel = environmentVariables.getLoggingLevel()?.toLowerCase();
+  if (envLevel === LOGGING_SILENT || envLevel === LOGGING_VERBOSE) {
+    return envLevel;
   }
 
   return LOGGING_NORMAL;
@@ -161,3 +167,34 @@ export function getPipCustomRegistries() {
   // Normalize each registry (remove protocol if any)
   return uniqueRegistries.map(normalizeRegistry);
 }
+
+/**
+ * Parses comma-separated exclusions from environment variable
+ * @param {string | undefined} envValue
+ * @returns {string[]}
+ */
+function parseExclusionsFromEnv(envValue) {
+  if (!envValue || typeof envValue !== "string") {
+    return [];
+  }
+
+  return envValue
+    .split(",")
+    .map((exclusion) => exclusion.trim())
+    .filter((exclusion) => exclusion.length > 0);
+}
+
+/**
+ * Gets the minimum package age exclusions from both environment variable and config file (merged)
+ * @returns {string[]}
+ */
+export function getNpmMinimumPackageAgeExclusions() {
+  const envExclusions = parseExclusionsFromEnv(
+    environmentVariables.getNpmMinimumPackageAgeExclusions()
+  );
+  const configExclusions = configFile.getNpmMinimumPackageAgeExclusions();
+
+  // Merge both sources and remove duplicates
+  const allExclusions = [...envExclusions, ...configExclusions];
+  return [...new Set(allExclusions)];
+}

package/src/registryProxy/interceptors/npm/modifyNpmInfo.js

@@ -1,4 +1,4 @@
-import { getMinimumPackageAgeHours } from "../../../config/settings.js";
+import { getMinimumPackageAgeHours, getNpmMinimumPackageAgeExclusions } from "../../../config/settings.js";
 import { ui } from "../../../environment/userInteraction.js";
 import { getHeaderValueAsString } from "../../http-utils.js";
 
@@ -65,6 +65,16 @@ export function modifyNpmInfoResponse(body, headers) {
       return body;
     }
 
+    // Check if this package is excluded from minimum age filtering
+    const packageName = bodyJson.name;
+    const exclusions = getNpmMinimumPackageAgeExclusions();
+    if (packageName && exclusions.some((pattern) => matchesExclusionPattern(packageName, pattern))) {
+      ui.writeVerbose(
+        `Safe-chain: ${packageName} is excluded from minimum package age filtering (minimumPackageAgeExclusions setting).`
+      );
+      return body;
+    }
+
     const cutOff = new Date(
       new Date().getTime() - getMinimumPackageAgeHours() * 3600 * 1000
     );
@@ -116,8 +126,10 @@ export function modifyNpmInfoResponse(body, headers) {
 function deleteVersionFromJson(json, version) {
   state.hasSuppressedVersions = true;
 
+  const packageName = typeof json?.name === "string" ? json.name : "(unknown)";
+
   ui.writeVerbose(
-    `Safe-chain: ${version} is newer than ${getMinimumPackageAgeHours()} hours and was removed (minimumPackageAgeInHours setting).`
+    `Safe-chain: ${packageName}@${version} is newer than ${getMinimumPackageAgeHours()} hours and was removed (minimumPackageAgeInHours setting).`
   );
 
   delete json.time[version];
@@ -175,3 +187,17 @@ function getMostRecentTag(tagList) {
 export function getHasSuppressedVersions() {
   return state.hasSuppressedVersions;
 }
+
+/**
+ * Checks if a package name matches an exclusion pattern.
+ * Supports trailing wildcard (*) for prefix matching.
+ * @param {string} packageName
+ * @param {string} pattern
+ * @returns {boolean}
+ */
+function matchesExclusionPattern(packageName, pattern) {
+  if (pattern.endsWith("/*")) {
+    return packageName.startsWith(pattern.slice(0, -1));
+  }
+  return packageName === pattern;
+}

package/src/shell-integration/startup-scripts/init-pwsh.ps1

@@ -6,27 +6,27 @@ $safeChainBin = Join-Path (Join-Path $HOME '.safe-chain') 'bin'
 $env:PATH = "$env:PATH$pathSeparator$safeChainBin"
 
 function npx {
-    Invoke-WrappedCommand "npx" $args
+    Invoke-WrappedCommand "npx" $args $MyInvocation.Line $MyInvocation.OffsetInLine
 }
 
 function yarn {
-    Invoke-WrappedCommand "yarn" $args
+    Invoke-WrappedCommand "yarn" $args $MyInvocation.Line $MyInvocation.OffsetInLine
 }
 
 function pnpm {
-    Invoke-WrappedCommand "pnpm" $args
+    Invoke-WrappedCommand "pnpm" $args $MyInvocation.Line $MyInvocation.OffsetInLine
 }
 
 function pnpx {
-    Invoke-WrappedCommand "pnpx" $args
+    Invoke-WrappedCommand "pnpx" $args $MyInvocation.Line $MyInvocation.OffsetInLine
 }
 
 function bun {
-    Invoke-WrappedCommand "bun" $args
+    Invoke-WrappedCommand "bun" $args $MyInvocation.Line $MyInvocation.OffsetInLine
 }
 
 function bunx {
-    Invoke-WrappedCommand "bunx" $args
+    Invoke-WrappedCommand "bunx" $args $MyInvocation.Line $MyInvocation.OffsetInLine
 }
 
 function npm {
@@ -37,37 +37,37 @@ function npm {
         return
     }
 
-    Invoke-WrappedCommand "npm" $args
+    Invoke-WrappedCommand "npm" $args $MyInvocation.Line $MyInvocation.OffsetInLine
 }
 
 function pip {
-    Invoke-WrappedCommand "pip" $args
+    Invoke-WrappedCommand "pip" $args $MyInvocation.Line $MyInvocation.OffsetInLine
 }
 
 function pip3 {
-    Invoke-WrappedCommand "pip3" $args
+    Invoke-WrappedCommand "pip3" $args $MyInvocation.Line $MyInvocation.OffsetInLine
 }
 
 function uv {
-    Invoke-WrappedCommand "uv" $args
+    Invoke-WrappedCommand "uv" $args $MyInvocation.Line $MyInvocation.OffsetInLine
 }
 
 function poetry {
-    Invoke-WrappedCommand "poetry" $args
+    Invoke-WrappedCommand "poetry" $args $MyInvocation.Line $MyInvocation.OffsetInLine
 }
 
 # `python -m pip`, `python -m pip3`.
 function python {
-    Invoke-WrappedCommand 'python' $args
+    Invoke-WrappedCommand 'python' $args $MyInvocation.Line $MyInvocation.OffsetInLine
 }
 
 # `python3 -m pip`, `python3 -m pip3'.
 function python3 {
-    Invoke-WrappedCommand 'python3' $args
+    Invoke-WrappedCommand 'python3' $args $MyInvocation.Line $MyInvocation.OffsetInLine
 }
 
 function pipx {
-    Invoke-WrappedCommand "pipx" $args
+    Invoke-WrappedCommand "pipx" $args $MyInvocation.Line $MyInvocation.OffsetInLine
 }
 
 function Write-SafeChainWarning {
@@ -108,13 +108,60 @@ function Invoke-RealCommand {
     }
 }
 
+function Get-ReconstructedArguments {
+    param(
+        [string]$RawLine,
+        [int]$RawOffset
+    )
+
+    if (-not $RawLine) { return $null }
+
+    $tokens = [System.Management.Automation.PSParser]::Tokenize($RawLine, [ref]$null)
+    $newArgs = @()
+    $foundCommand = $false
+
+    foreach ($t in $tokens) {
+        if (-not $foundCommand) {
+            if ($t.Start -eq ($RawOffset - 1)) { $foundCommand = $true }
+            continue
+        }
+        
+        if ($t.Type -eq 'Operator' -and $t.Content -match '[|;&]') { break }
+        
+        # Stop if complex variable expansion is used
+        if ($t.Type -eq 'Variable' -or $t.Type -eq 'Group' -or $t.Type -eq 'SubExpression') {
+            return $null
+        }
+        
+        $newArgs += $t.Content
+    }
+
+    if ($foundCommand) {
+        return ,$newArgs
+    }
+    return $null
+}
+
 function Invoke-WrappedCommand {
     param(
         [string]$OriginalCmd,
-        [string[]]$Arguments
+        [string[]]$Arguments,
+        [string]$RawLine = $null,
+        [int]$RawOffset = 0
     )
 
-    if (Test-CommandAvailable "safe-chain") {
+    # Use raw line parsing to recover arguments like '--' that PowerShell consumes
+    if ($RawLine) {
+        $reconstructedArgs = Get-ReconstructedArguments $RawLine $RawOffset
+        if ($null -ne $reconstructedArgs) {
+            $Arguments = $reconstructedArgs
+        }
+    }
+
+    if ($isWindowsPlatform -and (Test-CommandAvailable "safe-chain.cmd")) {
+        & safe-chain.cmd $OriginalCmd @Arguments
+    }
+    elseif (Test-CommandAvailable "safe-chain") {
         & safe-chain $OriginalCmd @Arguments
     }
     else {