API zostało zaprojektowane przy założeniu, że każde wywołanie ma bezpośredni wpływ finansowy i może umożliwiać dostęp do poufnych danych dostępowych serwerów. Wymagania bezpieczeństwa są dlatego znacznie wyższe niż standardowe REST.
Wdrożone mechanizmy ochronne
- HMAC-SHA256: Każde żądanie jest podpisywane HMAC-SHA256 obejmującym metodę, ścieżkę, znacznik czasu, nonce oraz skrót treści. Weryfikacja w czasie stałym (hash_equals).
- AES-256-GCM: Tajne klucze są utrwalane wyłącznie jako szyfrogramy AES-256-GCM (libsodium). Klucz główny znajduje się poza bazą danych w /etc/kh-reseller-api/master.key.v{N}.
- Replay protection: Okno znacznika czasu +-300s, pamięć podręczna nonce 600s. Pomyślnie podpisane żądanie nie może zostać odtworzone ponownie.
- Scope-based authorization: Jawna lista zakresów uprawnień dla każdego klucza. Zakresy zapisujące i wrażliwe muszą być włączone w sposób jawny.
- IP whitelist (optional): Opcjonalna biała lista IP dla każdego klucza (notacja CIDR, IPv4 oraz IPv6).
- Rate limit: Wielowarstwowy: na klucz (minuta + dzień) i na IP (minuta). Token bucket z tolerancją burst.
- Idempotency: Zamówienia i destrukcyjne akcje serwisowe wymagają nagłówka Idempotency-Key. Ochrona przed powtórzeniami przez 24h przy ponownych próbach sieciowych.
- Tenant isolation: Każde zapytanie do bazy danych filtruje twardo po identyfikatorze Państwa konta. Dostęp międzylokatorski jest niemożliwy z konstrukcji.
- Tamper-evident audit log: Każde żądanie trafia do dziennika audytu z chain-hash (chain_hash[n] = sha256(chain_hash[n-1] || row_n)). Retrospektywna manipulacja jest wykrywana przez przerwanie łańcucha skrótów.
- Credentials.read alerting: Każde wywołanie credentials.read tworzy dedykowany wpis audytu oraz opcjonalny e-mail potwierdzający do właściciela konta.
- SSRF-guarded webhooks: URL-e webhooków są sprawdzane przed zapisem: wyłącznie HTTPS, rozwiązanie DNS musi zwracać tylko publiczne adresy IP (bez RFC1918, bez link-local).
Dobre praktyki po Państwa stronie
- Tajny klucz proszę przechowywać w menedżerze sekretów (HashiCorp Vault, AWS Secrets Manager, Doppler, 1Password), nigdy w kodzie ani w repozytorium git.
- Tajny klucz proszę regularnie rotować (przynajmniej raz w roku lub po zmianach kadrowych). Rotacja w panelu klienta jednym kliknięciem, stary klucz zostaje natychmiast unieważniony.
- Dla każdego przypadku użycia jeden dedykowany klucz z minimalnym zakresem uprawnień (jeśli to możliwe, tylko do odczytu). Bez kluczy w trybie "god mode".
- Jeżeli integracja działa ze stałych adresów IP (chmura, bastion), proszę ustawić białą listę IP.
- Idempotency-Key proszę generować po stronie serwera i utrwalać, a nie generować świeży przy każdej próbie ponowienia. Zalecenie: UUIDv4 na każde logiczne zamówienie.
- Proszę ustawić webhook na własny URL i obserwować jako strumień zdarzeń co najmniej order.created oraz credentials.read.
Zgłaszanie podatności
Podatności bezpieczeństwa prosimy zgłaszać poufnie na security@kernelhost.com. Klucz PGP na życzenie. Reakcja w ciągu 24h gwarantowana. Program bug bounty w przygotowaniu.
