Resumo

O Guardian é uma CLI para análise de dependências que vai muito além do npm audit.

Ele combina análise técnica (vulnerabilidades + reachability) com contexto do mundo real (incidentes recentes), e entrega um relatório HTML pronto para compartilhar.

Tudo focado em responder:

o que realmente importa agora no seu projeto

Features

• Análise rápida de dependências Node.js
• Radar com os incidentes mais quentes da semana
• Priorização real de risco (não só CVE)
• Sugestões de atualização seguras
• Detecção de risco de manutenção
• Relatório HTML bonito e pronto para compartilhar
• Integração opcional com IA (OpenAI)

Instalação

npm install -g @mkafonso/guardian

ou

npx @mkafonso/guardian analyze .

Uso rápido

Dentro do seu projeto (na raiz, ou passando o path):

guardian analyze .

Isso irá:

• Ler seu package.json
• Detectar lockfiles (npm/yarn/pnpm)
• Avaliar vulnerabilidades + reachability (quando possível)
• Priorizar riscos e sugerir ações
• Gerar o relatório HTML

Você também pode passar o conteúdo de um package.json diretamente como texto, sem precisar de um projeto em disco:

guardian analyze '{"name":"my-app","dependencies":{"lodash":"4.17.20","express":"4.18.2"}}'

Se você quiser usar o Guardian em código, importe o analisador direto do pacote:

import { analyzePackageJsonText } from '@mkafonso/guardian'

const report = await analyzePackageJsonText(
  JSON.stringify({
    name: 'my-app',
    dependencies: {
      lodash: '4.17.21',
      express: '4.18.2',
    },
  }),
)

console.log(report)

O retorno é um objeto de relatório com as mesmas informações usadas para gerar o HTML.

Por padrão, um arquivo será gerado no diretório atual:

guardian-report.html

Abra no navegador e compartilhe com o time.

Opções

guardian analyze [projectPath|packageJsonText] [options]

• --output, -o <file>: caminho do HTML de saída
• --json [file]: gera o relatório em JSON; use > para redirecionar ou forneça um arquivo opcional
• --no-incidents: desabilita o radar de incidentes
• --no-reachability: desabilita a análise de reachability

Exemplos:

guardian analyze
guardian analyze .
guardian analyze ./my-app --output guardian-report.html
guardian analyze --json > guardian-report.json
guardian analyze --json guardian-report.json

# Modo inline: passa o package.json como texto
guardian analyze '{"name":"my-app","dependencies":{"express":"4.18.2"}}'
guardian analyze '{"dependencies":{"lodash":"4.17.20"}}' --json
guardian analyze '{"dependencies":{"axios":"1.6.0"}}' --output report.html

Radar de Incidentes

O Guardian mostra automaticamente:

• Ataques de supply chain
• Malware recente em npm
• Incidentes em vendors (Next.js, React, etc)
• Vazamentos e compromissos

Sempre focando nos:

6 incidentes mais relevantes da semana

IA (Opcional)

Para enriquecer os dados:

export OPENAI_API_KEY=your_key_here
export GITHUB_TOKEN=your_key_here

Isso adiciona:

• Explicação dos incidentes
• Vetor técnico
• Ações recomendadas
• Padrões emergentes

Comparação

| Feature | npm audit | Guardian | | --------------------------- | --------- | -------- | | Vulnerabilidades conhecidas | ✅ | ✅ | | Priorização real | ❌ | ✅ | | Incidentes atuais | ❌ | ✅ | | Insights acionáveis | ❌ | ✅ | | Relatório visual | ❌ | ✅ |

Exemplo

git clone https://github.com/mkafonso/guardian
cd guardian
npm install
npm run dev

Filosofia

O Guardian não tenta mostrar tudo.

Ele foca em:

🔥 o que é crítico agora

🧠 o que você deve fazer primeiro

Contribuição

Contribuições são bem-vindas!

• Issues
• PRs
• Ideias