Webhook intake keeps verifying what it parses #2021

Closed
opened 2026-11-16 01:24:28 +00:00 by sam · 2 comments
Owner

The invariant is that a webhook's signature is verified before the payload is parsed. The new events module accepts a per-source bearer token instead, which is weaker: a leaked source token replays events, and the connector's own verifier (the old webhook verifier) is not used.

Grow the source contract so a source can declare its verification (HMAC scheme, token, or none) and the events module verifies in that order before it calls the connector's Parse. Keep the per-source token as one scheme, not the only one.

Done when: a source with an HMAC scheme rejects a payload whose signature is wrong, before the connector sees it, and the check has a test that fails without the verification.

The invariant is that a webhook's signature is verified before the payload is parsed. The new events module accepts a per-source bearer token instead, which is weaker: a leaked source token replays events, and the connector's own verifier (the old webhook verifier) is not used. Grow the source contract so a source can declare its verification (HMAC scheme, token, or none) and the events module verifies in that order before it calls the connector's Parse. Keep the per-source token as one scheme, not the only one. Done when: a source with an HMAC scheme rejects a payload whose signature is wrong, before the connector sees it, and the check has a test that fails without the verification.
sam added the bughigh labels 2026-11-16 01:24:28 +00:00
Author
Owner

Part of epic #1977. The dependency could not be recorded: this Gitea's dependency write endpoint answers 404 and the connector that used to add it is disconnected, so this comment carries the link.

Part of epic #1977. The dependency could not be recorded: this Gitea's dependency write endpoint answers 404 and the connector that used to add it is disconnected, so this comment carries the link.
Author
Owner

Fixed in 01eb4aaf7, 30b4c28e0 and f47e60db0 (migration 00042).

  • A source declares its verification scheme: token (the default, so existing sources keep working), hmac (header, optional prefix such as sha256=, shared secret) or none. Intake checks it on the raw body before the connector's Parse runs. A wrong or missing signature gets 401 and the connector never sees the body. An unknown source gets the same response, so source names can't be discovered by probing.
  • The HMAC secret is sealed at rest under a label bound to the org and source. The API only accepts it, never returns it, and it is never logged. The verifier ports the digest comparison from internal/webhookguard/hmac.go and the header handling from internal/infrastructure/captureintake/receiver.go.
  • Saving a source without a scheme keeps its stored scheme and credentials, so a source can't be downgraded by accident. A token is rotated only when token is chosen explicitly.
  • The dashboard's Sources page can add and edit the scheme, header, prefix and secret. A blank secret keeps the stored one.

Verified: TestHMACSourceVerifiesBeforeParsing is a table test with fakes that checks the status code and asserts Parse is never called. With the check disabled, 5 of its 7 cases failed. task check passed on the merged tree.

Not covered: algorithms other than SHA-256, and the old capture intake, which is unchanged. The per-address delivery policy stays with #2078.

Fixed in 01eb4aaf7, 30b4c28e0 and f47e60db0 (migration 00042). - A source declares its verification scheme: `token` (the default, so existing sources keep working), `hmac` (header, optional prefix such as `sha256=`, shared secret) or `none`. Intake checks it on the raw body before the connector's Parse runs. A wrong or missing signature gets 401 and the connector never sees the body. An unknown source gets the same response, so source names can't be discovered by probing. - The HMAC secret is sealed at rest under a label bound to the org and source. The API only accepts it, never returns it, and it is never logged. The verifier ports the digest comparison from `internal/webhookguard/hmac.go` and the header handling from `internal/infrastructure/captureintake/receiver.go`. - Saving a source without a scheme keeps its stored scheme and credentials, so a source can't be downgraded by accident. A token is rotated only when `token` is chosen explicitly. - The dashboard's Sources page can add and edit the scheme, header, prefix and secret. A blank secret keeps the stored one. Verified: `TestHMACSourceVerifiesBeforeParsing` is a table test with fakes that checks the status code and asserts Parse is never called. With the check disabled, 5 of its 7 cases failed. `task check` passed on the merged tree. Not covered: algorithms other than SHA-256, and the old capture intake, which is unchanged. The per-address delivery policy stays with #2078.
sam closed this issue 2026-11-21 03:51:37 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sam/archie#2021