모든 호출이 직접적인 재무 영향을 발생시킬 수 있고 민감한 서버 자격증명에 접근할 수 있다는 전제로 설계됐어요. 보안 요구사항은 일반적인 REST 기본값보다 훨씬 높아요.
적용된 보호 메커니즘
- HMAC-SHA256: 모든 요청은 메서드, 경로, 타임스탬프, 논스, 본문 해시에 대해 HMAC-SHA256으로 서명돼요. 검증은 상수 시간(hash_equals)으로 수행돼요.
- AES-256-GCM: 시크릿은 AES-256-GCM 암호문(libsodium)으로만 저장돼요. 마스터 키는 데이터베이스 외부 /etc/kh-reseller-api/master.key.v{N}에 보관돼요.
- Replay protection: 타임스탬프 허용 범위 +-300초, 논스 캐시 600초. 성공적으로 서명된 요청은 재전송하실 수 없어요.
- Scope-based authorization: 키마다 명시적인 권한 범위 목록. 쓰기 및 민감한 권한 범위는 명시적으로 활성화해야 해요.
- IP whitelist (optional): 키마다 선택적 IP 허용 목록 (CIDR 표기, IPv4 및 IPv6 지원).
- Rate limit: 다중 계층 적용: 키 단위(분, 일) 및 IP 단위(분). 버스트 허용 토큰 버킷.
- Idempotency: 주문 및 파괴적인 서비스 액션에는 Idempotency-Key가 필요해요. 네트워크 재시도에 대해 24시간 재전송 방어가 적용돼요.
- Tenant isolation: 모든 데이터베이스 쿼리가 계정 ID로 강제 필터링돼요. 다른 테넌트 접근은 구조적으로 불가능해요.
- Tamper-evident audit log: 모든 요청은 체인 해시(chain_hash[n] = sha256(chain_hash[n-1] || row_n))와 함께 감사 로그에 기록돼요. 사후 변조는 해시 불일치로 즉시 감지돼요.
- Credentials.read alerting: credentials.read 호출마다 전용 감사 항목이 생성되며, 선택적으로 계정 소유자에게 확인 메일이 발송돼요.
- SSRF-guarded webhooks: 웹훅 URL은 저장 전에 검증돼요: HTTPS만 허용되며, DNS 해석 결과는 공개 IP만 가능해요(RFC1918, 링크 로컬 차단).
리셀러 측 모범 사례
- 시크릿은 시크릿 관리 도구(HashiCorp Vault, AWS Secrets Manager, Doppler, 1Password)에 저장해 주세요. 코드나 git 저장소에는 절대 두지 마세요.
- 시크릿을 정기적으로 회전해 주세요(최소 연 1회 또는 인사 변동 시). 고객 포털에서 클릭 한 번으로 회전 가능하며, 기존 시크릿은 즉시 무효화돼요.
- 용도마다 별도의 키를 발급하시고 최소 권한 범위(가능하면 읽기 전용)만 부여해 주세요. "전능 키"는 만들지 마세요.
- 통합 환경이 고정 IP에서 실행되시는 경우(클라우드, 베스천): IP 허용 목록을 설정해 주세요.
- Idempotency-Key는 서버 측에서 생성해 영속화해 주세요. 재시도마다 새로 생성하지 마시고, 논리적 주문마다 UUIDv4를 권장해요.
- 자체 URL로 웹훅을 설정하시고 최소 order.created 및 credentials.read를 이벤트 스트림으로 모니터링해 주세요.
보안 취약점 공개
보안 이슈는 security@kernelhost.com로 비공개로 제보해 주세요. PGP 키는 요청 시 제공해 드려요. 24시간 이내 회신을 보장해 드려요. 버그 바운티 프로그램도 준비 중이에요.
