🔐 GitHub Security Audit Tool

Ferramenta completa para auditoria e compliance de security.yml em organizações GitHub Enterprise.

🎯 Funcionalidades

✅ Auditoria Completa

Varre todas as organizações e repositórios
Analisa conteúdo dos arquivos security.yml
Valida templates e configurações
Gera relatórios detalhados (CSV, JSON, HTML)

✅ Análise de Compliance

Score de conformidade (0-100%)
Validação de templates Foundation
Verificação de secrets obrigatórios
Detecção de versões desatualizadas

✅ Relatórios Executivos

Dashboard HTML interativo
Estatísticas por organização
Problemas mais comuns

✅ Remediação Automática

Scripts de correção
Templates padronizados
Criação automática de security.yml

📁 Estrutura do Projeto

🏗️ Organização Modular

scripts/
├── core/                           # Scripts principais
│   ├── run-audit.sh               # Auditoria produção (lê config.json)
│   └── test-audit.sh              # Auditoria teste (acme-foundation)
├── workflows/                      # Análise de workflows
│   ├── security-report.js         # Relatórios específicos security.yml
│   └── actions-analysis.js        # Análise completa GitHub Actions
└── automation/                     # Automação organizacional
    ├── enforce-policies.js        # Políticas e restrições
    └── org-workflows.yml          # GitHub Actions organizacionais
docs/
└── DEV-GUIDE-TEMPLATE.md          # 📖 Guia para desenvolvedores

🚀 Instalação e Uso

Pré-requisitos

Node.js 18+
Token GitHub com permissões de leitura nas organizações
Acesso ao GitHub Enterprise

Setup Rápido

# 1. Instalar dependências
npm install

# 2. Configurar dados da empresa
cp config.example.json config.json
# Edite config.json com seus dados reais

# 3. Executar auditoria (modo fácil)
./scripts/core/run-audit.sh

# OU executar manualmente
npm run audit -- audit --token SEU_TOKEN --github-url https://github.empresa.com

Comandos Disponíveis

📊 Auditoria Completa

npm run audit -- audit \
  --token ghp_xxxxxxxxxxxx \
  --github-url https://github.empresa.com \
  --orgs "org1,org2,org3" \
  --generate-html \
  --generate-remediation

🔐 Verificar Permissões

npm run audit -- check-permissions \
  --token ghp_xxxxxxxxxxxx \
  --github-url https://github.empresa.com

📋 Arquitetura do Projeto

🏗️ Ambiente

GitHub: Enterprise
Organizações: 8
Repositórios: ~300 total
SonarQube: Instância centralizada
Linguagem: TypeScript + Node.js

📁 Estrutura

src/
├── types/           # Tipos TypeScript
├── services/        # Serviços principais
│   ├── GitHubClient.ts      # Cliente GitHub API
│   ├── AuditService.ts      # Lógica de auditoria
│   └── ReportService.ts     # Geração de relatórios
├── audit.ts         # CLI principal
└── index.ts         # Entry point

templates/
└── security.yml     # Template otimizado

reports/             # Relatórios gerados

📊 Relatórios Gerados

CSV: Dados detalhados para análise
JSON: Resumo estruturado
HTML: Dashboard executivo
Shell Script: Remediação automática

🛡️ Template Security.yml

O projeto inclui template otimizado com:

✅ Versionamento adequado (@v1.0.0)
✅ Branches padrão (main, master, staging, develop)
✅ Triggers corretos (push, PR, manual)
✅ Tratamento de erros
✅ Segurança para forks externos
✅ Fallback para análises básicas

🧪 Teste Rápido

Teste o projeto com a organização acme-foundation (GitHub.com público):

# 1. Configure seu token GitHub
export GITHUB_TOKEN=ghp_seu_token

# 2. Auditoria completa de teste
./scripts/core/test-audit.sh

🎯 GUIA COMPLETO: AUTOMATIZAÇÃO DE POLÍTICAS GITHUB

Vou explicar passo a passo, de forma super didática, como automatizar o uso obrigatório do template security.yml em toda sua organização.

📚 PARTE 1: ENTENDENDO O PROBLEMA

🔍 Situação Atual (Descoberta pela Auditoria):

📊 Status da organização acme-foundation:
- Total de repositórios: 18
- ✅ Com security.yml: 3 (16.7%)
- ❌ Sem security.yml: 15 (83.3%)
- 🎯 Meta: 100% compliance

💡 Por que automatizar?

Segurança: Garante que TODOS os repositórios tenham scans de segurança
Consistência: Padroniza workflows em toda organização
Eficiência: Evita trabalho manual repetitivo
Compliance: Atende auditoria automaticamente

🚀 PARTE 2: ESTRATÉGIAS DE AUTOMAÇÃO

📋 Estratégia 1: MONITORAR criação de repositórios

✅ ABORDAGEM: Permitir criação livre + monitoramento automático
✅ VANTAGEM: Flexibilidade para desenvolvedores + compliance garantido
✅ COMO: GitHub Actions organizacional que detecta repos sem security.yml
✅ RESULTADO: Repos são automaticamente corrigidos em minutos

📋 Estratégia 2: OBRIGAR security.yml em repositórios existentes

✅ Como: Branch Protection Rules
✅ Onde: Configuração de cada repositório
✅ Resultado: PRs são bloqueados se não tiver security.yml

📋 Estratégia 3: MONITORAR e CORRIGIR automaticamente

✅ Como: GitHub Actions organizacional
✅ Onde: Repositório .github da organização
✅ Resultado: Sistema cria PRs automaticamente com security.yml

📋 Estratégia 4: GUIA para desenvolvedores + template sugerido

📖 ABORDAGEM: Documentação clara sobre uso obrigatório de templates
✅ COMO: Guia passo a passo para desenvolvedores (ver docs/DEV-GUIDE-TEMPLATE.md)
🤖 BACKUP: Monitoramento automático corrige repos criados incorretamente
✅ RESULTADO: Desenvolvedores sabem como fazer + sistema corrige automaticamente

🛠️ PARTE 3: IMPLEMENTAÇÃO PASSO A PASSO

🎯 PASSO 1: PREPARAÇÃO (5 minutos)

1.1 Verifique seus acessos:

# Teste se seu token funciona
export GITHUB_TOKEN=ghp_seu_token_aqui
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user

1.2 Instale dependências:

# Se ainda não fez
npm install @octokit/rest

1.3 Teste a auditoria atual:

# Veja o estado atual
./scripts/core/test-audit.sh

Resultado esperado: Relatório mostrando compliance baixo (16.7%)

🔍 PASSO 2: VERIFICAR CONFIGURAÇÕES ATUAIS (1 minuto)

2.1 O que isso faz:

📋 VERIFICAÇÃO: Analisa configurações atuais da organização sem alterar
✅ FLEXIBILIDADE: Mantém criação livre para desenvolvedores
🤖 GARANTIA: Monitoramento automático corrige repos sem security.yml

2.2 Como executar:

# Execute o script de verificação
node scripts/automation/enforce-policies.js acme-foundation

2.3 O que acontece por baixo dos panos:

// O script apenas VERIFICA (não altera):
const { data: orgData } = await octokit.orgs.get({ org });
console.log(`Membros podem criar repos: ${orgData.members_can_create_repositories}`);
// Mantém configurações atuais + adiciona monitoramento

2.4 Vantagens desta abordagem:

✅ FLEXIBILIDADE: Desenvolvedores podem criar repos livremente
✅ VELOCIDADE: Não precisa aguardar DevOps para criar projeto
✅ COMPLIANCE: Monitoramento automático garante security.yml
✅ CORREÇÃO RÁPIDA: Repos são corrigidos em minutos automaticamente

🛡️ PASSO 3: CONFIGURAR PROTEÇÃO DE BRANCHES (10 minutos)

3.1 O que isso faz:

❌ Antes: Pode fazer merge sem security scan
✅ Depois: Merge só é permitido SE o security scan passar

3.2 Como funciona:

O script configura automaticamente em TODOS os 18 repositórios:

Branch Protection Rules:
- Branch: main (ou master)
- Required status checks:
  - "security-scan" ✅ OBRIGATÓRIO
  - "Security Analysis" ✅ OBRIGATÓRIO
- Required reviews: 1 pessoa deve aprovar
- Enforce for admins: false (DevOps pode bypasser emergências)

3.3 Execução automática:

# Já incluído no comando anterior, mas pode rodar separado:
node -e "
const PolicyEnforcer = require('./scripts/automation/enforce-policies.js');
const enforcer = new PolicyEnforcer(process.env.GITHUB_TOKEN);
enforcer.enforceBranchProtection('acme-foundation');
"

3.4 Como verificar:

Vá em qualquer repositório: https://github.com/acme-foundation/REPO_NAME/settings/branches
Deve mostrar: "Require status checks to pass before merging" ✅
Lista deve incluir: security-scan e Security Analysis

🤖 PASSO 4: GITHUB ACTION ORGANIZACIONAL (5 minutos)

4.1 O que isso faz:

Cria um "robô" que monitora todos os repositórios e:

✅ Verifica se security.yml existe
✅ Valida se usa o template correto
✅ Cria PR automaticamente se estiver faltando
❌ Falha o build se não estiver conforme

4.2 Como implementar:

Opção A: Via GitHub Web (Manual)

Vá para https://github.com/acme-foundation/.github
Se não existe, crie o repositório .github
Crie arquivo .github/workflows/organization-security-policy.yml
Cole o conteúdo de scripts/automation/org-workflows.yml

Opção B: Via Script (Automático)

# O script já faz isso automaticamente
node scripts/automation/enforce-policies.js acme-foundation

4.3 Como funciona por dentro:

# A GitHub Action verifica AUTOMATICAMENTE:
on:
  push:        # A cada commit
  pull_request: # A cada PR
  schedule:    # Diariamente às 2:00 AM

# Faz essas verificações:
- name: Check Security.yml Exists
  run: |
    if [ ! -f ".github/workflows/security.yml" ]; then
      echo "❌ security.yml not found!"
      exit 1  # FALHA O BUILD
    fi

4.4 Como verificar:

Faça um commit em qualquer repositório SEM security.yml
O build deve FALHAR automaticamente
Você verá: ❌ "Repository is not compliant with organization security policy"

🏗️ PASSO 5: TEMPLATE OBRIGATÓRIO (10 minutos)

5.1 O que isso faz:

Cria um "modelo" que TODO repositório novo deve usar, garantindo que:

✅ security.yml já vem incluído
✅ CI/CD básico configurado
✅ README com instruções de compliance
✅ Branch protection pré-configurado

5.2 Como criar:

# Execute o script
# Manual: Siga docs/DEV-GUIDE-TEMPLATE.md para criar template

5.3 O que o script faz:

# 1. Cria repositório template
gh repo create acme-foundation/acme-foundation-secure-template --template

# 2. Adiciona security.yml OBRIGATÓRIO
mkdir -p .github/workflows
cat > .github/workflows/security.yml << 'EOF'
# Template com security.yml já configurado
EOF

# 3. Adiciona CI básico
# 4. Adiciona README explicativo
# 5. Configura proteções

5.4 Como usar o template:

# Agora DevOps cria novos repos assim:
gh repo create meu-novo-projeto \
  --template acme-foundation/acme-foundation-secure-template \
  --private

5.5 Como verificar:

Vá para https://github.com/acme-foundation/acme-foundation-secure-template
Deve mostrar: 🏷️ "Template repository"
Deve ter .github/workflows/security.yml presente

🧪 PARTE 4: TESTANDO SE FUNCIONOU

🎯 TESTE 1: Auditoria Completa

# Execute nova auditoria
./scripts/core/test-audit.sh

# Resultado esperado:
# Compliance rate: 100% (ou próximo)
# Todos os repos com security.yml

🎯 TESTE 2: Tentativa de Criação de Repo

# Tente criar repo sem permissão (deve falhar)
gh repo create teste-sem-permissao

# Resultado esperado:
# ❌ Error: Insufficient permissions

🎯 TESTE 3: PR sem Security.yml

Remova .github/workflows/security.yml de um repositório
Faça commit e push
Resultado esperado: ❌ Build deve falhar automaticamente

🎯 TESTE 4: Criação com Template

# Crie novo repo com template (deve funcionar)
gh repo create projeto-teste \
  --template acme-foundation/acme-foundation-secure-template

# Resultado esperado:
# ✅ Repo criado com security.yml incluído

📊 PARTE 5: MONITORAMENTO CONTÍNUO

📈 Dashboard de Compliance

# Execute auditoria mensalmente
./scripts/core/test-audit.sh

# Monitore métricas:
# - Compliance rate (meta: >95%)
# - Repositórios não conformes
# - Tempo para correção

🔔 Alertas Automáticos

O sistema enviará alertas quando:

✅ Novo repositório é criado (via webhook)
❌ Repository fica não conforme
🔄 PR é criado automaticamente para correção

🎉 RESULTADO FINAL

✅ Antes vs Depois:

Métrica	🔴 Antes	🟢 Depois
Compliance	16.7%	100%
Novos repos	Sem security.yml	Sempre com security.yml
PRs perigosos	Passam sem scan	❌ Bloqueados
Criação repos	❌ Sem monitoramento	✅ Livre + correção automática
Monitoramento	Manual	Automático 24/7

🚀 Benefícios Alcançados:

🔒 Segurança: 100% dos repositórios com scan obrigatório
⚡ Velocidade: Novos projetos já nascem seguros
🎯 Compliance: Auditoria sempre aprovada
🤖 Automação: Sistema se auto-corrige
📊 Visibilidade: Dashboard executivo sempre atualizado

🛟 ROLLBACK (SE PRECISAR)

Se algo der errado, você pode reverter:

# Desativar monitoramento automático (se necessário)
# 1. Remover GitHub Actions organizacionais
# 2. Desabilitar webhooks de compliance

# Remover branch protection (se necessário)
# Desativar GitHub Actions organizacionais

🎯 EXECUTAR TUDO AGORA:

Pronto para implementar? Execute este comando único:

# 🚀 AUTOMAÇÃO COMPLETA EM 1 COMANDO:
export GITHUB_TOKEN=ghp_seu_token && \
node scripts/automation/enforce-policies.js acme-foundation && \
# Manual: Siga docs/DEV-GUIDE-TEMPLATE.md para criar template && \
./scripts/core/test-audit.sh

Em 15 minutos você terá 100% de compliance automatizado! 🎉

🔧 Próximas Implementações

Etapa 1: Auditoria e relatórios
Etapa 2: Automação de políticas GitHub
Etapa 3: Integração com Backstage
Etapa 4: Monitoramento contínuo
Bonus: Dashboard web em tempo real

📝 Observações Importantes

⚠️ Configure o token com permissões adequadas (public_repo, read:org) ⚠️ Teste primeiro com organização pública antes do seu ambiente ⚠️ Substitua organizações nos arquivos para produção ⚠️ Backup das configurações antes de alterações

Desenvolvido em TypeScript para máxima qualidade e manutenibilidade 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.claude		.claude
docs		docs
examples		examples
scripts		scripts
src		src
templates		templates
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md
README_SUGGESTED_CLAUDE.md		README_SUGGESTED_CLAUDE.md
config.example.json		config.example.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation