> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ghostable.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Security Controls Matrix
> Map Ghostable security controls to threats and evidence you can validate.
Use this matrix to assess where Ghostable controls align with common security concerns and what
evidence is available to reviewers.
## Controls Matrix
| Concern | Ghostable Control | Evidence |
| :---------------------------------- | :------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Client supply-chain tampering | Release checksums + signed build provenance + SBOM publication | Release assets: `SHA256SUMS`, SBOM, and provenance evidence (CLI public; server and desktop internal/private, with attestation support dependent on repository visibility and plan) |
| In-transit confidentiality | TLS transport and signed client payloads for secret updates | API request signatures (`client_sig`) |
| Push race conditions / lost updates | Optimistic concurrency via `if_version`, strict conflict mode, explicit force override | API 409 conflict payloads (`conflicts[]`), CLI `--conflict-mode` and `--force-overwrite` |
| Unauthorized push attempts | Device ownership validation and revocation checks | Push API rejects unknown/revoked devices |
| Least-privilege access | Role + permission model with scoped project/environment operations | Organization roles/permissions and permission matrix endpoint |
| External monitoring visibility | Audit webhook destinations with signed event delivery, retries, and dead-letter state | Audit webhook API + delivery status fields |
| Auditability | Structured activity logging across org/project/environment actions | Organization/project/environment history endpoints and activity export |
| SaaS dependency resilience | Encrypted backup + restore workflows | `backup create` / `backup restore` command flow |
## API Endpoints for Evidence Collection
* `GET /api/v2/organizations/{organization}/permission-matrix`
* `GET /api/v2/organizations/{organization}/audit-webhooks`
* `GET /api/v2/organizations/{organization}/audit-webhooks/metrics?window=24h|7d|30d`
* `POST /api/v2/organizations/{organization}/audit-webhooks`
* `POST /api/v2/organizations/{organization}/audit-webhooks/{auditWebhook}/rotate-secret`
* `POST /api/v2/organizations/{organization}/audit-webhooks/{auditWebhook}/disable`
* `POST /api/v2/organizations/{organization}/audit-webhooks/{auditWebhook}/test`
* `GET /api/v2/organizations/{organization}/audit-webhooks/metrics`
## Dashboard UI: Audit Webhooks
Audit webhooks can be managed in the Ghostable dashboard:
1. Open your organization in Ghostable.
2. Go to **Settings**.
3. Open the **Notifications** tab.
4. Use the **Audit Webhooks** section.
{/* ghostable:screenshot-output fundamentals-audit-webhooks:start */}
### What You Can Do in the UI
* Create a webhook with:
* a friendly name (for example, `Security SIEM`)
* an endpoint URL (`https://...`)
* Copy the signing secret shown once at creation/rotation time.
* Review delivery health fields:
* status (`active`, `disabled`, `dead_letter`)
* consecutive failures
* last delivery/error details
* Open the delivery metrics popover for a webhook to see attempt rates and latency buckets.
* Use the action dropdown per webhook row:
* **Send test event**
* **Rotate signing secret**
* **Disable webhook**
* Review delivery metrics:
* selected time window (`24h`, `7d`, `30d`)
* attempts, successes, failures, and success rate
* p50/p95/p99 latency + latency bucket distribution
Only organization admins can create or manage audit webhooks in the dashboard UI.
## API Contract Examples
### Version conflict payload (`409`)
Ghostable normalizes optimistic lock conflicts to a deterministic API shape:
```json theme={null}
{
"error": {
"code": "version_conflict",
"message": "Version conflict detected for one or more keys.",
"status": 409
},
"conflicts": [
{
"key": "APP_KEY",
"server_version": 12,
"client_if_version": 11
}
]
}
```
### Audit webhook metrics payload (`200`)
```json theme={null}
{
"window": "24h",
"summary": {
"attempted": 320,
"succeeded": 315,
"failed": 5,
"success_rate": 98.44,
"dead_lettered_webhooks": 0,
"latency": {
"p50_ms": 81,
"p95_ms": 403,
"p99_ms": 844
}
},
"webhooks": [
{
"id": "01H...",
"name": "Security SIEM",
"status": "active",
"attempted": 160,
"succeeded": 158,
"failed": 2,
"success_rate": 98.75,
"latency": {
"p50_ms": 79,
"p95_ms": 390,
"p99_ms": 801
},
"latency_buckets": {
"0_100_ms": 112,
"101_300_ms": 35,
"301_1000_ms": 13,
"1001_3000_ms": 0,
"3001_plus_ms": 0
},
"last_error": null
}
]
}
```
See [SIEM template mappings](/fundamentals/v2/security-and-operations/siem-audit-webhook-templates)
for ingestion examples.
## Webhook Signature Verification
Ghostable audit webhooks include the following headers:
* `X-Ghostable-Timestamp`: unix timestamp in seconds.
* `X-Ghostable-Signature`: HMAC in the format `sha256=`.
To verify a delivery:
1. Read the raw request body exactly as received.
2. Build the signed message as `.`.
3. Compute `HMAC-SHA256(message, signing_secret)`.
4. Compare the result to `X-Ghostable-Signature` using constant-time comparison.
5. Reject the request if `abs(now - timestamp) > 300` seconds.
For replay protection, cache each webhook event `id` for at least 5-10 minutes and reject
duplicates.
## Notes
* `push_force_overwrite` activity events are emitted when optimistic locking is intentionally
bypassed.
* Teams with strict change control should require `--conflict-mode strict` in CI workflows.