aikidosec/safe-chainProtégete contra el código malicioso instalado mediante npm, yarn, pnpm, npx, pnpx, pip, uv y poetry con Aikido Safe Chain. Uso gratuito, sin necesidad de tokens.
Aikido Device Protection se basa en Safe Chain, ampliando la seguridad de paquetes y extensiones a más ecosistemas: npm, PyPI, VS Code, Open VSX - (Cursor, Windsurf, Kiro, Vs Codium, ...), Maven, NuGet, extensiones de Chrome, Go, habilidades de IA de Skills.sh, Ruby, Rust, y más.
Obtén gestión centralizada de políticas, flujos de trabajo de solicitud y aprobación, y visibilidad en cada estación de trabajo de desarrollador de tu organización. Impulsado por el mismo feed de Aikido Intel. Despliégalo manualmente o adminístralo a través de tu herramienta MDM (Jamf, Fleet o Iru).
Aikido Safe Chain es compatible con los siguientes gestores de paquetes:
Instalar Aikido Safe Chain es fácil con el script de instalación.
curl -fsSL https://github.com/AikidoSec/safe-chain/releases/download/1.5.15/install-safe-chain.sh -o /tmp/install-safe-chain.sh
&& echo "de0565e3d6346407a604e84e639e95fea8758748063da2216bbfdca5feda5dd2 /tmp/install-safe-chain.sh" | sha256sum -c -
&& sh /tmp/install-safe-chain.sh
&& rm /tmp/install-safe-chain.sh
### Windows (PowerShell)```powershell
$installer = Join-Path $env:TEMP "install-safe-chain.ps1"
Invoke-WebRequest "https://github.com/AikidoSec/safe-chain/releases/download/1.5.15/install-safe-chain.ps1" -OutFile $installer -UseBasicParsing
$expectedHash = "5FC22EEF74814BEF6828AA07C0EAEC79598F343F98B94A4ACAB823769AD56DA1"
if ((Get-FileHash $installer -Algorithm SHA256).Hash -ne $expectedHash) {
Remove-Item $installer -ErrorAction SilentlyContinue
throw "Checksum verification failed for install-safe-chain.ps1"
}
& $installer
Remove-Item $installer
Los comandos de instalación anteriores hacen siempre referencia a una versión específica. Para instalar una versión distinta, sustituye la versión por el número de versión que desees. Todas las versiones disponibles están en la página de versiones.
Los scripts de instalación se sirven desde una URL de versión fija (releases/download/1.5.15/...). Los releases de GitHub son inmutables — una vez que un artefacto se publica en una URL versionada, no puede modificarse ni reemplazarse, por lo que el archivo que descargas está garantizado que es exactamente lo que se publicó.
❗Reinicia tu terminal para empezar a usar Aikido Safe Chain.
Verifica la instalación ejecutando el comando de verificación: ```shell npm safe-chain-verify pnpm safe-chain-verify pip safe-chain-verify uv safe-chain-verify
(Opcional) Probar el bloqueo de malware intentando instalar un paquete de prueba:
Para JavaScript/Node.js: ```shell npm install safe-chain-test
Para Python: ```shell pip3 install safe-chain-pi-test
- La salida debería mostrar que Aikido Safe Chain está bloqueando la instalación de estos paquetes de prueba, ya que se marcan como malware.
Al ejecutar comandos `npm`, `npx`, `yarn`, `pnpm`, `pnpx`, `rush`, `rushx`, `bun`, `bunx`, `pip`, `pip3`, `uv`, `uvx`, `poetry`, `pipx` y `pdm`, Aikido Safe Chain comprobará automáticamente si hay malware en los paquetes que intentas instalar. También intercepta las invocaciones de módulos de Python para pip cuando esté disponible (p. ej., `python -m pip install ...`, `python3 -m pip download ...`). Si se detecta malware, te pedirá que salgas del comando.
Puedes comprobar la versión instalada ejecutando:```shell
safe-chain --version
Aikido Safe Chain funciona ejecutando un servidor proxy ligero que intercepta las descargas de paquetes del registro npm y de PyPI. Cuando ejecutas comandos npm, npx, yarn, pnpm, pnpx, rush, rushx, bun, bunx, pip, pip3, uv, uvx, poetry, pipx o pdm, todas las descargas de paquetes se enrutan a través de este proxy local, que verifica los paquetes en tiempo real contra Aikido Intel - Inteligencia de amenazas de código abierto. Si se detecta malware en cualquier paquete (incluidas las dependencias profundas), el proxy bloquea la descarga antes de que el código malicioso llegue a tu máquina.
Safe Chain aplica comprobaciones de edad mínima del paquete a los ecosistemas compatibles.
La aplicación actual difiere según el ecosistema:
Por defecto, la edad mínima del paquete es de 48 horas. Esto proporciona una capa de seguridad adicional durante el período crítico en el que los paquetes recién publicados son más vulnerables a contener amenazas no detectadas. Puedes configurar este umbral u omitir esta protección por completo; consulta la sección Configuración de la edad mínima del paquete a continuación.
Aikido Safe Chain se integra con tu shell para proporcionar una experiencia fluida al usar npm, npx, yarn, pnpm, pnpx, rush, rushx, bun, bunx y administradores de paquetes de Python (pip, uv, uvx, poetry, pipx, pdm). Configura alias para estos comandos de modo que queden envueltos por los comandos de Aikido Safe Chain, que gestionan el servidor proxy antes de ejecutar los comandos originales. Actualmente admitimos:
Puedes encontrar más información sobre la integración con la shell en la documentación de integración con la shell.
Para desinstalar Aikido Safe Chain, usa nuestro desinstalador de una línea:
curl -fsSL https://github.com/AikidoSec/safe-chain/releases/download/1.5.15/uninstall-safe-chain.sh | sh
### Windows (PowerShell)```powershell
iex (iwr "https://github.com/AikidoSec/safe-chain/releases/download/1.5.15/uninstall-safe-chain.ps1" -UseBasicParsing)
❗Reinicia tu terminal después de desinstalar para asegurarte de que se eliminen todos los alias.
Puedes controlar la salida de Aikido Safe Chain utilizando la opción --safe-chain-logging o la variable de entorno SAFE_CHAIN_LOGGING.
Puedes establecer el nivel de registro a través de múltiples fuentes (en orden de prioridad):
Argumento de CLI (prioridad más alta):
--safe-chain-logging=silent - Suprime todo el resultado de Aikido Safe Chain excepto cuando se bloquea malware. La salida del gestor de paquetes se escribe en stdout como siempre, y Safe Chain solo escribe un mensaje corto si ha bloqueado malware y hace que el proceso termine.
npm install express --safe-chain-logging=silent
--safe-chain-logging=verbose - Activa la salida de diagnóstico detallada de Aikido Safe Chain. Útil para solucionar problemas o entender qué está haciendo Safe Chain entre bastidores.
npm install express --safe-chain-logging=verbose
Variable de Entorno: ```shell export SAFE_CHAIN_LOGGING=verbose npm install express
Valores válidos: silent, normal, verbose
Esto es útil para establecer un nivel de registro predeterminado para todos los comandos del gestor de paquetes en tu sesión de terminal o entorno de CI/CD.
Puedes reflejar la salida de Aikido Safe Chain en un archivo de registro utilizando el indicador --safe-chain-log-file o la variable de entorno SAFE_CHAIN_LOG_FILE. El registro en archivo está deshabilitado por defecto y se habilita cuando se establece una ruta. El formato del archivo (--safe-chain-log-file-format) y la verbosidad (--safe-chain-log-file-verbosity) se controlan de forma independiente de la salida del terminal.
Se configuran mediante cualquiera de estas opciones (en orden de prioridad):
~/.safe-chain/config.json): ```json
{
"logFile": "~/safe-chain.log",
"logFileFormat": "plain",
"logFileVerbosity": "normal"
}
logFileFormat — json (predeterminado) o plain.
logFileVerbosity — silent, normal o verbose (predeterminado). Independiente de --safe-chain-logging.
Puedes configurar cuánto tiempo deben existir los paquetes antes de que Safe Chain permita su instalación. De forma predeterminada, los paquetes deben tener al menos 48 horas de antigüedad antes de poder instalarse.
Para gestores de paquetes basados en npm, esta comprobación tiene actualmente dos modos de aplicación:
Para gestores de paquetes de Python, esta comprobación tiene actualmente dos modos de aplicación:
Puedes establecer la edad mínima del paquete mediante múltiples fuentes (en orden de prioridad):
~/.safe-chain/config.json): ```json
{
"minimumPackageAgeHours": 48
}
Excluye paquetes de confianza del filtrado por antigüedad mínima mediante una variable de entorno o un archivo de configuración (ambos se combinan). Usa @scope/* para confiar en todos los paquetes de una organización:```shell
export SAFE_CHAIN_MINIMUM_PACKAGE_AGE_EXCLUSIONS="@aikidosec/*"
No se proporcionó contenido en el campo INPUT para traducir.```json
{
"npm": {
"minimumPackageAgeExclusions": ["@aikidosec/*"]
},
"pip": {
"minimumPackageAgeExclusions": ["requests"]
}
}
Configura Safe Chain para escanear paquetes de registros personalizados o privados.
Ecosistemas compatibles:
Puedes configurar registros personalizados mediante una variable de entorno o un archivo de configuración. Ambas fuentes se combinan.
~/.safe-chain/config.json): ```json
{
"npm": {
"customRegistries": ["npm.company.com", "registry.internal.net"]
},
"pip": {
"customRegistries": ["pip.company.com", "registry.internal.net"]
}
}
Si dependes de un archivo pip.conf para la configuración de pip, debes señalárselo a pip explícitamente mediante la variable de entorno PIP_CONFIG_FILE para que Safe Chain pueda fusionarlo.
Safe Chain ejecuta pip detrás de su proxy MITM y escribe un archivo de configuración temporal de pip para inyectar su certificado y sus ajustes de proxy. Cuando PIP_CONFIG_FILE está definida, Safe Chain fusiona sus ajustes en una copia de tu archivo (tu archivo original nunca se modifica), de modo que tu index-url, credenciales y otras opciones se conservan. Cuando PIP_CONFIG_FILE no está definida, la configuración a nivel de usuario de pip (p. ej. ~/.config/pip/pip.conf) podría ser sobrescrita por el archivo temporal de Safe Chain y tus ajustes no se tendrán en cuenta.
Configura Safe Chain para obtener las bases de datos de malware y las listas de paquetes nuevos desde una URL de espejo personalizada. Esto te permite alojar tu propia copia de la base de datos de malware de Aikido.
Puedes establecer la URL base de la lista de malware desde múltiples fuentes (en orden de prioridad):
~/.safe-chain/config.json): ```json
{
"malwareListBaseUrl": "https://your-mirror.com"
}
La URL base debe apuntar a un servidor que reproduzca la estructura de https://malware-list.aikido.dev/, incluyendo las siguientes rutas:
/malware_predictions.json (base de datos de malware del ecosistema JavaScript)/malware_pypi.json (base de datos de malware del ecosistema Python)/releases/npm.json (lista de paquetes nuevos de JavaScript)/releases/pypi.json (lista de paquetes nuevos de Python)Además del archivo de configuración del directorio de inicio (~/.safe-chain/config.json), Safe Chain admite un archivo de configuración del proyecto para que los ajustes puedan incorporarse a un repositorio y compartirse en todo el equipo, en lugar de configurarse por máquina.
Añade una sección safe-chain: al archivo .aikido en la raíz de tu repositorio (el mismo archivo que usan otras herramientas de Aikido; Safe Chain solo lee su propia sección safe-chain: e ignora el resto). Cuando se encuentra, sus ajustes se fusionan sobre el archivo de configuración del directorio de inicio: los valores establecidos en la configuración del proyecto tienen prioridad, y los arrays (como customRegistries) se combinan desde ambos archivos en lugar de que uno reemplace al otro.
Solo los siguientes ajustes pueden establecerse desde un archivo de configuración del proyecto:```yaml safe-chain: minimumPackageAgeHours: 48 npm: customRegistries: - npm.company.com minimumPackageAgeExclusions: - "@aikidosec/*" pip: customRegistries: - pip.company.com minimumPackageAgeExclusions: - requests
Los ajustes como `scanTimeout`, `malwareListBaseUrl` y las opciones `logFile*` no pueden establecerse desde un archivo de configuración del proyecto; solo pueden provenir de la configuración de tu directorio personal, los argumentos de la CLI o las variables de entorno.
## Directorio de instalación personalizado
De forma predeterminada, Safe Chain se instala en `~/.safe-chain`. Puedes cambiarlo pasando un directorio de instalación explícito al instalador. Esto resulta útil para instalaciones en todo el sistema (p. ej., dentro de una imagen Docker) o cuando necesitas evitar conflictos con otras herramientas.
Cuando se establece, todos los datos de Safe Chain (binario, shims, scripts, configuración) se colocan en el directorio personalizado en lugar de `~/.safe-chain`.
### Unix/Linux/macOS```shell
curl -fsSL https://github.com/AikidoSec/safe-chain/releases/download/1.5.15/install-safe-chain.sh -o /tmp/install-safe-chain.sh \
&& echo "de0565e3d6346407a604e84e639e95fea8758748063da2216bbfdca5feda5dd2 /tmp/install-safe-chain.sh" | sha256sum -c - \
&& sh /tmp/install-safe-chain.sh --install-dir /usr/local/.safe-chain \
&& rm /tmp/install-safe-chain.sh
$installer = Join-Path $env:TEMP "install-safe-chain.ps1" Invoke-WebRequest "https://github.com/AikidoSec/safe-chain/releases/download/1.5.15/install-safe-chain.ps1" -OutFile $installer -UseBasicParsing $expectedHash = "5FC22EEF74814BEF6828AA07C0EAEC79598F343F98B94A4ACAB823769AD56DA1" if ((Get-FileHash $installer -Algorithm SHA256).Hash -ne $expectedHash) { Remove-Item $installer -ErrorAction SilentlyContinue throw "Checksum verification failed for install-safe-chain.ps1" } & $installer -InstallDir 'C:\ProgramData\safe-chain' Remove-Item $installer
# Uso en CI/CD
Puedes proteger tus pipelines de CI/CD contra paquetes maliciosos integrando Aikido Safe Chain en tu proceso de compilación. Esto asegura que cualquier paquete instalado durante tus compilaciones automatizadas se revise en busca de malware antes de la instalación.
## Instalación para CI/CD
Usa el indicador `--ci` para configurar automáticamente Aikido Safe Chain para entornos de CI/CD. Esto configura shims ejecutables en el PATH en lugar de alias de shell.
### Unix/Linux/macOS (GitHub Actions, Azure Pipelines, etc.)```shell
curl -fsSL https://github.com/AikidoSec/safe-chain/releases/download/1.5.15/install-safe-chain.sh -o /tmp/install-safe-chain.sh \
&& echo "de0565e3d6346407a604e84e639e95fea8758748063da2216bbfdca5feda5dd2 /tmp/install-safe-chain.sh" | sha256sum -c - \
&& sh /tmp/install-safe-chain.sh --ci \
&& rm /tmp/install-safe-chain.sh
$installer = Join-Path $env:TEMP "install-safe-chain.ps1" Invoke-WebRequest "https://github.com/AikidoSec/safe-chain/releases/download/1.5.15/install-safe-chain.ps1" -OutFile $installer -UseBasicParsing $expectedHash = "5FC22EEF74814BEF6828AA07C0EAEC79598F343F98B94A4ACAB823769AD56DA1" if ((Get-FileHash $installer -Algorithm SHA256).Hash -ne $expectedHash) { Remove-Item $installer -ErrorAction SilentlyContinue throw "Checksum verification failed for install-safe-chain.ps1" } & $installer -ci Remove-Item $installer
## Plataformas compatibles
- ✅ **GitHub Actions**
- ✅ **Azure Pipelines**
- ✅ **CircleCI**
- ✅ **Jenkins**
- ✅ **Bitbucket Pipelines**
- ✅ **GitLab Pipelines**
## Ejemplo de GitHub Actions```yaml
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: "22"
cache: "npm"
- name: Install safe-chain
run: |
curl -fsSL https://github.com/AikidoSec/safe-chain/releases/download/1.5.15/install-safe-chain.sh -o /tmp/install-safe-chain.sh
echo "de0565e3d6346407a604e84e639e95fea8758748063da2216bbfdca5feda5dd2 /tmp/install-safe-chain.sh" | sha256sum -c -
sh /tmp/install-safe-chain.sh --ci
rm /tmp/install-safe-chain.sh
- name: Install dependencies
run: npm ci
task: NodeTool@0 inputs: versionSpec: "22.x" displayName: "Install Node.js"
script: | curl -fsSL https://github.com/AikidoSec/safe-chain/releases/download/1.5.15/install-safe-chain.sh -o /tmp/install-safe-chain.sh echo "de0565e3d6346407a604e84e639e95fea8758748063da2216bbfdca5feda5dd2 /tmp/install-safe-chain.sh" | sha256sum -c - sh /tmp/install-safe-chain.sh --ci rm /tmp/install-safe-chain.sh displayName: "Install safe-chain"
script: npm ci displayName: "Install dependencies"
## Ejemplo de CircleCI```yaml
version: 2.1
jobs:
build:
docker:
- image: cimg/node:lts
steps:
- checkout
- run: |
curl -fsSL https://github.com/AikidoSec/safe-chain/releases/download/1.5.15/install-safe-chain.sh -o /tmp/install-safe-chain.sh
echo "de0565e3d6346407a604e84e639e95fea8758748063da2216bbfdca5feda5dd2 /tmp/install-safe-chain.sh" | sha256sum -c -
sh /tmp/install-safe-chain.sh --ci
rm /tmp/install-safe-chain.sh
- run: npm ci
workflows:
build_and_test:
jobs:
- build
Nota: Se asume que Node.js y npm están instalados en el agente de Jenkins.```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. // If you installed into a custom directory, replace ~/.safe-chain with that path here. 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/download/1.5.15/install-safe-chain.sh -o /tmp/install-safe-chain.sh
echo "de0565e3d6346407a604e84e639e95fea8758748063da2216bbfdca5feda5dd2 /tmp/install-safe-chain.sh" | sha256sum -c -
sh /tmp/install-safe-chain.sh --ci
rm /tmp/install-safe-chain.sh
'''
}
}
stage('Install project dependencies etc...') {
steps {
sh '''
set -euo pipefail
npm ci
'''
}
}
} }
## Ejemplo de Bitbucket Pipelines```yaml
image: node:22
steps:
- step:
name: Install
script:
- |
curl -fsSL https://github.com/AikidoSec/safe-chain/releases/download/1.5.15/install-safe-chain.sh -o /tmp/install-safe-chain.sh
echo "de0565e3d6346407a604e84e639e95fea8758748063da2216bbfdca5feda5dd2 /tmp/install-safe-chain.sh" | sha256sum -c -
sh /tmp/install-safe-chain.sh --ci
rm /tmp/install-safe-chain.sh
- export PATH=~/.safe-chain/shims:~/.safe-chain/bin:$PATH
- npm ci
Después de la configuración, todos los comandos posteriores del gestor de paquetes en tu pipeline de CI estarán protegidos automáticamente por la detección de malware de Aikido Safe Chain.
Para añadir safe-chain en pipelines de GitLab, debes instalarlo en la imagen que ejecuta el pipeline. Esto se puede hacer de la siguiente manera:
Define un dockerfile para ejecutar tu compilación ```dockerfile FROM node:lts
RUN curl -fsSL https://github.com/AikidoSec/safe-chain/releases/download/1.5.15/install-safe-chain.sh -o /tmp/install-safe-chain.sh
&& echo "de0565e3d6346407a604e84e639e95fea8758748063da2216bbfdca5feda5dd2 /tmp/install-safe-chain.sh" | sha256sum -c -
&& sh /tmp/install-safe-chain.sh --ci
&& rm /tmp/install-safe-chain.sh
ENV PATH="/root/.safe-chain/shims:/root/.safe-chain/bin:${PATH}"
Construye la imagen de Docker en tu pipeline de CI ```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
Usa la imagen en tu pipeline: ```yaml npm-ci: stage: install image: $CI_REGISTRY_IMAGE:latest script: - npm ci
El pipeline completo para este ejemplo se ve así:```yaml stages:
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
# Solución de problemas
¿Tienes problemas? Consulta la [Guía de solución de problemas](https://github.com/aikidosec/safe-chain/blob/HEAD/docs/troubleshooting.md) para obtener ayuda con problemas comunes.
# Reportar problemas
Si encuentras problemas:
1. Visita [Problemas de GitHub](https://github.com/AikidoSec/safe-chain/issues)
2. Incluye:
* Sistema operativo y versión
* Tipo de shell y versión
* Salida de `safe-chain --version`
* Salida de los comandos de verificación
* Registros detallados del comando fallido (añade el argumento `--safe-chain-logging=verbose`)