repositório de código aberto para validar aplicações de IA agêntica: redteam, comportamento, cadeia de suprimentos, análise estática
# 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:** ```bash 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. ```bash uv sync --dev ``` Execute a CLI com: ```bash uv run nuguard --help ``` Ou, a partir do ambiente virtual: ```bash . .venv/bin/activate nuguard --help ``` ### Usuários do Claude podem usar comandos de plugin. Siga as instruções em [docs/plugin-guide.md](https://github.com/nuguardai/nuguard/blob/develop/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 ```bash nuguard sbom generate --source . --output app.sbom.json ``` Também é possível escanear um repositório remoto: ```bash nuguard sbom generate \ --from-repo https://github.com/org/repo \ --ref main \ --output app.sbom.json ``` ### 2. Executar Análise Estática ```bash 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 ```bash nuguard behavior \ --sbom app.sbom.json \ --target http://localhost:3000 \ --format markdown ``` ### 4. Faça Red-Team em um Aplicativo ao Vivo ```bash 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 ```bash 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: ```bash 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`](https://github.com/nuguardai/nuguard/blob/develop/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`](https://github.com/nuguardai/nuguard/blob/develop/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`](https://github.com/nuguardai/nuguard/blob/develop/docs/redteam-engine.md). ## Desenvolvimento Instale as dependências de desenvolvimento: ```bash make dev ``` Executar testes: ```bash make test ``` Execute linting e verificação de tipos: ```bash make lint ``` Formate a base de código: ```bash make fmt ``` ## Publicação Este repositório inclui workflows do GitHub Actions para Trusted Publishing no TestPyPI e no PyPI: - [publish-testpypi.yml](https://github.com/nuguardai/nuguard/blob/develop/.github/workflows/publish-testpypi.yml) - [publish-pypi.yml](https://github.com/nuguardai/nuguard/blob/develop/.github/workflows/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 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` Executar manualmente por aplicativo (se necessário): ```bash # OpenAI CS agents demo uv run nuguard sbom generate --config tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml --format json -o tests/apps/openai-cs-agents-demo/openai-cs.sbom.json uv run nuguard behavior --config tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml --mode dynamic --format json --format markdown --output tests/apps/openai-cs-agents-demo/reports/openai-cs-prepublish-behavior --verbose uv run nuguard redteam --config tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml --format json --format markdown --output tests/apps/openai-cs-agents-demo/reports/openai-cs-prepublish-redteam --verbose # Gemini Auto app uv run nuguard sbom generate --config tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml --format json -o tests/apps/Gemini-Auto-app/gemini-auto.sbom.json uv run nuguard behavior --config tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml --mode dynamic --format json --format markdown --output tests/apps/Gemini-Auto-app/reports/gemini-auto-prepublish-behavior --verbose uv run nuguard redteam --config tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml --format json --format markdown --output tests/apps/Gemini-Auto-app/reports/gemini-auto-prepublish-redteam --verbose # Pinnacle Bank app uv run nuguard sbom generate --config tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml --format json -o tests/apps/pinnacle-bank-app/pinnacle-bank.sbom.json uv run nuguard behavior --config tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml --mode dynamic --format json --format markdown --output tests/apps/pinnacle-bank-app/reports/pinnacle-bank-prepublish-behavior --verbose uv run nuguard redteam --config tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml --format json --format markdown --output tests/apps/pinnacle-bank-app/reports/pinnacle-bank-prepublish-redteam --verbose ``` Importante: - Não use `|| true` em execuções de publicação com bloqueio. - O código de saída `2` pode indicar achados ou bloqueios de política; trate-o como um sinal e baseie-se nas verificações de qualidade do relatório para decidir aprovação/reprovação. ## Notas do Repositório - O repositório atualmente contém saídas de exemplo e fixtures de benchmark em `tests/output/` - Alguns testes de red-team e de benchmark são opcionais e controlados por variáveis de ambiente - Os recursos assistidos por LLM dependem de credenciais de provedor disponíveis por meio de variáveis de ambiente ## Licença As informações de licença estão disponíveis no arquivo [LICENSE](https://github.com/nuguardai/nuguard/blob/develop/LICENSE).