@aikidosec/safe-chain 1.4.1 → 1.4.3

package/README.md

@@ -66,7 +66,6 @@ You can find all available versions on the [releases page](https://github.com/Ai
 ### Verify the installation
 
 1. **❗Restart your terminal** to start using the Aikido Safe Chain.
-
    - This step is crucial as it ensures that the shell aliases for npm, npx, yarn, pnpm, pnpx, bun, bunx, pip, pip3, poetry, uv and pipx are loaded correctly. If you do not restart your terminal, the aliases will not be available.
 
 2. **Verify the installation** by running the verification command:
@@ -152,23 +151,35 @@ 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.
+
+### 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
+     ```
 
-- `--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.
+   - `--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.
 
-  Example usage:
+     ```shell
+     npm install express --safe-chain-logging=verbose
+     ```
 
-  ```shell
-  npm install express --safe-chain-logging=silent
-  ```
+2. **Environment Variable**:
 
-- `--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
+   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 +210,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 +285,8 @@ iex "& { $(iwr 'https://github.com/AikidoSec/safe-chain/releases/latest/download
 - ✅ **Azure Pipelines**
 - ✅ **CircleCI**
 - ✅ **Jenkins**
+- ✅ **Bitbucket Pipelines**
+- ✅ **GitLab Pipelines**
 
 ## GitHub Actions Example
 
@@ -347,8 +376,85 @@ pipeline {
 }
 ```
 
+## Bitbucket Pipelines Example
+
+```yaml
+image: node:22
+
+steps:
+  - step:
+      name: Install
+      script:
+        - curl -fsSL https://github.com/AikidoSec/safe-chain/releases/latest/download/install-safe-chain.sh | sh -s -- --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.
 
+## GitLab Pipelines Example
+
+To add safe-chain in GitLab pipelines, you need to install it in the image running the pipeline. This can be done by:
+
+1. Define a dockerfile to run your build
+
+   ```dockerfile
+   FROM node:lts
+
+   # Install safe-chain
+   RUN curl -fsSL https://github.com/AikidoSec/safe-chain/releases/latest/download/install-safe-chain.sh | sh -s -- --ci
+
+   # Add safe-chain to PATH
+   ENV PATH="/root/.safe-chain/shims:/root/.safe-chain/bin:${PATH}"
+   ```
+
+2. Build the Docker image in your CI pipeline
+
+   ```yaml
+   build-image:
+     stage: build-image
+     image: docker:latest
+     services:
+       - docker:dind
+     script:
+       - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
+       - docker build -t $CI_REGISTRY_IMAGE:latest .
+       - docker push $CI_REGISTRY_IMAGE:latest
+   ```
+
+3. Use the image in your pipeline:
+   ```yaml
+   npm-ci:
+     stage: install
+     image: $CI_REGISTRY_IMAGE:latest
+     script:
+       - npm ci
+   ```
+
+The full pipeline for this example looks like this:
+
+```yaml
+stages:
+  - build-image
+  - install
+
+build-image:
+  stage: build-image
+  image: docker:latest
+  services:
+    - docker:dind
+  script:
+    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
+    - docker build -t $CI_REGISTRY_IMAGE:latest .
+    - docker push $CI_REGISTRY_IMAGE:latest
+
+npm-ci:
+  stage: install
+  image: $CI_REGISTRY_IMAGE:latest
+  script:
+    - npm ci
+```
+
 # Troubleshooting
 
-Having issues? See the [Troubleshooting Guide](https://github.com/AikidoSec/safe-chain/blob/main/docs/troubleshooting.md) for help with common problems.
+Having issues? See the [Troubleshooting Guide](https://help.aikido.dev/code-scanning/aikido-malware-scanning/safe-chain-troubleshooting) for help with common problems.

package/bin/safe-chain.js

@@ -16,6 +16,14 @@ import path from "path";
 import { fileURLToPath } from "url";
 import fs from "fs";
 import { knownAikidoTools } from "../src/shell-integration/helpers.js";
+import {
+  installUltimate,
+  uninstallUltimate,
+} from "../src/installation/installUltimate.js";
+import {
+  printUltimateLogs,
+  troubleshootingExport,
+} from "../src/ultimate/ultimateTroubleshooting.js";
 
 /** @type {string} */
 // This checks the current file's dirname in a way that's compatible with:
@@ -62,9 +70,42 @@ if (tool) {
   process.exit(0);
 } else if (command === "setup") {
   setup();
+} else if (command === "ultimate") {
+  const cliArgs = initializeCliArguments(process.argv.slice(2));
+  const subCommand = cliArgs[1];
+  if (subCommand === "uninstall") {
+    guardCliArgsMaxLenght(2, cliArgs, "safe-chain ultimate uninstall");
+    (async () => {
+      await uninstallUltimate();
+    })();
+  } else if (subCommand === "troubleshooting-logs") {
+    guardCliArgsMaxLenght(
+      2,
+      cliArgs,
+      "safe-chain ultimate troubleshooting-logs",
+    );
+    (async () => {
+      await printUltimateLogs();
+    })();
+  } else if (subCommand === "troubleshooting-export") {
+    guardCliArgsMaxLenght(
+      2,
+      cliArgs,
+      "safe-chain ultimate troubleshooting-export",
+    );
+    (async () => {
+      await troubleshootingExport();
+    })();
+  } else {
+    guardCliArgsMaxLenght(1, cliArgs, "safe-chain ultimate");
+    // Install command = when no subcommand is provided (safe-chain ultimate)
+    (async () => {
+      await installUltimate();
+    })();
+  }
 } else if (command === "teardown") {
-  teardownDirectories();
   teardown();
+  teardownDirectories();
 } else if (command === "setup-ci") {
   setupCi();
 } else if (command === "--version" || command === "-v" || command === "-v") {
@@ -80,38 +121,77 @@ if (tool) {
   process.exit(1);
 }
 
+/**
+ * @param {Number} maxLength
+ * @param {String[]} args
+ * @param {String} command
+ */
+function guardCliArgsMaxLenght(maxLength, args, command) {
+  if (args.length > maxLength) {
+    ui.writeError(`Unexpected number of arguments for command ${command}.`);
+    ui.emptyLine();
+
+    writeHelp();
+
+    process.exit(1);
+  }
+}
+
 function writeHelp() {
   ui.writeInformation(
-    chalk.bold("Usage: ") + chalk.cyan("safe-chain <command>")
+    chalk.bold("Usage: ") + chalk.cyan("safe-chain <command>"),
   );
   ui.emptyLine();
   ui.writeInformation(
     `Available commands: ${chalk.cyan("setup")}, ${chalk.cyan(
-      "teardown"
-    )}, ${chalk.cyan("setup-ci")}, ${chalk.cyan("help")}, ${chalk.cyan(
-      "--version"
-    )}`
+      "teardown",
+    )}, ${chalk.cyan("setup-ci")}, ${chalk.cyan("ultimate")}, ${chalk.cyan("help")}, ${chalk.cyan(
+      "--version",
+    )}`,
   );
   ui.emptyLine();
   ui.writeInformation(
     `- ${chalk.cyan(
-      "safe-chain setup"
-    )}: This will setup your shell to wrap safe-chain around npm, npx, yarn, pnpm, pnpx, bun, bunx, pip and pip3.`
+      "safe-chain setup",
+    )}: This will setup your shell to wrap safe-chain around npm, npx, yarn, pnpm, pnpx, bun, bunx, pip and pip3.`,
   );
   ui.writeInformation(
     `- ${chalk.cyan(
-      "safe-chain teardown"
-    )}: This will remove safe-chain aliases from your shell configuration.`
+      "safe-chain teardown",
+    )}: This will remove safe-chain aliases from your shell configuration.`,
   );
   ui.writeInformation(
     `- ${chalk.cyan(
-      "safe-chain setup-ci"
-    )}: This will setup safe-chain for CI environments by creating shims and modifying the PATH.`
+      "safe-chain setup-ci",
+    )}: This will setup safe-chain for CI environments by creating shims and modifying the PATH.`,
   );
   ui.writeInformation(
     `- ${chalk.cyan("safe-chain --version")} (or ${chalk.cyan(
-      "-v"
-    )}): Display the current version of safe-chain.`
+      "-v",
+    )}): Display the current version of safe-chain.`,
+  );
+  ui.emptyLine();
+  ui.writeInformation(chalk.bold("Ultimate commands:"));
+  ui.emptyLine();
+  ui.writeInformation(
+    `- ${chalk.cyan(
+      "safe-chain ultimate",
+    )}: Install the ultimate version of safe-chain, enabling protection for more eco-systems.`,
+  );
+  ui.writeInformation(
+    `- ${chalk.cyan(
+      "safe-chain ultimate troubleshooting-logs",
+    )}: Prints standard and error logs for safe-chain ultimate and it's proxy.`,
+  );
+  ui.writeInformation(
+    `- ${chalk.cyan(
+      "safe-chain ultimate troubleshooting-export",
+    )}: Creates a zip archive of useful data for troubleshooting safe-chain ultimate, that can be shared with our support team.`,
+  );
+  ui.writeInformation(
+    `- ${chalk.cyan(
+      "safe-chain ultimate uninstall",
+    )}: Uninstall the ultimate version of safe-chain.`,
   );
   ui.emptyLine();
 }

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
@@ -97,6 +149,37 @@ Should include `~/.safe-chain/bin`
 
 **If persists:** Re-run the installation script
 
+### PowerShell Execution Policy Blocks Scripts (Windows)
+
+**Symptom:** When opening PowerShell, you see an error like:
+
+```
+. : File C:\Users\<username>\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1 cannot be loaded because
+running scripts is disabled on this system.
+CategoryInfo          : SecurityError: (:) [], PSSecurityException
+FullyQualifiedErrorId : UnauthorizedAccess
+```
+
+**Cause:** Windows PowerShell's default execution policy (`Restricted`) blocks all script execution, including safe-chain's initialization script that's sourced from your PowerShell profile.
+
+**Resolution:**
+
+1. **Set the execution policy to allow local scripts:**
+
+   Open PowerShell as Administrator and run:
+
+   ```powershell
+   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
+   ```
+
+   This allows:
+   - Local scripts (like safe-chain's) to run without signing
+   - Downloaded scripts to run only if signed by a trusted publisher
+
+2. **Restart PowerShell** and verify the error is resolved.
+
+> **Note:** `RemoteSigned` is Microsoft's recommended execution policy for client computers. It provides a good balance between security and usability.
+
 ### Shell Aliases Persist After Uninstallation
 
 **Symptom:** safe-chain commands still active after running uninstall script
@@ -225,17 +308,6 @@ Look for and remove:
 rm -rf ~/.safe-chain
 ```
 
-## Getting More Information
-
-### Enable Verbose Logging
-
-Get detailed diagnostic output:
-
-```bash
-npm install express --safe-chain-logging=verbose
-pip install requests --safe-chain-logging=verbose
-```
-
 ### Report Issues
 
 If you encounter problems:
@@ -246,4 +318,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.1",
+  "version": "1.4.3",
   "scripts": {
     "test": "node --test --experimental-test-module-mocks 'src/**/*.spec.js'",
     "test:watch": "node --test --watch --experimental-test-module-mocks 'src/**/*.spec.js'",
@@ -38,6 +38,7 @@
   "license": "AGPL-3.0-or-later",
   "description": "The Aikido Safe Chain wraps around the [npm cli](https://github.com/npm/cli), [npx](https://github.com/npm/cli/blob/latest/docs/content/commands/npx.md), [yarn](https://yarnpkg.com/), [pnpm](https://pnpm.io/), [pnpx](https://pnpm.io/cli/dlx), [bun](https://bun.sh/), [bunx](https://bun.sh/docs/cli/bunx), [uv](https://docs.astral.sh/uv/) (Python), and [pip](https://pip.pypa.io/) to provide extra checks before installing new packages. This tool will detect when a package contains malware and prompt you to exit, preventing npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, or pip/pip3 from downloading or running the malware.",
   "dependencies": {
+    "archiver": "^7.0.1",
     "certifi": "14.5.15",
     "chalk": "5.4.1",
     "https-proxy-agent": "7.0.6",
@@ -48,6 +49,7 @@
     "semver": "7.7.2"
   },
   "devDependencies": {
+    "@types/archiver": "^7.0.0",
     "@types/ini": "^4.1.1",
     "@types/make-fetch-happen": "^10.0.4",
     "@types/node": "^18.19.130",

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;
+}