A API foi projetada partindo do pressuposto de que cada chamada tem impacto financeiro direto e pode acessar credenciais sensíveis de servidor. Os requisitos de segurança estão, portanto, bem acima dos padrões REST.
Controles implementados
- HMAC-SHA256: Toda requisição é assinada com HMAC-SHA256 sobre método, caminho, timestamp, nonce e hash do corpo. Verificação em tempo constante (hash_equals).
- AES-256-GCM: Segredos são persistidos exclusivamente como texto cifrado AES-256-GCM (libsodium). A chave mestra fica fora do banco de dados em /etc/kh-reseller-api/master.key.v{N}.
- Replay protection: Janela de timestamp +-300s, cache de nonce de 600s. Uma requisição assinada com sucesso não pode ser repetida.
- Scope-based authorization: Lista explícita de escopos por chave API. Escopos de escrita e sensíveis precisam ser ativados explicitamente.
- IP whitelist (optional): Lista de IPs permitidos opcional por chave API (notação CIDR, IPv4 e IPv6).
- Rate limit: Multicamadas: por chave API (minuto e dia) e por IP (minuto). Token bucket com tolerância a burst.
- Idempotency: Pedidos e ações de serviço destrutivas exigem um Idempotency-Key. Proteção contra replay por 24h frente a retentativas de rede.
- Tenant isolation: Toda consulta ao banco filtra rigidamente pelo id da sua conta. Acesso entre tenants é impossível por construção.
- Tamper-evident audit log: Toda requisição entra no log de auditoria com chain hash (chain_hash[n] = sha256(chain_hash[n-1] || row_n)). Adulteração retroativa é detectada pela quebra do hash.
- Credentials.read alerting: Cada chamada credentials.read gera uma entrada dedicada no log de auditoria, além de um e-mail de confirmação opcional para o titular da conta.
- SSRF-guarded webhooks: URLs de webhook são validadas antes do armazenamento: somente HTTPS, e a resolução DNS deve retornar apenas IPs públicos (sem RFC1918, sem link-local).
Boas práticas do seu lado
- Guarde o segredo em um gerenciador de segredos (HashiCorp Vault, AWS Secrets Manager, Doppler, 1Password), nunca no código, nunca em um repositório git.
- Rotacione o segredo periodicamente (pelo menos anualmente ou após mudanças de pessoal). Rotação com um clique no portal, o segredo antigo é invalidado imediatamente.
- Uma chave API dedicada por caso de uso, com escopo mínimo (somente leitura, se possível). Nada de chaves "god mode".
- Se a sua integração roda a partir de IPs fixos (nuvem, bastion), defina uma lista de IPs permitidos.
- Gere o Idempotency-Key no servidor e persista-o; não gere um novo a cada retentativa. Recomendação: UUIDv4 por pedido lógico.
- Configure um webhook para a sua própria URL e acompanhe ao menos order.created e credentials.read como fluxo de eventos.
Divulgação de segurança
Por favor, reporte questões de segurança de forma confidencial para security@kernelhost.com. Chave PGP sob solicitação. Resposta em até 24h garantida. Programa de bug bounty em preparação.
