centisgood/duo-agentflow-auditorSegurança de Código com IA — quatro agentes que captam o que o SAST perde em código gerado por IA. Construído no GitLab Duo Agent Platform.
40-62% do código gerado por IA contém vulnerabilidades de segurança. O SAST tradicional captura CVEs. Nós capturamos o que o SAST não vê — injeção de prompt, execução de saída de LLM, desserialização insegura de ML.
A IA acelera a geração de código, mas cria novos gargalos de segurança:
| Problema | Impacto |
|---|---|
| Revisões de segurança bloqueiam MRs por horas ou dias | 7 horas/semana perdidas por membro da equipe |
| A IA dificulta o gerenciamento de conformidade | 70% das equipes relatam isso |
| Problemas de conformidade descobertos após a implantação | 76% das organizações |
| Ferramentas SAST tradicionais perdem riscos específicos de IA | Injeção de prompt, output-to-exec, desserialização insegura de ML |
| 40-62% do código gerado por IA contém vulnerabilidades | Nenhuma ferramenta existente detecta padrões de ameaça específicos de IA |
Fonte: Relatório Global DevSecOps do GitLab 2025
AgentFlow Auditor — Quatro agentes de IA que capturam riscos de segurança que o SAST tradicional perde em código gerado por IA. 41 regras de detecção incluindo injeção de prompt de LLM, output-to-exec, desserialização insegura, injeção SQL, SSRF e path traversal. Publica relatórios escaneáveis, gera patches de correção, monitora desvio de risco. Uma @menção aciona tudo.
Developer opens MR │ ▼ @duo-agentflow-auditor review this MR │ ▼ ┌───────────────────────────────────────────────────────┐ │ │ │ ┌─────────────┐ ┌──────────────────┐ │ │ │ Scanner │──────▶│ Reporter │ │ │ │ Agent │ │ Agent │ │ │ │ │ │ │ │ │ │ Read diffs │ │ Grade risk │ │ │ │ Match 34 │ │ Risk heatmap │ │ │ │ rules │ │ Post MR comment │ │ │ │ Score risk │ │ Create issue │ │ │ └─────────────┘ └────────┬─────────┘ │ │ │ │ │ ┌───────┴────────┐ │ │ │ SAFE? │ │ │ │ ├─ Yes ──────────────┐ │ │ │ └─ No ───┐ │ │ │ │ └───────────┘ │ │ │ │ │ │ │ │ │ ┌─────────────┐ ┌────────▼───────┘┐ │ │ │ │ Metrics │◀──────│ Fixer │ │ │ │ │ Agent │ │ Agent │ │ │ │ │ │◀──────────────────────────────┘ │ │ │ Baseline │ │ Confidence-scored│ │ │ │ Cross-MR │ │ patches │ │ │ │ Green │ │ Fix branch + MR │ │ │ │ Posture │ │ │ │ │ └─────────────┘ └─────────────────┘ │ │ │ │ GitLab Duo Agent Platform (ambient) │ │ │ │ ┌───────────────────────────────────────────┐ │ │ │ External SAST Agent (CI/CD container) │ │ │ │ bandit + semgrep + custom rules merge │ │ │ └───────────────────────────────────────────┘ │ └───────────────────────────────────────────────────────┘
### Lista de Agentes
| Agente | Função | Ferramentas | Capacidade Chave |
|:------|:-----|:------|:---------------|
| **Scanner** | Analisar diffs de MR | 10 ferramentas | 41 regras (26 regex + 15 Semgrep), deteção de ameaças específicas de IA, integração de vulnerabilidades |
| **Reporter** | Publicar relatórios de auditoria | 7 ferramentas | Scanável em 10s (nota + heatmap + top 5), ligação de vulnerabilidades, criação automática de issue em DANGER |
| **Fixer** | Gerar correções de código | 8 ferramentas | Patches com pontuação de confiança (ALTA/MÉDIA/BAIXA), criação automática de MR de correção |
| **Metrics** | Monitorizar linha de base de risco | 6 ferramentas | Aprendizagem entre MRs, postura da equipa, desvio de linha de base, monitorização de energia/carbono |
| **SAST Scanner** | SAST Externo | CI/CD | Executa bandit + semgrep, combina com regras personalizadas via script Python |
---
## Funcionalidades
<table>
<tr>
<td width="50%">
### Scan de Segurança
- **41 Regras de Deteção** — 26 regex + 15 regras personalizadas Semgrep
- **8 Categorias de Risco** — De comandos destrutivos a injeção de prompts
- **Deteção Específica de IA** — Injeção de prompts em LLM, output para execução, desserialização insegura
- **Pontuação de Risco** — 0-100 por descoberta (gravidade x contexto x categoria)
- **Sistema de Notas** — SAFE / WARNING / DANGER
</td>
<td width="50%">
### Automação
- **Ativação com um gatilho** — @menção ou atribuir revisor
- **Encaminhamento condicional** — Scans SAFE ignoram o fixer, poupando tokens
- **Comentários MR estruturados** — Tabelas de risco, sugestões de correção, detalhes expansíveis
- **Geração automática de correção** — Patches de código num novo branch
- **Criação de issue** — Automática em nota DANGER
</td>
</tr>
<tr>
<td width="50%">
### Monitorização de Linha de Base
- **Deteção de desvio de risco** — Comparar scans ao longo do tempo
- **Análise de tendências** — Melhorando / degradando / estável
- **Taxa de adoção de correções** — Monitorizar quantas sugestões foram aplicadas
- **Registo de histórico** — Anexo JSONL por scan
</td>
<td width="50%">
### Métricas Verdes
- **Monitorização de tokens** — Uso por scan
- **Estimativa de energia** — kWh por scan
- **Pegada de carbono** — kg CO2 com analogias do mundo real
- **Sugestões de otimização** — Reduzir âmbito do scan, baselines em cache
</td>
</tr>
</table>
---
## Categorias de Deteção
### Regras Personalizadas Semgrep
15 regras Semgrep de nível de produção em 6 categorias:
| Regra | Categoria | Severidade | Deteção |
|:-----|:---------|:---------|:----------|
| `llm-prompt-injection` | Segurança IA | AVISO | Entrada do utilizador a fluir para chamadas de API LLM |
| `llm-output-code-exec` | Segurança IA | ERRO | Saída do LLM passada para exec/eval |
| `unsafe-deserialization-ml` | Segurança IA | AVISO | pickle.load, torch.load em modelos não confiáveis |
| `sql-injection` | Segurança Web | ERRO | Consultas SQL formatadas strings (f-string, .format, concat) |
| `path-traversal` | Segurança Web | ERRO | Entrada do utilizador em operações de caminho de ficheiro (../ traversal) |
| `ssrf-request-forgery` | Segurança Web | ERRO | URLs controlados pelo utilizador em pedidos HTTP |
| `open-redirect` | Segurança Web | AVISO | Entrada do utilizador em funções de redirecionamento |
| `missing-input-validation` | Segurança Web | AVISO | Dados de pedido usados sem validação de esquema |
| `dangerous-eval-exec` | Python | AVISO | eval/exec com conteúdo dinâmico |
| `subprocess-shell-true` | Python | AVISO | subprocess com shell=True |
| `dangerous-os-system` | Python | AVISO | os.system/popen (obsoleto) |
| `insecure-random-python` | Criptografia | AVISO | módulo random para tokens de segurança |
| `insecure-random-javascript` | Criptografia | AVISO | Math.random() para tokens de segurança |
| `hardcoded-credentials` | Segredos | AVISO | Palavras-passe, chaves API, tokens codificados |
| `insecure-http` | Rede | INFO | URLs HTTP (com autofix para HTTPS) |
### Categorias de Deteção Regex
| Categoria | Severidade | Exemplos de Padrões |
|:---------|:---------|:-----------------|
| Comandos Destrutivos | 🚨 Perigo | `rm -rf /`, `mkfs`, `dd to disk` |
| Exfiltração de Credenciais | 🚨 Perigo | `curl` a publicar segredos para URLs externos |
| Injeção de Prompt (grave) | 🚨 Perigo | "Ignore instruções anteriores", substituições de função |
| Execução Ofuscada | 🚨 Perigo | `base64 -d \| bash`, pipe remoto para shell |
| Execução de Shell | ⚠️ Aviso | `shell=True`, `eval()`, `exec()`, `os.system()` |
| Chamadas de Rede | ⚠️ Aviso | `curl`/`wget`/`fetch` para URLs externos |
| Transporte Inseguro | ⚠️ Aviso | `http://` onde `https://` deveria ser usado |
| Credenciais Codificadas | ⚠️ Aviso | Palavras-passe, chaves API, tokens no código-fonte |
### Fórmula de Pontuação de Risco```
score = severity_weight + category_weight + executable_context + actionable + risk_modifier
= clamp(0, 100)
severity_weight: danger=50, warning=25
category_weight: destructive-command=15, credential-exfil=15, prompt-injection=10, ...
executable_context: +20 if file is .sh/.py/.js/.ts
actionable: +15 if executable AND not in trusted domain allowlist
risk_modifier: per-rule adjustment (0-15)
| Grau | Condição | Ação |
|---|---|---|
| 🚨 PERIGO | max_risk >= 90 OR high_risk_findings >= 3 | Bloquear merge + criar issue |
| ⚠️ AVISO | max_risk >= 70 OR high_risk_findings >= 1 | Revisar antes do merge |
| ✅ SEGURO | Nenhum sinal de risco significativo | Seguro para merge |
git clone https://gitlab.com/centisgood/duo-agentflow-auditor.git cd duo-agentflow-auditor
> 📖 Guia completo de espelhamento (3 métodos, configuração de CI, estratégias de sincronização): [`docs/GITLAB_MIRROR_GUIDE.md`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/docs/GITLAB_MIRROR_GUIDE.md)
### 2. Agentes e Fluxo Publicam Automaticamente
O grupo do hackathon impõe um [pipeline central de CI](https://gitlab.com/gitlab-ai-hackathon/ci) por meio de [política de segurança](https://gitlab.com/gitlab-ai-hackathon/security-policies). Quando você faz push para o GitLab, o job `catalog-sync` **automaticamente** publica todos os `agents/*.yml` e `flows/*.yml` no Catálogo de IA — sem necessidade de configuração manual ou tags git.
> O `.gitlab-ci.yml` do seu projeto é substituído pelo pipeline central do hackathon. O `.gitlab-ci.yml` incluído serve apenas como referência.
| # | Agente | Arquivo do Catálogo | Documentos de Prompt | Ferramentas |
|---|--------|---------------------|----------------------|-------------|
| 1 | Scanner | [`agents/scanner.yml`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/agents/scanner.yml) | [`agents/scanner.md`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/agents/scanner.md) | 8 ferramentas |
| 2 | Reporter | [`agents/reporter.yml`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/agents/reporter.yml) | [`agents/reporter.md`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/agents/reporter.md) | 6 ferramentas |
| 3 | Fixer | [`agents/fixer.yml`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/agents/fixer.yml) | [`agents/fixer.md`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/agents/fixer.md) | 8 ferramentas |
| 4 | Metrics | [`agents/metrics.yml`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/agents/metrics.yml) | [`agents/metrics.md`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/agents/metrics.md) | 5 ferramentas |
Fluxo: [`flows/security-audit.yml`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/flows/security-audit.yml) — pipeline de 4 agentes com roteamento Scanner → Reporter → Fixer → Metrics.
<details>
<summary>Alternativa: Configuração manual via interface do GitLab</summary>
**Agentes**: Automate → Agents → New agent → cole o prompt do sistema dos arquivos `.md`
**Fluxo**: Automate → Flows → New flow → cole a definição de [`flows/security-audit.yml`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/flows/security-audit.yml)
</details>
### 3. Ativar Gatilhos
| Gatilho | Como |
|---------|------|
| Menção | Comente `@duo-agentflow-auditor` em qualquer MR |
| Atribuir revisor | Atribua a conta de serviço como revisor do MR |
### 4. Experimente```bash
# Create test branch with vulnerable code
git checkout -b test/security-audit
cp examples/vulnerable-mr/* .
git add . && git commit -m "test: add vulnerable code for audit"
git push origin test/security-audit
# Open MR → Comment: @duo-agentflow-auditor please review this MR
Passo a passo detalhado: Veja
docs/SETUP_GUIDE.md
Grade: 🚨 DANGER Recommendation: FAIL — do not merge without fixes
| Risk | File | Findings | Max Score |
|---|---|---|---|
| 🟥🟥🟥🟥🟥 | unsafe_script.py | 5 | 95 |
| 🟥🟥🟥🟧⬜ | risky_config.yaml | 3 | 78 |
| 🟧🟧⬜⬜⬜ | insecure_fetch.js | 2 | 62 |
🚨 unsafe_script.py:55 — rm -rf (95/100) 🚨 unsafe_script.py:13 — shell=True (88/100) 🚨 unsafe_script.py:27 — eval() (85/100) ⚠️ insecure_fetch.js:41 — HTTP (62/100)
### Green Metrics```markdown
### 🌱 Sustainability Report
| Metric | Value |
|---------------------|---------------------|
| Tokens Used | 12,450 |
| Energy | 0.0037 kWh |
| CO₂ Footprint | 0.0014 kg |
| Efficiency | 2.4 findings/1K tok |
💡 LED bulb for 13 seconds | 🚗 Car driving 5.6 meters
duo-agentflow-auditor/ │ ├── agents/ │ ├── scanner.yml # Catalog agent — security scanner │ ├── reporter.yml # Catalog agent — report generator │ ├── fixer.yml # Catalog agent — auto-fix patches │ ├── metrics.yml # Catalog agent — green metrics │ ├── scanner.md # Detailed prompt documentation │ ├── reporter.md # Detailed prompt documentation │ ├── fixer.md # Detailed prompt documentation │ └── metrics.md # Detailed prompt documentation │ ├── flows/ │ └── security-audit.yml # Catalog flow — conditional routing pipeline │ ├── scripts/ │ ├── merge_sast_results.py # SAST result merger (bandit + semgrep + custom rules) │ └── demo.sh # E2E demo automation (glab CLI) │ ├── tests/ │ └── test_merge_sast_results.py # 76 pytest tests — scoring, grading, parsing │ ├── .gitlab/ │ └── duo/ │ └── flows/ │ └── sast-scanner.yaml # External SAST agent (CI/CD container) │ ├── rules/ │ ├── danger_rules.json # 11 high-severity detection patterns │ ├── warning_rules.json # 15 medium-severity detection patterns │ └── semgrep/ # 15 Semgrep custom rules │ ├── ai-security/ # LLM prompt injection, output exec, unsafe deser │ ├── web-security/ # SQL injection, path traversal, SSRF, open redirect, input validation │ ├── python-security/ # eval/exec, subprocess, os.system │ ├── crypto/ # Insecure random (Python + JavaScript) │ ├── secrets/ # Hardcoded credentials │ └── network/ # Insecure HTTP (with autofix) │ ├── Dockerfile # Production SAST container (python:3.11-slim) ├── requirements.txt # bandit + semgrep dependencies │ ├── examples/ │ ├── vulnerable-mr/ # Intentionally risky code (demo) │ │ ├── unsafe_script.py # shell=True, eval(), rm -rf, cred leak │ │ ├── risky_config.yaml # Prompt injection, hardcoded secrets │ │ └── insecure_fetch.js # HTTP, exec(), token exposure │ └── safe-mr/ # Secure code for contrast (demo) │ ├── safe_script.py │ ├── safe_config.yaml │ └── safe_script.js # HTTPS, execFile, env vars │ ├── docs/ │ ├── SETUP_GUIDE.md # Step-by-step setup │ ├── EXECUTION_PLAN.md # Implementation plan │ ├── WOW_MOMENTS.md # Visual impact & demo choreography │ ├── DEVPOST_SUBMISSION.md # Devpost submission draft │ └── GITLAB_MIRROR_GUIDE.md # GitHub → GitLab mirroring │ ├── .gitlab-ci.yml # CI — catalog-sync + validation ├── AGENTS.md # Project-level agent customization ├── IMPLEMENTATION.md # Architecture & design document ├── CONTRIBUTING.md # Contribution guidelines ├── LICENSE # MIT License └── README.md # This file
---
## Tecnologia
| Componente | Tecnologia |
|:----------|:-----------|
| **Plataforma** | GitLab Duo Agent Platform (GA no GitLab 18.8) |
| **Modelo de IA** | Anthropic Claude Sonnet |
| **Esquema de Fluxo** | Flow Registry v1 (ambiente `ambient`) |
| **Gatilhos** | Mencionar, Atribuir, Atribuir Revisor |
| **Ferramentas do Agente** | Mais de 30 ferramentas integradas do GitLab em 4 agentes (incluindo vinculação de vulnerabilidade) |
| **Detecção** | 41 regras: 26 regex + 15 Semgrep (segurança de IA, segurança web, criptografia, segredos, rede) |
| **SAST Externo** | Dockerized bandit + semgrep pipeline with result merger |
| **Testes** | 76 testes pytest cobrindo pontuação, classificação e análise |
| **Saída** | Comentários MR em Markdown, Issues do GitLab, Fix MRs |
---
## Documentação
| Documento | Descrição |
|:---------|:-----------|
| [`IMPLEMENTATION.md`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/IMPLEMENTATION.md) | Arquitetura, fórmula de pontuação, script de demonstração, alinhamento de julgamento |
| [`docs/SETUP_GUIDE.md`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/docs/SETUP_GUIDE.md) | Passo a passo de 7 etapas com solução de problemas |
| [`docs/EXECUTION_PLAN.md`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/docs/EXECUTION_PLAN.md) | Plano de 6 fases com aproximadamente 35 tarefas granulares |
| [`docs/WOW_MOMENTS.md`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/docs/WOW_MOMENTS.md) | Design de impacto visual e coreografia de demonstração |
| [`docs/DEVPOST_SUBMISSION.md`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/docs/DEVPOST_SUBMISSION.md) | Texto do formulário de submissão para copiar e colar |
| [`AGENTS.md`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/AGENTS.md) | Personalização de varredura no nível do projeto |
| [`docs/GITLAB_MIRROR_GUIDE.md`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/docs/GITLAB_MIRROR_GUIDE.md) | Espelhamento GitHub → GitLab (3 métodos) |
| [`CONTRIBUTING.md`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/CONTRIBUTING.md) | Como contribuir |
---
## Testes```bash
# Run the full test suite (76 tests)
python -m pytest tests/ -v
# Run with coverage
python -m pytest tests/ --cov=scripts --cov-report=term-missing
Testes abrangem: carregamento de JSON, análise de regras, normalização de gravidade/categoria, fórmula de pontuação de risco, classificação de nota, análise de saída do bandit/semgrep, deduplicação de achados e ponto de entrada da CLI.
scripts/demo.sh
scripts/demo.sh --gitlab-remote origin
scripts/demo.sh --cleanup
O script de demonstração cria um MR de teste com código vulnerável, aciona o auditor via `@mention` e consulta os resultados.
---
## Contribuindo
Veja [`CONTRIBUTING.md`](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/CONTRIBUTING.md) para diretrizes.
**Resumo rápido:**
1. Faça um fork do repositório
2. Crie um branch de funcionalidade (`git checkout -b feature/amazing`)
3. Faça commit das alterações (`git commit -m 'feat: add amazing feature'`)
4. Envie para o branch (`git push origin feature/amazing`)
5. Abra um Merge Request
---
## O Paradoxo da IA — Por que Isso é Importante
<div align="center">
| Sem o AgentFlow Auditor | Com o AgentFlow Auditor |
|:--------------------------|:----------------------|
| MR espera 2+ dias por revisão | **45 segundos** para auditoria completa |
| SAST perde riscos específicos de IA | **41 regras** incl. 3 específicas de IA + 7 ameaças de segurança web |
| Nenhuma sugestão de correção | **Correções com pontuação de confiança** (ALTA/MÉDIA/BAIXA) |
| Verificações SAFE desperdiçam tokens de correção | **Roteamento condicional** pula corretor |
| Sem rastreamento ao longo do tempo | **Aprendizado entre MRs** + postura da equipe |
| Sem consciência energética | **Métricas verdes** por verificação |
</div>
---
## Licença
Este projeto está licenciado sob a [Licença MIT](https://gitlab.com/centisgood/duo-agentflow-auditor/-/blob/main/LICENSE).
---
<div align="center">
**Um Gatilho. Quatro Agentes. Zero Pontos Cegos de IA.**
Construído com a [Plataforma de Agentes GitLab Duo](https://docs.gitlab.com/user/duo_agent_platform/) e [Anthropic Claude](https://www.anthropic.com/)
</div>