Skip to main content
Safe Chain runs a lightweight local proxy server that sits between your package managers and the npm registry or PyPI. Every package download is routed through this proxy, which checks each package against real-time threat intelligence before allowing it to reach your machine.

​
Request flow

1

You run a package manager command

You run a normal command such as npm install, pip install, or yarn add. Safe Chain’s shell integration intercepts the call and routes it through the aikido-* wrapper.
2

The local proxy starts

Safe Chain starts a local HTTP/HTTPS proxy server on a random available port. The package manager process is configured to route all registry traffic through this proxy via environment variables (HTTPS_PROXY, NODE_EXTRA_CA_CERTS).
3

Package requests are intercepted

As the package manager resolves dependencies and downloads tarballs, each request passes through the proxy. Safe Chain inspects both package metadata responses and direct download requests.
4

Malware check runs

Each package name and version is checked against the Aikido Intel threat intelligence database. The database is fetched from malware-list.aikido.dev and cached locally; only the version (ETag) is checked on subsequent runs to avoid unnecessary downloads.
5

Package is allowed or blocked

If no threat is detected, the response is passed through unmodified. If malware is found, the proxy blocks the download and Safe Chain exits with an error before any malicious code is written to disk.

​
Malware detection

Safe Chain checks every package — including transitive dependencies — against Aikido Intel, an open-source threat intelligence feed maintained by Aikido Security. The database covers both npm and PyPI ecosystems. When a match is found, Safe Chain:
  1. Blocks the download request at the proxy level.
  2. Prints the blocked package name and version.
  3. Exits the process without installing anything.
The malware database is cached locally and refreshed by comparing ETags, so checks are fast even on repeated runs.

​
Minimum package age

Newly published packages are among the highest-risk targets for supply chain attacks. Safe Chain applies a minimum age threshold — 48 hours by default — to suppress or block packages that were published too recently to be trusted. Enforcement differs by ecosystem:
Safe Chain uses two layers of enforcement:
  • Metadata suppression: During normal dependency resolution, Safe Chain modifies the package metadata response from the registry to remove versions that are newer than the configured minimum age. The package manager never sees these versions and resolves to an older, trusted release instead.
  • Direct download blocking: For requests that bypass metadata resolution (for example, direct tarball fetches), Safe Chain blocks the request using a cached list of newly released packages fetched from malware-list.aikido.dev/releases/npm.json.
You can configure the minimum age threshold or exclude specific packages. See the minimum package age configuration for details.

​
Shell integration

Safe Chain integrates with your shell by adding startup scripts to your shell profile. These scripts define functions or aliases that wrap each supported package manager command with its aikido-* equivalent, which manages the proxy lifecycle before executing the real command. Supported shells:
  • Bash
  • Zsh
  • Fish
  • PowerShell
  • PowerShell Core
Each supported command (npm, npx, yarn, pnpm, pnpx, bun, bunx, pip, pip3, uv, poetry, pipx) is wrapped transparently — your existing commands and scripts work without modification. Safe Chain also intercepts Python module invocations such as python -m pip install when available.

​
CI/CD mode

In CI/CD environments, shell startup scripts are not sourced between pipeline steps. Safe Chain’s --ci flag installs executable shims into ~/.safe-chain/shims and adds that directory to PATH instead of using shell aliases. This ensures every package manager call in the pipeline is intercepted without requiring a shell restart. 
curl -fsSL https://github.com/AikidoSec/safe-chain/releases/latest/download/install-safe-chain.sh | sh -s -- --ci

​
Data privacy

Safe Chain is tokenless. No account is required, no build data is sent to Aikido, and no information about your dependencies or environment is transmitted. The only external requests Safe Chain makes are to download the malware database and newly-released packages list from malware-list.aikido.dev.

Build docs developers (and LLMs) love

Get started for freeTalk to us