47 lines
2.5 KiB
Markdown
47 lines
2.5 KiB
Markdown
# Gitea webhook threat model
|
|
|
|
Status: design gate only. Incoming webhooks are disabled and no webhook is
|
|
registered by DevRunbook. Periodic PostgreSQL-backed refresh remains the sole
|
|
automatic freshness mechanism for this release.
|
|
|
|
## Trust boundary
|
|
|
|
A webhook body, headers, event name, repository identity and delivery ID are
|
|
untrusted network input. They may request only the same bounded, read-only
|
|
snapshot job that an authorized refresh already creates. They must never carry
|
|
forge credentials, select a workspace directly, execute content or mutate a
|
|
repository.
|
|
|
|
## Mandatory controls before enabling an endpoint
|
|
|
|
- Authenticate the exact raw body with HMAC-SHA-256 and a per-integration
|
|
secret; compare the digest in constant time before parsing JSON.
|
|
- Require a signed timestamp within five minutes and a cryptographically
|
|
random delivery ID. Persist `(integration_id, delivery_id)` with a TTL and
|
|
atomically reject replays before enqueueing work.
|
|
- Resolve workspace and repository exclusively from the authenticated
|
|
integration and allowlisted remote identity. Never trust workspace IDs or
|
|
callback URLs supplied by the body.
|
|
- Limit the raw body before buffering, allowlist push/default-branch and
|
|
repository-change events, validate content type and reject unknown fields.
|
|
- Apply independent per-source-IP, per-integration and per-workspace token
|
|
buckets before database work. Return `429` with bounded jitter and never
|
|
bypass the normal queue's deduplication or retry limits.
|
|
- Use the existing snapshot preflight and idempotency contract. A delivery may
|
|
enqueue work but cannot force full analysis or create a profile revision.
|
|
- Log only a hashed delivery ID, integration ID, event class and safe outcome.
|
|
Never log the signature, raw body, token or repository content.
|
|
- Respond with generic errors so signature, tenant and repository existence
|
|
cannot be enumerated. Keep last-known-good snapshots on every failure.
|
|
|
|
## Required verification gate
|
|
|
|
The feature stays disabled until integration tests prove valid/invalid
|
|
signatures, raw-byte verification, expired/future timestamps, replay races,
|
|
body limits, event allowlisting, flood limits, queue deduplication and strict
|
|
cross-workspace isolation. Deployment documentation must also cover secret
|
|
rotation with an explicitly bounded overlap window and immediate revocation.
|
|
|
|
This keeps the Gitea integration read-only: webhook registration itself is an
|
|
operator action outside DevRunbook, and the callback can only schedule reads.
|