80 lines
2.5 KiB
Markdown
80 lines
2.5 KiB
Markdown
# WHMCS integration security
|
|
|
|
Security controls for the API-only link between WHMCS and HexaHost GameCloud.
|
|
|
|
## Trust model
|
|
|
|
- WHMCS is the **commercial system of record** (payments, invoices)
|
|
- GameCloud is the **technical system of record** (servers, nodes)
|
|
- Integration is **one-way authenticated API** — no shared database
|
|
|
|
## Authentication layers
|
|
|
|
### 1. HMAC request signing (required)
|
|
|
|
Every request to `/api/v1/integrations/whmcs/*` includes:
|
|
|
|
| Header | Purpose |
|
|
|--------|---------|
|
|
| `X-HGC-Integration-Id` | Installation identifier |
|
|
| `X-HGC-Timestamp` | Unix epoch seconds |
|
|
| `X-HGC-Signature` | HMAC-SHA256 of canonical request |
|
|
|
|
Secret: `WHMCS_API_SECRET` — rotate via [secrets](../../security/secrets.md).
|
|
|
|
Clock skew tolerance: ± 300 seconds. Sync NTP on both hosts.
|
|
|
|
### 2. mTLS (production recommended)
|
|
|
|
When `INTEGRATION_MTLS_ENABLED=true`:
|
|
|
|
- Client certificate required from WHMCS host
|
|
- Fingerprint registered in GameCloud installation record
|
|
- See [mtls](../mtls.md)
|
|
|
|
### 3. Network controls
|
|
|
|
- Allowlist WHMCS egress IP at firewall or Traefik
|
|
- No public exposure of WHMCS admin URL without 2FA
|
|
- API only on HTTPS (`api.example.net`)
|
|
|
|
## WHMCS hardening
|
|
|
|
| Control | Recommendation |
|
|
|---------|----------------|
|
|
| Admin 2FA | Required for all staff |
|
|
| File permissions | Module PHP not writable by web user |
|
|
| API Secret storage | WHMCS encrypted settings storage |
|
|
| Module logs | Restrict **Utilities → Logs** access |
|
|
| Hooks file | `includes/hooks/hexagamecloud.php` owned by root/deploy user |
|
|
|
|
## Least privilege
|
|
|
|
WHMCS server module credentials are **not** stored in WHMCS server username/password fields — only in addon encrypted settings. GameCloud API keys for customers are separate from integration secret.
|
|
|
|
## Audit
|
|
|
|
GameCloud logs integration calls with integration ID and action. WHMCS module log redacts secrets. Correlate by timestamp and `externalServiceId`.
|
|
|
|
## Incident response
|
|
|
|
On suspected secret leak:
|
|
|
|
1. Rotate `WHMCS_API_SECRET` on GameCloud first, then WHMCS addon
|
|
2. Review module log for anomalous provisioning
|
|
3. Run reconciliation dry-run
|
|
4. Re-register mTLS fingerprint if cert compromised
|
|
|
|
See [incident response](../../operations/incident-response.md).
|
|
|
|
## Compliance
|
|
|
|
- PCI: WHMCS handles card data; GameCloud never receives PAN
|
|
- GDPR: Customer PII flows in `upsertClient` — subject to [data retention](../../security/data-retention.md)
|
|
|
|
## Related
|
|
|
|
- [Configuration](configuration.md)
|
|
- [mTLS](../mtls.md)
|
|
- [Troubleshooting](troubleshooting.md)
|