aikidosec/safe-chainProteja contra código malicioso instalado via npm, yarn, pnpm, npx, pnpx, pip, uv e poetry com Aikido Safe Chain. Grátis para usar, sem necessidade de tokens.
O Aikido Device Protection se baseia no Safe Chain, estendendo a segurança de pacotes e extensões para mais ecossistemas: npm, PyPI, VS Code, Open VSX - (Cursor, Windsurf, Kiro, Vs Codium, ...), Maven, NuGet, extensões do Chrome, Go, habilidades de IA do Skills.sh, Ruby, Rust e mais.
Obtenha gerenciamento centralizado de políticas, fluxos de trabalho de solicitação e aprovação, e visibilidade em todas as estações de trabalho de desenvolvedores da sua organização. Alimentado pelo mesmo feed do Aikido Intel. Implante-o manualmente ou gerencie-o por meio da sua ferramenta de MDM (Jamf, Fleet ou Iru).
O Aikido Safe Chain suporta os seguintes gerenciadores de pacotes:
Instalar o Aikido Safe Chain é fácil com o script de instalação.
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
Os comandos de instalação acima sempre referenciam uma versão específica. Para instalar uma versão diferente, substitua a versão pelo número da versão desejada. Todas as versões disponíveis estão na página de releases.
Os scripts de instalação são servidos a partir de uma URL de release versionada (releases/download/1.5.15/...). Releases do GitHub são imutáveis — uma vez que um artefato é publicado em uma URL versionada, ele não pode ser modificado ou substituído, portanto, o arquivo que você baixa tem a garantia de ser exatamente o que foi publicado.
❗Reinicie o seu terminal para começar a usar o Aikido Safe Chain.
Verifique a instalação executando o comando de verificação: ```shell npm safe-chain-verify pnpm safe-chain-verify pip safe-chain-verify uv safe-chain-verify
(Opcional) Teste o bloqueio de malware tentando instalar um pacote de teste:
Para JavaScript/Node.js: ```shell npm install safe-chain-test
Para Python: ```shell pip3 install safe-chain-pi-test
- A saída deve mostrar que a Aikido Safe Chain está bloqueando a instalação desses pacotes de teste, pois eles são sinalizados como malware.
Ao executar comandos `npm`, `npx`, `yarn`, `pnpm`, `pnpx`, `rush`, `rushx`, `bun`, `bunx`, `pip`, `pip3`, `uv`, `uvx`, `poetry`, `pipx` e `pdm`, a Aikido Safe Chain verificará automaticamente se há malware nos pacotes que você está tentando instalar. Ela também intercepta invocações de módulos Python para pip quando disponível (por exemplo, `python -m pip install ...`, `python3 -m pip download ...`). Se qualquer malware for detectado, ela solicitará que você saia do comando.
Você pode verificar a versão instalada executando:```shell
safe-chain --version
O Aikido Safe Chain funciona executando um servidor proxy leve que intercepta downloads de pacotes do registro npm e do PyPI. Quando você executa comandos npm, npx, yarn, pnpm, pnpx, rush, rushx, bun, bunx, pip, pip3, uv, uvx, poetry, pipx ou pdm, todos os downloads de pacotes são roteados por esse proxy local, que verifica os pacotes em tempo real contra Aikido Intel - Open Sources Threat Intelligence. Se malware for detectado em qualquer pacote (incluindo dependências profundas), o proxy bloqueia o download antes que o código malicioso chegue à sua máquina.
O Safe Chain aplica verificações de idade mínima do pacote aos ecossistemas suportados.
A aplicação atual difere por ecossistema:
Por padrão, a idade mínima do pacote é de 48 horas. Isso fornece uma camada de segurança adicional durante o período crítico em que pacotes recém-publicados são mais vulneráveis a conter ameaças não detectadas. Você pode configurar esse limite ou ignorar completamente essa proteção — consulte a seção Configuração da Idade Mínima do Pacote abaixo.
O Aikido Safe Chain se integra ao seu shell para proporcionar uma experiência perfeita ao usar npm, npx, yarn, pnpm, pnpx, rush, rushx, bun, bunx e gerenciadores de pacotes Python (pip, uv, uvx, poetry, pipx, pdm). Ele configura aliases para esses comandos, de modo que eles sejam encapsulados pelos comandos do Aikido Safe Chain, que gerenciam o servidor proxy antes de executar os comandos originais. Atualmente suportamos:
Mais informações sobre a integração com shell podem ser encontradas na documentação de integração com shell.
Para desinstalar o Aikido Safe Chain, use nosso desinstalador de uma linha:
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)
❗Reinicie o seu terminal após a desinstalação para garantir que todos os aliases sejam removidos.
Você pode controlar a saída do Aikido Safe Chain usando a opção --safe-chain-logging ou a variável de ambiente SAFE_CHAIN_LOGGING.
Você pode definir o nível de registro por meio de várias fontes (em ordem de prioridade):
Argumento de CLI (prioridade mais alta):
--safe-chain-logging=silent - Suprime toda a saída do Aikido Safe Chain, exceto quando malware é bloqueado. A saída do gerenciador de pacotes é gravada no stdout normalmente, e o Safe Chain escreve apenas uma mensagem curta se tiver bloqueado malware e fizer o processo encerrar.
npm install express --safe-chain-logging=silent
--safe-chain-logging=verbose - Ativa a saída de diagnóstico detalhada do Aikido Safe Chain. Útil para solucionar problemas ou entender o que o Safe Chain está fazendo nos bastidores.
npm install express --safe-chain-logging=verbose
Variável de ambiente: ```shell export SAFE_CHAIN_LOGGING=verbose npm install express
Valores válidos: silent, normal, verbose
Isso é útil para definir um nível de log padrão para todos os comandos do gerenciador de pacotes na sua sessão de terminal ou no ambiente de CI/CD.
Você pode espelhar a saída do Aikido Safe Chain em um arquivo de log usando a flag --safe-chain-log-file ou a variável de ambiente SAFE_CHAIN_LOG_FILE. O log em arquivo fica desabilitado por padrão e é habilitado quando um caminho é definido. O formato do arquivo (--safe-chain-log-file-format) e a verbosidade (--safe-chain-log-file-verbosity) são controlados independentemente da saída do terminal.
Defina por qualquer uma destas (em ordem de prioridade):
~/.safe-chain/config.json): ```json
{
"logFile": "~/safe-chain.log",
"logFileFormat": "plain",
"logFileVerbosity": "normal"
}
logFileFormat — json (padrão) ou plain.
logFileVerbosity — silent, normal ou verbose (padrão). Independente de --safe-chain-logging.
Você pode configurar por quanto tempo os pacotes devem existir antes que o Safe Chain permita sua instalação. Por padrão, os pacotes devem ter pelo menos 48 horas de existência antes de poderem ser instalados.
Para gerenciadores de pacotes baseados em npm, essa verificação atualmente tem dois modos de aplicação:
Para gerenciadores de pacotes Python, essa verificação atualmente tem dois modos de aplicação:
Você pode definir a idade mínima do pacote por meio de várias fontes (em ordem de prioridade):
~/.safe-chain/config.json): ```json
{
"minimumPackageAgeHours": 48
}
Exclua pacotes confiáveis da filtragem por idade mínima por meio de variável de ambiente ou arquivo de configuração (ambos são mesclados). Use @scope/* para confiar em todos os pacotes de uma organização:```shell
export SAFE_CHAIN_MINIMUM_PACKAGE_AGE_EXCLUSIONS="@aikidosec/*"
I don't see any content to translate after "INPUT:". Please provide the actual Markdown content for chunk 33 of 73, and I'll translate it into Portuguese.```json
{
"npm": {
"minimumPackageAgeExclusions": ["@aikidosec/*"]
},
"pip": {
"minimumPackageAgeExclusions": ["requests"]
}
}
Configure o Safe Chain para escanear pacotes de registries personalizados ou privados.
Ecossistemas suportados:
Você pode definir registries personalizados por meio de variável de ambiente ou arquivo de configuração. Ambas as fontes são mescladas.
~/.safe-chain/config.json): ```json
{
"npm": {
"customRegistries": ["npm.company.com", "registry.internal.net"]
},
"pip": {
"customRegistries": ["pip.company.com", "registry.internal.net"]
}
}
Se você depende de um arquivo pip.conf para configurar o pip, deve apontar o pip para ele explicitamente por meio da variável de ambiente PIP_CONFIG_FILE para que o Safe Chain possa mesclá-lo.
O Safe Chain executa o pip por trás do seu proxy MITM e escreve um arquivo de configuração temporário do pip para injetar seu certificado e configurações de proxy. Quando PIP_CONFIG_FILE está definido, o Safe Chain mescla suas configurações em uma cópia do seu arquivo (o arquivo original nunca é modificado), preservando assim o seu index-url, credenciais e outras opções. Quando PIP_CONFIG_FILE não está definido, a configuração de nível de usuário do pip (ex.: ~/.config/pip/pip.conf) pode ser sobrescrita pelo arquivo temporário do Safe Chain e as suas configurações não serão consideradas.
Configure o Safe Chain para buscar bancos de dados de malware e listas de novos pacotes a partir de uma URL de espelho personalizada. Isso permite hospedar sua própria cópia do banco de dados de malware da Aikido.
Você pode definir a URL base da lista de malware por meio de várias fontes (em ordem de prioridade):
~/.safe-chain/config.json): ```json
{
"malwareListBaseUrl": "https://your-mirror.com"
}
A URL base deve apontar para um servidor que espelhe a estrutura de https://malware-list.aikido.dev/, incluindo os seguintes caminhos:
/malware_predictions.json (banco de dados de malware do ecossistema JavaScript)/malware_pypi.json (banco de dados de malware do ecossistema Python)/releases/npm.json (lista de novos pacotes JavaScript)/releases/pypi.json (lista de novos pacotes Python)Além do arquivo de configuração no diretório inicial (~/.safe-chain/config.json), o Safe Chain oferece suporte a um arquivo de configuração do projeto, permitindo que as configurações sejam versionadas em um repositório e compartilhadas em uma equipe, em vez de serem configuradas por máquina.
Adicione uma seção safe-chain: ao arquivo .aikido na raiz do seu repositório (o mesmo arquivo usado por outras ferramentas Aikido; o Safe Chain lê apenas a própria seção safe-chain: e ignora o restante). Quando encontrada, as configurações são mescladas sobre o arquivo de configuração do diretório inicial: os valores definidos na configuração do projeto têm prioridade, e os arrays (como customRegistries) são combinados de ambos os arquivos, em vez de um substituir o outro.
Apenas as seguintes configurações podem ser definidas a partir de um arquivo de configuração do projeto:```yaml safe-chain: minimumPackageAgeHours: 48 npm: customRegistries: - npm.company.com minimumPackageAgeExclusions: - "@aikidosec/*" pip: customRegistries: - pip.company.com minimumPackageAgeExclusions: - requests
Configurações como `scanTimeout`, `malwareListBaseUrl` e as opções `logFile*` não podem ser definidas a partir de um arquivo de configuração do projeto - elas só podem vir da configuração do seu diretório pessoal, argumentos de CLI ou variáveis de ambiente.
## Diretório de Instalação Personalizado
Por padrão, o Safe Chain se instala em `~/.safe-chain`. Você pode alterar isso passando um diretório de instalação explícito ao instalador. Isso é útil para instalações em todo o sistema (por exemplo, dentro de uma imagem Docker) ou quando você precisa evitar conflitos com outras ferramentas.
Quando definido, todos os dados do Safe Chain (binário, shims, scripts, configuração) são colocados no diretório personalizado em vez 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 em CI/CD
Você pode proteger seus pipelines de CI/CD contra pacotes maliciosos integrando o Aikido Safe Chain ao seu processo de build. Isso garante que qualquer pacote instalado durante seus builds automatizados seja verificado quanto a malware antes da instalação.
## Instalação para CI/CD
Use a flag `--ci` para configurar automaticamente o Aikido Safe Chain para ambientes de CI/CD. Isso cria shims executáveis no PATH em vez de aliases 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 Suportadas
- ✅ **GitHub Actions**
- ✅ **Azure Pipelines**
- ✅ **CircleCI**
- ✅ **Jenkins**
- ✅ **Bitbucket Pipelines**
- ✅ **GitLab Pipelines**
## Exemplo do 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"
## Exemplo 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: Isso pressupõe que Node.js e npm estejam instalados no agente 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
'''
}
}
} }
## Exemplo 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
Após a configuração, todos os comandos subsequentes do gerenciador de pacotes no seu pipeline de CI serão automaticamente protegidos pela detecção de malware do Aikido Safe Chain.
Para adicionar o safe-chain nos pipelines do GitLab, você precisa instalá-lo na imagem que executa o pipeline. Isso pode ser feito por:
Defina um dockerfile para executar sua build ```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}"
Construa a imagem Docker no seu 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
Use a imagem no seu pipeline: ```yaml npm-ci: stage: install image: $CI_REGISTRY_IMAGE:latest script: - npm ci
O pipeline completo para este exemplo é assim:```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
# Solução de Problemas
Está com problemas? Consulte o [Guia de Solução de Problemas](https://github.com/aikidosec/safe-chain/blob/HEAD/docs/troubleshooting.md) para obter ajuda com problemas comuns.
# Relatar Problemas
Se você encontrar problemas:
1. Visite [GitHub Issues](https://github.com/AikidoSec/safe-chain/issues)
2. Inclua:
* Sistema operacional e versão
* Tipo de shell e versão
* Saída de `safe-chain --version`
* Saída dos comandos de verificação
* Logs detalhados do comando com falha (adicione o argumento `--safe-chain-logging=verbose`)