CodeSentry

CLI de verificação de vulnerabilidades e qualidade de código. O scanner combina regras próprias para JavaScript/TypeScript e o ruleset OWASP do Semgrep CE para as linguagens suportadas por ele.

• 🔎 Dois motores num só comando — regras próprias em TS/JS + Semgrep CE (OWASP Top 10) para dezenas de outras linguagens.
• 📦 Uma instalação, zero fricção — npm install -g codesentry e pronto: sem Python, Docker, Semgrep ou conta em lugar nenhum.
• 🔌 Análise de código offline — nunca consulta a Semgrep Registry nem envia métricas; a auditoria de dependências, que usa serviços públicos, pode ser desativada com --no-deps.
• 🪟🐧 Windows e Linux nativamente — sem WSL, sem container.
• 📊 Console, JSON ou Markdown — saída pronta tanto para ler no terminal quanto para plugar em CI.

O que o CodeSentry faz

Rodando codesentry scan num projeto, três motores de análise trabalham juntos e o resultado sai unificado em um único relatório:

• Motor nativo — regras próprias em TypeScript, sem dependências externas, cobrindo JS/TS/JSX/TSX: segredos hardcoded, SQL injection, XSS, command injection, JWT mal configurado, CORS permissivo, hash/ cifra fracos, promises sem tratamento de erro, complexidade excessiva (funções longas, aninhamento profundo, muitos if/for/try), entre outras. A lista completa e sempre atualizada está em codesentry rules.
• Semgrep CE embutido — roda o ruleset p/owasp-top-ten sobre todas as linguagens que o Semgrep suporta (não só JS/TS), cobrindo os riscos do OWASP Top 10 de forma mais ampla que regras hand-rolled sozinhas conseguiriam.
• Auditoria de dependências (npm audit + OSV.dev + NVD) — identifica vulnerabilidades conhecidas nas dependências reais do projeto, lendo o lockfile presente: package-lock.json, pnpm-lock.yaml ou yarn.lock para JS/TS (ecossistema npm), e poetry.lock ou requirements.txt (só linhas com pin exato ==) para Python (ecossistema PyPI). Se houver mais de um lockfile no projeto (ex.: um monorepo poliglota), todos os suportados são lidos e combinados num único relatório. O OSV identifica versões afetadas e corrigidas; quando seus aliases contêm CVEs, o NVD enriquece o mesmo finding com CVSS, CWE, referências e dados da CISA. npm audit só roda quando existe package-lock.json/npm-shrinkwrap.json — um projeto só-pnpm ou só-Yarn tem cobertura só do OSV.dev (npm audit exige seu próprio lockfile). Roda por padrão e exige rede; use --no-nvd para manter npm + OSV sem enriquecimento ou --no-deps para um scan 100% offline. Ver ADR 0005, ADR 0006 e ADR 0007.

Cada achado no relatório mostra o arquivo, a linha, a severidade e qual motor encontrou o problema (prefixo semgrep/ para achados do Semgrep). Saídas disponíveis: tabela no console, JSON (--json) e, quando há mais de 20 problemas, um relatório Markdown detalhado é gerado automaticamente.

Exemplo de saída no console:

❯ codesentry scan .
✔ Scanning files...
┌──────────┬──────────────────────┬─────────────────┬──────┬──────────────────────────────────────────┐
│ Severity │ Rule                 │ File             │ Line │ Message                                    │
├──────────┼──────────────────────┼─────────────────┼──────┼──────────────────────────────────────────┤
│ high     │ no-hardcoded-secret  │ src/config.ts    │ 12   │ Possível segredo hardcoded na variável...  │
│ high     │ semgrep/...shell-true│ scripts/run.py   │ 8    │ subprocess com shell=True é perigoso...    │
│ medium   │ jwt-no-expiration    │ src/auth.ts      │ 34   │ Token JWT assinado sem "expiresIn"...      │
└──────────┴──────────────────────┴─────────────────┴──────┴──────────────────────────────────────────┘

3 problema(s) encontrado(s) em 87 arquivo(s) (4213ms). CodeSentry: 87 JS/TS; Semgrep: 64 arquivo(s).

Como funciona por baixo dos panos

O ponto central do design é zero fricção de instalação: o usuário final roda npm install -g codesentry e não precisa instalar Python, Docker, Semgrep, nem criar conta em lugar nenhum.

Isso é possível porque o Semgrep CE e um Python portátil vêm empacotados como dependências opcionais específicas da plataforma (codesentry-semgrep-linux-x64 / -win32-x64), resolvidas automaticamente pelo npm na instalação. O ruleset OWASP também é distribuído como pacote próprio (codesentry-semgrep-rules), como um snapshot local fixado por versão — o scan nunca consulta a Semgrep Registry nem envia métricas, e funciona 100% offline depois de instalado. O racional completo está na ADR 0004.

Instalação

Pré-requisito único: Node.js 22.12 ou mais recente (node --version para conferir). Nenhum outro requisito — não precisa instalar Python, Docker, Semgrep, criar conta ou autenticar em nada.

Windows

No PowerShell ou no Prompt de Comando (não precisa de WSL):

npm install -g codesentry
codesentry scan .

Linux

npm install -g codesentry
codesentry scan .

Em ambos os casos, o npm install já resolve automaticamente o pacote de runtime compatível com a sua plataforma (Semgrep CE + Python portátil) como dependência opcional — é isso que faz codesentry scan funcionar com cobertura OWASP completa sem nenhuma instalação manual. Plataformas com runtime publicado hoje: Linux x64 e Windows x64. Os pacotes têm dezenas de MB porque incluem esse runtime embutido; essa é a troca para o scan funcionar 100% offline depois de instalado.

Se codesentry não for encontrado no terminal depois de instalado globalmente, feche e reabra o terminal (ou rode npx codesentry scan .) — alguns terminais não recarregam o PATH do npm automaticamente na mesma sessão.

A partir do código-fonte (desenvolvimento)

Para rodar a partir do repositório clonado, em vez do pacote publicado, use npm link:

git clone [email protected]:Ivan-ReisDev/code-sentry.git
cd code-sentry
npm install
npm run build
npm link

Depois disso, o comando codesentry fica disponível em qualquer diretório do seu terminal.

Atenção: npx codesentry rodado de dentro deste repositório clonado executa o dist/index.js local (o package.json daqui se chama codesentry, e o npx prioriza isso sobre a instalação global/publicada). O workspace de desenvolvimento sempre tem o ruleset do Semgrep vazio por design (populado só via npm run prepare:owasp-rules ou durante a release — ver ADR 0004), então o scan roda sem erro mas sempre reporta zero arquivos analisados pelo Semgrep. Para testar o pacote publicado de verdade, rode codesentry scan (sem npx) fora deste diretório.

Uso

codesentry scan [path]

Analisa um diretório (padrão: diretório atual) em busca de vulnerabilidades e problemas de qualidade.

codesentry scan .
codesentry scan ./src
codesentry scan . --json
codesentry scan . --concurrency 4
codesentry scan . --config ./rules/security.yml
codesentry scan . --tests
codesentry scan . --no-nvd
codesentry scan . --no-deps

O Semgrep CE embutido é executado automaticamente depois das regras nativas, usando um snapshot local do ruleset OWASP e --metrics=off. O comando não consulta a Semgrep Registry, não envia métricas e não requer internet após a instalação.

Por padrão, scan também roda a auditoria de dependências (npm audit + OSV.dev + NVD) e funde os achados no mesmo relatório — isso exige acesso à rede. package-lock.json, pnpm-lock.yaml, yarn.lock, poetry.lock e requirements.txt são detectados automaticamente (todos os presentes são lidos); npm audit em si só roda quando existe package-lock.json/npm-shrinkwrap.json — pnpm/Yarn/Python ficam só com a cobertura do OSV.dev. O OSV é a fonte principal: o NVD é consultado somente para aliases CVE- retornados pelo OSV e uma falha do NVD nunca remove o finding. Use --no-nvd para desativar apenas o enriquecimento ou --no-deps para pular toda a auditoria e manter o scan 100% offline (CI sem egress, ambientes air-gapped).

O console mostra quantos pacotes dos lockfiles foram considerados e quantos o OSV.dev conseguiu verificar de fato (OSV.dev: 360/363 verificados, por exemplo — a diferença indica pacotes cuja consulta falhou, reportados também como aviso). Quando houver CVEs, mostra ainda a cobertura NVD separando registros enriquecidos, sem resultado, falhas e cache hits. No relatório Markdown gerado automaticamente (mais de 20 problemas), a lista completa de dependências verificadas no OSV.dev (nome@versão, com (PyPI) etc. quando não for npm) aparece numa seção própria.

Chave opcional do NVD

A integração funciona sem autenticação. Para maior capacidade de consulta, solicite gratuitamente uma chave no formulário oficial Request an API Key, confirme a solicitação recebida por e-mail e configure NVD_API_KEY no ambiente antes de executar o CodeSentry.

Linux/macOS:

export NVD_API_KEY="sua-chave"
codesentry scan .

# Ou somente para uma execução:
NVD_API_KEY="sua-chave" codesentry dependency-audit .

PowerShell:

$env:NVD_API_KEY = "sua-chave"
codesentry scan .

A chave é enviada apenas no header apiKey; não é adicionada à URL, ao cache, a logs ou aos relatórios. O CodeSentry não carrega arquivos .env automaticamente. Sem chave, as consultas são serializadas com intervalo mínimo de 6,1 segundos; com chave, 610 ms. Respostas bem-sucedidas ficam em cache por 24 horas e respostas sem resultado por 1 hora. O cache fica no diretório de cache do usuário, nunca no projeto analisado. Timeout, rate limit ou indisponibilidade do NVD aparecem como aviso e não interrompem o scan.

Versões e atualização dos motores

Use codesentry version --engines para auditar exatamente os componentes embutidos na sua instalação. O comando não executa o Semgrep nem acessa a rede; ele mostra a versão do CodeSentry, a versão do Semgrep CE e Python do runtime da plataforma, e a proveniência do snapshot p/owasp-top-ten (origem, data de captura, revisão upstream quando disponível e SHA-256).

codesentry version --engines
codesentry version --engines --json

O snapshot do ruleset é identificado pela versão do pacote publicada junto ao CodeSentry e pelo SHA-256 do seu conteúdo. A Semgrep Registry não fornece necessariamente um commit estável para um ruleset público; nesse caso, o hash é o identificador imutável que permite comparar o conteúdo auditado.

Política de atualização: revisamos semanalmente novas versões do Semgrep e alterações no p/owasp-top-ten; atualizações regulares são publicadas em até 30 dias. Correções upstream classificadas como críticas ou que afetem a integridade da análise têm prioridade para uma release em até 48 horas. Toda release que atualizar um motor ou ruleset registra as versões e hashes nos artefatos publicados.

--concurrency <n> limita o processamento paralelo do scanner nativo; use apenas inteiros positivos. Sem valor, o limite é ajustado para a máquina (min(8, availableParallelism())). Não há --config remoto: atualizações de Semgrep e das regras OWASP chegam em novas releases do CodeSentry. Quando necessário, --config aceita exclusivamente um arquivo YAML local.

Por padrão, arquivos de teste não são analisados: nenhum diretório chamado tests, test ou __tests__ (em qualquer profundidade) e nenhum arquivo com sufixo .spec.*/.test.* (em qualquer lugar, mesmo fora dessas pastas) entra no scan. Use --tests para incluí-los.

Em macOS, ARM e plataformas sem runtime publicado, o comando interrompe explicitamente em vez de declarar uma análise parcial como completa.

codesentry rules

Lista as regras de análise disponíveis (id e descrição de cada uma).

codesentry rules

codesentry help

Lista todos os comandos disponíveis, sempre atualizada — inclui tanto os comandos gerais quanto os individuais listados a seguir.

codesentry help

Comandos individuais por regra

Cada regra nativa também tem um comando próprio, que roda só ela sobre um diretório — útil para focar em um tipo de problema específico sem esperar o scan completo (e sem o Semgrep, que só roda como parte de scan). Todos seguem o mesmo formato:

codesentry <comando> [path] [--json] [--tests]

Alguns exemplos:

codesentry long-functions .          # funções com mais de 30 linhas
codesentry no-eval ./src             # uso de eval()
codesentry xss ./src --json          # possíveis XSS (innerHTML, document.write, dangerouslySetInnerHTML)
codesentry unsafe-sql ./src          # SQL injection por concatenação
codesentry command-injection ./src   # child_process com entrada não sanitizada
codesentry weak-hash-algorithm ./src # uso de MD5/SHA-1 para hashing sensível
codesentry dependency-audit .        # npm/pnpm/Yarn + Python via OSV.dev, + npm audit + NVD (sem --tests: não lê arquivos-fonte)
codesentry dependency-audit . --no-nvd # mantém npm + OSV e desativa só o NVD

Assim como em scan, --tests inclui arquivos de teste na análise (por padrão são ignorados) — exceto em dependency-audit, que nunca lê arquivos-fonte e por isso não tem essa flag.

A lista completa (30+ comandos, um por regra) sai de codesentry help — mantê-la sempre em sincronia aqui manualmente não seria viável.

codesentry init

Assistente interativo para configurar o CodeSentry no projeto atual.

codesentry init

A persistência da configuração em arquivo ainda não está implementada (ver src/config/config.ts).

Desenvolvimento

npm install       # instala as dependências
npm run dev        # roda a CLI direto do TypeScript (via tsx)
npm run build      # gera o build de produção em dist/
npm run typecheck  # checagem de tipos (tsc --noEmit)
npm test           # roda a suíte de testes uma vez
npm run test:watch # roda os testes em modo watch

Este projeto segue TDD obrigatório: toda nova regra, comando ou comportamento do scanner/reporter deve começar por um teste que falha, em tests/, antes de qualquer implementação.

Para entender a estrutura de pastas e o fluxo de dados (command → scanner → rules → reporter), veja docs/architecture.md. Para o racional por trás das bibliotecas usadas na CLI, veja docs/adr/0001-cli-libs.md.

Licença

MIT