@aikidosec/safe-chain 1.3.2 → 1.3.4

package/README.md

@@ -23,15 +23,16 @@ Aikido Safe Chain supports the following package managers:
 - 📦 **pip3**
 - 📦 **uv**
 - 📦 **poetry**
+- 📦 **pipx**
 
 # Usage
 
+![Aikido Safe Chain demo](https://raw.githubusercontent.com/AikidoSec/safe-chain/main/docs/safe-package-manager-demo.gif)
+
 ## Installation
 
 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
@@ -49,11 +50,13 @@ iex (iwr "https://github.com/AikidoSec/safe-chain/releases/latest/download/insta
 To install a specific version instead of the latest, replace `latest` with the version number in the URL (available from version 1.3.2 onwards):
 
 **Unix/Linux/macOS:**
+
 ```shell
 curl -fsSL https://github.com/AikidoSec/safe-chain/releases/download/x.x.x/install-safe-chain.sh | sh
 ```
 
 **Windows (PowerShell):**
+
 ```powershell
 iex (iwr "https://github.com/AikidoSec/safe-chain/releases/download/x.x.x/install-safe-chain.ps1" -UseBasicParsing)
 ```
@@ -64,9 +67,22 @@ You can find all available versions on the [releases page](https://github.com/Ai
 
 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, and pip/pip3 are loaded correctly. If you do not restart your terminal, the aliases will not be available.
+   - 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:
+
+   ```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
+   ```
 
-2. **Verify the installation** by running one of the following commands:
+   - 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:
 
@@ -82,7 +98,7 @@ You can find all available versions on the [releases page](https://github.com/Ai
 
    - The output should show that Aikido Safe Chain is blocking the installation of these test packages as they are flagged as malware.
 
-When running `npm`, `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, `bunx`, `uv`, `pip`, `pip3` or `poetry` commands, the Aikido Safe Chain will automatically check for malware in the packages you are trying to install. It also intercepts Python module invocations for pip when available (e.g., `python -m pip install ...`, `python3 -m pip download ...`). If any malware is detected, it will prompt you to exit the command.
+When running `npm`, `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, `bunx`, `pip`, `pip3`, `uv`, `poetry` and `pipx` commands, the Aikido Safe Chain will automatically check for malware in the packages you are trying to install. It also intercepts Python module invocations for pip when available (e.g., `python -m pip install ...`, `python3 -m pip download ...`). If any malware is detected, it will prompt you to exit the command.
 
 You can check the installed version by running:
 
@@ -94,17 +110,17 @@ safe-chain --version
 
 ### Malware Blocking
 
-The Aikido Safe Chain works by running a lightweight proxy server that intercepts package downloads from the npm registry and PyPI. When you run npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, pip, pip3 or poetry commands, all package downloads are routed through this local proxy, which verifies packages in real-time against **[Aikido Intel - Open Sources Threat Intelligence](https://intel.aikido.dev/?tab=malware)**. If malware is detected in any package (including deep dependencies), the proxy blocks the download before the malicious code reaches your machine.
+The Aikido Safe Chain works by running a lightweight proxy server that intercepts package downloads from the npm registry and PyPI. When you run npm, npx, yarn, pnpm, pnpx, bun, bunx, pip, pip3, uv, poetry or pipx commands, all package downloads are routed through this local proxy, which verifies packages in real-time against **[Aikido Intel - Open Sources Threat Intelligence](https://intel.aikido.dev/?tab=malware)**. If malware is detected in any package (including deep dependencies), the proxy blocks the download before the malicious code reaches your machine.
 
 ### Minimum package age (npm only)
 
 For npm packages, Safe Chain temporarily suppresses packages published within the last 24 hours (by default) until they have been validated against malware. This provides an additional security layer during the critical period when newly published packages are most vulnerable to containing undetected threats. You can configure this threshold or bypass this protection entirely - see the [Minimum Package Age Configuration](#minimum-package-age) section below.
 
-⚠️ This feature **only applies to npm-based package managers** (npm, npx, yarn, pnpm, pnpx, bun, bunx) and does not apply to Python package managers (uv, pip, pip3, poetry).
+⚠️ This feature **only applies to npm-based package managers** (npm, npx, yarn, pnpm, pnpx, bun, bunx) and does not apply to Python package managers (uv, pip, pip3, poetry, pipx).
 
 ### Shell Integration
 
-The Aikido Safe Chain integrates with your shell to provide a seamless experience when using npm, npx, yarn, pnpm, pnpx, bun, bunx, and Python package managers (uv, pip). It sets up aliases for these commands so that they are wrapped by the Aikido Safe Chain commands, which manage the proxy server before executing the original commands. We currently support:
+The Aikido Safe Chain integrates with your shell to provide a seamless experience when using npm, npx, yarn, pnpm, pnpx, bun, bunx, and Python package managers (pip, uv, poetry, pipx). It sets up aliases for these commands so that they are wrapped by the Aikido Safe Chain commands, which manage the proxy server before executing the original commands. We currently support:
 
 - ✅ **Bash**
 - ✅ **Zsh**
@@ -183,6 +199,39 @@ You can set the minimum package age through multiple sources (in order of priori
    }
    ```
 
+## Custom Registries
+
+Configure Safe Chain to scan packages from custom or private registries.
+
+Supported ecosystems:
+
+- Node.js
+- Python
+
+### Configuration Options
+
+You can set custom registries through environment variable or config file. Both sources are merged together.
+
+1. **Environment Variable** (comma-separated):
+
+   ```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`):
+
+   ```json
+   {
+     "npm": {
+       "customRegistries": ["npm.company.com", "registry.internal.net"]
+     },
+     "pip": {
+       "customRegistries": ["pip.company.com", "registry.internal.net"]
+     }
+   }
+   ```
+
 # Usage in CI/CD
 
 You can protect your CI/CD pipelines from malicious packages by integrating Aikido Safe Chain into your build process. This ensures that any packages installed during your automated builds are checked for malware before installation.
@@ -207,6 +256,8 @@ iex "& { $(iwr 'https://github.com/AikidoSec/safe-chain/releases/latest/download
 
 - ✅ **GitHub Actions**
 - ✅ **Azure Pipelines**
+- ✅ **CircleCI**
+- ✅ **Jenkins**
 
 ## GitHub Actions Example
 
@@ -239,4 +290,61 @@ iex "& { $(iwr 'https://github.com/AikidoSec/safe-chain/releases/latest/download
   displayName: "Install dependencies"
 ```
 
+## CircleCI Example
+
+```yaml
+version: 2.1
+jobs:
+  build:
+    docker:
+      - image: cimg/node:lts
+    steps:
+      - checkout
+      - run: |
+          curl -fsSL https://raw.githubusercontent.com/AikidoSec/safe-chain/main/install-scripts/install-safe-chain.sh | sh -s -- --ci
+      - run: npm ci
+workflows:
+  build_and_test:
+    jobs:
+      - 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.

package/bin/aikido-pipx.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { main } from "../src/main.js";
+import { initializePackageManager } from "../src/packagemanager/currentPackageManager.js";
+import { setEcoSystem, ECOSYSTEM_PY } from "../src/config/settings.js";
+
+// Set eco system
+setEcoSystem(ECOSYSTEM_PY);
+
+initializePackageManager("pipx");
+
+(async () => {
+  // Pass through only user-supplied pipx args
+  var exitCode = await main(process.argv.slice(2));
+  process.exit(exitCode);
+})();

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/shell-integration.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The shell integration automatically wraps common package manager commands (`npm`, `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, `bunx`, `pip`, `pip3`) with Aikido's security scanning functionality. It also intercepts Python module invocations for pip when available: `python -m pip`, `python -m pip3`, `python3 -m pip`, `python3 -m pip3`. This is achieved by sourcing startup scripts that define shell functions to wrap these commands with their Aikido-protected equivalents.
+The shell integration automatically wraps common package manager commands (`npm`, `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, `bunx`, `pip`, `pip3`, `uv`, `poetry`, `pipx`) with Aikido's security scanning functionality. It also intercepts Python module invocations for pip when available: `python -m pip`, `python -m pip3`, `python3 -m pip`, `python3 -m pip3`. This is achieved by sourcing startup scripts that define shell functions to wrap these commands with their Aikido-protected equivalents.
 
 ## Supported Shells
 
@@ -28,7 +28,7 @@ This command:
 
 - Copies necessary startup scripts to Safe Chain's installation directory (`~/.safe-chain/scripts`)
 - Detects all supported shells on your system
-- Sources each shell's startup file to add Safe Chain functions for `npm`, `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, `bunx`, `pip`, and `pip3`
+- Sources each shell's startup file to add Safe Chain functions for `npm`, `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, `bunx`, `pip`, `pip3`, `uv`, `poetry` and `pipx`
 - Adds lightweight interceptors so `python -m pip[...]` and `python3 -m pip[...]` route through Safe Chain when invoked by name
 
 ❗ After running this command, **you must restart your terminal** for the changes to take effect. This ensures that the startup scripts are sourced correctly.
@@ -78,7 +78,7 @@ The system modifies the following files to source Safe Chain startup scripts:
 This means the shell functions are working but the Aikido commands aren't installed or available in your PATH:
 
 - Make sure Aikido Safe Chain is properly installed on your system
-- Verify the `aikido-npm`, `aikido-npx`, `aikido-yarn`, `aikido-pnpm`, `aikido-pnpx`, `aikido-bun`, `aikido-bunx`, `aikido-pip`, and `aikido-pip3` commands exist
+- Verify the `aikido-npm`, `aikido-npx`, `aikido-yarn`, `aikido-pnpm`, `aikido-pnpx`, `aikido-bun`, `aikido-bunx`, `aikido-pip`, `aikido-pip3`, `aikido-uv`, `aikido-poetry` and `aikido-pipx` commands exist
 - Check that these commands are in your system's PATH
 
 ### Manual Verification
@@ -121,7 +121,7 @@ npm() {
 }
 ```
 
-Repeat this pattern for `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, `bunx`, `pip`, and `pip3` using their respective `aikido-*` commands. After adding these functions, restart your terminal to apply the changes.
+Repeat this pattern for `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, `bunx`, `pip`, `pip3`, `uv`, `poetry` and `pipx` using their respective `aikido-*` commands. After adding these functions, restart your terminal to apply the changes.
 
 To intercept Python module invocations for pip without altering Python itself, you can add small forwarding functions:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikidosec/safe-chain",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "scripts": {
     "test": "node --test --experimental-test-module-mocks 'src/**/*.spec.js'",
     "test:watch": "node --test --watch --experimental-test-module-mocks 'src/**/*.spec.js'",
@@ -21,6 +21,7 @@
     "aikido-python": "bin/aikido-python.js",
     "aikido-python3": "bin/aikido-python3.js",
     "aikido-poetry": "bin/aikido-poetry.js",
+    "aikido-pipx": "bin/aikido-pipx.js",
     "safe-chain": "bin/safe-chain.js"
   },
   "type": "module",

package/src/config/configFile.js

@@ -7,10 +7,15 @@ import { getEcoSystem } from "./settings.js";
 /**
  * @typedef {Object} SafeChainConfig
  *
- * This should be a number, but can be anything because it is user-input.
+ * We cannot trust the input and should add the necessary validations
+ * @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.
- * @property {unknown} scanTimeout
- * @property {unknown} minimumPackageAgeHours
+ * @property {unknown | string[]} customRegistries
  */
 
 /**
@@ -78,6 +83,50 @@ export function getMinimumPackageAgeHours() {
   return undefined;
 }
 
+/**
+ * Gets the custom npm registries from the config file (format parsing only, no validation)
+ * @returns {string[]}
+ */
+export function getNpmCustomRegistries() {
+  const config = readConfigFile();
+
+  if (!config || !config.npm) {
+    return [];
+  }
+
+  // TypeScript needs help understanding that config.npm exists and has customRegistries
+  const npmConfig = /** @type {SafeChainRegistryConfiguration} */ (config.npm);
+  const customRegistries = npmConfig.customRegistries;
+
+  if (!Array.isArray(customRegistries)) {
+    return [];
+  }
+
+  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
@@ -136,23 +185,29 @@ export function readDatabaseFromLocalCache() {
  * @returns {SafeChainConfig}
  */
 function readConfigFile() {
+  /** @type {SafeChainConfig} */
+  const emptyConfig = {
+    scanTimeout: undefined,
+    minimumPackageAgeHours: undefined,
+    npm: {
+      customRegistries: undefined,
+    },
+    pip: {
+      customRegistries: undefined,
+    },
+  };
+
   const configFilePath = getConfigFilePath();
 
   if (!fs.existsSync(configFilePath)) {
-    return {
-      scanTimeout: undefined,
-      minimumPackageAgeHours: undefined,
-    };
+    return emptyConfig;
   }
 
   try {
     const data = fs.readFileSync(configFilePath, "utf8");
     return JSON.parse(data);
   } catch {
-    return {
-      scanTimeout: undefined,
-      minimumPackageAgeHours: undefined,
-    };
+    return emptyConfig;
   }
 }
 

package/src/config/environmentVariables.js

@@ -5,3 +5,23 @@
 export function getMinimumPackageAgeHours() {
   return process.env.SAFE_CHAIN_MINIMUM_PACKAGE_AGE_HOURS;
 }
+
+/**
+ * Gets the custom npm registries from environment variable
+ * Expected format: comma-separated list of registry domains
+ * Example: "npm.company.com,registry.internal.net"
+ * @returns {string | undefined}
+ */
+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

@@ -98,3 +98,66 @@ export function skipMinimumPackageAge() {
 
   return defaultSkipMinimumPackageAge;
 }
+
+/**
+ * Normalizes a registry URL by removing protocol if present
+ * @param {string} registry
+ * @returns {string}
+ */
+function normalizeRegistry(registry) {
+  // Remove protocol (http://, https://) if present
+  return registry.replace(/^https?:\/\//, "");
+}
+
+/**
+ * Parses comma-separated registries from environment variable
+ * @param {string | undefined} envValue
+ * @returns {string[]}
+ */
+function parseRegistriesFromEnv(envValue) {
+  if (!envValue || typeof envValue !== "string") {
+    return [];
+  }
+
+  // Split by comma and trim whitespace
+  return envValue
+    .split(",")
+    .map((registry) => registry.trim())
+    .filter((registry) => registry.length > 0);
+}
+
+/**
+ * Gets the custom npm registries from both environment variable and config file (merged)
+ * @returns {string[]}
+ */
+export function getNpmCustomRegistries() {
+  const envRegistries = parseRegistriesFromEnv(
+    environmentVariables.getNpmCustomRegistries()
+  );
+  const configRegistries = configFile.getNpmCustomRegistries();
+
+  // 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);
+}
+
+/**
+ * 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/packagemanager/currentPackageManager.js

@@ -12,6 +12,7 @@ import { createYarnPackageManager } from "./yarn/createPackageManager.js";
 import { createPipPackageManager } from "./pip/createPackageManager.js";
 import { createUvPackageManager } from "./uv/createUvPackageManager.js";
 import { createPoetryPackageManager } from "./poetry/createPoetryPackageManager.js";
+import { createPipXPackageManager } from "./pipx/createPipXPackageManager.js";
 
 /**
  * @type {{packageManagerName: PackageManager | null}}
@@ -61,6 +62,8 @@ export function initializePackageManager(packageManagerName, context) {
     state.packageManagerName = createUvPackageManager();
   } else if (packageManagerName === "poetry") {
     state.packageManagerName = createPoetryPackageManager();
+  } else if (packageManagerName === "pipx") {
+    state.packageManagerName = createPipXPackageManager();
   } else {
     throw new Error("Unsupported package manager: " + packageManagerName);
   }

package/src/packagemanager/pipx/createPipXPackageManager.js

@@ -0,0 +1,18 @@
+import { runPipX } from "./runPipXCommand.js";
+
+/**
+ * @returns {import("../currentPackageManager.js").PackageManager}
+ */
+export function createPipXPackageManager() {
+  return {
+    /**
+     * @param {string[]} args
+     */
+    runCommand: (args) => {
+      return runPipX("pipx", args);
+    },
+    // MITM only
+    isSupportedCommand: () => false,
+    getDependencyUpdatesForCommand: () => [],
+  };
+}

package/src/packagemanager/pipx/runPipXCommand.js

@@ -0,0 +1,65 @@
+import { ui } from "../../environment/userInteraction.js";
+import { safeSpawn } from "../../utils/safeSpawn.js";
+import { mergeSafeChainProxyEnvironmentVariables } from "../../registryProxy/registryProxy.js";
+import { getCombinedCaBundlePath } from "../../registryProxy/certBundle.js";
+
+/**
+ * Sets CA bundle environment variables used by Python libraries and pipx.
+ * 
+ * @param {NodeJS.ProcessEnv} env - Env object
+ * @param {string} combinedCaPath - Path to the combined CA bundle
+ * @return {NodeJS.ProcessEnv} Modified environment object
+ */
+function getPipXCaBundleEnvironmentVariables(env, combinedCaPath) {
+  let retVal = { ...env };
+
+  if (env.SSL_CERT_FILE) {
+    ui.writeWarning("Safe-chain: User defined SSL_CERT_FILE found in environment. It will be overwritten.");
+  }
+  retVal.SSL_CERT_FILE = combinedCaPath;
+
+  if (env.REQUESTS_CA_BUNDLE) {
+    ui.writeWarning("Safe-chain: User defined REQUESTS_CA_BUNDLE found in environment. It will be overwritten.");
+  }
+  retVal.REQUESTS_CA_BUNDLE = combinedCaPath;
+
+  if (env.PIP_CERT) {
+    ui.writeWarning("Safe-chain: User defined PIP_CERT found in environment. It will be overwritten.");
+  }
+  retVal.PIP_CERT = combinedCaPath;
+  return retVal;
+}
+
+/**
+ * Runs a pipx command with safe-chain's certificate bundle and proxy configuration.
+ * 
+ * @param {string} command - The command to execute
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<{status: number}>} Exit status of the command
+ */
+export async function runPipX(command, args) {
+  try {
+    const env = mergeSafeChainProxyEnvironmentVariables(process.env);
+
+    const combinedCaPath = getCombinedCaBundlePath();
+    const modifiedEnv = getPipXCaBundleEnvironmentVariables(env, combinedCaPath);
+
+    // Note: pipx uses HTTPS_PROXY and HTTP_PROXY environment variables for proxy configuration
+    // These are already set by mergeSafeChainProxyEnvironmentVariables
+
+    const result = await safeSpawn(command, args, {
+      stdio: "inherit",
+      env: modifiedEnv,
+    });
+
+    return { status: result.status };
+  } catch (/** @type any */ error) {
+    if (error.status) {
+      return { status: error.status };
+    } else {
+      ui.writeError(`Error executing command: ${error.message}`);
+      ui.writeError(`Is '${command}' installed and available on your system?`);
+      return { status: 1 };
+    }
+  }
+}

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

@@ -1,4 +1,7 @@
-import { skipMinimumPackageAge } from "../../../config/settings.js";
+import {
+  getNpmCustomRegistries,
+  skipMinimumPackageAge,
+} from "../../../config/settings.js";
 import { isMalwarePackage } from "../../../scanning/audit/index.js";
 import { interceptRequests } from "../interceptorBuilder.js";
 import {
@@ -8,14 +11,20 @@ import {
 } from "./modifyNpmInfo.js";
 import { parseNpmPackageUrl } from "./parseNpmPackageUrl.js";
 
-const knownJsRegistries = ["registry.npmjs.org", "registry.yarnpkg.com"];
+const knownJsRegistries = [
+  "registry.npmjs.org",
+  "registry.yarnpkg.com",
+  "registry.npmjs.com",
+];
 
 /**
  * @param {string} url
  * @returns {import("../interceptorBuilder.js").Interceptor | undefined}
  */
 export function npmInterceptorForUrl(url) {
-  const registry = knownJsRegistries.find((reg) => url.includes(reg));
+  const registry = [...knownJsRegistries, ...getNpmCustomRegistries()].find(
+    (reg) => url.includes(reg)
+  );
 
   if (registry) {
     return buildNpmInterceptor(registry);

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/registryProxy/tunnelRequestHandler.js

@@ -43,6 +43,7 @@ export function tunnelRequest(req, clientSocket, head) {
 function tunnelRequestToDestination(req, clientSocket, head) {
   const { port, hostname } = new URL(`http://${req.url}`);
   const isImds = isImdsEndpoint(hostname);
+  const targetPort = Number.parseInt(port) || 443;
 
   if (timedoutImdsEndpoints.includes(hostname)) {
     clientSocket.end("HTTP/1.1 502 Bad Gateway\r\n\r\n");
@@ -58,64 +59,77 @@ function tunnelRequestToDestination(req, clientSocket, head) {
     return;
   }
 
-  const serverSocket = net.connect(
-    Number.parseInt(port) || 443,
-    hostname,
-    () => {
-      clientSocket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
-      serverSocket.write(head);
-      serverSocket.pipe(clientSocket);
-      clientSocket.pipe(serverSocket);
-    }
-  );
-
-  // Set explicit connection timeout to avoid waiting for OS default (~2 minutes).
-  // IMDS endpoints get shorter timeout (3s) since they're commonly unreachable outside cloud environments.
   const connectTimeout = getConnectTimeout(hostname);
-  serverSocket.setTimeout(connectTimeout);
 
-  serverSocket.on("timeout", () => {
-    // Suppress error logging for IMDS endpoints - timeouts are expected when not in cloud
+  // Use JS setTimeout for true connection timeout (not idle timeout).
+  // socket.setTimeout() measures inactivity, not time since connection attempt.
+  const connectTimer = setTimeout(() => {
     if (isImds) {
       timedoutImdsEndpoints.push(hostname);
       ui.writeVerbose(
-        `Safe-chain: connect to ${hostname}:${
-          port || 443
-        } timed out after ${connectTimeout}ms`
+        `Safe-chain: connect to ${hostname}:${targetPort} timed out after ${connectTimeout}ms`
       );
     } else {
       ui.writeError(
-        `Safe-chain: connect to ${hostname}:${
-          port || 443
-        } timed out after ${connectTimeout}ms`
+        `Safe-chain: connect to ${hostname}:${targetPort} timed out after ${connectTimeout}ms`
       );
     }
-    serverSocket.destroy(); // Clean up socket to prevent event loop hanging
-    clientSocket.end("HTTP/1.1 502 Bad Gateway\r\n\r\n");
+    serverSocket.destroy();
+    if (clientSocket.writable) {
+      clientSocket.end("HTTP/1.1 504 Gateway Timeout\r\n\r\n");
+    }
+  }, connectTimeout);
+
+  const serverSocket = net.connect(targetPort, hostname, () => {
+    // Clear timer to prevent false timeout errors after successful connection
+    clearTimeout(connectTimer);
+
+    clientSocket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+    serverSocket.write(head);
+    serverSocket.pipe(clientSocket);
+    clientSocket.pipe(serverSocket);
   });
 
   clientSocket.on("error", () => {
     // This can happen if the client TCP socket sends RST instead of FIN.
     // Not subscribing to 'error' event will cause node to throw and crash.
+    clearTimeout(connectTimer);
+    if (serverSocket.writable) {
+      serverSocket.end();
+    }
+  });
+
+  clientSocket.on("close", () => {
+    // Client closed connection - clean up server socket
+    clearTimeout(connectTimer);
     if (serverSocket.writable) {
       serverSocket.end();
     }
   });
 
   serverSocket.on("error", (err) => {
+    clearTimeout(connectTimer);
     if (isImds) {
       ui.writeVerbose(
-        `Safe-chain: error connecting to ${hostname}:${port} - ${err.message}`
+        `Safe-chain: error connecting to ${hostname}:${targetPort} - ${err.message}`
       );
     } else {
       ui.writeError(
-        `Safe-chain: error connecting to ${hostname}:${port} - ${err.message}`
+        `Safe-chain: error connecting to ${hostname}:${targetPort} - ${err.message}`
       );
     }
     if (clientSocket.writable) {
       clientSocket.end("HTTP/1.1 502 Bad Gateway\r\n\r\n");
     }
   });
+
+  serverSocket.on("close", () => {
+    // Server closed connection - clean up client socket
+    clearTimeout(connectTimer);
+    if (clientSocket.writable) {
+      clientSocket.end();
+    }
+  });
 }
 
 /**

package/src/shell-integration/helpers.js

@@ -94,6 +94,12 @@ export const knownAikidoTools = [
     ecoSystem: ECOSYSTEM_PY,
     internalPackageManagerName: "pip",
   },
+  {
+    tool: "pipx",
+    aikidoCommand: "aikido-pipx",
+    ecoSystem: ECOSYSTEM_PY,
+    internalPackageManagerName: "pipx",
+  }
   // When adding a new tool here, also update the documentation for the new tool in the README.md
 ];
 

package/src/shell-integration/setup-ci.js

@@ -157,6 +157,14 @@ function modifyPathForCi(shimsDir, binDir) {
     ui.writeInformation("##vso[task.prependpath]" + shimsDir);
     ui.writeInformation("##vso[task.prependpath]" + binDir);
   }
+
+  if (process.env.BASH_ENV) {
+    // In CircleCI, persisting PATH across steps is done by appending shell exports
+    // to the file referenced by BASH_ENV. CircleCI sources this file for 'run' each step.
+    const exportLine = `export PATH="${shimsDir}:${binDir}:$PATH"` + os.EOL;
+    fs.appendFileSync(process.env.BASH_ENV, exportLine, "utf-8");
+    ui.writeInformation(`Added shims directory to BASH_ENV for CircleCI.`);
+  }
 }
 
 function getToolsToSetup() {

package/src/shell-integration/startup-scripts/init-fish.fish

@@ -39,7 +39,6 @@ function npm
     wrapSafeChainCommand "npm" $argv
 end
 
-
 function pip
     wrapSafeChainCommand "pip" $argv
 end
@@ -66,6 +65,10 @@ function python3
     wrapSafeChainCommand "python3" $argv
 end
 
+function pipx
+    wrapSafeChainCommand "pipx" $argv
+end
+
 function printSafeChainWarning
     set original_cmd $argv[1]
     

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

@@ -35,7 +35,6 @@ function npm() {
   wrapSafeChainCommand "npm" "$@"
 }
 
-
 function pip() {
   wrapSafeChainCommand "pip" "$@"
 }
@@ -62,6 +61,10 @@ function python3() {
   wrapSafeChainCommand "python3" "$@"
 }
 
+function pipx() {
+  wrapSafeChainCommand "pipx" "$@"
+}
+
 function printSafeChainWarning() {
   # \033[43;30m is used to set the background color to yellow and text color to black
   # \033[0m is used to reset the text formatting

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

@@ -66,6 +66,9 @@ function python3 {
     Invoke-WrappedCommand 'python3' $args
 }
 
+function pipx {
+    Invoke-WrappedCommand "pipx" $args
+}
 
 function Write-SafeChainWarning {
     param([string]$Command)