AWS devopsagent documentation change
Summary
Added HMAC authentication documentation, comparison table between HMAC/Bearer tokens, and payload schema for incident webhooks
Security assessment
The change adds detailed documentation about HMAC authentication security features including cryptographic verification, replay protection, and risk comparisons. This enhances security awareness but doesn't address a specific vulnerability.
Diff
diff --git a/devopsagent/latest/userguide/configuring-capabilities-for-aws-devops-agent-invoking-devops-agent-through-webhook.md b/devopsagent/latest/userguide/configuring-capabilities-for-aws-devops-agent-invoking-devops-agent-through-webhook.md index f563c4f3f..c0717ea8d 100644 --- a//devopsagent/latest/userguide/configuring-capabilities-for-aws-devops-agent-invoking-devops-agent-through-webhook.md +++ b//devopsagent/latest/userguide/configuring-capabilities-for-aws-devops-agent-invoking-devops-agent-through-webhook.md @@ -63,0 +64 @@ The authentication method for your webhook depends on which integration it's ass + * Grafana integration webhooks @@ -66,0 +68,17 @@ The authentication method for your webhook depends on which integration it's ass + +### Understanding HMAC authentication + +HMAC (Hash-based Message Authentication Code) is a cryptographic mechanism that verifies both the integrity and authenticity of a webhook request. When you send a webhook with HMAC authentication, you generate a signature by hashing the request timestamp and payload together using your secret key with the SHA-256 algorithm. AWS DevOps Agent independently computes the same hash on its side and compares the two signatures. If they match, the request is accepted. + +Because the timestamp is included in the signature, HMAC also provides replay protection — AWS DevOps Agent can reject requests with timestamps that are too far in the past, preventing an attacker from capturing and resending a valid request. + +### Choosing between HMAC and Bearer token + +Consideration | HMAC | Bearer token +---|---|--- +Setup complexity | More complex — your client must compute a signature for each request using the timestamp and payload | Simpler — include a static token in the `Authorization` header +Payload integrity | Verified — any modification to the payload after signing invalidates the signature | Not verified — the token authenticates the sender but does not protect the payload contents +Replay protection | Built-in — the timestamp in the signature allows the server to reject stale requests | Not built-in — a captured token can be reused until it is rotated +Secret exposure risk | Lower — the secret is never transmitted in the request; only the computed signature is sent | Higher — the token is sent in every request header, increasing exposure if traffic is intercepted +When to use | Recommended when you need stronger security guarantees, such as for generic webhooks or environments with strict compliance requirements | Suitable when ease of integration is a priority and your network transport is trusted, such as for managed SaaS integrations over HTTPS + @@ -163,0 +182,16 @@ The request body should include information about the incident: +**Payload schema:** + + + { + eventType: 'incident'; + incidentId: string; + action: 'created' | 'updated' | 'closed' | 'resolved'; + priority: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "MINIMAL"; + title: string; + description?: string; + timestamp?: string; + service?: string; + // The original event generated by service is attached here. + data?: object; + } +