Conteúdo

• Introdução — do zero à instalação em cerca de cinco minutos
• O que ele faz
• O que o aciona
• O que há neste repositório
• Ecossistemas suportados
• Instalação
  • Configuração
  • Alterando o período de espera
• Níveis de aviso
• Como funciona
  • Modo Normal (Manual)
  • Modo de Interceptação (Automático)
  • Modo Pré-Instalação (Hook Bash)
  • Modo Pós-Instalação (Hook Bash)
  • Modo Pós-Agente (Par de Hooks de Agente)
• Registro de auditoria
• Requisitos
• FAQ

Introdução

GETTING-STARTED.md leva você do zero a uma instalação funcional em cerca de cinco minutos — pré-requisitos, a instalação interativa e a verificação. Para a referência completa de instalação (instalações globais/projeto/manuais, especificidades do Windows, a lista de permissões, atualização e desinstalação), consulte INSTALLATION.md.

Uso diário: uma vez que os hooks estão instalados, não há nada para executar — safer-dependencies funciona automaticamente em segundo plano. À medida que o Claude adiciona ou instala pacotes, ele sinaliza dependências arriscadas e atualiza versões vulneráveis para uma versão segura no local — e bloqueia uma instalação conhecidamente vulnerável antes mesmo de ela ser executada — para que pacotes inseguros sejam detectados e corrigidos sem que você precise pedir. Você ainda pode invocá-lo diretamente a qualquer momento: "[email protected] é seguro?", "verifique a configuração do safer-dependencies" ou "mostre estatísticas do safer-dependencies".

O que ele faz

Quando o Claude está prestes a adicionar um pacote ao seu projeto, o safer-dependencies intercepta e executa 5 verificações:

1. Proveniência — registro oficial, detecção de typosquat (npm/PyPI/RubyGems/Maven/crates.io), idade do pacote
2. Idade da versão — escolhe a versão estável mais recente publicada há 7+ dias (janela de espera)
3. Varredura de vulnerabilidades — API OSV, com ferramentas nativas do ecossistema (npm audit, pip-audit, bundle audit) quando disponíveis
4. Integridade de pin de hash — para linhas de requirements.txt do PyPI com pins --hash=sha256:..., o hash declarado é validado contra os hashes publicados do PyPI; uma incompatibilidade emite um AVISO
5. Pacotes abandonados e desatualizados — pacotes conhecidamente abandonados (ex.: paperclip, request, pycrypto, github.com/dgrijalva/jwt-go) são bloqueados imediatamente com uma substituição sugerida; pacotes sem lançamento estável em 2+ anos recebem um aviso consultivo STALE:. Pacotes bloqueados são removidos do manifesto e o Claude perguntará como proceder; pacotes apenas desatualizados são mantidos no local.

Se problemas forem encontrados, o Claude emite avisos e pode recuar para uma versão mais segura. Todas as verificações são registradas em ~/.claude/safer-dependencies-audit-YYYY-MM.log (um arquivo por mês calendário).

O que o aciona

A skill é acionada automaticamente quando o Claude:

Operações de manifesto / instalação

• Adiciona ou atualiza um pacote em package.json, requirements.txt, Gemfile, pom.xml, build.gradle, Cargo.toml, go.mod ou qualquer outro manifesto suportado
• Escreve um import, require ou use para um pacote ainda não declarado no manifesto
• Gera ou atualiza um arquivo de bloqueio (verifica apenas entradas novas/alteradas)
• Executa uma instalação do gerenciador de pacotes via Bash (npm install, bundle install, poetry install, uv sync, go mod tidy, etc.) — Pré-Instalação audita os argumentos do comando, Pós-Instalação audita o arquivo de bloqueio resultante
• Escreve um Dockerfile ou fluxo de trabalho de CI (.github/workflows/*.yml, etc.) que incorpora etapas de instalação fixadas do gerenciador de pacotes

Perguntas de seleção e recomendação

• Comparações de bibliotecas/frameworks: "devo usar axios ou node-fetch?", "moment vs dayjs?", "qual é melhor X ou Y?"
• Solicitações de recomendação: "qual é um bom cliente HTTP para Python?", "recomende uma biblioteca de logging para Go", "qual pacote lida com CSV no Node?"
• Seleção de versão: "qual versão do Django devo usar?", "Flask estável mais recente?"

Expressões de intenção de uso (pré-adição)

• "Quero usar FastAPI para isso", "estou pensando em adicionar Celery", "estamos considerando Prisma como o ORM", "vamos usar Tailwind"

Perguntas sobre saúde e confiança de pacotes

• "O moment.js ainda é mantido?", "este gem ainda está ativo?", "X está abandonado?", "X está em fim de vida?", "posso confiar neste pacote?", "quando o faker foi atualizado pela última vez?"

Comandos de scaffolding

• npx create-react-app, npm create vite@latest, django-admin startproject, rails new, cargo new + cargo add, "inicializar um novo projeto FastAPI"

Adições implícitas de pacotes (solicitações de recursos que implicam uma nova dependência)

• "Adicione cache Redis ao aplicativo", "conecte ao Postgres", "adicione autenticação JWT", "escreva código para enviar e-mails" — dispara quando nenhum pacote para essa capacidade já está no manifesto

Migração e portabilidade

• "Migre de requests para httpx", "mude de CRA para Vite", "porte de moment para date-fns" — audita o pacote de entrada

Ele não dispara para:

• Imports da biblioteca padrão (os, fs, java.util.*, etc.)
• Dependências já declaradas que não estão sendo alteradas
• Discussão acadêmica sobre como um pacote funciona internamente ("explique o reconciler do React", "como funciona a resolução de módulos do webpack?") — perguntas de comparação e seleção ainda disparam
• Instalação de aplicativos de nível de sistema operacional, runtimes ou extensões de IDE (o próprio Python, Docker, Homebrew, extensões do VS Code)

O que há neste repositório

Este é um pacote de skill + hooks, não um único arquivo de skill. Uma instalação completa implanta estas peças:

Apenas o arquivo de skill não é suficiente — sem hooks, a invocação automática depende de o Claude decidir alcançar a skill. Instale todas as cinco peças para cobertura completa; muitas skills e comandos de barra despacham subagentes internamente, então o par Pós-Agente importa mesmo se você nunca gerar um explicitamente. (Consulte FAQ.md para saber por que uma skill sozinha não pode garantir cobertura.)

Ecossistemas suportados

Instalação

Novo no projeto? Comece com GETTING-STARTED.md. A versão resumida:```bash git clone https://github.com/robert-auger/safer-dependencies /tmp/safer-dependencies python3 /tmp/safer-dependencies/skills/scripts/safer_dependencies_manager.py interactive_install

As mesmas ações funcionam fora de uma sessão do Claude:```bash python3 skills/scripts/safer_dependencies_manager.py config set cooloff.days 14

O agente pai usa esses sinais para identificar código afetado e refatorar conforme necessário.

Modo Pré-Instalação (Hook Bash)

Configure .claude/settings.json com um hook PreToolUse:Bash para habilitar auditoria pré-voo de comandos de instalação de gerenciadores de pacotes. Isso complementa (não substitui) o Modo Interceptação — juntos, eles formam uma defesa em camadas.

1. Claude tenta uma chamada de ferramenta Bash (ex.: npm install [email protected])
2. O hook PreToolUse dispara antes da chamada ser executada e invoca safer-dependencies-pretooluse-bash.sh
3. Um filtro inicial puramente em bash encurta comandos que não são de gerenciadores de pacotes em ~115 ms (sem invocação de Python), então git status / ls / npm test pagam custo desprezível no caminho crítico
4. Para instalações reconhecidas de gerenciadores de pacotes (npm/pnpm/yarn install/i/add), o helper tokeniza via shlex, extrai cada argumento pkg@version e faz POST para o OSV
5. Qualquer pin concreto vulnerável → o hook retorna permissionDecision: "deny" com um GHSA-id por achado + CVSS + resumo, além de uma dica para invocar a skill safer-dependencies
6. A instalação nunca é executada — sem fetch de rede, sem scripts postinstall

Por que isso existe além do Modo Interceptação: o shim pós-escrita é cego para Bash. npm install [email protected] é executado até o fim (e scripts postinstall são executados) antes de qualquer auditoria disparar; npm install -g typosquat-pkg não escreve nenhum manifesto de projeto. O Modo Pré-Instalação fecha essas lacunas estruturalmente.

O Modo Pré-Instalação só vê o que o usuário digitou (argumentos pkg@version na linha de comando). Ele não consegue ver a árvore transitiva que o resolvedor realmente instalará. O Modo Pós-Instalação (abaixo) audita o lockfile assim que a instalação é concluída — os dois modos são complementares, não redundantes.

Escopo: os CLIs de gerenciadores de pacotes cobertos aqui abrangem cinco ecossistemas (npm/pnpm/yarn/bun/npx/deno, pip/pip3/pipx/pipenv/uv/uvx/poetry, gem/bundle, go, cargo), além de Maven via Modo Interceptação (dependências Maven são tipicamente declaradas em pom.xml/build.gradle, não adicionadas via um verbo CLI).

Lacuna conhecida: o CLI do Maven suporta downloads diretos via mvn dependency:get -Dartifact=group:art:version e mvn dependency:copy. Este hook ainda não reconhece essas invocações. Se você as usa regularmente, o shim pós-escrita existente ainda captura o que quer que chegue ao seu manifesto, mas a proteção pré-fetch só se aplica aos ecossistemas listados acima. Rastreado como acompanhamento.

Sintaxe reconhecida por ecossistema:

Pins de intervalo (npm ^4.17, pip >=, poetry ^/~, Go @latest) e versões não especificadas passam para o Modo Interceptação após a instalação — o shim pós-escrita audita o que o resolvedor escolher. A reescrita automática para uma versão segura está na fila como acompanhamento.

Modo de falha: fail-open. Qualquer erro (Python ausente, instabilidade de rede, entrada malformada) sai com código 0 e sem saída, permitindo que o bash prossiga. O Modo Interceptação ainda é executado após a instalação, então uma falha pré-voo degrada graciosamente para a proteção existente.

Exemplo de negação:``` safer-dependencies pre-flight audit blocked this install. Vulnerable pinned version(s) detected:

• [email protected] → GHSA-35jh-r3h4-6jhm (CVSS:7.4): Command Injection in lodash Re-run with a patched version, or invoke the safer-dependencies skill for a recommended pin.

Modo Pós-Agente (Par de Hooks de Agente)

Os quatro modos acima só disparam para chamadas de ferramentas da sessão raiz. Quando a sessão raiz despacha um subagente (via a ferramenta Agent — muitas skills e comandos de barra fazem isso internamente), as chamadas Write/Edit/Bash do subagente ignoram todos eles. O Modo Pós-Agente é a rede de segurança reativa para essa lacuna.

1. Um hook PreToolUse:Agent (safer-dependencies-pretooluse-agent.sh) é executado imediatamente antes de cada despacho de Agent e toca um arquivo sentinela em /tmp/.safer-deps-agent-<PPID>-<session_id>.sentinel (recorrendo a um nome apenas com PPID quando não há id de sessão disponível)
2. O subagente é executado e pode escrever manifests ou lockfiles
3. Um hook PostToolUse:Agent (safer-dependencies-posttooluse-agent.sh) é executado após a chamada do Agent retornar, faz find em todo manifest e lockfile mais recente que o sentinela e audita cada um pelo mesmo caminho do shim
4. Os achados surgem como additionalContext para a próxima rodada da sessão raiz; o sentinela é removido

Subagentes aninhados são cobertos automaticamente — o PostToolUse:Agent da raiz só dispara depois que todo o trabalho do agente externo (incluindo qualquer coisa que ele tenha despachado) está em disco. A única lacuna é uma instalação global que não escreve manifest nem lockfile (npm install -g …): não há nada para escanear. Como os outros hooks, ele falha aberto — qualquer erro (sentinela ausente, shim ausente, payload ilegível) sai com código 0 silenciosamente. A justificativa completa do design está em skills/safer-dependencies.md.

Log de auditoria

Cada verificação é registrada em ~/.claude/safer-dependencies-audit-YYYY-MM.log (um arquivo por mês calendário, onde YYYY-MM é o ano-mês UTC) como uma única linha JSON. Substitua o caminho completo com a variável de ambiente SAFE_DEP_AUDIT_LOG (quando definida, o sufixo de data não é anexado). Os arquivos também sofrem rotação por tamanho quando excedem SAFE_DEP_LOG_MAX_BYTES (padrão 10 MiB; defina como 0 para desativar). Defina SAFE_DEP_MODEL para substituir o valor do modelo gravado em source.model em cada entrada — útil para comparações A/B entre versões de modelo.

Todos os cinco modos anexam ao mesmo arquivo. Cada entrada carrega um bloco source (esquema 2.2) identificando qual componente o escreveu:

source.model registra o modelo do Claude Code ativo na sessão (ex.: "claude-sonnet-4-6"). Presente no esquema 2.1+; entradas escritas por instalações mais antigas omitem o campo. O comando de estatísticas degrada graciosamente para "unknown" quando ele está ausente.

Filtre por source.component com jq:```bash jq -r '.source.component' audit.log | sort | uniq -c | sort -rn jq -c 'select(.source.component == "bash.pretooluse")' audit.log

Surface every silent fail-open across all hooks:

jq -c 'select(.source.mode == "fail_open") | {component: .source.component, reason: .fail_open.reason, ts}' audit.log

Este fornece resumos legíveis por humanos de atividade, impacto de segurança e métricas de desempenho extraídos desses logs de auditoria.

Formatos de entrada (esquema 2.2). Três formatos distintos compartilham o mesmo cabeçalho ts / schema / source:

Entradas de auditoria: o Modo de Interceptação executa o pipeline completo (proveniência, idade da versão, OSV, abandonado/obsoleto, typosquat, assinaturas), portanto todos os arrays podem ser preenchidos. O Modo Pré-Instalação executa apenas OSV hoje, então abandoned / stale / typosquat / signatures estão sempre vazios. O despacho pós-instalação (auditoria de lockfile) grava sob shim.posttooluse com findings preenchido por strings WARNING: dos auditores de lockfile. O array notes carrega sinais informativos NOTE: (por exemplo, manifesto-ignorado-porque-não-pinned).

O esquema 2.2 adicionou — de forma aditiva — quatro campos às entradas de auditoria de lockfile: lockfile, manifest_ref, relation_summary (uma classificação direta/transitiva/desconhecida de cada pacote sinalizado em relação ao manifesto irmão) e um bloco policy registrando o nível transitive em vigor. O incremento é retrocompatível: leitores de entradas 2.1 toleram os novos campos, e o campo source.model permanece presente a partir da versão 2.1 em diante.```json { "ts": "2026-04-19T12:34:56Z", "schema": "2.2", "source": { "component": "shim.posttooluse", "script": "shim.sh", "hook": "PostToolUse:Write", "tool": "Write", "mode": "intercept", "model": "claude-sonnet-4-6" }, "file": "/path/to/project/package.json", "ecosystem": "npm", "checked": ["[email protected]", "[email protected]"], "findings": ["UPDATED: express 4.18.2 → 4.22.1 (HIGH: 1 CVE fixed)"], "abandoned": [], "stale": [], "typosquat": [], "unknown": [], "signatures": [], "notes": [], "clean": ["[email protected]"] }

Fail-open Mode example (hook Bash pós-instalação chamado sem shim adjacente — instalação quebrada):```json { "ts": "2026-05-03T07:14:11Z", "schema": "2.2", "source": { "component": "bash.posttooluse", "script": "safer-dependencies-posttooluse-bash.sh", "hook": "PostToolUse", "tool": "Bash", "mode": "fail_open", "model": "claude-sonnet-4-6" }, "fail_open": { "reason": "shim_missing", "detail": "/home/alice/.claude/skills/safer-dependencies" } }