NuGuard Open Source

NuGuard é um kit de ferramentas de código aberto para segurança de aplicações de IA. Seu objetivo é fornecer a mais extensa validação de redteaming e comportamental de aplicações de IA Agêntica.

Com o NuGuard, desenvolvedores de IA podem focar na construção de suas aplicações enquanto o NuGuard continuamente as testa e valida contra uma ampla gama de riscos de segurança, incluindo ataques à cadeia de suprimentos, injeção de prompt, uso indevido de ferramentas MCP, ataques a APIs, exfiltração de dados e muito mais. O NuGuard permite que os desenvolvedores acelerem seus fluxos de trabalho de segurança e cheguem à produção mais rapidamente com confiança.

Uma versão comercial do NuGuard está disponível como produto SaaS com recursos e suporte adicionais, confira em http://nuguard.ai.

O Que Ele Faz

• Gera um AI-SBOM a partir de uma base de código local ou repositório Git
• Analisa o SBOM em busca de riscos estruturais de segurança de IA e problemas de cadeia de suprimentos
• Propõe uma política comportamental de IA com base no SBOM
• Realiza testes comportamentais estáticos e em tempo de execução, criados especificamente em torno do AI-SBOM e da política comportamental
• Faz red-team de uma aplicação de IA em sandbox: o mais extenso e atualizado catálogo de vetores de ataque, além de cenários personalizados. Isso inclui injeção de prompt, abuso de ferramentas, exfiltração de dados e cenários de ataque relacionados que exercitam os diversos subagentes, ferramentas e capacidades do sistema alvo.
• Sugestões automatizadas de remediação para os achados, incluindo trechos de código e ajustes de política
• Exporta achados em fluxos de trabalho orientados a texto, JSON, Markdown e SARIF

Superfície Atual da CLI

Implementado e utilizável hoje:

• nuguard sbom
• nuguard analyze
• nuguard scan
• nuguard policy
• nuguard behavior
• nuguard redteam

Requisitos

• Python 3.12+
• uv para o fluxo de trabalho local recomendado

Instalação

CLI Python:

pip install nuguard

As etapas abaixo descrevem como configurar um ambiente de desenvolvimento local. Isso é recomendado se você quiser executar o código mais recente, contribuir com o projeto ou executar a CLI com recursos assistidos por LLM que exigem configuração de variáveis de ambiente locais.

uv sync --dev

Execute a CLI com:

uv run nuguard --help

Ou, a partir do ambiente virtual:

. .venv/bin/activate
nuguard --help

Usuários do Claude podem usar comandos de plugin.

Siga as instruções em docs/plugin-guide.md para configurar o plugin NuGuard para o Claude e usá-lo para executar comandos como /nuguard-sbom, /nuguard-analyze e /nuguard-redteam diretamente em suas conversas com o Claude.

Início Rápido

1. Gerar um AI-SBOM

nuguard sbom generate --source . --output app.sbom.json

Também é possível escanear um repositório remoto:

nuguard sbom generate \
  --from-repo https://github.com/org/repo \
  --ref main \
  --output app.sbom.json

2. Executar Análise Estática

nuguard analyze --sbom app.sbom.json --format markdown

Saídas típicas:

• markdown para revisão humana
• json para automação
• sarif para pipelines de varredura de código

3. Testes Comportamentais

nuguard behavior \
  --sbom app.sbom.json \
  --target http://localhost:3000 \
  --format markdown

4. Faça Red-Team em um Aplicativo ao Vivo

nuguard redteam \
  --config nuguard.yaml \
  --output reports/redteam.md \
  --format markdown

Para uma cobertura de red-team mais rica, você também pode fornecer:

• uma política cognitiva com --policy
• valores canary com --canary
• um arquivo de configuração com --config

5. Execute o Pipeline Unificado

nuguard scan \
  --source . \
  --output-dir nuguard-reports

Por padrão, isto executa a geração de SBOM mais a análise estática em uma única passagem. Para incluir validações de política e de red-team, opte por essas etapas e forneça as entradas necessárias:

nuguard scan \
  --source . \
  --steps sbom,analyze,policy,redteam \
  --policy cognitive_policy.md \
  --target http://localhost:3000 \
  --output-dir nuguard-reports

Configuração

O NuGuard oferece suporte à configuração de projeto por meio do nuguard.yaml. Um exemplo pronto para edição está disponível em nuguard.yaml.example.

Principais áreas na configuração de exemplo:

• sbom: caminho do SBOM existente
• source: diretório de origem para geração
• policy: caminho da política cognitiva
• llm: configurações de modelo para recursos assistidos por LLM
• behavior: configurações de URL de destino, endpoint e perfil de teste para testes comportamentais
• redteam: configurações de URL de destino, endpoint, arquivo canário, perfis, filtros de cenário, configurações de conversa guiada e controles de acionamento de descobertas (finding_triggers.*)
• analyze: limite mínimo de severidade
• database: configurações de armazenamento com suporte a SQLite ou Postgres
• output: formato de saída e limite de falha

As flags da CLI têm precedência sobre o nuguard.yaml, que tem precedência sobre as variáveis de ambiente e os padrões internos.

Canários de Red-Team

O NuGuard pode monitorar valores canário pré-inseridos durante testes dinâmicos para produzir descobertas de exfiltração de alta confiança. Comece a partir de canary.example.json, crie seu canary.json local, insira esses valores no sistema de destino e então aponte o nuguard redteam para esse arquivo com --canary.

Mais detalhes estão disponíveis em docs/redteam-engine.md.

Desenvolvimento

Instale as dependências de desenvolvimento:

make dev

Executar testes:

make test

Execute linting e verificação de tipos:

make lint

Formate a base de código:

make fmt

Publicação

Este repositório inclui workflows do GitHub Actions para Trusted Publishing no TestPyPI e no PyPI:

• publish-testpypi.yml
• publish-pypi.yml

Antes que os workflows possam publicar, configure os Trusted Publishers no TestPyPI e no PyPI para o projeto nuguard com:

• owner/org: NuGuardAI
• repositório: nuguard
• arquivo de workflow: publish-testpypi.yml ou publish-pypi.yml
• ambiente: testpypi ou pypi

Fluxo de release recomendado:

1. Execute o workflow do TestPyPI manualmente a partir do GitHub Actions.
2. Verifique a instalação do pacote e o comportamento da CLI a partir do TestPyPI.
3. Crie um release no GitHub para acionar o workflow de publicação no PyPI.

Verificações de Sanidade Pré-Publicação

Antes de publicar no TestPyPI ou no PyPI, execute a verificação rápida de sanidade multi-app.

Executor único:

bash tests/apps/prepublish-sanity.sh

Este runner executa:

• Uma verificação rápida de fumaça do repositório (nuguard --help mais testes locais críticos)
• Execuções de comportamento em modo dinâmico com o workflow intent_happy_path
• Execuções de redteam com profile: ci
• Portões de artefatos e qualidade (relatórios não vazios, cenários executados diferentes de zero, verificações estritas de origem de endpoint e proteções contra erros de transporte)

Arquivos de configuração de pré-publicação usados pelo runner:

• tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml
• tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml
• tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml