Metadata-Version: 2.4
Name: vcsp-guard
Version: 1.0.1
Summary: Vibe Coding Security Protocol - Security & Quality Guardrails for AI Coding
Author-email: Giordano Alves <giordano.alves9@gmail.com>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bandit
Requires-Dist: pip-audit
Requires-Dist: ruff
Requires-Dist: matplotlib
Requires-Dist: pandas
Requires-Dist: pytest
Dynamic: license-file

# 🛡️ Vibe Coding Security Protocol (VCPS)

![CI Status](https://github.com/Giordano10/VCSP/actions/workflows/security_scan.yml/badge.svg)
![Latest Release](https://img.shields.io/github/v/release/Giordano10/VCSP)
![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Security](https://img.shields.io/badge/security-bandit%20%7C%20pip--audit-red)

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:

```bash
python src/vcsp_guard/install_hooks.py
```

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

### 3. Configurar Ambiente
```bash
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:
```bash
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.

![Bug Trend](.vibe/assets/bug_trend.png)

> **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:

```bash
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 **giordano.alves9@gmail.com**, 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)

---

## 🚀 Como Lançar Novas Versões (Mantenedores)

Para manter GitHub e PyPI sempre sincronizados, siga este fluxo:

1.  **Crie uma Release no GitHub:**
    *   Crie uma nova tag (ex: `v1.1.0`).
    *   Publique a release.
2.  **Automação:** O GitHub Actions detectará a tag, ajustará a versão no código e publicará no PyPI automaticamente.
3.  **Sincronização:** Se a versão já existir no PyPI (ex: você subiu manualmente), o workflow apenas registrará o sucesso no GitHub, mantendo tudo alinhado.
