codesentry 0.1.10 → 0.2.1

package/README.md

@@ -16,7 +16,7 @@ Semgrep CE para as linguagens suportadas por ele.
 
 ## O que o CodeSentry faz
 
-Rodando `codesentry scan` num projeto, dois motores de análise trabalham
+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
@@ -29,6 +29,12 @@ juntos e o resultado sai unificado em um único relatório:
   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](https://osv.dev)) —
+  identifica vulnerabilidades conhecidas nas dependências reais do
+  projeto (via `package-lock.json`), com a sugestão de correção vindo
+  diretamente do banco consultado. Roda por padrão a partir desta versão
+  e exige rede; use `--no-deps` para um scan 100% offline. Ver
+  [ADR 0005](docs/adr/0005-osv-dependency-database.md).
 
 Cada achado no relatório mostra o arquivo, a linha, a severidade e qual
 motor encontrou o problema (prefixo `semgrep/` para achados do Semgrep).
@@ -140,6 +146,8 @@ codesentry scan ./src
 codesentry scan . --json
 codesentry scan . --concurrency 4
 codesentry scan . --config ./rules/security.yml
+codesentry scan . --tests
+codesentry scan . --no-deps
 ```
 
 O Semgrep CE embutido é executado automaticamente depois das regras nativas,
@@ -147,12 +155,55 @@ 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) e funde os achados no mesmo relatório — isso exige `npm` no `PATH`
+e acesso à rede. Use `--no-deps` para pular essa etapa e manter o scan
+100% offline (CI sem egress, ambientes air-gapped). Ver
+[ADR 0005](docs/adr/0005-osv-dependency-database.md).
+
+O console mostra quantos pacotes o `npm audit` cobriu e quantos deles 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). No relatório Markdown gerado automaticamente (mais de
+20 problemas), a lista completa de dependências verificadas no OSV.dev
+(`nome@versão`) aparece numa seção própria ao final do arquivo.
+
+### 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).
+
+```bash
+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.
 
@@ -181,7 +232,7 @@ o scan completo (e sem o Semgrep, que só roda como parte de `scan`). Todos
 seguem o mesmo formato:
 
 ```bash
-codesentry <comando> [path] [--json]
+codesentry <comando> [path] [--json] [--tests]
 ```
 
 Alguns exemplos:
@@ -193,9 +244,13 @@ codesentry xss ./src --json          # possíveis XSS (innerHTML, document.write
 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
+codesentry dependency-audit .        # `npm audit` + OSV.dev nas 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.