vcsp-guard 1.0.0

Vibe Coding Security Protocol - Security & Quality Guardrails for AI Coding

🛡️ Vibe Coding Security Protocol (VCPS)

Template seguro para desenvolvimento ágil com IA (Vibe Coding). Já vem configurado com Scanner de Segredos, Pentest Lógico, Auditoria de Dependências, Quality Gate e Histórico de Logs.

---

🎯 Para que serve?

No mundo de hoje, com a crescente adoção das Inteligências Artificiais, muitos projetos ganharam um boost na produção e no lançamento de features. Porém, nem todo mundo está preocupado com a manutenção e segurança do próprio código, podendo ficar vulnerável caso não haja um revisor experiente para encontrar brechas que podem ser exploradas por atacantes.

Foi pensando nisso que criei essa ferramenta: ela vai varrer seu código, seja ele criado por IA ou não, em busca dessas potenciais falhas, atuando como uma camada de segurança automatizada.

---

🚀 Como usar este Template

Opção A: Começando do Zero (Recomendado)

1. Clique no botão verde "Use this template" (topo da página).
2. Selecione "Create a new repository".
3. Crie seu projeto.

Opção B: Em Projeto Já Existente

1. Baixe este repositório (ZIP ou Clone).
2. Copie a pasta src/vcsp_guard para o seu projeto (ou instale via pip).
3. Certifique-se de ter o Python 3.10+ instalado.

2. Ativar a Proteção (Obrigatório para ambos os casos)

O Git, por padrão, não baixa scripts de automação (Hooks) por motivos de segurança. Portanto, você precisa rodar este script para "ligar" a proteção na sua máquina.

O que o install_hooks.py faz?

1. Instala o Pre-Commit Hook: Cria um arquivo oculto em .git/hooks/ que intercepta todo comando git commit.
2. Configura o Ambiente: Verifica se você tem as ferramentas de auditoria (Bandit, Ruff, Pip-Audit) e as instala se necessário.
3. Limpa Conflitos: Remove arquivos de exemplo duplicados que possam causar erros.

🤖 O Menu de Seleção de IA: Durante a execução, o script perguntará qual IA você utiliza (Cursor, Cline, etc.).

• Para que serve? Ele copia automaticamente os arquivos de configuração (ex: .cursorrules) da pasta .vibe/ para a raiz.
• Por que isso importa? Isso "ensina" sua IA a gerar código seguro desde o início, evitando que o Guardião bloqueie seus commits depois.

No terminal, na raiz do projeto, rode:

python src/vcsp_guard/install_hooks.py

✅ Pronto! Hooks ativados e ferramentas instaladas (Bandit, Pip-Audit, Ruff).

3. Configurar Ambiente

cp .env.example .env
# Edite o .env com suas chaves (ele já é ignorado pelo Git)

---

🤖 Automação de IA (Magic Files)

As configurações de IA e CI/CD estão organizadas na pasta .vibe/ para manter a raiz limpa. Se você rodou o install_hooks.py (Passo 2), a configuração da sua IA já foi aplicada automaticamente!

Caso queira trocar de IA ou configurar manualmente, basta rodar novamente o Install_hooks.py, e selecionar a opção correspondente a IA que está usando. Caso queira excluir o arquivo de configuração da raiz, rode o install_hooks.py e selecione a opção 99 para limpar os arquivos da raiz.

Ferramenta	Arquivo (em .vibe/)	Função
Cursor	.cursorrules	Regras de segurança e estilo.
Cline	.clinerules	Agente autônomo com foco em qualidade.
Qodo Gen	.codiumai.toml	Testes focados em falhas e edge cases.
Copilot	.github/...	Instruções globais.
Gemini	GEMINI.md	Prompt otimizado para Google AI Studio / Vertex AI.
GitHub	.github/workflows	CI/CD Pipeline.

🧠 ChatGPT, Perplexity & Claude

Para IAs de chat que não aceitam arquivos de configuração (como ChatGPT ou Perplexity), copie o conteúdo de .vibe/AUDITORIA_IA.md (System Prompt) e cole no início da conversa.

Isso garante que a IA siga as mesmas regras de segurança e estilo do restante do projeto.

---

⚡ O Fluxo de Trabalho (Vibe Coding)

Como este kit protege você enquanto a IA codifica?

1. Você pede: "Crie uma conexão com o banco AWS." (no Cursor/Copilot/ChatGPT).
2. A IA gera: Um código funcional, mas coloca a AWS_ACCESS_KEY direto no arquivo python.
3. Você commita: git commit -m "add db connection"
4. O Guardião Atua: O hook (instalado no passo 2) intercepta o commit antes dele ser salvo.
5. Bloqueio: O terminal exibe: ❌ [BLOQUEADO] AWS Access Key encontrada.
6. Correção: Você move a chave para o .env (como deve ser) e tenta de novo.

Resultado: Você codifica na velocidade da IA, mas com a segurança de um sênior revisando cada linha em tempo real.

---

🕵️ Varredura e Histórico (Scanner)

Para que serve o scan_project.py? Enquanto o install_hooks.py protege o futuro (novos commits), o scan_project.py protege o passado. Ele serve para varrer todo o código que já existe no projeto em busca de vulnerabilidades antigas que passaram despercebidas.

O script scan_project.py executa 4 camadas de verificação e salva tudo na pasta logs/:

1. 🔐 Segredos: Busca por chaves vazadas no código.
2. 🔫 Pentest (Bandit): Busca por falhas de lógica e injeção.
3. 📦 SCA (Pip Audit): Busca por bibliotecas desatualizadas/vulneráveis.
4. 🧹 Linter (Ruff): Busca por bugs, variáveis não usadas e código sujo.

Para rodar a auditoria:

python src/vcsp_guard/scan_project.py

📂 Confira seu progresso: Abra a pasta logs/ para ver o histórico de correções e garantir que você não está repetindo erros antigos.

📅 Relatório Semanal Automático

O VCSP já vem configurado para rodar uma auditoria completa toda segunda-feira às 08:00 UTC via GitHub Actions.

• Objetivo: Gerar um relatório de tudo que foi produzido na semana anterior.
• Benefício: Permite que você revise e corrija dívidas técnicas ou de segurança antes de iniciar o novo ciclo de desenvolvimento.

Nota: Este gráfico ilustra o formato do relatório. Como foi gerado dentro do próprio VCSP (que é um código limpo), ele não apresenta falhas. Ao utilizar esta ferramenta no seu projeto, o gráfico refletirá os dados reais do seu ambiente, variando de acordo com o histórico de cada usuário.

---

🚨 PROTOCOLO DE PÂNICO (Vazamento de Credenciais)

Se você acidentalmente comitou uma chave de API ou senha:

1. REVOGUE a chave imediatamente no painel do fornecedor (AWS, OpenAI, etc).
2. NÃO tente apenas apagar o arquivo e comitar de novo (o histórico do Git mantém o segredo).
3. Rotacione todas as credenciais que possam ter sido expostas.

🔓 Bypass (Ignorar Verificações)

Se o hook bloquear um arquivo legítimo (falso-positivo) ou você precisar forçar um commit urgente:

git commit -m "mensagem" --no-verify

Aviso: Isso desativa todas as verificações de segurança para aquele commit.

---

🤝 Contribuições e Novas IAs

Caso queira sugerir arquivos de configuração para outras IAs, mande um email para [e-mail], ou submeta uma PR solicitando a criação de mais modelos de IA para esse projeto.

---

👨‍💻 Sobre o Mantenedor

Este projeto foi criado e é mantido por Giordano Alves, Desenvolvedor Backend Python especialista em Infraestrutura, Linux e Segurança.

O objetivo deste template é permitir que desenvolvedores usem o poder da IA ("Vibe Coding") sem sacrificar a solidez e a segurança da engenharia de software tradicional.

"Codifique na velocidade da luz, mas com a segurança de um cofre."

---

📦 Instalação via PyPI

Este projeto está disponível como um pacote Python oficial.

1. Instalação: pip install vcsp-guard
2. Inicialização: vcsp-init (Configura os hooks e arquivos no projeto atual)
3. Varredura: vcsp-scan (Roda a auditoria de segurança)