Aponte para uma pasta. O CodeVault faz uma varredura estrutural, encontra vulnerabilidades e vazamentos, mostra onde está o erro e como corrigir — sem nunca executar o seu código.
⚠️ Status honesto: o CodeVault está em fase alpha (v0.1.0-alpha1). A base do pacote está pronta; o núcleo de análise está em construção conforme o roadmap. Este README descreve a visão do produto e o que já existe vs. o que está planejado — sem alegar recursos ainda não implementados.
À medida que mais código passa a ser escrito por assistentes de IA, cresce um problema: esse código costuma conter falhas de segurança que passam despercebidas — injeções, segredos embutidos, dependências perigosas e até pacotes que não existem.
O CodeVault é um revisor pensado para esse cenário. Você entrega a pasta do projeto e ele faz uma varredura estrutural:
- 📂 Percorre os arquivos com segurança
- 🌳 Lê a estrutura do código (via AST) — sem executá-lo
- 🔍 Analisa com ferramentas maduras de segurança
- 📦 Verifica dependências — inclusive pacotes alucinados pela IA
- 📝 Explica cada achado: o quê, por quê é perigoso, como corrigir e a referência (CWE/OWASP)
🧠 Princípio central: o CodeVault analisa código como texto/AST — nunca importa, instala ou executa o projeto-alvo. Revisar código de IA (que ainda não foi auditado) exige ler, não rodar. É a diferença entre ler uma receita e cozinhá-la.
| Diferencial | |
|---|---|
| 🤖 | Focado em código de IA — detecta os padrões que assistentes de IA repetem com mais frequência |
| 👻 | Detecção de slopsquatting — sinaliza imports de pacotes que não existem no PyPI (vetor de ataque específico de código gerado por IA) |
| 🛡️ | Estático por design — analisa sem executar; não roda o código que está revisando |
| 📚 | Educacional — cada problema vem com explicação e correção, não só um código de erro |
| 📍 | Aponta o local exato — arquivo e linha de cada achado |
| 📊 | Relatórios — Console, Markdown, HTML e JSON |
💡 A CLI abaixo reflete a interface planejada. Acompanhe o roadmap para o que já está funcional.
# Analisar um projeto
codevault analyze /caminho/do/projeto
# Gerar relatório HTML
codevault analyze /caminho/do/projeto --format html --output report.html
# Modo interativo (guia a revisão)
codevault interactive /caminho/do/projeto📺 Exemplo ilustrativo de saída (mockup do formato planejado — não são resultados reais)
🔍 CodeVault — análise de "meu_projeto"
Arquivos varridos: 42 Tempo: 3.1s Modo: estático
┌ Achados por severidade ──────────────────────────────┐
│ 🔴 Crítico 2 🟠 Alto 5 🟡 Médio 8 ⚪ Info 3 │
└──────────────────────────────────────────────────────┘
🔴 app/db.py:47 SQL Injection (CWE-89)
Consulta montada por f-string com entrada do usuário.
→ Use consultas parametrizadas. Ref.: OWASP A05:2025
🔴 requirements.txt Pacote possivelmente inexistente: "fastjson-py"
Não encontrado no PyPI — possível alucinação de IA (slopsquatting).
→ Verifique o nome real da biblioteca antes de instalar.
🟠 app/auth.py:12 Segredo embutido (CWE-798) [valor redigido]
→ Mova para variável de ambiente / gerenciador de segredos.
Formato sujeito a mudanças durante o desenvolvimento.
Foco nos padrões inseguros mais comuns — com atenção especial aos que código de IA costuma produzir:
| Categoria | Exemplo | Referência |
|---|---|---|
| Injeção de SQL | Query por f-string com entrada do usuário | CWE-89 · A05:2025 |
| Injeção de comando | subprocess(..., shell=True), os.system |
CWE-78 · A05:2025 |
| Execução de código | eval / exec sobre entrada |
CWE-94/95 |
| Segredos embutidos | Chaves e tokens no código | CWE-798 · A04:2025 |
| Aleatoriedade fraca | random para tokens (em vez de secrets) |
CWE-330 |
| Desserialização insegura | pickle, yaml.load sem safe_load |
CWE-502 · A08:2025 |
| TLS desabilitado | verify=False |
CWE-295 |
| Falta de validação de entrada | Causa raiz frequente em código de IA | CWE-20 |
| Pacote alucinado (slopsquatting) | import de lib inexistente |
A03:2025 |
⚠️ As referências CWE/OWASP orientam a categorização; a lista evolui e será ampliada conforme o desenvolvimento.
O CodeVault segue um protocolo de construção com segurança embutida em cada etapa (secure by design):
Fundação → modelos de dados → varredura (descoberta de arquivos + parse AST) → análise (SAST, segredos, dependências, regras de IA) → saída (score, explicação, relatórios, CLI) → qualidade e entrega (testes, CI/CD, empacotamento).
📄 Detalhes completos em PROTOCOLO_CONSTRUCAO_CODEVAULT.md e PROTOCOLO_DESENVOLVIMENTO_SEGURO.md.
Requisitos: Python 3.9+ · Git
# Clonar
git clone https://github.com/carla-bioinfo/codevault.git
cd codevault
# Ambiente virtual
python3 -m venv venv
source venv/bin/activate # Linux/Mac
# venv\Scripts\activate # Windows
# Instalar em modo desenvolvimento
pip install -e .
pip install -r requirements-dev.txt
# Rodar os testes
pytest tests/Legenda: ✅ feito · 🔜 em progresso · ⏳ planejado
Núcleo
- ✅ Estrutura do pacote (src layout,
pyproject.toml, testes-base) - 🔜 Modelos de dados (
Finding,Severity,ScanResult) com Pydantic - ⏳ Descoberta segura de arquivos (proteção contra path traversal)
- ⏳ Parser estrutural via AST (análise sem execução)
Análise
- ⏳ Integração SAST (Ruff, Bandit, Semgrep)
- ⏳ Detecção de segredos
- ⏳ Auditoria de dependências (pip-audit) + detecção de slopsquatting
- ⏳ Catálogo de regras para padrões de código de IA
Saída e entrega
- ⏳ Sistema de pontuação por dimensão
- ⏳ Camada educacional (explicação + correção)
- ⏳ Relatórios (Console / Markdown / HTML / JSON)
- ⏳ CLI (
codevault analyze) - ⏳ Testes adversariais + CI/CD seguro
Futuro
- ⏳ Dashboard (Streamlit) · Extensão VS Code · Suporte a R/JavaScript
O CodeVault é desenvolvido segundo princípios de desenvolvimento seguro:
- Estático por padrão — nunca executa, importa ou instala o projeto analisado.
- Validação de entrada — caminhos e configurações validados (proteção contra path traversal).
- Falha segura (fail-closed) — em erro, o resultado é reprovado/indeterminado, nunca aprovado por omissão.
- Saída sem vazamento — segredos detectados são redigidos nos relatórios.
Referenciais que orientam o projeto (não são certificações obtidas): OWASP Top 10:2025 · NIST CSF 2.0 · CWE · CIS Controls.
⚠️ Sobre conformidade regulatória: o CodeVault pode apoiar práticas de código seguro úteis em contextos de saúde e pesquisa, mas não substitui e não assegura conformidade formal (HIPAA, GDPR, LGPD, FDA 21 CFR Part 11), que exige avaliação jurídica e de processos específica. Nenhuma alegação de conformidade é feita.
SECURITY.md para a política de divulgação responsável.
| Camada | Ferramentas |
|---|---|
| Núcleo | Python 3.9+ · Typer (CLI) · Pydantic (validação) · Rich (terminal) |
| Análise | Ruff · Bandit · Semgrep · pip-audit · ast (stdlib) |
| Relatórios | Jinja2 (com autoescape) · JSON · Markdown |
| Qualidade / CI | Pytest · pytest-cov · Mypy · GitHub Actions · pre-commit |
⚠️ Versões serão fixadas e auditadas (pip-audit) durante o desenvolvimento; confirme as vigentes nopyproject.toml.
Contribuições são bem-vindas!
- Faça fork e crie uma branch (
git checkout -b feature/minha-feature) - Adicione testes para a sua mudança
- Rode
pyteste os linters antes de abrir o PR - Abra um Pull Request descrevendo o quê, por quê e como testar
Padrões: formatação com Black · type hints verificados por Mypy · cobertura mínima de testes 80% · docstrings nas funções públicas.
Distribuído sob a Licença MIT — veja LICENSE.
Permite uso comercial, modificação, distribuição e uso privado. Fornecido sem garantia e sem responsabilidade — um revisor de segurança é um auxílio à análise, não um substituto de revisão humana qualificada.
CodeVault · Qualidade, Segurança e Educação para código na era da IA
Desenvolvido por Carla Rodrigues de Moraes GitHub @carla-bioinfo · LinkedIn · carlabio.biomol@gmail.com
Projeto de portfólio em bioinformática, ciência de dados e desenvolvimento seguro.
Última atualização: julho de 2026