audit-mcp-cli

audit-mcp-cli

Español | 中文

Una herramienta ligera de auditoría de vulnerabilidades de dependencias para proyectos Node.js. Admite modos CLI y MCP Server, cubre proyectos npm y pnpm, y genera informes estructurados en Markdown/HTML con cadenas de dependencias completas.

Características

• Cadenas de dependencias completas — rastrea la ruta completa desde tu package.json hasta cada paquete vulnerable
• Soporte npm + pnpm — detecta automáticamente el gestor de paquetes mediante el lockfile
• Auditoría remota de GitHub — audita cualquier repositorio público o privado sin clonarlo
• Servidor MCP — se integra con asistentes de codificación de IA (Claude, Cursor, etc.)
• Informes Markdown / HTML — informes limpios y estructurados ordenados por severidad
• Puerta de CI — código de salida --fail-on para pipelines de CI/CD
• Mecanismo de ignorar — suprime vulnerabilidades aceptadas con fechas de expiración
• Filtrado por severidad — muestra solo vulnerabilidades por encima de un umbral

Instalación

# Run directly
npx audit-mcp-cli

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

Requiere 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

Opciones de CLI

Opción	Descripción	Predeterminado
--path <path>	Ruta del proyecto local	process.cwd()
--remote <repo>	Repositorio remoto: github:owner/repo o https://github.com/owner/repo	—
--ref <ref>	Referencia de Git (nombre de rama / etiqueta / SHA de commit)	main
--token <token>	Token de acceso personal de GitHub (para repositorios privados)	env GITHUB_TOKEN
--format <fmt>	Formato de informe: md o html	md
--output <path>	Ruta del archivo de salida	audit-report.md o .html
--severity <level>	Severidad mínima a mostrar: low / moderate / high / critical	low
--fail-on <level>	Umbral de fallo de CI — sale con 1 si existen vulnerabilidades en este nivel o superior	—
--mcp	Iniciar como servidor MCP	—
--lang <lang>	Idioma: en o zh-CN	Detección automática del sistema

Códigos de salida --fail-on

Valor	Sale con 1 cuando
critical	Se encuentra cualquier vulnerabilidad crítica
high	Se encuentra cualquier vulnerabilidad alta o crítica
moderate	Se encuentra cualquier vulnerabilidad moderada, alta o crítica
low	Se encuentra cualquier vulnerabilidad
(no establecido)	Siempre sale con 0

Servidor MCP

Ejecutar como servidor MCP stdio para asistentes de IA:

audit-mcp-cli --mcp

Claude Desktop

Básico (proyectos locales y repositorios públicos):

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

Con token de GitHub (repositorios privados / evita límites de tasa):

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

Cursor

Añadir a .cursor/mcp.json:

Básico (proyectos locales y repositorios públicos):

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

Con token de GitHub (repositorios privados / evita límites de tasa):

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

Herramienta: audit_dependencies

El servidor MCP expone una herramienta que admite auditoría local y remota:

Parámetro	Descripción
projectPath	Ruta del proyecto local
remoteRepo	Repositorio remoto: github:owner/repo
ref	Referencia de Git (rama / etiqueta / SHA)
token	Token de GitHub (para repositorios privados, o usa la env GITHUB_TOKEN)
format	md o html
severity	Filtro de severidad mínima
outputPath	Ruta personalizada del archivo de salida

Devuelve: ruta del archivo de informe + detalles estructurados de vulnerabilidades (CVSS, cadenas de dependencias, sugerencias de corrección).

El token es opcional. La auditoría de proyectos locales nunca requiere token. Los repositorios públicos remotos funcionan sin token (60 solicitudes/hora). Solo los repositorios privados requieren un token de GitHub.

Mecanismo de ignorar

Crea .audit-mcp-cli-ignore.json en la raíz de tu proyecto para suprimir vulnerabilidades aceptadas:

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

• packageName — coincide con todos los avisos de este paquete, o combínalo con advisorySource para coincidencia exacta
• expiresAt — opcional, el ignorado expira automáticamente después de esta fecha
• Las vulnerabilidades ignoradas se muestran en una sección separada del informe y se excluyen de las comprobaciones de --fail-on

Integración de 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"

Licencia

MIT