AWS CloudFront

Deploy Centinel Analytica on an existing CloudFront distribution via Lambda@Edge.

Overview

This guide covers the console workflow for installing the Centinel Lambda@Edge function. After associating the function, allow 15-20 minutes for CloudFront to propagate the protection globally.

Prerequisites

Centinel secret key
CloudFront distribution you can edit
AWS Console access with Lambda and CloudFront permissions

Install

Prepare the package

Download centinel-cloudfront.js.
Open the file and replace the empty CENTINEL_SECRET_KEY value with your key.
Zip the modified centinel-cloudfront.js to create a deployment archive.

Create the Lambda function

Switch the AWS Console region to N. Virginia (us-east-1).
Go to Lambda → Create function → Author from scratch.
Name the function (e.g. centinel-cloudfront), choose a currently supported Lambda@Edge Node.js runtime, and create it.
In the Code tab, select Upload from → .zip file and upload your archive.
Under Configuration → Runtime settings, set Handler to centinel-cloudfront.handler.
Under Configuration → General configuration, set Timeout to 5 seconds and Memory to 128 MB. These are the Lambda@Edge maxima for a viewer-request function, not preferences. If the validator is slow, lower CENTINEL_TIMEOUT rather than raising these.
Under Configuration → Permissions, edit the execution role's trust relationship so it trusts both lambda.amazonaws.com and edgelambda.amazonaws.com. CloudFront refuses the association without the second principal.
Choose Actions → Publish new version and note the versioned ARN. CloudFront rejects $LATEST, so always associate a published version.

Associate with CloudFront

Open CloudFront → Distributions, select the distribution to protect, and edit the cache behavior you want covered.
In Function associations, click Add function, choose Lambda@Edge, paste the versioned ARN, and set the event type to Viewer request. This is the only supported event type.
Save the behavior to start global deployment.

Configure

Edit these constants at the top of centinel-cloudfront.js before zipping it.

Setting	Default	Purpose
`CENTINEL_SECRET_KEY`	empty	Required. While empty, every request is forwarded unvalidated.
`CENTINEL_PROTECTED_PATHS`	empty (all paths)	Paths to protect. `*` matches a single path segment only.
`CENTINEL_UNPROTECTED_PATHS`	30 static extensions	Paths to skip. `*.ext` matches at any depth.
`CENTINEL_VALIDATOR_URL`	`validator.centinelanalytica.com`	Alternate validator endpoint.
`CENTINEL_TIMEOUT`	`300`	Validator timeout in ms. Unrelated to the Lambda timeout.
`CENTINEL_LOG_ENABLED`	`true`	Gates the `[Centinel]` log lines the Verify step looks for.

Two behaviors worth knowing before you deploy:

Fails open. A missing key, a timeout, an unparseable response, or an error all allow the request through. After a validator failure the function also stops calling the validator for a spell, backing off up to five minutes, so a sustained outage leaves traffic unvalidated for that window.
First protected request costs a redirect. When an allow carries cookies, the function answers with a 302 back to the same URL to deliver them, so the visitor makes one extra round trip.

Viewer-request functions can only return a small generated response, so a large block or challenge page cannot be delivered on this platform and CloudFront answers 502 instead. Keep custom pages small.

Verify

Watch the distribution status until it says Deployed (15-20 minutes).
Lambda@Edge logs land in the region nearest the viewer, in the log group /aws/lambda/us-east-1.<function-name>, not in us-east-1.
Browse the distribution domain to confirm traffic flows normally.
Check CloudWatch logs for entries prefixed with [Centinel] if you need to troubleshoot.

Changelog

v1.1.0 — Honor validator status codes
v1.0.2 — Typo fix
v1.0.1 — Response header passthrough
v1.0.0 — Initial release