# aikidosec/safe-chain architecture

> Architecture diagram of the GitHub repository aikidosec/safe-chain, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aikidosec/safe-chain
- Repository: https://github.com/aikidosec/safe-chain

## Overview

Safe Chain wraps package-manager commands, optionally pre-scans requested dependencies, and routes registry traffic through a local security proxy. The proxy checks malware intelligence and enforces minimum package age; shell integration installs command wrappers. The README documents npm/PyPI protection, package-manager support, and safe-patch age exemptions. Unsampled wiring is represented only where documented; package-manager and interceptor internals are grouped at their supported source paths.

Main entry points: [`packages/safe-chain/src/main.js`](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/main.js) (Safe Chain runtime), [`packages/safe-chain/src/packagemanager/currentPackageManager.js`](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/packagemanager/currentPackageManager.js) (Manager dispatch), [`packages/safe-chain/src/registryProxy/interceptors/minimumPackageAgeChecker.js`](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/registryProxy/interceptors/minimumPackageAgeChecker.js) (Minimum age checks), [`packages/safe-chain/src/registryProxy/registryProxy.js`](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/registryProxy/registryProxy.js) (Local registry proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_command["Command handling"]
  node_shim["Command shim<br/>[safe-chain.js]"]
  node_main["Safe Chain runtime<br/>[main.js]"]
  node_dispatch["Manager dispatch"]
  node_npm["npm-family managers"]
  node_python["Python managers"]
  node_othermanagers["Other managers"]
  node_settings["Runtime settings<br/>[settings.js]"]
end

subgraph group_security["Package security"]
  node_scanner["Command scanning<br/>[index.js]"]
  node_audit["Dependency audit<br/>[index.js]"]
  node_malware[("Malware intelligence<br/>[malwareDatabase.js]")]
  node_remotelist[("Threat list cache<br/>[remoteListCache.js]")]
  node_safeversions[("Safe patch exemptions")]
  node_newpackages[("New package cache")]
end

subgraph group_proxy["Registry proxy"]
  node_proxy["Local registry proxy<br/>[registryProxy.js]"]
  node_requesthandler["Request handling"]
  node_interceptors["Registry interceptors"]
  node_npmint["npm interceptor<br/>[npmInterceptor.js]"]
  node_pipint["PyPI interceptor<br/>[pipInterceptor.js]"]
  node_agecheck["Minimum age checks"]
end

subgraph group_integration["Shell integration"]
  node_shellsetup["Shell setup<br/>[setup.js]"]
  node_shellaliases["Shell wrappers"]
end

node_developer(("Developer or CI"))
node_npmregistry[("npm registry")]
node_pypi[("PyPI registry")]
node_intel[("Aikido Intel")]

node_developer -->|"runs command"| node_shim
node_shim -->|"starts runtime"| node_main
node_main -->|"gets manager"| node_dispatch
node_dispatch -->|"selects"| node_npm
node_dispatch -->|"selects"| node_python
node_dispatch -->|"selects"| node_othermanagers
node_main -->|"scans command"| node_scanner
node_scanner -->|"audits packages"| node_audit
node_audit -->|"checks threats"| node_malware
node_malware -->|"uses cached list"| node_remotelist
node_main -->|"starts proxy"| node_proxy
node_npm -->|"sets proxy environment"| node_proxy
node_python -->|"sets proxy environment"| node_proxy
node_proxy -->|"handles requests"| node_requesthandler
node_requesthandler -->|"dispatches by ecosystem"| node_interceptors
node_interceptors -->|"selects npm"| node_npmint
node_interceptors -->|"selects PyPI"| node_pipint
node_npmint -->|"forwards requests"| node_npmregistry
node_pipint -->|"forwards requests"| node_pypi
node_npmint -->|"checks release age"| node_agecheck
node_pipint -->|"checks release age"| node_agecheck
node_agecheck -->|"checks cached releases"| node_newpackages
node_agecheck -->|"allows safe patches"| node_safeversions
node_malware -.->|"refreshes threat data"| node_intel
node_developer -->|"configures shell"| node_shellsetup
node_shellsetup -->|"installs wrappers"| node_shellaliases
node_shellaliases -->|"wraps commands"| node_shim
node_main -->|"reads configuration"| node_settings

click node_shim "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/bin/safe-chain.js"
click node_main "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/main.js"
click node_dispatch "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/packagemanager/currentPackageManager.js"
click node_npm "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/packagemanager/npm/createPackageManager.js"
click node_python "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/packagemanager/pip/createPackageManager.js"
click node_othermanagers "https://github.com/aikidosec/safe-chain/tree/main/packages/safe-chain/src/packagemanager"
click node_scanner "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/scanning/index.js"
click node_audit "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/scanning/audit/index.js"
click node_malware "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/scanning/malwareDatabase.js"
click node_remotelist "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/scanning/remoteListCache.js"
click node_safeversions "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/scanning/safePatchesListCache.js"
click node_newpackages "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/scanning/newPackagesListCache.js"
click node_proxy "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/registryProxy/registryProxy.js"
click node_requesthandler "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/registryProxy/mitmRequestHandler.js"
click node_interceptors "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/registryProxy/interceptors/createInterceptorForEcoSystem.js"
click node_npmint "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/registryProxy/interceptors/npm/npmInterceptor.js"
click node_pipint "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/registryProxy/interceptors/pip/pipInterceptor.js"
click node_agecheck "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/registryProxy/interceptors/minimumPackageAgeChecker.js"
click node_shellsetup "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/shell-integration/setup.js"
click node_shellaliases "https://github.com/aikidosec/safe-chain/tree/main/packages/safe-chain/src/shell-integration/supported-shells"
click node_settings "https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/config/settings.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_shim,node_main,node_dispatch,node_npm,node_python,node_othermanagers,node_settings toneBlue
class node_scanner,node_audit,node_malware,node_remotelist,node_safeversions,node_newpackages,node_npmregistry,node_pypi,node_intel toneAmber
class node_proxy,node_requesthandler,node_interceptors,node_npmint,node_pipint,node_agecheck toneMint
class node_shellsetup,node_shellaliases toneRose
class node_developer toneIndigo
```

## Components

### Command handling

- [Command shim](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/bin/safe-chain.js): `packages/safe-chain/bin/safe-chain.js`
- [Safe Chain runtime](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/main.js): `packages/safe-chain/src/main.js`
- [Manager dispatch](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/packagemanager/currentPackageManager.js): `packages/safe-chain/src/packagemanager/currentPackageManager.js`
- [npm-family managers](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/packagemanager/npm/createPackageManager.js): `packages/safe-chain/src/packagemanager/npm/createPackageManager.js`
- [Python managers](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/packagemanager/pip/createPackageManager.js): `packages/safe-chain/src/packagemanager/pip/createPackageManager.js`
- [Other managers](https://github.com/aikidosec/safe-chain/tree/main/packages/safe-chain/src/packagemanager): `packages/safe-chain/src/packagemanager`
- [Runtime settings](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/config/settings.js): `packages/safe-chain/src/config/settings.js`

### Package security

- [Command scanning](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/scanning/index.js): `packages/safe-chain/src/scanning/index.js`
- [Dependency audit](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/scanning/audit/index.js): `packages/safe-chain/src/scanning/audit/index.js`
- [Malware intelligence](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/scanning/malwareDatabase.js): `packages/safe-chain/src/scanning/malwareDatabase.js`
- [Threat list cache](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/scanning/remoteListCache.js): `packages/safe-chain/src/scanning/remoteListCache.js`
- [Safe patch exemptions](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/scanning/safePatchesListCache.js): `packages/safe-chain/src/scanning/safePatchesListCache.js`
- [New package cache](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/scanning/newPackagesListCache.js): `packages/safe-chain/src/scanning/newPackagesListCache.js`

### Registry proxy

- [Local registry proxy](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/registryProxy/registryProxy.js): `packages/safe-chain/src/registryProxy/registryProxy.js`
- [Request handling](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/registryProxy/mitmRequestHandler.js): `packages/safe-chain/src/registryProxy/mitmRequestHandler.js`
- [Registry interceptors](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/registryProxy/interceptors/createInterceptorForEcoSystem.js): `packages/safe-chain/src/registryProxy/interceptors/createInterceptorForEcoSystem.js`
- [npm interceptor](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/registryProxy/interceptors/npm/npmInterceptor.js): `packages/safe-chain/src/registryProxy/interceptors/npm/npmInterceptor.js`
- [PyPI interceptor](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/registryProxy/interceptors/pip/pipInterceptor.js): `packages/safe-chain/src/registryProxy/interceptors/pip/pipInterceptor.js`
- [Minimum age checks](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/registryProxy/interceptors/minimumPackageAgeChecker.js): `packages/safe-chain/src/registryProxy/interceptors/minimumPackageAgeChecker.js`

### Shell integration

- [Shell setup](https://github.com/aikidosec/safe-chain/blob/main/packages/safe-chain/src/shell-integration/setup.js): `packages/safe-chain/src/shell-integration/setup.js`
- [Shell wrappers](https://github.com/aikidosec/safe-chain/tree/main/packages/safe-chain/src/shell-integration/supported-shells): `packages/safe-chain/src/shell-integration/supported-shells`

### Other components

- **Developer or CI**
- **npm registry**
- **PyPI registry**
- **Aikido Intel**

## Connections

- Developer or CI → Command shim: runs command
- Command shim → Safe Chain runtime: starts runtime
- Safe Chain runtime → Manager dispatch: gets manager
- Manager dispatch → npm-family managers: selects
- Manager dispatch → Python managers: selects
- Manager dispatch → Other managers: selects
- Safe Chain runtime → Command scanning: scans command
- Command scanning → Dependency audit: audits packages
- Dependency audit → Malware intelligence: checks threats
- Malware intelligence → Threat list cache: uses cached list
- Safe Chain runtime → Local registry proxy: starts proxy
- npm-family managers → Local registry proxy: sets proxy environment
- Python managers → Local registry proxy: sets proxy environment
- Local registry proxy → Request handling: handles requests
- Request handling → Registry interceptors: dispatches by ecosystem
- Registry interceptors → npm interceptor: selects npm
- Registry interceptors → PyPI interceptor: selects PyPI
- npm interceptor → npm registry: forwards requests
- PyPI interceptor → PyPI registry: forwards requests
- npm interceptor → Minimum age checks: checks release age
- PyPI interceptor → Minimum age checks: checks release age
- Minimum age checks → New package cache: checks cached releases
- Minimum age checks → Safe patch exemptions: allows safe patches
- Malware intelligence → Aikido Intel: refreshes threat data
- Developer or CI → Shell setup: configures shell
- Shell setup → Shell wrappers: installs wrappers
- Shell wrappers → Command shim: wraps commands
- Safe Chain runtime → Runtime settings: reads configuration