Dependências mais seguras para o Claude Code

Quando assistentes de codificação com IA, como o Claude, adicionam pacotes ao seu projeto, eles geralmente escolhem qualquer versão que pareça certa — sem verificar se ela tem vulnerabilidades de segurança conhecidas, se o pacote ainda é mantido ativamente ou se o nome está a um typo de distância de um impostor malicioso.

safer-dependencies é uma camada de segurança para o Claude Code: ele fica entre o Claude e seus arquivos de manifesto e executa suas verificações de segurança automaticamente: instalações vulneráveis são negadas antes de serem executadas, e uma versão arriscada gravada em um manifesto é corrigida no disco logo após a gravação. Ele detecta e corrige dependências arriscadas — CVEs, typosquats, pacotes abandonados e problemas de idade de versão, além de um período de espera para lançamentos recém-publicados — em npm, PyPI, RubyGems, Maven, Go, Rust e PHP (Composer). Consulte CAPABILITIES.md para saber exatamente o que é e o que não é coberto.

Novo aqui? GETTING-STARTED.md leva você do zero a uma instalação funcional em cerca de cinco minutos.

Segurança e privacidade: consulte SECURITY.md (divulgação de vulnerabilidades), PRIVACY.md (saída de dados, sem telemetria) e CAPABILITIES.md (contra o que a ferramenta defende e contra o que não defende).

Licença (código-fonte disponível — NÃO é "open source" da OSI): livre para usar e modificar para seus próprios fins, incluindo uso interno comercial/empresarial e criação de produtos que você vende. Uma licença paga separada é necessária apenas para monetizar o software em si — vendê-lo, distribuí-lo dentro de um produto ou serviço que é vendido, ou oferecer sua funcionalidade a terceiros por uma taxa (incluindo hospedado/SaaS/API). A redistribuição e os derivados devem manter a licença e creditar este projeto. Consulte LICENSE (Seção 4 para a restrição comercial); solicitações de licença comercial via github.com/robert-auger.

Conteúdo

• Primeiros passos — do zero à instalação em cerca de cinco minutos
• O que ele faz
• 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)
• O que o aciona
• O que há neste repositório
• Ecossistemas suportados
• Instalação
  • Configuração
• Níveis de aviso
• Log de auditoria
• Requisitos
• FAQ

Primeiros passos

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

Uso diário: depois que os hooks estão instalados, não há nada para executar — o safer-dependencies funciona automaticamente em segundo plano. Quando o Claude adiciona ou instala pacotes, ele sinaliza dependências arriscadas e atualiza versões vulneráveis para uma versão segura no lugar — 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: "o [email protected] é seguro?", "verifique a configuração do safer-dependencies" ou "mostre as 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. Procedência -- registro oficial, detecção de typosquat (npm/PyPI/RubyGems/Maven/crates.io), idade do pacote
2. Idade da versão -- seleciona a versão estável mais recente publicada há 7+ dias (período de espera)
3. Verificação de vulnerabilidades -- API OSV, com ferramentas nativas do ecossistema (npm audit, pip-audit, bundle audit) quando disponíveis
4. Integridade do hash-pin -- para linhas do PyPI requirements.txt com pins --hash=sha256:..., o hash declarado é validado contra os hashes publicados pelo PyPI; uma incompatibilidade emite um WARNING
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 versão estável há 2+ anos recebem um aviso consultivo STALE:. Pacotes com bloqueio definitivo são removidos do manifesto e o Claude perguntará como proceder; pacotes apenas desatualizados são mantidos no lugar.

Se forem encontrados problemas, 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 civil).

Como funciona

A skill opera em cinco modos (resumidos abaixo; a justificativa de design mais profunda está em skills/safer-dependencies.md):

Modo Normal (Manual)

Quando o Claude está prestes a escrever um import, adicionar um pacote a um manifesto ou atualizar um arquivo de lock, a skill é executada inline na sua sessão:

1. Consulta o registro de pacotes em busca de versões estáveis
2. Seleciona automaticamente a versão mais recente publicada há 7+ dias (determinístico -- sem julgamento de LLM)
3. Verifica vulnerabilidades conhecidas por meio de ferramentas do ecossistema e da API OSV
4. Verifica assinaturas de pacotes quando disponíveis
5. Emite avisos se problemas forem encontrados, fixa a versão exata
6. Registra o resultado na trilha de auditoria

A seleção de versão é feita por scripts Python independentes que acompanham a skill, não pelo LLM interpretando regras. O comando emite SELECTED: <version> e o Claude usa exatamente essa versão.

Modo de Interceptação (Automático)

Configure o .claude/settings.json com um hook PostToolUse para ativar a verificação automática e transparente de pacotes:

1. O Claude escreve um arquivo de manifesto (ex.: package.json) com a versão originalmente solicitada — o arquivo é gravado no disco
2. O hook PostToolUse é disparado imediatamente após a conclusão da gravação e invoca safer-dependencies-shim.sh
3. O shim lê o arquivo, analisa os pacotes declarados e executa todas as verificações de segurança (typosquat, abandonado, CVE, desatualização, hash-pin)
4. Se forem necessárias correções, o shim reescreve o manifesto no lugar com versões seguras (ou remove entradas que não têm versão segura)
5. O shim emite sinais (UPDATED:, BLOCKED:, WARNING:, STALE:, MAJOR-UPDATE-CONFIRM:, REFACTOR-REQUIRED:, REGRESSION:, TYPOSQUAT-CONFIRM:, VERIFY:, ) via em stdout. precede um quando o log de auditoria mostra que o mesmo (arquivo, pacote) foi corrigido anteriormente para o mesmo alvo seguro — ou seja, um subagente ou plano desatualizado reintroduziu uma versão conhecidamente vulnerável, e o orquestrador deve restaurar a versão previamente aprovada em vez de decidir novamente o salto de versão principal.

Nota de design — Forma C (corretiva pós-gravação): o hook NÃO bloqueia gravações. Cada versão vulnerável é gravada no disco primeiro e depois corrigida automaticamente no mesmo ciclo de uso da ferramenta. Essa é uma escolha deliberada em relação a um design de bloqueio PreToolUse — consulte FAQ.md para conhecer os trade-offs.

Exemplo de sinal:``` UPDATED: aiohttp 3.8.5 → 3.9.0 (HIGH: 33 CVEs fixed)

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

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

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

1. O Claude tenta uma chamada de ferramenta Bash (ex.: `npm install [email protected]`)
2. O hook `PreToolUse` dispara antes de a chamada ser executada e invoca
   `safer-dependencies-pretooluse-bash.sh`
3. Um filtro inicial puro em bash ignora rapidamente comandos não-PM em ~115 ms
   (sem invocar Python), então `git status` / `ls` / `npm test` têm
   custo desprezível no caminho crítico
4. Para instalações reconhecidas de gerenciadores de pacotes (`npm`/`pnpm`/`yarn`
   `install`/`i`/`add`), o auxiliar 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 busca na rede, sem scripts de pós-instalação

**Por que isso existe além do Modo de Interceptação:** o shim pós-escrita
é cego ao Bash. `npm install [email protected]` é executado até o fim (e
os scripts de pós-instalação 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ó enxerga 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 termina — 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 do Maven via Modo de Interceptação (as dependências do Maven normalmente são
declaradas em `pom.xml`/`build.gradle`, não adicionadas por um verbo de 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 cair no
> seu manifesto, mas a proteção pré-busca só se aplica aos
> ecossistemas listados acima. Registrado como acompanhamento futuro.

Sintaxe reconhecida por ecossistema:

| Gerenciador de Pacotes | Verbos | Sintaxe de pin concreto |
|---|---|---|
| `npm`, `pnpm`, `yarn`, `bun` | `install`, `i`, `add` (além de `yarn`/`pnpm dlx`, `bun x`, `yarn create`) | `[email protected]`, `@scope/[email protected]` |
| `npx` | (sem verbo — o pacote é o primeiro argumento posicional) | `[email protected]` |
| `deno` | `add`, `install` | `npm:[email protected]` (especificações prefixadas com npm) |
| `pip`, `pip3`, `pipx`, `pipenv`, `uv`, `uvx`, `poetry` | `install` (pip/pip3/pipx/pipenv) / `add` (uv/poetry) / sem verbo (uvx) | `pkg==1.2.3` (extras `pkg[extra]==X` também são tratados) |
| `gem`, `bundle` | `install` (gem) / `add` | `-v 1.2.3`, `--version 1.2.3`, `--version=1.2.3` (flag separada) |
| `go` | `get`, `install` | `[email protected]` (deve incluir o prefixo `v` conforme os módulos Go) |
| `cargo` | `add`, `install` | `[email protected]` |

Pins de faixa (npm `^4.17`, pip `>=`, poetry `^`/`~`, Go `@latest`) e
versões não especificadas passam para o Modo de 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 um follow-up.

**Modo de falha:** fail-open. Qualquer erro (Python ausente, instabilidade de rede,
entrada malformada) retorna 0 sem nenhuma saída, permitindo que o bash prossiga.
O Modo de Interceptação ainda é executado após a instalação, então uma pré-execução com falha
degrada suavemente 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-Instalação (Bash Hook)

Configure o .claude/settings.json com um hook PostToolUse:Bash para habilitar a auditoria pós-execução após comandos Bash. Ele executa três varreduras independentes contra o cwd do comando, cada uma fechando uma lacuna que os outros hooks não conseguem tratar:

• Scan A — lockfiles. Após um comando de instalação bem-sucedido (npm install, bundle install, poetry install, uv sync, go mod tidy, etc.), audita lockfiles recém-modificados (package-lock.json, Gemfile.lock, poetry.lock, uv.lock, go.sum, yarn.lock, pnpm-lock.yaml, Pipfile.lock). Isso fecha a lacuna de CVEs transitivas que o Pre-Install não consegue ver: o usuário digitou pkg@version, mas o resolvedor pode ter puxado dezenas de dependências transitivas que ninguém nomeou.

Como uma varredura é executada:

1. O Claude executa uma chamada de ferramenta Bash
2. O hook PostToolUse é acionado após o comando terminar e invoca safer-dependencies-posttooluse-bash.sh
3. Um filtro inicial em bash puro curto-circuita comandos que não correspondem a nenhum gate de varredura em ~115 ms (mesma convenção de caminho rápido do Pre-Install), então ls / git / cat têm custo desprezível
4. Cada varredura percorre cwd com find -maxdepth 5 (cobre layouts de monorepo; exclui node_modules, .git, .venv, venv) para arquivos modificados dentro dos últimos 60 s — substitua via SAFE_DEP_POSTINSTALL_MTIME_WINDOW
5. Para cada arquivo recém-modificado (Scan A/B), o hook forja um payload sintético PostToolUse:Write e o envia via pipe para o shim existente — os auditores de lockfile e manifestos do shim são executados sem alteração, sem lógica duplicada

O que ele detecta e o Pre-Install não detecta: vulnerabilidades transitivas. Um bundle install aparentemente limpo pode puxar [email protected] (CVE-2025-27610) como transitiva de sinatra — o usuário nunca digitou rack, então o Pre-Install não consegue vê-la, mas o Post-Install lê o Gemfile.lock resolvido e reporta a CVE.

Escopo: o Scan A não reescreve versões resolvidas — o contrato de correção automática só se aplica a manifestos que o Claude escreveu diretamente. Para CVEs transitivas, a correção normalmente é "atualizar a dependência direta que possui a transitiva", o que exige julgamento humano. O Scan B faz correção automática, porque audita manifestos pelo mesmo caminho de shim que o Intercept Mode. O Scan A é ignorado quando o nível de verificação transitive está definido como off (config set checks.transitive off).

Modo de falha: fail-open, igual aos outros hooks. Qualquer erro (shim ausente, payload malformado, Python indisponível) sai com status 0 silenciosamente.

Exemplo de AVISO:``` WARNING: [email protected] in lock file has GHSA-29mw-wpgm-hmr9, GHSA-35jh-r3h4-6jhm

### 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 raiz
sessão despacha um subagente (por meio da 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` (com fallback para um nome
   apenas com PPID quando não há id de sessão disponível)
2. O subagente é executado e pode gravar manifests ou lockfiles
3. Um hook `PostToolUse:Agent` (`safer-dependencies-posttooluse-agent.sh`) é executado
   após a chamada do Agent retornar, executa `find` em todos os manifests e lockfiles mais recentes que
   o sentinela e audita cada um pelo mesmo caminho do shim
4. Os achados são apresentados como `additionalContext` no próximo turno 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á no disco. A única lacuna é uma instalação global que não grava
manifest nem lockfile (`npm install -g …`): não há nada para verificar. Como os
outros hooks, ele falha aberto — qualquer erro (sentinela ausente, shim ausente,
payload ilegível) sai com status 0 silenciosamente. A justificativa completa do design está em
`skills/safer-dependencies.md`.

## O que dispara

A skill dispara automaticamente quando o Claude:

**Operações de manifest / instalação**
- Adiciona ou atualiza um pacote em `package.json`, `requirements.txt`, `Gemfile`, `pom.xml`, `build.gradle`, `Cargo.toml`, `go.mod` ou qualquer outro manifest suportado
- Escreve um `import`, `require` ou `use` para um pacote ainda não declarado no manifest
- Gera ou atualiza um lockfile (verifica apenas entradas novas/alteradas)
- Executa uma instalação via gerenciador de pacotes pelo Bash (`npm install`, `bundle install`, `poetry install`, `uv sync`, `go mod tidy`, etc.) — o Pre-Install audita os argumentos do comando, o Post-Install audita o lockfile resultante
- Escreve um `Dockerfile` ou workflow de CI (`.github/workflows/*.yml`, etc.) que incorpora etapas de instalação do gerenciador de pacotes com versões fixadas

**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?"
- Pedidos de recomendação: "qual é um bom cliente HTTP para Python?", "recomende uma biblioteca de logging para Go", "qual pacote lida com CSV em Node?"
- Seleção de versão: "qual versão do Django devo usar?", "última versão estável do Flask?"

**Expressões de intenção de uso (pré-adição)**
- "quero usar FastAPI para isso", "estou pensando em adicionar Celery", "estamos considerando Prisma como ORM", "vamos usar Tailwind"

**Perguntas sobre saúde e confiança de pacotes**
- "o moment.js ainda é mantido?", "esta gem ainda está ativa?", "X foi abandonado?", "X está em EOL?", "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`, "iniciar um novo projeto FastAPI"

**Adições implícitas de pacotes (pedidos de funcionalidade que implicam uma nova dependência)**
- "Adicionar cache Redis ao aplicativo", "conectar ao Postgres", "adicionar autenticação JWT", "escrever código para enviar e-mails" — dispara quando nenhum pacote para essa funcionalidade já está no manifest

**Migração e portabilidade**
- "Migrar de requests para httpx", "mover de CRA para Vite", "portar de moment para date-fns" — audita o pacote que está entrando

Ele **não** dispara para:

- Importações 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 SO, 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:

| Arquivo | Função |
|---|---|
| `skills/safer-dependencies.md` | A **skill** (`SKILL.md` depois de instalada). Descreve procedimentos de auditoria e inclui modo de gerenciamento para instalação/estatísticas. |
| `skills/safer-dependencies-shim.sh` | Hook `PostToolUse:Write`/`Edit` — audita gravações de manifests + lockfiles e corrige automaticamente versões vulneráveis no local (Modo Interceptação). |
| `skills/safer-dependencies-pretooluse-bash.sh` | Hook `PreToolUse:Bash` — auditoria OSV de pré-execução de comandos de instalação de gerenciador de pacotes; nega pins concretos vulneráveis antes da instalação ser executada (Modo Pré-Instalação). |
| `skills/safer-dependencies-posttooluse-bash.sh` | Hook `PostToolUse:Bash` — auditoria pós-execução após comandos Bash; captura CVEs transitivas em lockfiles recém-escritos, manifests editados via `sed`/`jq`/scripts e o ambiente resolvido de `pip install` simples (Modo Pós-Instalação). |
| `skills/safer-dependencies-pretooluse-agent.sh` + `skills/safer-dependencies-posttooluse-agent.sh` | Par de hooks `PreToolUse:Agent` + `PostToolUse:Agent` — fecha a lacuna de cobertura de subagentes. Os Modos 2–4 só disparam para chamadas de ferramentas da sessão raiz, então qualquer manifest que um subagente escreva os ignora. O Pós-Agente audita tudo o que o subagente escreveu após cada chamada da ferramenta Agent retornar (Modo Pós-Agente). |
| `skills/scripts/` | Biblioteca Python compartilhada (`safedep/`) e scripts de resolução independentes usados por todos os hooks. |
| `skills/scripts/safer_dependencies_manager.py` | Módulo de gerenciamento para instalação interativa, estatísticas de uso e validação da configuração. |

O arquivo da skill sozinho não é suficiente — sem os hooks, a invocação automática depende de o Claude decidir usar 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 que você nunca crie um explicitamente. (Veja [FAQ.md](https://github.com/robert-auger/safer-dependencies/blob/HEAD/FAQ.md#why-a-skill-alone-is-not-sufficient) para saber por que uma skill por si só não pode garantir cobertura.)

## Ecossistemas suportados

| Ecossistema | Manifest | Lockfile |
|-----------|----------|-----------|
| npm | `package.json` | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` |
| PyPI | `requirements.txt`, `pyproject.toml`, `Pipfile`, `setup.py`, `setup.cfg` | `Pipfile.lock`, `poetry.lock`, `uv.lock` |
| RubyGems | `Gemfile`, `*.gemspec` | `Gemfile.lock` |
| Maven | `pom.xml`, `build.gradle`, `libs.versions.toml` | -- |
| Go | `go.mod` | `go.sum` |
| Rust | `Cargo.toml` | `Cargo.lock` |
| PHP (Composer) | `composer.json` | `composer.lock` |

## Instalação

Novo no projeto? Comece com **[GETTING-STARTED.md](https://github.com/robert-auger/safer-dependencies/blob/HEAD/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

O instalador solicita o escopo (global vs projeto) e quais hooks habilitar e, em seguida, grava o settings.json para você — tanto as entradas de hooks quanto a allowlist de permissões que permite que os comandos de verificação da skill sejam executados sem um prompt de aprovação a cada auditoria.

Todo o resto relacionado à instalação está em INSTALLATION.md, a referência única para a mecânica de instalação: instalações manuais arquivo por arquivo (global e em nível de projeto), especificidades do Windows, hooks Post-Agent, a allowlist de permissões, verificação da configuração, atualização, fixação a uma tag de release e desinstalação.

Após a instalação, o gerenciamento do dia a dia funciona por linguagem natural para o Claude — install safer-dependencies (reexecutar / alterar hooks), show safer-dependencies stats, check safer-dependencies setup — ou pelo menu /safer-dependencies. A atualização também acontece na própria sessão: /safer-dependencies update aplica a release mais recente (update --check para um dry-run, update --rollback para desfazer); consulte INSTALLATION.md para o modelo de confiança.

Nota sobre plataformas: macOS, Linux e Windows são suportados. O Windows precisa do Git for Windows (fornece bash) e do Python 3 no PATH — não é necessário WSL. Os testes práticos até o momento se concentraram em macOS e Windows; o suporte a Linux é exercitado pela matriz de CI automatizada.

Configuração

Duas coisas são configuráveis após a instalação:

• Allowlist de permissões — pré-aprova os comandos de verificação somente leitura da skill (as regras de formato exato npm audit / bundle audit e os scripts de resolução da própria skill) para que as auditorias sejam executadas sem um prompt de aprovação a cada vez; curl nunca é pré-aprovado, e npm view / pip-audit são opt-in por meio do perfil Convenience. O instalador interativo grava as entradas principais para você; instalações manuais adicionam o bloco completo à mão. Bloco completo e justificativa: INSTALLATION.md → Allowlist de permissões.
• Política de segurança — a janela/modo de cooldown por idade da release e um nível off/warn/block por verificação para cada tipo de verificação, editado com /safer-dependencies config e armazenado em ~/.config/safer-dependencies/config.toml. Schema e semântica dos níveis: .

Níveis de aviso

Log de auditoria

Cada verificação é registrada em ~/.claude/safer-dependencies-audit-YYYY-MM.log (um arquivo por mês do calendário, em que YYYY-MM é o ano-mês em UTC) como uma única linha JSON. Substitua o caminho completo pela variável de ambiente SAFE_DEP_AUDIT_LOG (quando definida, o sufixo de data não é acrescentado). Os arquivos também são rotacionados por tamanho quando excedem SAFE_DEP_LOG_MAX_BYTES (padrão: 10 MiB; defina 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 modelos.

Todos os cinco modos fazem append ao mesmo arquivo. Cada entrada carrega um bloco source (schema 2.2) que identifica qual componente a gravou:

source.model registra o modelo do Claude Code ativo na sessão (por exemplo, "claude-sonnet-4-6"). Presente no schema 2.1+; entradas gravadas por instalações mais antigas omitem o campo. O comando stats 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

Para uma análise mais fácil, peça ao Claude estatísticas de uso em vez de analisar os logs manualmente:```
"Show safer-dependencies stats for the last month"

Isto fornece resumos legíveis por humanos da atividade, do impacto de segurança e das métricas de desempenho extraídas destes registos de auditoria.

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

Entradas de auditoria: o Intercept Mode executa o pipeline completo (proveniência, idade da versão, OSV, abandoned/stale, typosquat, assinaturas), pelo que todas as arrays podem ser preenchidas. O Pre-Install Mode executa apenas OSV atualmente, pelo que abandoned / stale / typosquat / signatures estão sempre vazios. O dispatch pós-instalação (auditoria de lockfile) escreve sob shim.posttooluse com findings preenchido pelas strings WARNING: dos auditores de lockfile. A array notes transporta sinais informativos NOTE: (por exemplo, manifest-skipped-because-unpinned).

O schema 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 manifest irmão) e um bloco policy que regista o nível transitive em vigor. O incremento é retrocompatível: os 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]"] }

Exemplo do Modo Pré-Instalação (hook Bash, pino vulnerável negado):```json
{
  "ts": "2026-04-23T06:56:21Z",
  "schema": "2.2",
  "source": {
    "component": "bash.pretooluse",
    "script": "pretooluse-bash.sh",
    "hook": "PreToolUse:Bash",
    "tool": "Bash",
    "mode": "intercept",
    "model": "claude-sonnet-4-6"
  },
  "file": "bash:npm install [email protected] [email protected]",
  "ecosystem": "npm",
  "checked": ["[email protected]", "[email protected]"],
  "findings": [
    "BLOCKED: [email protected] GHSA-35jh-r3h4-6jhm (CVSS:3.1/...): Command Injection in lodash"
  ],
  "abandoned": [],
  "stale": [],
  "typosquat": [],
  "unknown": [],
  "signatures": [],
  "notes": [],
  "clean": ["[email protected]"]
}

Exemplo de modo fail-open (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" } }

Uma entrada fail-open diz: "este hook foi acionado, mas saiu cedo sem auditar porque faltava algum pré-requisito." Use o filtro jq acima (`select(.source.mode == "fail_open")`) para expor cada evento silencioso de perda de proteção no seu log.

Quando o shim roda em modo dry-run (`SAFE_DEP_DRY_RUN=1`), as entradas também incluem `"mode": "dry_run"` para que a análise posterior possa filtrar invocações somente de auditoria.

## Requisitos

- Python 3.9+ (os hooks verificam isso e entram em fail-open em interpretadores mais antigos)
- `curl` (para chamadas à API do registry e verificações de vulnerabilidade OSV)
- Ferramentas do ecossistema (opcionais; a skill usa a API OSV como fallback se estiverem ausentes):
  - `npm` para pacotes npm
  - `pip-audit` para pacotes Python
  - `bundle` para pacotes Ruby
  - `dependency-check` para pacotes Java

## FAQ

Fundamentação das decisões de design (por que `PostToolUse` em vez de `PreToolUse`, por que assinaturas não são verificadas, por que scripts e shim são duplicados, pegadinhas de carregamento da skill, etc.) está documentada em [`FAQ.md`](https://github.com/robert-auger/safer-dependencies/blob/HEAD/FAQ.md).