@aikidosec/safe-chain 1.3.3 → 1.4.0

package/README.md

@@ -33,8 +33,6 @@ Aikido Safe Chain supports the following package managers:
 
 Installing the Aikido Safe Chain is easy with our one-line installer.
 
-> ⚠️ **Already installed via npm?** See the [migration guide](https://github.com/AikidoSec/safe-chain/blob/main/docs/npm-to-binary-migration.md) to switch to the binary version.
-
 ### Unix/Linux/macOS
 
 ```shell
@@ -71,7 +69,20 @@ You can find all available versions on the [releases page](https://github.com/Ai
 
    - 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 one of the following commands:
+2. **Verify the installation** by running the verification command:
+
+   ```shell
+   npm safe-chain-verify
+   pnpm safe-chain-verify
+   pip safe-chain-verify
+   uv safe-chain-verify
+
+   # Any other supported package manager: {packagemanager} safe-chain-verify
+   ```
+
+   - The output should display "OK: Safe-chain works!" confirming that Aikido Safe Chain is properly installed and running.
+
+3. **(Optional) Test malware blocking** by attempting to install a test package:
 
    For JavaScript/Node.js:
 
@@ -188,9 +199,14 @@ You can set the minimum package age through multiple sources (in order of priori
    }
    ```
 
-## Custom NPM Registries
+## Custom Registries
 
-Configure Safe Chain to scan packages from custom or private npm registries.
+Configure Safe Chain to scan packages from custom or private registries.
+
+Supported ecosystems:
+
+- Node.js
+- Python
 
 ### Configuration Options
 
@@ -200,6 +216,7 @@ You can set custom registries through environment variable or config file. Both
 
    ```shell
    export SAFE_CHAIN_NPM_CUSTOM_REGISTRIES="npm.company.com,registry.internal.net"
+   export SAFE_CHAIN_PIP_CUSTOM_REGISTRIES="pip.company.com,registry.internal.net"
    ```
 
 2. **Config File** (`~/.aikido/config.json`):
@@ -208,6 +225,9 @@ You can set custom registries through environment variable or config file. Both
    {
      "npm": {
        "customRegistries": ["npm.company.com", "registry.internal.net"]
+     },
+     "pip": {
+       "customRegistries": ["pip.company.com", "registry.internal.net"]
      }
    }
    ```
@@ -237,6 +257,7 @@ iex "& { $(iwr 'https://github.com/AikidoSec/safe-chain/releases/latest/download
 - ✅ **GitHub Actions**
 - ✅ **Azure Pipelines**
 - ✅ **CircleCI**
+- ✅ **Jenkins**
 
 ## GitHub Actions Example
 
@@ -288,4 +309,46 @@ workflows:
       - build
 ```
 
+## Jenkins Example
+
+Note: This assumes Node.js and npm are installed on the Jenkins agent.
+
+```groovy
+pipeline {
+  agent any
+
+  environment {
+    // Jenkins does not automatically persist PATH updates from setup-ci,
+    // so add the shims + binary directory explicitly for all stages.
+    PATH = "${env.HOME}/.safe-chain/shims:${env.HOME}/.safe-chain/bin:${env.PATH}"
+  }
+
+  stages {
+    stage('Install safe-chain') {
+      steps {
+        sh '''
+          set -euo pipefail
+
+          # Install Safe Chain for CI
+          curl -fsSL https://github.com/AikidoSec/safe-chain/releases/latest/download/install-safe-chain.sh | sh -s -- --ci
+        '''
+      }
+    }
+
+    stage('Install project dependencies etc...') {
+      steps {
+        sh '''
+          set -euo pipefail
+          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
+
+Having issues? See the [Troubleshooting Guide](https://github.com/AikidoSec/safe-chain/blob/main/docs/troubleshooting.md) for help with common problems.

package/bin/safe-chain.js

@@ -3,7 +3,10 @@
 import chalk from "chalk";
 import { ui } from "../src/environment/userInteraction.js";
 import { setup } from "../src/shell-integration/setup.js";
-import { teardown, teardownDirectories } from "../src/shell-integration/teardown.js";
+import {
+  teardown,
+  teardownDirectories,
+} from "../src/shell-integration/teardown.js";
 import { setupCi } from "../src/shell-integration/setup-ci.js";
 import { initializeCliArguments } from "../src/config/cliArguments.js";
 import { setEcoSystem } from "../src/config/settings.js";
@@ -45,7 +48,7 @@ if (tool) {
   const args = process.argv.slice(3);
 
   setEcoSystem(tool.ecoSystem);
-  
+
   // Provide tool context to PM (pip uses this; others ignore)
   const toolContext = { tool: tool.tool, args };
   initializePackageManager(tool.internalPackageManagerName, toolContext);

package/docs/troubleshooting.md

@@ -0,0 +1,249 @@
+# Troubleshooting
+
+This guide helps you diagnose and resolve common issues with Aikido Safe Chain.
+
+## Verification & Diagnostics
+
+### Check Installation
+
+```bash
+# Check version
+safe-chain --version
+```
+
+### Verify Shell Integration
+
+Run the verification command for your package manager:
+
+```bash
+npm safe-chain-verify
+pnpm safe-chain-verify
+pip safe-chain-verify
+uv safe-chain-verify
+
+# Any other supported package manager: {packagemanager} safe-chain-verify
+```
+
+Expected output: `OK: Safe-chain works!`
+
+### Test Malware Blocking
+
+Verify that malware detection is working:
+
+**For JavaScript/Node.js:**
+
+```bash
+npm install safe-chain-test
+```
+
+**For Python:**
+
+```bash
+pip3 install safe-chain-pi-test
+```
+
+These test packages are flagged as malware and should be blocked by Safe Chain.
+
+### Logging Options
+
+Use logging flags to get more information:
+
+```bash
+# Verbose mode - detailed diagnostic output for troubleshooting
+npm install express --safe-chain-logging=verbose
+
+# Silent mode - suppress all output except malware blocking
+npm install express --safe-chain-logging=silent
+```
+
+## Common Issues
+
+### Shell Aliases Not Working After Installation
+
+**Symptom:** Running `npm` shows regular npm instead of safe-chain wrapped version
+
+**First step:** Restart your terminal (most common fix)
+
+**Verify it's working:**
+
+```bash
+type npm
+```
+
+Should show: `npm is a function`
+
+**If still not working:**
+
+Check that your startup file sources safe-chain scripts from `~/.safe-chain/scripts/`:
+
+- Bash: `~/.bashrc`
+- Zsh: `~/.zshrc`
+- Fish: `~/.config/fish/config.fish`
+- PowerShell: `$PROFILE`
+
+### "Command Not Found: safe-chain"
+
+**Symptom:** Binary not found in PATH
+
+**First step:** Restart your terminal
+
+**Check PATH:**
+
+```bash
+echo $PATH
+```
+
+Should include `~/.safe-chain/bin`
+
+**If persists:** Re-run the installation script
+
+### Shell Aliases Persist After Uninstallation
+
+**Symptom:** safe-chain commands still active after running uninstall script
+
+**Steps:**
+
+1. Run `safe-chain teardown` (if binary still exists)
+2. Restart your terminal
+3. If still present, manually edit shell config files:
+   - Bash: `~/.bashrc`
+   - Zsh: `~/.zshrc`
+   - Fish: `~/.config/fish/config.fish`
+   - PowerShell: `$PROFILE`
+4. Remove lines that source scripts from `~/.safe-chain/scripts/`
+5. Restart terminal again
+
+## Manual Verification Steps
+
+### Check Installation Status
+
+```bash
+# Check installation location (helps identify if installed via npm or as standalone binary)
+which safe-chain
+
+# Verify binary exists
+ls ~/.safe-chain/bin/safe-chain
+
+# Check version
+safe-chain --version
+
+# Test shell integration
+type npm
+type pip
+```
+
+**Expected `which` output:**
+
+- Standalone binary (correct): `~/.safe-chain/bin/safe-chain` or `/Users/<username>/.safe-chain/bin/safe-chain`
+- npm global (outdated): path containing `node_modules` or nvm version paths
+
+If `which` shows an npm installation, see [Check for Conflicting Installations](#check-for-conflicting-installations).
+
+### Check Shell Integration
+
+```bash
+# Which shell you're using
+echo $SHELL
+
+# Check if startup file sources safe-chain
+# For Bash:
+grep safe-chain ~/.bashrc
+
+# For Zsh:
+grep safe-chain ~/.zshrc
+
+# For Fish:
+grep safe-chain ~/.config/fish/config.fish
+
+# Verify scripts exist
+ls ~/.safe-chain/scripts/
+```
+
+### Check for Conflicting Installations
+
+> **Note:** The install/uninstall scripts automatically detect and remove conflicting installations, but you can manually check:
+
+```bash
+# Check npm global
+npm list -g @aikidosec/safe-chain
+
+# Check Volta
+volta list safe-chain
+
+# Check nvm (all versions)
+for version in $(nvm list | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+'); do
+  nvm exec "$version" npm list -g @aikidosec/safe-chain 2>/dev/null && echo "Found in $version"
+done
+```
+
+## Manual Cleanup
+
+> **Note:** The install and uninstall scripts automatically handle these cleanup steps. Use these manual commands only if automatic cleanup fails.
+
+### Remove npm Global Installation
+
+```bash
+npm uninstall -g @aikidosec/safe-chain
+```
+
+### Remove Volta Installation
+
+```bash
+volta uninstall @aikidosec/safe-chain
+```
+
+### Remove nvm Installations (All Versions)
+
+```bash
+# Automated approach
+for version in $(nvm list | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+'); do
+  nvm exec "$version" npm uninstall -g @aikidosec/safe-chain
+done
+
+# Or manual per version
+nvm use <version>
+npm uninstall -g @aikidosec/safe-chain
+```
+
+### Clean Shell Configuration Files
+
+Manually remove safe-chain entries from:
+
+- Bash: `~/.bashrc`
+- Zsh: `~/.zshrc`
+- Fish: `~/.config/fish/config.fish`
+- PowerShell: `$PROFILE`
+
+Look for and remove:
+
+- Lines sourcing from `~/.safe-chain/scripts/`
+- Any safe-chain related function definitions
+
+### Remove Installation Directory
+
+```bash
+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:
+
+1. Visit [GitHub Issues](https://github.com/AikidoSec/safe-chain/issues)
+2. Include:
+   - Operating system and version
+   - Shell type and version
+   - `safe-chain --version` output
+   - Output from verification commands
+   - Verbose logs of the failing command

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikidosec/safe-chain",
-  "version": "1.3.3",
+  "version": "1.4.0",
   "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/config/configFile.js

@@ -11,6 +11,7 @@ import { getEcoSystem } from "./settings.js";
  * @property {unknown | Number} scanTimeout
  * @property {unknown | Number} minimumPackageAgeHours
  * @property {unknown | SafeChainRegistryConfiguration} npm
+ * @property {unknown | SafeChainRegistryConfiguration} pip
  *
  * @typedef {Object} SafeChainRegistryConfiguration
  * We cannot trust the input and should add the necessary validations.
@@ -104,6 +105,28 @@ export function getNpmCustomRegistries() {
   return customRegistries.filter((item) => typeof item === "string");
 }
 
+/**
+ * Gets the custom npm registries from the config file (format parsing only, no validation)
+ * @returns {string[]}
+ */
+export function getPipCustomRegistries() {
+  const config = readConfigFile();
+
+  if (!config || !config.pip) {
+    return [];
+  }
+
+  // TypeScript needs help understanding that config.pip exists and has customRegistries
+  const pipConfig = /** @type {SafeChainRegistryConfiguration} */ (config.pip);
+  const customRegistries = pipConfig.customRegistries;
+
+  if (!Array.isArray(customRegistries)) {
+    return [];
+  }
+
+  return customRegistries.filter((item) => typeof item === "string");
+}
+
 /**
  * @param {import("../api/aikido.js").MalwarePackage[]} data
  * @param {string | number} version
@@ -169,6 +192,9 @@ function readConfigFile() {
     npm: {
       customRegistries: undefined,
     },
+    pip: {
+      customRegistries: undefined,
+    },
   };
 
   const configFilePath = getConfigFilePath();

package/src/config/environmentVariables.js

@@ -15,3 +15,13 @@ export function getMinimumPackageAgeHours() {
 export function getNpmCustomRegistries() {
   return process.env.SAFE_CHAIN_NPM_CUSTOM_REGISTRIES;
 }
+
+/**
+ * Gets the custom pip registries from environment variable
+ * Expected format: comma-separated list of registry domains
+ * Example: "pip.company.com,registry.internal.net"
+ * @returns {string | undefined}
+ */
+export function getPipCustomRegistries() {
+  return process.env.SAFE_CHAIN_PIP_CUSTOM_REGISTRIES;
+}

package/src/config/settings.js

@@ -143,3 +143,21 @@ export function getNpmCustomRegistries() {
   // Normalize each registry (remove protocol if any)
   return uniqueRegistries.map(normalizeRegistry);
 }
+
+/**
+ * Gets the custom npm registries from both environment variable and config file (merged)
+ * @returns {string[]}
+ */
+export function getPipCustomRegistries() {
+  const envRegistries = parseRegistriesFromEnv(
+    environmentVariables.getPipCustomRegistries()
+  );
+  const configRegistries = configFile.getPipCustomRegistries();
+
+  // Merge both sources and remove duplicates
+  const allRegistries = [...envRegistries, ...configRegistries];
+  const uniqueRegistries = [...new Set(allRegistries)];
+
+  // Normalize each registry (remove protocol if any)
+  return uniqueRegistries.map(normalizeRegistry);
+}

package/src/main.js

@@ -13,6 +13,10 @@ import { getAuditStats } from "./scanning/audit/index.js";
  * @returns {Promise<number>}
  */
 export async function main(args) {
+  if (isSafeChainVerify(args)) {
+    return 0;
+  }
+
   process.on("SIGINT", handleProcessTermination);
   process.on("SIGTERM", handleProcessTermination);
 
@@ -104,3 +108,12 @@ export async function main(args) {
 function handleProcessTermination() {
   ui.writeBufferedLogsAndStopBuffering();
 }
+
+/** @param {string[]} args  */
+function isSafeChainVerify(args) {
+  const safeChainCheckCommand = "safe-chain-verify";
+  if (args.length > 0 && args[0] === safeChainCheckCommand) {
+    ui.writeInformation("OK: Safe-chain works!");
+    return true;
+  }
+}

package/src/registryProxy/interceptors/pipInterceptor.js

@@ -1,3 +1,4 @@
+import { getPipCustomRegistries } from "../../config/settings.js";
 import { isMalwarePackage } from "../../scanning/audit/index.js";
 import { interceptRequests } from "./interceptorBuilder.js";
 
@@ -13,7 +14,9 @@ const knownPipRegistries = [
  * @returns {import("./interceptorBuilder.js").Interceptor | undefined}
  */
 export function pipInterceptorForUrl(url) {
-  const registry = knownPipRegistries.find((reg) => url.includes(reg));
+  const customRegistries = getPipCustomRegistries();
+  const registries = [...knownPipRegistries, ...customRegistries];
+  const registry = registries.find((reg) => url.includes(reg));
 
   if (registry) {
     return buildPipInterceptor(registry);
@@ -37,8 +40,8 @@ function buildPipInterceptor(registry) {
     // Per python, packages that differ only by hyphen vs underscore are considered the same.
     const hyphenName = packageName?.includes("_") ? packageName.replace(/_/g, "-") : packageName;
 
-    const isMalicious = 
-       await isMalwarePackage(packageName, version) 
+    const isMalicious =
+       await isMalwarePackage(packageName, version)
     || await isMalwarePackage(hyphenName, version);
 
     if (isMalicious) {

package/src/registryProxy/mitmRequestHandler.js

@@ -15,7 +15,7 @@ import { gunzipSync, gzipSync } from "zlib";
  */
 export function mitmConnect(req, clientSocket, interceptor) {
   ui.writeVerbose(`Safe-chain: Set up MITM tunnel for ${req.url}`);
-  const { hostname } = new URL(`http://${req.url}`);
+  const { hostname, port } = new URL(`http://${req.url}`);
 
   clientSocket.on("error", (err) => {
     ui.writeVerbose(
@@ -26,7 +26,7 @@ export function mitmConnect(req, clientSocket, interceptor) {
     // Not subscribing to 'close' event will cause node to throw and crash.
   });
 
-  const server = createHttpsServer(hostname, interceptor);
+  const server = createHttpsServer(hostname, port, interceptor);
 
   server.on("error", (err) => {
     ui.writeError(`Safe-chain: HTTPS server error: ${err.message}`);
@@ -46,10 +46,11 @@ export function mitmConnect(req, clientSocket, interceptor) {
 
 /**
  * @param {string} hostname
+ * @param {string} port
  * @param {Interceptor} interceptor
  * @returns {import("https").Server}
  */
-function createHttpsServer(hostname, interceptor) {
+function createHttpsServer(hostname, port, interceptor) {
   const cert = generateCertForHost(hostname);
 
   /**
@@ -80,7 +81,7 @@ function createHttpsServer(hostname, interceptor) {
     }
 
     // Collect request body
-    forwardRequest(req, hostname, res, requestInterceptor);
+    forwardRequest(req, hostname, port, res, requestInterceptor);
   }
 
   const server = https.createServer(
@@ -109,11 +110,12 @@ function getRequestPathAndQuery(url) {
 /**
  * @param {import("http").IncomingMessage} req
  * @param {string} hostname
+ * @param {string} port
  * @param {import("http").ServerResponse} res
  * @param {import("./interceptors/interceptorBuilder.js").RequestInterceptionHandler} requestHandler
  */
-function forwardRequest(req, hostname, res, requestHandler) {
-  const proxyReq = createProxyRequest(hostname, req, res, requestHandler);
+function forwardRequest(req, hostname, port, res, requestHandler) {
+  const proxyReq = createProxyRequest(hostname, port, req, res, requestHandler);
 
   proxyReq.on("error", (err) => {
     ui.writeVerbose(
@@ -144,13 +146,14 @@ function forwardRequest(req, hostname, res, requestHandler) {
 
 /**
  * @param {string} hostname
+ * @param {string} port
  * @param {import("http").IncomingMessage} req
  * @param {import("http").ServerResponse} res
  * @param {import("./interceptors/interceptorBuilder.js").RequestInterceptionHandler} requestHandler
  *
  * @returns {import("http").ClientRequest}
  */
-function createProxyRequest(hostname, req, res, requestHandler) {
+function createProxyRequest(hostname, port, req, res, requestHandler) {
   /** @type {NodeJS.Dict<string | string[]> | undefined} */
   let headers = { ...req.headers };
   // Remove the host header from the incoming request before forwarding.
@@ -163,7 +166,7 @@ function createProxyRequest(hostname, req, res, requestHandler) {
   /** @type {import("http").RequestOptions} */
   const options = {
     hostname: hostname,
-    port: 443,
+    port: port || 443,
     path: req.url,
     method: req.method,
     headers: { ...headers },

package/src/shell-integration/startup-scripts/init-posix.sh

@@ -83,6 +83,6 @@ function wrapSafeChainCommand() {
     # If the aikido command is not available, print a warning and run the original command
     printSafeChainWarning "$original_cmd"
 
-    command "$original_cmd" "$@"
+    command "$@"
   fi
 }

package/docs/npm-to-binary-migration.md

@@ -1,89 +0,0 @@
-# Migrating from npm global tool to binary installation
-
-If you previously installed safe-chain as an npm global package, you need to migrate to the binary installation.
-
-Depending on the version manager you're using, the uninstall process differs:
-
-### Standard npm (no version manager)
-
-1. **Clean up shell aliases:**
-
-   ```bash
-   safe-chain teardown
-   ```
-
-2. **Restart your terminal**
-
-3. **Uninstall the npm package:**
-
-   ```bash
-   npm uninstall -g @aikidosec/safe-chain
-   ```
-
-4. **Install the binary version** (see [Installation](https://github.com/AikidoSec/safe-chain/blob/main/README.md#installation))
-
-### nvm (Node Version Manager)
-
-**Important:** nvm installs global packages separately for each Node version, so safe-chain must be uninstalled from each version where it was installed.
-
-1. **Clean up shell aliases:**
-
-   ```bash
-   safe-chain teardown
-   ```
-
-2. **Restart your terminal**
-
-3. **Uninstall from all Node versions:**
-
-   **Option A** - Automated script (recommended):
-
-   ```bash
-   for version in $(nvm list | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+'); do nvm use $version && npm uninstall -g @aikidosec/safe-chain; done
-   ```
-
-   **Option B** - Manual per version:
-
-   ```bash
-   nvm use <version>
-   npm uninstall -g @aikidosec/safe-chain
-   ```
-
-   Repeat for each Node version where safe-chain was installed.
-
-4. **Install the binary version** (see [Installation](https://github.com/AikidoSec/safe-chain/blob/main/README.md#installation))
-
-### Volta
-
-1. **Clean up shell aliases:**
-
-   ```bash
-   safe-chain teardown
-   ```
-
-2. **Restart your terminal**
-
-3. **Uninstall the Volta package:**
-
-   ```bash
-   volta uninstall @aikidosec/safe-chain
-   ```
-
-4. **Install the binary version** (see [Installation](https://github.com/AikidoSec/safe-chain/blob/main/README.md#installation))
-
-## Troubleshooting
-
-### Shell aliases still present after migration
-
-1. Run `safe-chain teardown` (if the binary is installed)
-2. Manually remove any safe-chain entries from your shell config files:
-   - Bash: `~/.bashrc`
-   - Zsh: `~/.zshrc`
-   - Fish: `~/.config/fish/config.fish`
-   - PowerShell: `$PROFILE`
-3. Restart your terminal
-4. Re-run the install script
-
-### "command not found: safe-chain" after migration
-
-The binary installation directory (`~/.safe-chain/bin`) may not be in your PATH. Restart your terminal. If the problem persists: re-run the installation of safe-chain.