feat: package as a Claude Code plugin with a deterministic quality gate
Workflows move to skills/<name>/SKILL.md so the repo installs as a plugin. scripts/quality-gate runs only the checks of the requested tier on the diff and reports missing tools as unverified instead of passing them. Hooks block stopping on a failed or stale gate, guard destructive shell commands and format edited files with the project's own formatter. Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
EvandroandClaude Opus 5.5 committed
1 parent
18c2304575
commit
768b5f6d83
12 files changed
+535
No files matched your search
@@ -0,0 +1,281 @@
|
||||
---
|
||||
name: wf-backend
|
||||
description: "Use p/ backend/API. Fluxo PLAN→BUILD→SECURITY→TEST."
|
||||
version: 1.0.0
|
||||
author: Hermes Agent
|
||||
license: MIT
|
||||
platforms: [linux, macos, windows]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [backend, api, security, rest, sql, auth, workflow]
|
||||
---
|
||||
|
||||
# Workflow Backend/API
|
||||
|
||||
Orquestrador obrigatório para TODO trabalho backend: APIs REST/GraphQL,
|
||||
autenticação, banco de dados, integrações, serviços, jobs. Processo de 4
|
||||
fases com skills fixas.
|
||||
|
||||
## When to Use
|
||||
|
||||
Sempre que a tarefa envolver servidor: criar/editar endpoints, auth, schema
|
||||
DB, integrações, filas, webhooks, ou revisar segurança de backend/models.
|
||||
|
||||
## Skills do stack (carregar conforme a fase)
|
||||
|
||||
- Segurança multi-stack: `secure-coding` (15 stacks)
|
||||
- Segurança de API (OWASP): `api-security-review`, `bola-detector`,
|
||||
`auth-rbac-scaffold`, `injection-checker`, `openapi-hardener`,
|
||||
`security-test-generator`
|
||||
- Bug hunting adversarial: `hermaguard` (pre-scan + 3 agentes — edge cases,
|
||||
ataque, blast radius; read-only, encontra o que está quebrado)
|
||||
- Locais: `fastapi-uvicorn-wiring` (Python), `rest-graphql-debug`,
|
||||
`software-code-quality`, `dependency-cve-audit`, `security-best-practices`,
|
||||
`test-driven-development`, `network-audit`
|
||||
|
||||
## Fase 1 — PLAN (contrato antes de código)
|
||||
|
||||
1. Definir API contract primeiro: rotas, métodos, payloads, status codes,
|
||||
erros (RFC 9457 / RFC 7807), rate limit, versionamento.
|
||||
2. Validar schema: `openapi-hardener` — OpenAPI/Zod/Pydantic saneado antes
|
||||
de escrever handler.
|
||||
3. Definir modelo de dados + migração (idempotente) ANTES de query.
|
||||
4. Decidir auth: sessão/OAuth/JWT com base no contexto; documentar.
|
||||
5. Approved do contrato pelo usuário antes de build.
|
||||
6. VERIFICAR: validar o contrato com `openapi-hardener` (schemas coerentes),
|
||||
conferir rate limit + versionamento definidos, e confirmar que o modelo
|
||||
de dados tem migração idempotente antes de construir.
|
||||
7. VERIFICAR (comandos de plano): usar `curl` para provar o contrato contra
|
||||
um stub (ex: `curl -i localhost:PORT/health`) e `git log`/branches para
|
||||
confirmar que o contrato fica versionado no repo.
|
||||
8. CHECKPOINT: registrar contrato em `docs/contract.md` (ou OpenAPI) para as
|
||||
fases seguintes referenciarem.
|
||||
9. VERIFICAR (comandos de contrato completo): `grep -c "->" docs/contract.md` — todas as rotas têm status codes esperados; e `grep -c "429\|rate" docs/contract.md` para provar que rate limit está no contrato.
|
||||
10. VERIFICAR (auth no contrato): `grep -rn "auth\|bearer\|session" docs/contract.md` — decidir e documentar o modelo de auth ANTES do build (não deixar para a Fase 2/3).
|
||||
11. VERIFICAR (validação de contrato): se OpenAPI, `python3 -m json.tool docs/openapi.json > /dev/null` para provar que o schema é válido em JSON.
|
||||
|
||||
**Checklist da fase 1 (validar antes do build):**
|
||||
- [ ] Rotas/métodos/payloads/status codes definidos e aprovados.
|
||||
- [ ] Erros no padrão RFC 9457/7807; rate limit e versionamento especificados.
|
||||
- [ ] `openapi-hardener` validou os schemas (Zod/Pydantic/OpenAPI).
|
||||
- [ ] Migração de dados idempotente desenhada antes de qualquer query.
|
||||
|
||||
**Anti-padrões desta fase:**
|
||||
- NUNCA escrever handler sem contrato aprovado.
|
||||
- NUNCA deixar schema "se inferir na mão livre" — definir e validar.
|
||||
- NÃO esquecer rate limit/versionamento na fase 1 (correção é cara depois).
|
||||
- NÃO misturar payload v2 com contrato v1 sem versionamento explícito.
|
||||
|
||||
## Fase 2 — BUILD (escrever com defaults seguros)
|
||||
|
||||
1. `secure-coding` — aplicar padrões da stack em uso (Node/FastAPI/Go/etc).
|
||||
2. Validação na borda (Zod/Pydantic), erros estruturados, timeouts em
|
||||
clientes HTTP e DB, idempotência em mutações.
|
||||
3. Argon2id p/ senhas, httpOnly cookies p/ sessões, nunca logar segredos.
|
||||
4. Type-safe boundaries; evitar `any`/`as` descontrolados em TS.
|
||||
5. VERIFICAR: rodar `secure-coding` como checklist da stack (validação na
|
||||
borda, timeouts, idempotência) e `rest-graphql-debug` para confirmar
|
||||
que os status codes/mensagens batem com o contrato da Fase 1.
|
||||
6. VERIFICAR (timeouts): para todo cliente HTTP do serviço, confirmar
|
||||
`timeout` definido — `grep -rn "requests\|fetch(" src/ | wc -l` contra
|
||||
o número de `timeout` presentes; igual = OK.
|
||||
7. VERIFICAR (redação de segredos): `grep -rniE "password|secret|token" src/ --include="*.py" --include="*.ts" | grep -i "log\|print"` — zero
|
||||
hits é o esperado (nenhum segredo sendo logado).
|
||||
8. VERIFICAR (queries): conferir que toda listagem tem `LIMIT` — checar
|
||||
com `search_files` as chamadas sem paginação antes de seguir.
|
||||
|
||||
**Checklist da fase 2 (build seguro):**
|
||||
- [ ] Validação na borda (Zod/Pydantic) em TODA entrada externa.
|
||||
- [ ] Erros estruturados; timeouts em clientes HTTP e DB.
|
||||
- [ ] Mutações idempotentes; transações onde há múltiplas gravações.
|
||||
- [ ] Senhas com Argon2id; sessões httpOnly; nenhum segredo em log.
|
||||
- [ ] Type-safe boundaries; sem `any` solto no que atravessa a fronteira.
|
||||
|
||||
**Anti-padrões desta fase:**
|
||||
- NUNCA logar senha/token/dado sensível.
|
||||
- NUNCA confiar em input externo sem validação na borda.
|
||||
- NÃO fazer query sem LIMIT/paginação em listas não limitadas.
|
||||
- NÃO engolir erro com `except: pass` / catch vazio (mascara falha).
|
||||
|
||||
## Fase 3 — SECURITY (auditar tudo)
|
||||
|
||||
1. `bola-detector` em rotas com `:id`/`findUnique` (Object-Level Authz).
|
||||
2. `auth-rbac-scaffold` em qualquer fluxo de JWT/login/roles.
|
||||
3. `injection-checker` em SQL/ORM/shell/templates.
|
||||
4. `api-security-review` no conjunto final (OWASP API Top 10).
|
||||
5. `dependency-cve-audit` nas deps do projeto (local).
|
||||
6. VERIFICAR: consolidar achados P0/P1 por severidade, validar que cada
|
||||
rota sensível tem auth + ownership-scope, e re-auditar depois de
|
||||
qualquer fix (nada de despachar cego).
|
||||
7. VERIFICAR (ownership): para rotas com `:id`, conferir que a query usa o
|
||||
ID autenticado — `grep -rn "user_id\|user.id\|req.user" src/ | wc -l`
|
||||
>= número de rotas protegidas.
|
||||
8. VERIFICAR (rate limit): `grep -rniE "ratelimit|rate_limit|limiter" src/`
|
||||
— toda rota de escrita tem rate limit de referência; se ausente, anotar
|
||||
como P2.
|
||||
9. VERIFICAR (headers/CORS): conferir CSP/CORS configurados (CORS
|
||||
allowlist explícita, não `*` com credenciais); `grep -rn "access-control\|csp\|content-security" src/`.
|
||||
10. VERIFICAR (re-audit pós-fix): após corrigir P0/P1, re-rodar
|
||||
`bola-detector` + `api-security-review` e confirmar que os achados
|
||||
sumiram (não só mudaram de arquivo).
|
||||
11. VERIFICAR (critério de aceite de segurança): para cada achado P0/P1,
|
||||
reexecutar o teste que o reproduzia e confirmar que agora passa;
|
||||
manter o PoC no repositório de testes.
|
||||
12. VERIFICAR (comandos de confirmação): `grep -c "auth\|ownership" src/`
|
||||
deve ser >= número de rotas que mexem em dado de usuário — cada rota
|
||||
sensível tem o controle por objeto documentado no código.
|
||||
|
||||
**Checklist da fase 3 (segurança):**
|
||||
- [ ] `bola-detector` limpo em rotas com `:id` (object-level authz).
|
||||
- [ ] Auth/RBAC (`auth-rbac-scaffold`) cobrindo roles e sessions.
|
||||
- [ ] `injection-checker` limpo (SQL/ORM/shell/templates).
|
||||
- [ ] `api-security-review` sem P0/P1 (OWASP API Top 10).
|
||||
- [ ] `dependency-cve-audit` sem CVEs críticas pendentes.
|
||||
|
||||
**Anti-padrões desta fase:**
|
||||
- NUNCA definir query escopada por outro ID que não o autenticado.
|
||||
- NUNCA aceitar finding P0/P1 sem evidência de correção.
|
||||
- NÃO revisar segurança só nos endpoints novos — escopar também os existentes.
|
||||
- NÃO tratar auditoria como checklist burocrático: achado não resolvido bloqueia.
|
||||
|
||||
## Fase 4 — TEST + BUG HUNT (provar antes de entregar)
|
||||
|
||||
1. `hermaguard` no diff do backend — dispachar os 3 agentes adversariais
|
||||
(Edge Case Hunter, Adversarial Reviewer, Blast Radius). Esperar falhar:
|
||||
NUNCA parar em "parece ok"; exigir cobertura de edge cases, races,
|
||||
rollback safety e schema drift. Read-only (não corrige — acha).
|
||||
2. `test-driven-development`: testar o que valida/auth/idempotência.
|
||||
3. `security-test-generator`: testes de segurança (authz negativa,
|
||||
payloads malformados, rate limit).
|
||||
4. Rodar suíte + lint + typecheck; status real, não suposição.
|
||||
5. Corrigir os findings P0/P1 do hermaguard como tarefas separadas; rodar
|
||||
hermaguard de novo se o fix mudou >3 arquivos.
|
||||
6. Relatório: contrato entregue, achados de segurança P0/P1/P2 resolvidos,
|
||||
bugs caçados pelo hermaguard (por severidade), testes passando (contagem).
|
||||
7. VERIFICAR (não-regressão QA): rodar `test_quality.py` (gate do workflow)
|
||||
— score não pode cair em relação ao baseline.
|
||||
8. VERIFICAR (cobertura de classes): para rolls em produção, conferir que
|
||||
o hermaguard cobriu edge cases, races, rollback safety e schema drift —
|
||||
não aceitar "sem achados" sem essa cobertura.
|
||||
9. VERIFICAR (efeito colateral): se a mudança alterou contrato/DB, rodar
|
||||
`rest-graphql-debug` para confirmar status codes e mensagens sem
|
||||
regressão.
|
||||
10. VERIFICAR (cobertura de testes real): `python3 -m pytest --cov=app -q`
|
||||
(ou `npm test -- --coverage`) — anotar % de cobertura e garantir que
|
||||
os módulos críticos (auth, validação, idempotência) têm pelo menos
|
||||
smoke test.
|
||||
11. VERIFICAR (migração reversível): se houve schema change, rodar
|
||||
`alembic downgrade -1`/equivalente em dev para provar rollback; e
|
||||
`git diff --stat` para conferir o escopo do que está indo pra frente.
|
||||
12. VERIFICAR (config por ambiente): `grep -rn "getenv\|os.environ\|process.env" src/` — toda configuração via env, sem valores hardcoded que
|
||||
vazam para prod.
|
||||
13. VERIFICAR (comandos de entrega): `python3 -m pytest -q && npm run build` (ou stack equivalente) como smoke final; e `git status` para
|
||||
confirmar que os artefatos de teste não vazaram pro repo.
|
||||
14. VERIFICAR (critério de entrega): relatório final só fecha quando cada
|
||||
item do checklist da Fase 4 está marcado — sem exceção de última hora
|
||||
não auditada.
|
||||
|
||||
**Checklist da fase 4 (gate de entrega):**
|
||||
- [ ] `hermaguard` rodado; findings CRITICAL/HIGH zero ou com plano de fix.
|
||||
- [ ] TDD: testes de validação, auth e idempotência verdes.
|
||||
- [ ] `security-test-generator`: authz negativa, payloads mal, rate limit.
|
||||
- [ ] Suíte + lint + typecheck verdes (contagem real, não suposição).
|
||||
- [ ] Findings P0/P1 corrigidos e re-verificados (hermaguard rodado de novo
|
||||
se o fix alterou >3 arquivos).
|
||||
|
||||
**Anti-padrões desta fase:**
|
||||
- NUNCA rodar hermaguard em código com testes quebrados (polui o review).
|
||||
- NUNCA dar "suíte passando" sem ter executado a suíte.
|
||||
- NÃO aceitar "hermaguard não achou nada" sem exigir a cobertura por classe
|
||||
(edge cases, races, rollback, schema drift).
|
||||
- NÃO reportar achado P0/P1 como resolvido sem a verificação de volta.
|
||||
|
||||
## Comandos de Verificação (executáveis)
|
||||
|
||||
```bash
|
||||
# Gate de qualidade do próprio workflow (sem regressão)
|
||||
python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py
|
||||
|
||||
# Testes + meta-testes (prova que o harness detecta regressão)
|
||||
python3 ~/.hermes/skills/software-development/wf-qa/test_tests.py
|
||||
|
||||
# Audit OWASP de um endpoint/controller
|
||||
# (skill api-security-review) — veja a skill
|
||||
|
||||
# CVE nas deps do projeto
|
||||
# (skill dependency-cve-audit) — veja a skill
|
||||
|
||||
# Bug hunt adversarial no diff (read-only)
|
||||
# (skill hermaguard: "hermaguard this")
|
||||
```
|
||||
|
||||
## Critérios de Aceite (checklist não-regressivo)
|
||||
|
||||
- [ ] Contrato aprovado (PLAN) antes de qualquer handler.
|
||||
- [ ] BUILD com defaults seguros; `secure-coding` validado na stack.
|
||||
- [ ] SECURITY: bola/auth/injection/api-review/CVE rodados; P0/P1 resolvidos.
|
||||
- [ ] TEST: hermaguard + TDD + security-test-generator; suíte verde com
|
||||
contagem real.
|
||||
- [ ] Nenhuma skill do stack removida do arquivo.
|
||||
- [ ] Rodar `python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py`
|
||||
→ exit 0 (sem regressão).
|
||||
|
||||
## Exemplos de execução por fase (comandos reais)
|
||||
|
||||
Fase 1 — validar contrato antes de codar:
|
||||
|
||||
```bash
|
||||
# Lista de rotas planejadas (contrato em aberto)
|
||||
cat > docs/contract.md <<'EOF'
|
||||
POST /api/v1/users -> 201 | 400 | 401 | 409 | 429
|
||||
GET /api/v1/users/:id -> 200 | 404 | 403
|
||||
Erros: RFC 9457 (application/problem+json)
|
||||
EOF
|
||||
```
|
||||
|
||||
Fase 2 — build seguro (exemplo FastAPI + Pydantic):
|
||||
|
||||
```bash
|
||||
# Rodar a stack e conferir a OpenAPI gerada
|
||||
uvicorn app.main:app --reload # ou npm run dev
|
||||
curl -s localhost:8000/openapi.json | python3 -m json.tool > /tmp/openapi.json
|
||||
python3 -c "import sys,json; d=json.load(open('/tmp/openapi.json')); print('schemas:', len(d.get('components',{}).get('schemas',{})))"
|
||||
|
||||
# Validação de contrato contra a OpenAPI real
|
||||
curl -s localhost:8000/health -i | head -5 # status codes do health
|
||||
curl -s -X POST localhost:8000/api/v1/users -d '{}' -i | head -5 # 400 esperado
|
||||
```
|
||||
|
||||
Fase 3 — auditoria de segurança:
|
||||
|
||||
```bash
|
||||
# Rodar as skills de auditoria OWASP (veja cada skill p/ uso exato)
|
||||
# bola-detector: "audite rotas com :id" / auth-rbac-scaffold: "valide o fluxo de login"
|
||||
# injection-checker: "escaneie SQL/ORM" / api-security-review: "revisão OWASP do conjunto"
|
||||
# dependency-cve-audit: "audite as dependências" (skill local)
|
||||
```
|
||||
|
||||
Fase 4 — testes e bug hunt:
|
||||
|
||||
```bash
|
||||
python3 -m pytest -v # ou npm test
|
||||
python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py # gate do workfl
|
||||
# "hermaguard this" (bug hunt adversarial no diff)
|
||||
```
|
||||
|
||||
Gates anti-regressão (rodar junto com o fluxo):
|
||||
|
||||
```bash
|
||||
python3 ~/.hermes/skills/software-development/wf-qa/test_tests.py # teste dos testes
|
||||
# verifica que o harness DETECTA regressão (mutações sempre derrubam o score)
|
||||
python3 -m pytest tests/security/ -x # se existir suíte de segurança
|
||||
```
|
||||
|
||||
## Regras duras
|
||||
|
||||
- NUNCA escrever handler antes do contrato aprovado.
|
||||
- NUNCA entregar endpoint sem passar pelas 4 fases (security + testes +
|
||||
hermaguard).
|
||||
- Rota que mexe em dado do usuário → ownership-check obrigatório (query
|
||||
escopada ao ID autenticado).
|
||||
- Tests vermelhos = fixar primeiro; hermaguard não roda em código quebrado.
|
||||
Reference in new issue
Block a user