codesentry 0.1.9 → 0.1.11

package/README.md

@@ -1,9 +1,19 @@
+<p align="center">
+  <img src="docs/assets/logo.png" alt="Logo do CodeSentry" width="640">
+</p>
+
 # 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.
+- 🔌 **100% offline depois de instalado** — nunca consulta a Semgrep Registry nem envia métricas.
+- 🪟🐧 **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, dois motores de análise trabalham
@@ -25,6 +35,22 @@ 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:
+
+```text
+❯ 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
@@ -42,20 +68,43 @@ O racional completo está na [ADR 0004](docs/adr/0004-bundled-semgrep-runtime.md
 
 ## Instalação
 
-Em uma release publicada, basta uma instalação:
+Pré-requisito único: [Node.js](https://nodejs.org) 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):
+
+```powershell
+npm install -g codesentry
+codesentry scan .
+```
+
+### Linux
 
 ```bash
 npm install -g codesentry
+codesentry scan .
 ```
 
-O pacote compatível de Semgrep CE e Python portátil é instalado como
-dependência opcional automaticamente. Não é necessário instalar Python,
-Docker, Semgrep, criar conta ou autenticar em um site.
+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.
 
-As plataformas inicialmente suportadas são Linux x64 e Windows x64. Os
-pacotes têm tamanho de dezenas de MB porque incluem o runtime; essa é a troca
-para o scan funcionar offline após a instalação. Durante o desenvolvimento,
-use `npm link`:
+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`:
 
 ```bash
 git clone git@github.com:Ivan-ReisDev/code-sentry.git
@@ -68,6 +117,16 @@ 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](docs/adr/0004-bundled-semgrep-runtime.md)), 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]`
@@ -81,6 +140,7 @@ codesentry scan ./src
 codesentry scan . --json
 codesentry scan . --concurrency 4
 codesentry scan . --config ./rules/security.yml
+codesentry scan . --tests
 ```
 
 O Semgrep CE embutido é executado automaticamente depois das regras nativas,
@@ -94,36 +154,61 @@ apenas inteiros positivos. Sem valor, o limite é ajustado para a máquina
 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.
+Lista as regras de análise disponíveis (id e descrição de cada uma).
 
 ```bash
 codesentry rules
 ```
 
-### `codesentry long-functions [path]`
+### `codesentry help`
 
-Analisa um diretório (padrão: diretório atual) em busca apenas de
-funções com mais de 30 linhas (severidade `low`). Essa mesma regra
-também roda automaticamente como parte do `codesentry scan`.
+Lista **todos** os comandos disponíveis, sempre atualizada — inclui tanto
+os comandos gerais quanto os individuais listados a seguir.
 
 ```bash
-codesentry long-functions .
-codesentry long-functions ./src --json
+codesentry help
 ```
 
-### `codesentry help`
+### Comandos individuais por regra
 
-Lista os comandos disponíveis.
+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:
 
 ```bash
-codesentry help
+codesentry <comando> [path] [--json] [--tests]
 ```
 
+Alguns exemplos:
+
+```bash
+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 audit` das dependências do projeto (sem --tests: não lê arquivos-fonte)
+```
+
+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.