Sistema automatizado de varredura de conformidade para repositórios GitHub, mapeado ao formulário AI-DSRM (AI Data Security and Risk Management). Este projeto garante arquitetura limpa, scans assíncronos e validação via motores de políticas locais, mantendo o controle total da conformidade do lado do servidor sem dependências externas complexas.
A arquitetura moderna foi desenhada pensando na separação clara de papéis e escalabilidade horizontal dos Scanners.
C4Context
title Diagrama de Contexto de Sistema: AI-DSRM Scanner
Person(developer, "Pessoa Desenvolvedora / Security", "Acessa a interface web e responde aos alertas via PR")
System(ai_dsrm, "AI-DSRM Scanner", "O orquestrador responsável por disparar scanners de análise, normalizar resultados e validar as 12 regras do formulário AI-DSRM")
System_Ext(github, "GitHub API / GitHub App", "Plataforma de CI/CD, eventos Push/Pull Request e APIs de configurações do repositório")
System_Ext(jira, "Jira (Opcional)", "Ferramenta externa de rastreio de tickets")
System_Ext(veracode, "Veracode (Opcional)", "Ferramenta SaaS terceira de escaneamento externo")
Rel(developer, ai_dsrm, "Acessa os dashboards consolidados", "HTTPS")
Rel(github, ai_dsrm, "Notifica de Push, recebe Workflows (Webhooks)", "HTTPS")
Rel(ai_dsrm, github, "Fornece status de compliance e remediações (PRs)", "HTTPS (API/GraphQL)")
Rel(ai_dsrm, jira, "Atualizações de incidentes/Abre chamados", "HTTPS")
Rel(ai_dsrm, veracode, "Solicita disparos SAST corporativos", "HTTPS")
C4Container
title Diagrama de Containers: Componentes Internos
Person(developer, "Equipe AppSec", "Gere o modelo compliance usando visualização rica")
System_Boundary(b0, "Platforma AI-DSRM Local Docker") {
Container(frontend, "Dashboard React", "React, Vite, TypeScript", "Visualiza relatórios e gerencia as permissões dos tokens do repositório.")
Container(backend, "API Orchestrator", "Fastify Node.js, TS", "Integra via WebHooks, recebe comandos e enfileira trabalhos de Scan.")
ContainerDb(minio, "MinIO Storage (Evidence)", "Objetos S3 local", "Armazena os relatórios JSON e SARIF não manipulados.")
ContainerDb(postgres, "Relational Store", "PostgreSQL", "Dados estruturados de status, históricos, usuários e meta-dados.")
Container(normalizer, "Normalizer Service", "NodeJS Worker", "Pega relatórios desestruturados brutos e mapeia para SARIF padronizado.")
Container(scanners, "Container Workers", "ZAP / Checkov / Semgrep / Trivy", "Instâncias isoladas responsáveis por executar scans reais do filesystem/código temporário")
Container(opa, "Política (OPA)", "Rego Scripts", "Sabe as 12 políticas da norma. Diz se os dados consolidados passam em cada regra AI-DSRM.")
}
Rel(developer, frontend, "Acompanha status", "RESTful")
Rel(frontend, backend, "Consume API, visualiza SARIFs e painéis", "HTTPS")
Rel(backend, scanners, "Enfileira Jobs em container e dispara", "Docker API/Orchestration")
Rel(scanners, minio, "Entrega Raw Relatory JSON", "HTTPS (S3 Compatible)")
Rel(scanners, normalizer, "Transfere payloads (se standalone)", "HTTPS")
Rel(minio, normalizer, "Busca arquivo e processa", "HTTPS")
Rel(normalizer, opa, "Pede aprovação do modelo traduzido", "HTTPS (Eval)")
Rel(normalizer, postgres, "Confecciona relatório estático final/Histórico", "TCP 5432")
Rel(backend, postgres, "Armazena e Busca", "TCP 5432")
Como os dados fluem durante um evento de inicialização de Scanner até a política de Compliance.
sequenceDiagram
participant GH as GitHub Webhook
participant BE as Backend Orquestrador
participant SC as Scanners (Workers)
participant MN as MinIO S3
participant NO as Normalizer Service
participant OPA as Open Policy Agent
participant DB as PostgresSQL
GH->>BE: POST Event (Push na Main)
BE->>BE: Constrói Payload do Repo (Branch/Token)
BE->>SC: Instanciar Worker com Alvo (Checkov/Semgrep)
Note over SC: Execução local/isolda em Docker
SC-->>MN: Salva JSON SARIF (Raw) em bucket
SC-->>BE: Status = COMPLETED
BE->>NO: Emit Message: Relatório Disponível!
NO->>MN: Leitura S3 Raw Data
NO->>NO: Normaliza os diferentes outputs numa Estrutura Comum
NO->>OPA: Eval policies/dsrm.rego com JSON
OPA-->>NO: Retorna Status das 12 Regras (Pass/Fail)
NO->>DB: Consolida Relatório AI-DSRM Final no DB
NO-->>BE: Resumo Executivo para FrontEnd Ready
ai-dsrm-scanner/
├── README.md # Este arquivo
├── passo-a-passo.md # Guia de inicialização do ambiente e dependências locais
├── docker-compose.yml # Ambiente de desenvolvimento local (Todos os contêineres e mocks)
├── .env.example # Variáveis de ambiente e secrets
├── demo.sh # Script de demonstração test-drive completo offline
│
├── backend/ # API Fastify + TypeScript (Controller de integrações GitHub e Front)
├── scanners/ # Workers conteinerizados das ferramentas reais CLI
│ ├── semgrep/
│ ├── checkov/
│ ├── trivy/
│ ├── zap/
│ └── ... # Modelos Mocks e afins
│
├── policy-engine/ # OPA/Rego Container. Alojando as métricas de validação.
├── normalizer/ # Serviço de Agregação de resultados
├── frontend/ # View em React / Vite
├── database/ # Script SQL e Seeds
└── github-app/ # Material e docs adicionais caso queira cadastrar o WebHook Real
Para desenvolvedores querendo provisionar a stack localmente, siga os passos abaixo ou consulte o guia detalhado em passo-a-passo.md.
- Docker Desktop 4.x+
- Docker Compose v2+
- Git
-
Clonar e Configurar:
git clone <sua-url-do-repositorio> cd IA-Security-Scan-Github cp .env.example .env
-
Subir Ambiente Local:
docker compose up -d
Aguarde cerca de 30 segundos e verifique a saúde da API:
curl http://localhost:4000/health -
Acessar os Serviços:
- Dashboard (Frontend): http://localhost:3001
- API (Swagger Docs): http://localhost:4000/docs
- MinIO Console: http://localhost:9001 (admin / minioadmin)
- OPA Policy Engine: http://localhost:8181
-
Test-Drive (Demo): Execute o script de demonstração automatizado:
chmod +x demo.sh && ./demo.sh
- Acesse: GitHub → Settings → Developer Settings → GitHub Apps → New GitHub App
- Preencha os campos usando o seu IP/Ngrok como callbacks:
- Nome:
AI-DSRM-Scanner-[sua-org] - Homepage / Callback URL:
http://localhost:3000/http://localhost:4000/auth/callback - Webhook:
Aponte pro seu NGROK local porta 4000/webhooks
- Nome:
- Mapeie as Permissões (Read/Write) em PRs, Alerts de Segredos, Branch, Administrations, e Content.
- Alimente seu
.envcom ID, Private Keys Base64 e os Clients ID/Secret. - Desligue e Ligue os Containers Docker para atualizar as variáveis de ambiente.
Nenhuma política fica "chumbada" (hardcoded) no TypeScript. As diretivas são validadas na linguagem Rego rodando num Sandbox OPA:
| # | Controle (Norma AI) | Motor do Scanner (Alvo) | Regra OPA no Registry |
|---|---|---|---|
| 1 | Repositório sob controle de versão | GitHub API Native | version_control |
| 2 | Workflow SAST presente | GitHub Actions / Veracode | sast_workflow |
| 3 | Varredura de segredos ativa | TruffleHog / Git API | secret_scanning |
| 4 | Armazenamento IaC público | Checkov (Terraform/Kubernetes) | iac_public_storage |
| 5 | Vulnerabilidades em containers | Trivy (A partir da imagem deploy) | container_vulns |
| 6 | Detecção de bibliotecas RAG | Semgrep Regex Custom | rag_libs_detection |
| 7 | Exportadores de logging visíveis | Semgrep Regex Custom | logging_exporters |
| 8 | Autenticação em APIs e Tokens | Semgrep / ZAP | api_auth_detection |
| 9 | Proteção de branch (Push Protection) | GitHub API Native | branch_protection |
| 10 | Dependabot habilitado | GitHub API Native | dependabot_enabled |
| 11 | Code scanning default habilitado | GitHub API Native | code_scanning |
| 12 | Revisão de código obrigatória (Pull Request) | GitHub API Native | required_reviews |
Sistemas locais guardam credenciais temporárias, mas em ambientes de Cloud, prefira injeção de segredos via Vaults (para proteger chaves do App do Github, a JWT Master, ou API dos Scanners).
A classe services/secrets.service.ts do framework em Node já vem equipada para aceitar conectores como AWS Secrets Manager e/ou Azure Key Vault.