https://github.com/mkafonso/guardian
[NPM] Analise dependências Node.js, priorize riscos reais e gere relatórios acionáveis em segundos
https://github.com/mkafonso/guardian
audit cli dependencies devtools nodejs npm security typescript vulnerabilities
Last synced: 2 months ago
JSON representation
[NPM] Analise dependências Node.js, priorize riscos reais e gere relatórios acionáveis em segundos
- Host: GitHub
- URL: https://github.com/mkafonso/guardian
- Owner: mkafonso
- License: mit
- Created: 2026-04-21T01:04:22.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-29T04:47:02.000Z (3 months ago)
- Last Synced: 2026-04-29T06:28:42.198Z (3 months ago)
- Topics: audit, cli, dependencies, devtools, nodejs, npm, security, typescript, vulnerabilities
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@mkafonso/guardian
- Size: 1.18 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
Guardian
Analise dependências Node.js, priorize riscos reais e gere relatórios acionáveis em segundos.
GitHub -
Instalação -
Uso rápido -
Opções -
IA
## 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
```bash
npm install -g @mkafonso/guardian
```
ou
```bash
npx @mkafonso/guardian analyze .
```
## Uso rápido
Dentro do seu projeto (na raiz, ou passando o path):
```bash
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:
```bash
guardian analyze '{"name":"my-app","dependencies":{"lodash":"4.17.20","express":"4.18.2"}}'
```
## Uso como biblioteca
Se você quiser usar o Guardian em código, importe o analisador direto do pacote:
```ts
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.
## Output
Por padrão, um arquivo será gerado no diretório atual:
```bash
guardian-report.html
```
Abra no navegador e compartilhe com o time.
## Opções
```bash
guardian analyze [projectPath|packageJsonText] [options]
```
- `--output, -o `: 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:
```bash
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:
```bash
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
```bash
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