cfn-guardian 0.12.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5773577700ce2126b991c8277b9d00e55938b69437bd2847783a10846bdea83d
-  data.tar.gz: d82f6da2de87df72602901a91a93f183a17bd16155c4fd079b50864383bc790e
+  metadata.gz: 6a1ed7183d14b7d1bc05fdfcffc1ff4272c04ff6db43fc47e4fdcf2124b1d898
+  data.tar.gz: 9b3bcc2a4b2d578983f549f93a0ca482b9842a30eac3ef84fe6e4781575a5440
 SHA512:
-  metadata.gz: '063745566801762e26b5b478dfd2ef9fe3f3c467a7253f8eae11b174816d4cf1193c7a8b152107b6e4e6348763f4d6a8017c1f3c6ad4a7a6b876c9f4c027c00e'
-  data.tar.gz: 5d3af30d08c4eefa1ec355bf3a28f5d5306524e56ed248b56b1871cae62c18ea57cb3142109d3bfade5d12d1de79a0c39ae7f37ee7d8afd14629276407ed0e32
+  metadata.gz: b058796599f33efd09aff544129071b087a5cde59d87b06d3b19f5036947fc4b1679a32ba371a1a7707b05923a978c31af25e72f486b65c0f9e96d0bedff5122
+  data.tar.gz: 00ec6b9c0c79dd9afc146e135a0eb9512008a1dae030f8e38beed322f5ca3f6ed2ba5eaeb2a82af5b2b1335970d3f3244ff4773c65db3056d81a1b951e692e07

data/docs/custom_checks/http.md

@@ -13,7 +13,7 @@ Resources:
     StatusCode: 200
     # enables the SSL check
     Ssl: true
-    # boolean tp request a compressed response
+    # boolean to request a compressed response
     Compressed: true
   - Id: https://www.example.com
     StatusCode: 301
@@ -38,6 +38,55 @@ Resources:
     Payload: '{"name": "john"}'
 ```
 
+## HMAC signed requests
+
+For health endpoints that require authenticated requests, Guardian can send HMAC-signed headers so your application can verify the request came from Guardian and resist replay attacks.
+
+When enabled, the HTTP check Lambda (see [aws-lambda-http-check](https://github.com/base2/aws-lambda-http-check)) adds these headers to each request:
+
+| Header (default prefix `X-Health`) | Description |
+|-----------------------------------|-------------|
+| `X-Health-Signature` | HMAC-SHA256 hex digest of the canonical string |
+| `X-Health-Key-Id` | Key identifier (e.g. `default`) |
+| `X-Health-Timestamp` | Unix epoch timestamp in seconds |
+| `X-Health-Nonce` | Random value (e.g. UUID hex) to prevent replay |
+
+**Configuration (Public or Internal HTTP):**
+
+| Key | Required | Description |
+|-----|----------|-------------|
+| `HmacSecretSsm` | Yes | SSM Parameter Store path to the HMAC secret (SecureString). The Guardian-generated IAM role grants the Lambda `ssm:GetParameter` for this path. |
+| `HmacKeyId` | No | Key id sent in the `Key-Id` header. Default: `default`. |
+| `HmacHeaderPrefix` | No | Prefix for all HMAC header names. Default: `X-Health` (yields `X-Health-Signature`, `X-Health-Key-Id`, etc.). |
+
+**Example:**
+
+```yaml
+Resources:
+  Http:
+  - Id: https://api.example.com/health
+    StatusCode: 200
+    HmacSecretSsm: /guardian/myapp/hmac-secret
+    HmacKeyId: default
+    HmacHeaderPrefix: X-Health
+```
+
+Internal HTTP checks support the same keys under each host:
+
+```yaml
+Resources:
+  InternalHttp:
+  - Environment: Prod
+    VpcId: vpc-1234
+    Subnets: [subnet-abcd]
+    Hosts:
+    - Id: http://api.example.com/health
+      StatusCode: 200
+      HmacSecretSsm: /guardian/myapp/hmac-secret
+```
+
+Create the secret in SSM (e.g. SecureString) and use the same value in your application when verifying the signature.
+
 ## Private HTTP Check
 
 Cloudwatch NameSpace: `InternalHttpCheck`
@@ -58,4 +107,84 @@ Resources:
     # Array of resources defining the http endpoint with the Id: key
     # All the same options as Http including ssl check on the internal endpoint
     - Id: http://api.example.com
-```
+```
+
+## Supporting HMAC-signed health checks in your application
+
+If you want Guardian to call a health endpoint that only accepts HMAC-authenticated requests, your server must verify the same scheme the Lambda uses.
+
+**Canonical string (what gets signed):**
+
+The Lambda signs this string (newline-separated, no trailing newline):
+
+```
+METHOD\nPATH\nTIMESTAMP\nNONCE\nQUERY\nBODY_HASH
+```
+
+- `METHOD` – HTTP method (e.g. `GET`).
+- `PATH` – URL path (e.g. `/health`), no query.
+- `TIMESTAMP` – Same value as the `{prefix}-Timestamp` header (Unix seconds).
+- `NONCE` – Same value as the `{prefix}-Nonce` header.
+- `QUERY` – Raw query string (e.g. `foo=bar` or empty).
+- `BODY_HASH` – SHA-256 hex digest of the raw request body (empty string for GET; for POST/PUT, hash the body as sent).
+
+**Verification steps (pseudo code):**
+
+1. Read headers (default prefix `X-Health`):  
+   `signature`, `key_id`, `timestamp`, `nonce`.
+2. **Optional – replay protection:**  
+   Reject if `timestamp` is too old (e.g. outside last 5 minutes).  
+   Reject if `nonce` has been seen before (e.g. cache or DB) and treat as replay.
+3. Look up the shared secret for `key_id` (e.g. from config or secrets store – same value as in SSM for Guardian).
+4. Build the canonical string from the incoming request:
+   - Use request method, path, and query.
+   - Use `timestamp` and `nonce` from the headers.
+   - For body: compute SHA-256 hex of the raw request body (empty string for no body).
+5. Compute `expected = HMAC-SHA256(secret, canonical_string)` and compare to `signature` (constant-time).
+6. If equal, treat the request as authenticated.
+
+**Pseudo code example:**
+
+```python
+import hmac
+import hashlib
+
+def verify_health_request(request, secret_by_key_id, header_prefix="X-Health", max_age_seconds=300):
+    sig_h = f"{header_prefix}-Signature"
+    key_h = f"{header_prefix}-Key-Id"
+    ts_h  = f"{header_prefix}-Timestamp"
+    nonce_h = f"{header_prefix}-Nonce"
+
+    signature = request.headers.get(sig_h)
+    key_id    = request.headers.get(key_h)
+    timestamp = request.headers.get(ts_h)
+    nonce     = request.headers.get(nonce_h)
+
+    if not all([signature, key_id, timestamp, nonce]):
+        return False
+
+    # Replay: reject old timestamps
+    if abs(int(timestamp) - time.time()) > max_age_seconds:
+        return False
+    # Replay: reject duplicate nonce (check your cache/DB)
+    if nonce_already_used(nonce):
+        return False
+
+    secret = secret_by_key_id.get(key_id)
+    if not secret:
+        return False
+
+    body_hash = hashlib.sha256(request.body or b"").hexdigest()
+    canonical = "\n".join([
+        request.method,
+        request.path,
+        timestamp,
+        nonce,
+        request.query_string or "",
+        body_hash,
+    ])
+    expected = hmac.new(secret.encode(), canonical.encode(), hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, signature)
+```
+
+Use the same HMAC secret in SSM (Guardian config) and in your app’s config or secrets store. Keep the secret in SecureString or equivalent and restrict access appropriately.

data/lib/cfnguardian/models/check.rb

@@ -42,7 +42,7 @@ module CfnGuardian
         @name = 'HttpCheck'
         @package = 'http-check'
         @handler = 'handler.http_check'
-        @version = '077c726ed691a1176caf95497b8b02f05f00e0cb'
+        @version = '685c17ced2429954fccbf8b8b8f2132b37b3f4ff'
         @runtime = 'python3.11'
       end
     end

data/lib/cfnguardian/models/event.rb

@@ -55,6 +55,10 @@ module CfnGuardian
         @user_agent = resource.fetch('UserAgent',nil)
         @payload = resource.fetch('Payload',nil)
         @compressed = resource.fetch('Compressed',false)
+        @hmac_secret_ssm = resource.fetch('HmacSecretSsm',nil)
+        @hmac_key_id = resource.fetch('HmacKeyId','default')
+        @hmac_header_prefix = resource.fetch('HmacHeaderPrefix','X-Health')
+        @report_response_body = resource.fetch('ReportResponseBody',false)
       end
       
       def payload
@@ -69,8 +73,18 @@ module CfnGuardian
         payload['USER_AGENT'] = @user_agent unless @user_agent.nil?
         payload['PAYLOAD'] = @payload unless @payload.nil?
         payload['COMPRESSED'] = '1' if @compressed
+        payload['REPORT_RESPONSE_BODY'] = '1' if @report_response_body
+        unless @hmac_secret_ssm.nil?
+          payload['HMAC_SECRET_SSM'] = @hmac_secret_ssm
+          payload['HMAC_KEY_ID'] = @hmac_key_id
+          payload['HMAC_HEADER_PREFIX'] = @hmac_header_prefix
+        end
         return payload.to_json
       end
+
+      def ssm_parameters
+        @hmac_secret_ssm.nil? ? [] : [@hmac_secret_ssm]
+      end
     end
 
     class WebSocketEvent < BaseEvent

data/lib/cfnguardian/resources/dms_cluster.rb

@@ -25,6 +25,7 @@ module CfnGuardian::Resource
       alarm.statistic = 'Minimum'
       alarm.threshold = 10000000000
       alarm.evaluation_periods = 1
+      alarm.comparison_operator = 'LessThanThreshold'
       @alarms.push(alarm)
       
       alarm = CfnGuardian::Models::DMSClusterAlarm.new(@resource)
@@ -34,6 +35,7 @@ module CfnGuardian::Resource
       alarm.threshold = 20000000000
       alarm.evaluation_periods = 1
       alarm.alarm_action = 'Warning'
+      alarm.comparison_operator = 'LessThanThreshold'
       @alarms.push(alarm)
     end
   end

data/lib/cfnguardian/version.rb

@@ -1,4 +1,4 @@
 module CfnGuardian
-  VERSION = "0.12.0"
+  VERSION = "0.12.1"
   CHANGE_SET_VERSION = VERSION.gsub('.', '-').freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cfn-guardian
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.12.1
 platform: ruby
 authors:
 - Guslington
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-16 00:00:00.000000000 Z
+date: 2026-03-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor