@lugom.io/hefesto 0.2.0 → 1.0.0

package/skills/hefesto-new-feature/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: hefesto-new-feature
+description: >
+  Cria o spec de uma nova feature no Hefesto. Coleta visão e requisitos, propõe abordagens,
+  decompõe em fases risk-first com rastreabilidade de requisitos.
+  Usar com: /hefesto-new-feature. Gera o documento FEAT-NNN — para implementar, usar
+  /hefesto-execute depois.
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Hefesto New Feature
+
+Cria um novo documento de feature em `.hefesto/features/`. Guia o usuário desde a visão inicial até um spec completo com requisitos testáveis, fases de implementação ordenadas por risco, e rastreabilidade requisito→fase.
+
+## Pré-requisitos
+
+Verificar se `.hefesto/` existe. Se não, sugerir `/hefesto-init`.
+
+## Workflow
+
+### Fase 0 — Explorar Contexto
+
+Antes de perguntar, entender o terreno:
+
+1. Ler `PROJECT.md` (valor central, stack, receitas), `STATE.md` (feature ativa, bloqueios), `config.json` (próximo ID)
+2. Listar features existentes (frontmatter) — notar áreas cobertas, padrões de naming
+3. Se há features `draft`/`blocked`, mencionar — talvez retomar em vez de criar nova
+
+Resumo: `Projeto: X | Stack: Y | Features: N (X done, Y active) | Próxima: FEAT-NNN`
+
+### Fase 1 — Entender a Feature
+
+O objetivo é sair desta fase com entendimento completo do que construir. Conversar com o usuário até ter clareza — pode ser uma mensagem ou várias.
+
+1. **Título** — curto e descritivo, identifica a feature de relance
+2. **Problema** — qual dor ou necessidade motiva essa feature? Por que importa agora?
+3. **Visão** — o que entrega e como o usuário se beneficia quando estiver pronta
+4. **Fluxo do usuário** — passos concretos que o usuário percorre do início ao fim
+5. **Requisitos** — testáveis, com critério claro de pass/fail. Perguntar: "como sei que está funcionando?"
+6. **Fora do escopo** — o que explicitamente NÃO faz parte. Perguntar: "tem algo parecido que não devemos incluir?"
+7. **Riscos/incertezas** — integração externa, tech nova, performance, dependência de terceiros
+8. **Receitas** — Se o PROJECT.md contiver receitas, consultar e sugerir as relevantes (ex: feature com formulário → React Hook Form + Zod). Se não houver, pular
+
+### Fase 2 — Propor Abordagens
+
+Propor 2-3 abordagens com trade-offs quando relevante. Recomendar uma com razão concreta. Pular se feature é simples/óbvia.
+
+### Fase 3 — Decompor em Fases
+
+Seguir estrutura de `TPL-FEATURE.md` (seção "Implementação"). Para definições de status e ciclo de vida, ver `/hefesto-context`.
+
+#### Risk-first ordering
+
+Incerteza primeiro — invalidar premissas cedo. Se sem risco, ordenar por dependência natural.
+
+#### Rastreabilidade REQ→Fase
+
+Cada fase lista quais REQ-NN cobre. Verificar cobertura total — alertar se algum REQ ficou órfão.
+
+Cada fase atômica (~30 min).
+
+### Fase 4 — Detectar Escopo Excessivo
+
+Se > 5 fases ou > 10 requisitos: alertar e sugerir divisão concreta. Advisory, não mandatório.
+
+### Fase 5 — Self-Review
+
+- [ ] Título claro (não genérico)
+- [ ] Visão inclui O QUE e POR QUÊ
+- [ ] Pelo menos 2 requisitos testáveis
+- [ ] "Fora do Escopo" preenchido
+- [ ] Fases atômicas com critérios de aceitação
+
+Se falhar, pedir complemento. Se usuário disser "segue assim", respeitar.
+
+### Fase 6 — Criar Arquivo
+
+1. Gerar ID `FEAT-NNN` (counter + 1, zero-padded) e slug (lowercase, hifenizado, max 40 chars, sem acentos)
+2. Ler `.hefesto/templates/TPL-FEATURE.md` e criar `.hefesto/features/FEAT-NNN-slug.md` substituindo placeholders
+3. Atualizar `config.json` (feature.counter)
+4. Atualizar tabela de Features em `PROJECT.md`
+5. Atualizar `STATE.md` se for primeira feature ou nenhuma ativa
+6. Seletor: "Promover para `ready` ou continuar iterando?"
+   - Se **ready**: atualizar status e STATE.md
+   - Se **iterar**: coletar ajustes, aplicar, repetir até promoção ou encerramento
+7. Sugerir `/hefesto-execute` quando pronto

package/skills/hefesto-security/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: hefesto-security
+description: >
+  Revisão de segurança de código. Encontra vulnerabilidades e aplica fixes.
+  ATIVAR quando: "segurança", "security", "vulnerabilidade", "XSS", "injection", "OWASP",
+  "segredo exposto", "código seguro", "auditoria de segurança", "security review".
+  Também: padrões perigosos (eval, exec, deserialização), inputs não validados, falhas silenciosas.
+user-invocable: true
+disable-model-invocation: false
+argument-hint: '[arquivos ou escopo opcional]'
+---
+
+# Hefesto Security
+
+Revisão de segurança que encontra vulnerabilidades reais e aplica fixes concretos. Zero tolerância a falhas silenciosas e padrões perigosos.
+
+## Princípios
+
+1. **Falhas silenciosas são inaceitáveis** — catch vazio é bug escondido; todo erro deve ser logado
+2. **Validar nas bordas** — inputs de usuário, APIs externas, env vars. Dados internos entre módulos não precisam
+3. **Sem segredos em código** — API keys, tokens, passwords em variáveis de ambiente, nunca hardcoded
+
+## Workflow
+
+### Fase 1 — Identificar escopo
+
+1. Se argumentos fornecidos → usar esses arquivos
+2. Senão, buscar feature ativa:
+   - Ler `.hefesto/STATE.md` → extrair arquivos modificados do frontmatter
+   - Se STATE.md não existir ou não tiver arquivos → `git diff --name-only` (staged + unstaged)
+3. Fallback → `git diff --name-only HEAD~1`
+4. Filtrar apenas código-fonte (excluir binários, lock files, build artifacts, código gerado)
+5. Excluir: diretórios de dependências, `dist/`, `build/`, `*.lock`, `*.lockb`, arquivos auto-gerados
+
+### Fase 2 — Análise de vulnerabilidades
+
+Ler `references/severity-and-judgment.md` — usar critérios de severidade e regras de falso positivo ao longo de toda a análise. Ler `references/boundaries-and-bypasses.md` — verificar cada boundary type aplicável.
+
+Para cada arquivo no escopo, analisar semanticamente estas categorias universais:
+
+1. **Code injection** — eval, exec, desserialização insegura, template injection, dynamic imports — em qualquer linguagem
+2. **Data injection** — SQL, NoSQL, LDAP, command injection, XSS — em qualquer framework ou ORM
+3. **Input validation gaps** — dados cruzando trust boundaries sem validação (consultar boundaries reference)
+4. **Auth & access control** — rotas sem auth, IDOR, CORS permissivo, CSRF, missing role checks
+5. **Insecure configuration** — debug mode em produção, headers de segurança ausentes, crypto fraco, default credentials
+6. **Data exposure** — dados sensíveis em logs, responses, URLs, query params, error messages
+7. **Resource exhaustion** — queries sem limit, missing pagination, missing timeouts, body size ilimitado
+
+Para cada finding, avaliar contexto antes de reportar — consultar "When NOT to Report" na referencia de severidade.
+
+### Fase 3 — Falhas silenciosas
+
+Ler `references/severity-and-judgment.md` seção "Silent Failures" — contém as 6 categorias universais, critérios de classificação e exceções.
+
+1. Encontrar todos os construtos de error handling na(s) linguagem(ns) detectada(s)
+2. Classificar cada um usando as categorias e critérios da referência
+3. Consultar "Quando silenciamento é aceitável" antes de reportar
+
+### Fase 4 — Segredos
+
+Ler `references/secrets-detection.md`.
+
+1. Usar regex por provider e genericos para grep nos arquivos do escopo
+2. Consultar "Exceptions" em `references/severity-and-judgment.md` antes de reportar — nem todo match e secret real
+3. Verificar `.gitignore` conforme "Gitignore Audit"
+4. Verificar se `.env` esta committed no git
+
+### Fase 5 — Aplicar correções
+
+1. Para issues **🔴 critical**: aplicar fix automaticamente
+   - Gerar correção apropriada para a linguagem/framework detectado
+   - Erros engolidos → adicionar log + re-throw ou return adequado
+   - Code injection → substituir por alternativa segura
+   - Segredos hardcoded → mover para variável de ambiente
+   - Queries com interpolação → parameterized queries
+
+2. Para issues **⚠ warning**: aplicar fix se a correção é clara e segura. Para mudanças que alteram comportamento (ex: adicionar validação que pode rejeitar inputs), perguntar antes
+
+3. Rodar verification commands após fixes para garantir que nada quebrou
+
+4. Apresentar relatório no formato `TPL-SECURITY.md` — preencher todas as seções aplicáveis, omitir seções sem issues
+
+## Notas
+
+- Se o projeto não tiver `.hefesto/`, o skill funciona com `git diff` e `CLAUDE.md`
+- Não reportar vulnerabilidades em dependências (escopo de ferramentas de audit de dependências)
+- Não reportar issues em código gerado
+- Priorizar issues com impacto real sobre issues teóricas
+- Se invocado pelo `/hefesto-execute`, o relatório é passado para o Argos junto com o resultado da feature

package/skills/hefesto-security/references/boundaries-and-bypasses.md

@@ -0,0 +1,152 @@
+# Boundaries e Bypass Techniques
+
+Trust boundaries universais e tecnicas de bypass de validacao. Independente de linguagem ou framework.
+
+## Quick Index
+
+- **Tipos de boundary** → "Boundaries" (linha 12)
+- **Tecnicas de bypass** → "Bypass Vectors" (linha 72)
+- **Como detectar** → "How to Detect" (linha 117)
+
+---
+
+## Boundaries
+
+### Form inputs / JSON body
+
+Dados submetidos via form HTML ou JSON body em POST/PUT/PATCH.
+
+| O que verificar                 | Quando e problema                                    |
+| ------------------------------- | ---------------------------------------------------- |
+| Usado diretamente em DB query   | Sempre                                               |
+| Usado em operacao de filesystem | Sempre                                               |
+| Usado em redirect               | Sempre                                               |
+| Tipos nao verificados           | Se vem de JSON body (pode ser string, array, objeto) |
+| Tamanho nao limitado            | Se e string longa — DoS via payload gigante          |
+
+### Query params / route params
+
+Dados na URL: `/users/:id?sort=name&order=asc`.
+
+| O que verificar                      | Quando e problema             |
+| ------------------------------------ | ----------------------------- |
+| Param numerico sem validacao de tipo | Sempre                        |
+| Param usado em regex                 | Sempre — ReDoS                |
+| Param usado em path de filesystem    | Sempre — path traversal       |
+| Sort/order sem whitelist             | Se usado em query — injection |
+| Pagination sem limites               | Se usado em LIMIT — DoS       |
+
+### Respostas de API externa
+
+Dados retornados por APIs de terceiros. Nao confiar mesmo em APIs "de confianca".
+
+| O que verificar                | Quando e problema                     |
+| ------------------------------ | ------------------------------------- |
+| Estrutura nao validada         | Sempre — crash se estrutura mudou     |
+| Dados renderizados no frontend | Se contem HTML/JS — XSS stored        |
+| Status code nao verificado     | Se assume sucesso                     |
+| Dados usados em query          | Sempre — injection via dados externos |
+
+### Headers / Cookies
+
+| O que verificar                               | Quando e problema                                        |
+| --------------------------------------------- | -------------------------------------------------------- |
+| Cookie usado sem validacao                    | Se contem dados de sessao (JWT sem verificar assinatura) |
+| Header Host / X-Forwarded-For usado em logica | Sempre — spoofavel                                       |
+| Content-Type nao verificado                   | Se processa body condicionalmente                        |
+| Referer / Origin para autenticacao            | Sempre — spoofavel                                       |
+
+### File uploads
+
+| O que verificar                        | Quando e problema                       |
+| -------------------------------------- | --------------------------------------- |
+| Tipo nao validado (MIME + magic bytes) | Sempre                                  |
+| Tamanho nao limitado                   | Sempre — DoS                            |
+| Nome do arquivo nao sanitizado         | Se usado no filesystem — path traversal |
+| Conteudo nao escaneado                 | Se armazenado/servido — polyglot files  |
+| Extensao dupla                         | Se whitelist por extensao — bypass      |
+
+### Boundaries adicionais
+
+| Boundary                         | O que verificar                                                                          |
+| -------------------------------- | ---------------------------------------------------------------------------------------- |
+| **WebSocket messages**           | Cada mensagem deve ser validada — nao ha "sessao validada" que garanta mensagens futuras |
+| **GraphQL inputs**               | Validar args de cada resolver. Queries aninhadas → DoS (query depth limiting)            |
+| **CLI args**                     | Validar antes de usar em shell commands, file operations, ou regex                       |
+| **Variaveis de ambiente**        | Validar formato esperado no startup (URL valida, numero, enum)                           |
+| **IPC / inter-process**          | Mensagens entre processos devem ser validadas — outro processo pode ser comprometido     |
+| **Database read-back**           | Dados lidos do DB podem ter sido inseridos sem sanitizacao em versao anterior do codigo  |
+| **gRPC / RPC inputs**            | Mesmo com tipos definidos no proto, validar ranges e constraints de negocio              |
+| **Event queue / message broker** | Mensagens de filas (Kafka, RabbitMQ, SQS) sao tao untrusted quanto HTTP requests         |
+
+---
+
+## Bypass Vectors
+
+Tecnicas que atacantes usam para contornar validacao fraca. Verificar se a validacao cobre estes cenarios:
+
+### Type coercion
+
+Input esperado num tipo, recebido em outro. Comparacoes fracas (`==` vs `===`), conversoes implicitas, e frameworks que aceitam tipos variados para o mesmo parametro (string se 1 valor, array se multiplos).
+
+**Deteccao**: comparacao fraca de input com valor fixo; ausencia de type check explicito.
+
+### Prototype / object pollution
+
+Payload JSON com propriedades especiais (`__proto__`, `constructor.prototype`) que injetam propriedades em objetos. Afeta linguagens com heranca prototipal ou merge recursivo de objetos.
+
+**Deteccao**: JSON parse seguido de merge/assign/spread sem filtrar keys especiais.
+
+### Unicode normalization
+
+Caracteres Unicode que normalizam para equivalentes ASCII. Pode bypassar blacklists de filename, filtros de input, e comparacoes de string.
+
+**Deteccao**: validacao de filename ou input sem normalizacao previa; filtros baseados em comparacao byte-a-byte.
+
+### Null byte injection
+
+Null bytes (`\0`, `\x00`, `%00`) que truncam strings em sistemas baseados em C. Path traversal classico: `../../etc/passwd\0.png` — extensao ignorada.
+
+**Deteccao**: input usado em operacoes de filesystem sem filtrar null bytes.
+
+### Array vs scalar ambiguity
+
+Parametros que podem ser string ou array dependendo de quantos valores sao enviados. Frameworks web frequentemente tem este comportamento em query params.
+
+**Deteccao**: input de query params usado sem type check ou conversao explicita.
+
+---
+
+## How to Detect
+
+Heuristicas para identificar "input → operacao sem validacao no meio":
+
+### 1. Rastrear fluxo de dados
+
+```
+input source → variavel local → operacao perigosa
+```
+
+Se entre a origem (request, CLI arg, env var, file upload, API response) e o destino (DB query, filesystem op, shell command, redirect, HTML render) nao ha:
+
+- Schema validation (qualquer biblioteca de validacao)
+- Type assertion / type guard
+- Sanitizacao explicita
+- Parameterized query / prepared statement
+
+→ Reportar como ⚠ warning.
+
+### 2. Sinais de validacao ausente
+
+- Input de request usado na mesma funcao que operacao perigosa sem chamada de validacao entre eles
+- Dados de API externa usados diretamente sem schema validation
+- Parametros de rota usados em query sem conversao de tipo
+
+### 3. Sinais de validacao presente
+
+- Import de biblioteca de validacao no arquivo
+- Schema definido antes do handler
+- Middleware de validacao na rota
+- Type guards explicitos
+- Parameterized queries (placeholders em vez de interpolacao)
+- Sanitization functions entre input e uso

package/skills/hefesto-security/references/secrets-detection.md

@@ -0,0 +1,121 @@
+# Detecção de Segredos
+
+Regex por provider e padrões genéricos para detecção automatizada de segredos hardcoded. Inclui auditoria de `.gitignore`.
+
+## Quick Index
+
+- **API keys por provider** → "API Keys by Provider" (linha 12)
+- **Padrões genéricos** → "Generic Patterns" (linha 31)
+- **.env commitado** → ".env Committed" (linha 47)
+- **Auditoria de .gitignore** → "Gitignore Audit" (linha 55)
+- **Regex para grep** → "Grep Patterns" (linha 87)
+
+---
+
+## API Keys by Provider
+
+| Provider      | Prefixo / Padrão       | Regex                                                    |
+| ------------- | ---------------------- | -------------------------------------------------------- |
+| **AWS**       | `AKIA` (access key)    | `AKIA[0-9A-Z]{16}`                                       |
+| **AWS**       | Secret key             | `['"]\w{40}['"]` proximo de `aws_secret` ou `AWS_SECRET` |
+| **GCP**       | Service account JSON   | `"type":\s*"service_account"` em `.json`                 |
+| **GCP**       | API key                | `AIza[0-9A-Za-z_-]{35}`                                  |
+| **GitHub**    | Personal access token  | `ghp_[0-9a-zA-Z]{36}`                                    |
+| **GitHub**    | OAuth token            | `gho_[0-9a-zA-Z]{36}`                                    |
+| **GitHub**    | App token              | `ghs_[0-9a-zA-Z]{36}`                                    |
+| **Stripe**    | Secret key (live)      | `sk_live_[0-9a-zA-Z]{24,}`                               |
+| **Stripe**    | Publishable key (live) | `pk_live_[0-9a-zA-Z]{24,}`                               |
+| **Slack**     | Bot token              | `xoxb-[0-9]{10,}-[0-9a-zA-Z]{24,}`                       |
+| **Slack**     | User token             | `xoxp-[0-9]{10,}-[0-9a-zA-Z]{24,}`                       |
+| **Anthropic** | API key                | `sk-ant-[0-9a-zA-Z_-]{80,}`                              |
+| **OpenAI**    | API key                | `sk-[0-9a-zA-Z]{48,}`                                    |
+| **Twilio**    | Account SID            | `AC[0-9a-f]{32}`                                         |
+| **SendGrid**  | API key                | `SG\.[0-9A-Za-z_-]{22}\.[0-9A-Za-z_-]{43}`               |
+| **Mailgun**   | API key                | `key-[0-9a-zA-Z]{32}`                                    |
+
+---
+
+## Generic Patterns
+
+| Tipo                    | O que procurar                                     | Regex                                                                  |
+| ----------------------- | -------------------------------------------------- | ---------------------------------------------------------------------- |
+| **API key generica**    | Variavel com nome sugestivo atribuida a string     | `(?:api_key\|apikey\|api_secret\|secret_key)\s*=\s*['"][^'"]{10,}['"]` |
+| **Password hardcoded**  | Variavel password/senha atribuida a string         | `(?:password\|passwd\|pwd\|senha)\s*=\s*['"][^'"]+['"]`                |
+| **JWT hardcoded**       | String que comeca com `eyJ` (base64 de `{"`)       | `['"]eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]+['"]` |
+| **URL com credentials** | `user:pass@` em URL                                | `https?://[^/\s:]+:[^/\s@]+@`                                          |
+| **Connection string**   | MongoDB, Postgres, MySQL, Redis                    | `(?:mongodb\|postgres\|mysql\|redis)://[^/\s:]+:[^/\s@]+@`             |
+| **SSH private key**     | Begin/end markers                                  | `-----BEGIN (?:RSA\|DSA\|EC\|OPENSSH) PRIVATE KEY-----`                |
+| **Arquivo de key**      | Extensoes de arquivo sensiveis                     | `\.(pem\|key\|p12\|pfx\|keystore)$` em arquivos tracked                |
+| **Base64 longa**        | Strings base64 suspeitas (>40 chars) em atribuicao | `['"][A-Za-z0-9+/=]{40,}['"]` proximo de `key\|secret\|token`          |
+
+---
+
+## .env Committed
+
+Verificar se `.env` esta no git:
+
+1. `git ls-files .env .env.local .env.production .env.staging` — se retorna algo, esta commitado
+2. Verificar `.gitignore` — se `.env` nao esta listado, qualquer .env futuro sera commitado
+
+---
+
+## Gitignore Audit
+
+Verificar que estes padroes estao em `.gitignore`:
+
+```
+# Secrets e credentials
+.env
+.env.local
+.env.production
+.env.staging
+*.pem
+*.key
+*.p12
+*.pfx
+*.keystore
+credentials.json
+service-account*.json
+*-credentials.json
+
+# IDE e sistema
+.idea/
+.vscode/settings.json
+*.swp
+.DS_Store
+
+# Databases locais
+*.sqlite
+*.sqlite3
+*.db
+```
+
+Se `.gitignore` nao tem estes padroes, reportar como ⚠ warning.
+
+Se algum destes arquivos ja esta tracked (`git ls-files`), reportar como 🔴 critical — precisam ser removidos do tracking com `git rm --cached`.
+
+---
+
+## Grep Patterns
+
+Regex prontos para busca automatizada com `Grep` tool.
+
+```
+AKIA[0-9A-Z]{16}
+AIza[0-9A-Za-z_-]{35}
+ghp_[0-9a-zA-Z]{36}
+gho_[0-9a-zA-Z]{36}
+sk_live_[0-9a-zA-Z]{24,}
+pk_live_[0-9a-zA-Z]{24,}
+xoxb-[0-9]{10,}
+xoxp-[0-9]{10,}
+sk-ant-[0-9a-zA-Z_-]{80,}
+sk-[0-9a-zA-Z]{48,}
+SG\.[0-9A-Za-z_-]{22}
+-----BEGIN\s+(?:RSA|DSA|EC|OPENSSH)\s+PRIVATE\s+KEY
+eyJ[A-Za-z0-9_-]{10,}\.eyJ
+(?:password|passwd|pwd|senha)\s*=\s*['"][^'"]+['"]
+(?:api_key|apikey|api_secret|secret_key)\s*=\s*['"][^'"]{10,}['"]
+https?://[^/\s:]+:[^/\s@]+@
+(?:mongodb|postgres|mysql|redis)://[^/\s:]+:[^/\s@]+@
+```

package/skills/hefesto-security/references/severity-and-judgment.md

@@ -0,0 +1,176 @@
+# Severidade e Julgamento
+
+Critérios universais para classificar findings, evitar falsos positivos e calibrar decisões de fix.
+
+## Quick Index
+
+- **Níveis de severidade** → "Severity Levels" (linha 14)
+- **Falhas silenciosas** → "Silent Failures" (linha 50)
+- **Quando NÃO reportar** → "When NOT to Report" (linha 108)
+- **SEMPRE reportar** → "When to ALWAYS Report" (linha 156)
+- **Migrations e schema** → "Migration and Schema Changes" (linha 172)
+
+---
+
+## Severity Levels
+
+### Critical — aplicar fix automaticamente
+
+Condições (independente de linguagem):
+
+- Erro completamente ignorado (catch vazio, erro descartado, bare except equivalente)
+- Processo pode crashar ou ficar em estado inconsistente
+- Panic/crash engolido sem log
+- Segredos de produção hardcoded
+- Input de usuário direto em code execution, shell commands, ou queries sem sanitização
+- Desserialização de dados não confiáveis usando deserializadores inseguros
+- Permissões excessivas de filesystem (world-writable)
+
+### Warning — aplicar fix se seguro, perguntar se altera comportamento
+
+Condições:
+
+- Erro logado mas não propagado (pode ser intencional)
+- Valor default pode confundir chamador (retorna `[]` ou `null` em vez de erro)
+- Catch/except muito amplo mas pelo menos trata o erro
+- Validação ausente em trust boundary
+- Configuração permissiva (CORS wildcard, debug mode, crypto fraco)
+- Rate limiting ausente em endpoints sensíveis (login, reset, signup)
+- Queries sem limit/pagination
+
+### Info — apenas reportar
+
+Condições:
+
+- Optional chaining ou null coalescing que pode ser intencional
+- Error handling via context managers sem except explícito
+- Configuração que pode ser intencional no contexto
+- Minor code smells sem impacto de segurança direto
+
+---
+
+## Silent Failures
+
+Falhas silenciosas são um dos riscos mais subestimados em segurança. Quando erros são engolidos, bugs ficam invisíveis em produção — incluindo bugs de segurança.
+
+### Categorias universais
+
+Estas categorias se aplicam a **qualquer linguagem** — os mecanismos mudam (try/catch, error returns, Result types, defer, promises), mas os anti-padrões são os mesmos:
+
+| Categoria                   | Definição                                                                                     | Severidade |
+| --------------------------- | --------------------------------------------------------------------------------------------- | ---------- |
+| **Swallowed errors**        | Erro capturado/retornado e completamente ignorado. Sem log, sem propagação, sem feedback      | critical   |
+| **Log-only handling**       | Erro logado mas execução continua como se fosse sucesso. Chamador não sabe que houve falha    | warning    |
+| **Deceptive defaults**      | Handler retorna valor indistinguível de sucesso (lista vazia, null, zero) sem indicar erro    | warning    |
+| **Overly broad catching**   | Captura todos os erros quando só específicos eram esperados, escondendo bugs não relacionados | warning    |
+| **Abandoned intent**        | Handler com TODO/FIXME — intenção de tratar nunca materializada                               | critical   |
+| **Panic/crash suppression** | Mecanismo de recovery (recover, catch-all, global handler) que suprime sem logar              | critical   |
+
+### O que procurar (por paradigma)
+
+| Paradigma                                                | Mecanismos a inspecionar                                                        |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| **Exception-based** (JS/TS, Python, Java, C#, Ruby, PHP) | try/catch/except blocks, promise .catch(), global exception handlers            |
+| **Error-return** (Go, Rust, C)                           | `_ = err`, `Result` não verificado, errno ignorado                              |
+| **Event-based** (Node.js, browsers)                      | EventEmitters sem handler de 'error', unhandled rejection handlers              |
+| **Async** (qualquer)                                     | Promises/Futures sem tratamento de rejeição, async sem try/catch em entrypoints |
+| **Deferred cleanup** (Go defer, Python with, C++ RAII)   | Erros em cleanup ignorados (ex: close() falha em escrita)                       |
+
+### Quando silenciamento é aceitável
+
+Não reportar como critical se:
+
+- **Cleanup code** — tentativa de deletar temp file em finally/defer. Falha não é crítica
+- **Feature detection** — testar se recurso existe, catch para saber que não existe
+- **Documentado** — catch com comentário explicando por que é intencional
+- **Best-effort** — operações explicitamente opcionais (ex: enviar analytics, prefetch de cache)
+
+---
+
+## When NOT to Report
+
+### Test code
+
+Arquivos em diretórios ou com padrões de teste:
+
+- `*.test.*`, `*.spec.*`, `__tests__/`, `test_*`, `*_test.go`, `*_test.py`, `*_test.rs`, `*Test.java`, `*_test.rb`, `tests/`, `spec/`
+- Exceção: se o teste usa input de PRODUÇÃO ou segredos reais → reportar
+
+### Static/literal input
+
+- O valor perigoso é uma string fixa no código, não controlada pelo usuário
+- `eval("2 + 2")` é code smell, não vulnerabilidade
+- Pode ser mencionado como ℹ info, nunca como 🔴 critical
+
+### Sanitization present
+
+- Existe validação/sanitização entre a fonte de input e a operação perigosa
+- Procurar: schema validation, type guards, sanitization functions, parameterized queries, middleware de validação
+- Se a sanitização está presente mas é insuficiente → reportar com contexto
+
+### Generated code
+
+- Arquivos com header de auto-geração, em diretórios de código gerado (ex: `components/ui/`, migrations geradas por ORM, código de protobuf)
+- Vulnerabilidades devem ser reportadas ao gerador, não corrigidas inline
+
+### Dependencies
+
+- Código em diretórios de dependência (`node_modules/`, `vendor/`, `site-packages/`, `.cargo/`, `Pods/`, etc.)
+- Escopo de ferramentas de auditoria de dependências, não desta revisão
+
+### Secret exceptions
+
+| Situação                                                             | Por quê                                                                |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Valores em `.env.example` / `.env.template`                          | Placeholders, não segredos reais                                       |
+| Referências a variáveis de ambiente (leitura, não valor)             | Estão usando env vars corretamente                                     |
+| Valores em arquivos de teste que são claramente mock                 | Fixtures intencionais                                                  |
+| Keys de modo teste de providers (ex: `sk_test_`, `pk_test_`)         | Keys de teste são públicas por design                                  |
+| Keys de exemplo em documentação                                      | Exemplos pedagógicos                                                   |
+| Variáveis marcadas como públicas pelo framework (ex: `NEXT_PUBLIC_`) | Intencionalmente públicas — mas verificar que não contêm secrets reais |
+
+---
+
+## When to ALWAYS Report
+
+Independente de contexto — estas são sempre vulnerabilidades:
+
+| Situação                                                                           | Por quê                                       |
+| ---------------------------------------------------------------------------------- | --------------------------------------------- |
+| Secrets de produção hardcoded (live API keys, SSH private keys, credentials reais) | Compromisso imediato se repositório é público |
+| `.env` com valores reais commitado no git                                          | Credenciais no git history permanentemente    |
+| Desserialização insegura de dados de rede                                          | Arbitrary code execution                      |
+| Shell execution com input de usuário não sanitizado                                | Command injection                             |
+| Permissões excessivas em filesystem (world-writable, 777)                          | Qualquer processo pode modificar              |
+| Private key no repositório                                                         | Compromisso criptográfico                     |
+
+---
+
+## Migration and Schema Changes
+
+### Operações destrutivas
+
+| Operação                     | Risco                                    | Verificação necessária                                           |
+| ---------------------------- | ---------------------------------------- | ---------------------------------------------------------------- |
+| DROP TABLE / DROP COLLECTION | Perda de dados irreversível              | Backup confirmado. Dados migrados antes                          |
+| DROP COLUMN / Remove field   | Perda de dados da coluna                 | Confirmar que campo não é usado. Deploy em fases                 |
+| TRUNCATE / Delete all        | Deleta todos os registros                | Nunca em migration de produção sem backup                        |
+| ALTER TYPE / Change schema   | Pode falhar com dados existentes         | Testar com dados reais. Considerar nova coluna + migrar + dropar |
+| RENAME                       | Quebra código que referencia nome antigo | Deploy em fases com período de compatibilidade                   |
+
+### Seed files
+
+- Sem passwords reais em seeds
+- Sem API keys de produção em dados de seed
+- Sem PII real (usar dados fake)
+- Guard de ambiente: seeds não devem ser executáveis em produção
+
+### Permissões
+
+| Contexto                 | Princípio                                                   |
+| ------------------------ | ----------------------------------------------------------- |
+| User da aplicação        | Apenas CRUD nas tabelas da app. Sem CREATE/DROP/ALTER/GRANT |
+| User de migration        | Pode ter DDL. Não deve ser usado pelo app em runtime        |
+| Connection string do app | Apontar para user da aplicação, não admin/root              |
+| Backups                  | SELECT apenas                                               |
+| Row-level security       | Habilitar em tabelas multi-tenant onde suportado            |