audit-mcp-cli

audit-mcp-cli

English | 中文

Uma ferramenta leve de auditoria de vulnerabilidades de dependências para projetos Node.js. Suporta modos CLI e MCP Server, cobre projetos npm e pnpm, e gera relatórios estruturados em Markdown/HTML com cadeias completas de dependências.

Recursos

• Cadeias completas de dependências — rastreia o caminho completo do seu package.json até cada pacote vulnerável
• Suporte a npm + pnpm — detecta automaticamente o gerenciador de pacotes pelo lockfile
• Auditoria remota no GitHub — audita qualquer repositório público ou privado sem clonar
• MCP Server — integra-se com assistentes de codificação por IA (Claude, Cursor, etc.)
• Relatórios Markdown / HTML — relatórios limpos e estruturados, ordenados por severidade
• Gate de CI — código de saída --fail-on para pipelines de CI/CD
• Mecanismo de ignorar — suprime vulnerabilidades aceitas com datas de expiração
• Filtro de severidade — mostra apenas vulnerabilidades acima de um limite

Instalação

# Run directly
npx audit-mcp-cli

# Or install globally
npm install -g audit-mcp-cli

Requer Node.js >= 18.

Uso

# Audit current directory
audit-mcp-cli

# Specific project path
audit-mcp-cli --path /path/to/project

# Remote GitHub repo (branch)
audit-mcp-cli --remote github:facebook/react --ref main

# Remote GitHub repo (tag)
audit-mcp-cli --remote github:facebook/react --ref v18.2.0

# Remote GitHub repo (commit SHA)
audit-mcp-cli --remote github:facebook/react --ref abc123def

# HTML report
audit-mcp-cli --format html --output report.html

# CI: fail if high+ severity vulnerabilities found
audit-mcp-cli --fail-on high

# Severity filtering (only show high and critical)
audit-mcp-cli --severity high

Opções da CLI

Opção	Descrição	Padrão
--path <path>	Caminho do projeto local	process.cwd()
--remote <repo>	Repositório remoto: github:owner/repo ou https://github.com/owner/repo	—
--ref <ref>	Ref do Git (nome do branch / tag / SHA do commit)	main
--token <token>	Token de acesso pessoal do GitHub (para repositórios privados)	variável de ambiente GITHUB_TOKEN
--format <fmt>	Formato do relatório: md ou html	md
--output <path>	Caminho do arquivo de saída	audit-report.md ou .html
--severity <level>	Severidade mínima para exibir: low / moderate / high / critical	low
--fail-on <level>	Limite de falha de CI — sai com 1 se existirem vulnerabilidades neste nível ou acima	—
--mcp	Iniciar como MCP Server	—
--lang <lang>	Idioma: en ou zh-CN	Detecção automática do sistema

Códigos de saída --fail-on

Valor	Sai com 1 quando
critical	Qualquer vulnerabilidade crítica encontrada
high	Qualquer vulnerabilidade alta ou crítica encontrada
moderate	Qualquer vulnerabilidade moderada, alta ou crítica encontrada
low	Qualquer vulnerabilidade encontrada
(não definido)	Sempre sai com 0

MCP Server

Execute como um servidor MCP stdio para assistentes de IA:

audit-mcp-cli --mcp

Claude Desktop

Básico (projetos locais e repositórios públicos):

{
  "mcpServers": {
    "audit-mcp-cli": {
      "command": "npx",
      "args": ["-y", "audit-mcp-cli", "--mcp"]
    }
  }
}

Com token do GitHub (repositórios privados / evite limites de requisição):

{
  "mcpServers": {
    "audit-mcp-cli": {
      "command": "npx",
      "args": ["-y", "audit-mcp-cli", "--mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxx"
      }
    }
  }
}

Cursor

Adicione em .cursor/mcp.json:

Básico (projetos locais e repositórios públicos):

{
  "mcpServers": {
    "audit-mcp-cli": {
      "command": "npx",
      "args": ["-y", "audit-mcp-cli", "--mcp"]
    }
  }
}

Com token do GitHub (repositórios privados / evite limites de requisição):

{
  "mcpServers": {
    "audit-mcp-cli": {
      "command": "npx",
      "args": ["-y", "audit-mcp-cli", "--mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxx"
      }
    }
  }
}

Ferramenta: audit_dependencies

O servidor MCP expõe uma ferramenta que suporta auditoria local e remota:

Parâmetro	Descrição
projectPath	Caminho do projeto local
remoteRepo	Repositório remoto: github:owner/repo
ref	Ref do Git (branch / tag / SHA)
token	Token do GitHub (para repositórios privados, ou use a variável de ambiente GITHUB_TOKEN)
format	md ou html
severity	Filtro de severidade mínima
outputPath	Caminho personalizado do arquivo de saída

Retorna: caminho do arquivo de relatório + detalhes estruturados de vulnerabilidades (CVSS, cadeias de dependências, sugestões de correção).

O token é opcional. A auditoria de projetos locais nunca exige token. Repositórios públicos remotos funcionam sem token (60 requisições/hora). Apenas repositórios privados exigem um token do GitHub.

Mecanismo de ignorar

Crie .audit-mcp-cli-ignore.json na raiz do seu projeto para suprimir vulnerabilidades aceitas:

{
  "ignore": [
    {
      "packageName": "minimist",
      "advisorySource": 1179,
      "reason": "Accepted risk, limited impact in our usage",
      "expiresAt": "2025-12-31T00:00:00Z"
    }
  ]
}

• packageName — corresponde a todos os avisos de segurança para este pacote, ou combine com advisorySource para correspondência exata
• expiresAt — opcional, a regra de ignorar expira automaticamente após esta data
• Vulnerabilidades ignoradas são exibidas em uma seção separada do relatório e excluídas das verificações de --fail-on

Integração com CI

# GitHub Actions example
- name: Security Audit
  run: npx audit-mcp-cli --fail-on high

# Generic CI
npx audit-mcp-cli --fail-on high && echo "pass" || echo "fail"

Licença

MIT