zuplo 6.67.32 → 6.68.0

package/docs/articles/waf-ddos-akamai.md

@@ -0,0 +1,133 @@
+---
+title: Configuring Zuplo with Akamai App & API Protector
+sidebar_label: Akamai App & API Protector
+---
+
+Akamai App & API Protector runs at Akamai edge locations. Zuplo can be
+configured to run as a custom origin behind Akamai.
+
+## Securing Zuplo from Direct Access
+
+With any WAF product, you will want to ensure that network traffic can't bypass
+your WAF and hit your API Gateway directly. Akamai offers several ways to ensure
+that your API Gateway is only accessible through the WAF.
+
+The information below is a summary of Akamai's own recommendations for securing
+your backend - regardless of whether you are using Zuplo, another API Gateway,
+or Akamai origins. You can reference the
+[Akamai documentation](https://techdocs.akamai.com/application-security/docs/origin-server-protection).
+
+### IP Address Restrictions
+
+Akamai maintains a list of IP addresses that you can use to restrict access to
+your API Gateway. This is a good way to ensure that only Akamai can access your
+API Gateway. However, as Akamai is a multi-tenant service, this method isn't
+sufficient to protect unauthorized traffic from hitting your API Gateway.
+
+In Zuplo, you can utilize the IP Address Restriction policy to limit traffic to
+only the Akamai IP addresses. You don't need to provide the address list
+manually, instead you can utilize the built-in list as shown below.
+
+```json
+{
+  "name": "allow-akamai-only",
+  "policyType": "ip-address-restriction-inbound",
+  "handler": {
+    "export": "IPAddressRestrictionInbound",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "allowedIpAddresses": ["list:akamai"]
+    }
+  }
+}
+```
+
+With this policy in place, only Akamai traffic will be allowed to hit your Zuplo
+API Gateway.
+
+### Custom Headers
+
+Another way to ensure that traffic is coming from Akamai is to use custom
+headers. Custom headers can be added to your Akamai configuration and then
+checked by your API Gateway. This provides an additional layer of security on
+top of IP address restrictions and prevents any unauthorized traffic from
+hitting your API Gateway - regardless of the source.
+
+In Akamai, you can configure custom headers using the Property Manager or the
+Akamai API. Add a custom header with a secret value that only you and Akamai
+know.
+
+In Zuplo, you can utilize the Header Restriction policy to limit traffic to only
+those requests that include the custom header and secret value.
+
+```json
+{
+  "name": "allow-akamai-custom-header",
+  "policyType": "require-header-inbound",
+  "handler": {
+    "export": "RequireHeaderInboundPolicyOptions",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "headerName": "x-akamai-auth",
+      "allowedValues": ["$env(AKAMAI_SECRET_HEADER_VALUE)"]
+    }
+  }
+}
+```
+
+With this policy in place, only requests that include the custom header with the
+secret value will be allowed to hit your Zuplo API Gateway.
+
+## Additional Akamai Origin Security Options
+
+Akamai provides several additional security features to protect your origin
+servers beyond IP restrictions and custom headers:
+
+### Mutual TLS (mTLS) Authentication
+
+Use mutual TLS to establish secure, certificate-based authentication between
+Akamai edge servers and your origin. This ensures only authenticated Akamai
+servers can connect to your backend.
+
+Learn more:
+[mTLS Origin Keystore](https://techdocs.akamai.com/property-mgr/docs/mtls-origin-keystore)
+
+### Origin IP Access Control List
+
+Configure an IP-based access control list that specifically defines which Akamai
+IP addresses can access your origin servers. This provides more granular control
+than general IP restrictions.
+
+Learn more:
+[Origin IP ACL](https://techdocs.akamai.com/origin-ip-acl/docs/welcome)
+
+### Site Shield
+
+Site Shield provides a dedicated set of IP addresses that Akamai uses to connect
+to your origin servers. This creates a more predictable and secure connection
+pattern between Akamai and your backend infrastructure.
+
+Learn more:
+[Site Shield](https://techdocs.akamai.com/site-shield/docs/welcome-site-shield)
+
+### Authentication Token 2.0
+
+Implement token-based authentication for origin requests. This method allows you
+to validate that requests are coming from legitimate Akamai edge servers using
+cryptographic tokens.
+
+Learn more:
+[Auth Token 2.0](https://techdocs.akamai.com/property-mgr/docs/auth-token-2-0-ver)
+
+### Custom Request Headers with Shared Secrets
+
+Configure Akamai to modify incoming request headers and add shared secret values
+that your origin can validate. This is similar to the custom header approach
+mentioned above but provides more advanced header manipulation capabilities.
+
+Learn more:
+[Modify Incoming Request Header](https://techdocs.akamai.com/property-mgr/docs/modify-incoming-req-header)
+
+These security measures can be used individually or combined to create multiple
+layers of protection for your Zuplo API Gateway when running behind Akamai App &
+API Protector.

package/docs/articles/waf-ddos-aws-waf-shield.mdx

@@ -0,0 +1,85 @@
+---
+title: Configuring Zuplo with AWS WAF + Shield
+sidebar_label: AWS WAF + Shield
+---
+
+AWS WAF + Shield run at AWS CloudFront edge locations. Zuplo can be configured
+to run as a custom backend behind CloudFront.
+
+## Securing Zuplo from Direct Access
+
+With any WAF product, you will want to ensure that network traffic can't bypass
+your WAF and hit your API Gateway directly. AWS WAF + Shield offer several ways
+to ensure that your API Gateway is only accessible through the WAF.
+
+The information below is a summary of Amazon's own recommendations for securing
+your backend - regardless of whether you are using Zuplo, another API Gateway,
+or AWS origins. You can also reference
+[the AWS documentation](https://docs.aws.amazon.com/whitepapers/latest/secure-content-delivery-amazon-cloudfront/custom-origin-with-cloudfront.html)
+directly.
+
+### IP Address Restrictions
+
+Amazon maintains a list of CloudFront IP addresses (separate from other AWS
+uses) that you can use to restrict access to your API Gateway. This is a good
+way to ensure that only CloudFront can access your API Gateway. However, as
+CloudFront is available to any AWS customer, this method isn't sufficient to
+protect unauthorized traffic from hitting your API Gateway.
+
+In Zuplo, you can utilize the IP Address Restriction policy to limit traffic to
+only the CloudFront IP addresses. You don't need to provide the address list
+manually, instead you can utilize the built-in list as shown below.
+
+```json
+{
+  "name": "allow-cloudfront-only",
+  "policyType": "ip-address-restriction-inbound",
+  "handler": {
+    "export": "IPAddressRestrictionInbound",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "allowedIpAddresses": ["list:aws-cloudfront"]
+    }
+  }
+}
+```
+
+With this policy in place, only CloudFront traffic will be allowed to hit your
+Zuplo API Gateway.
+
+### Custom Headers
+
+Another way to ensure that traffic is coming from CloudFront is to use custom
+headers. Custom headers can be added to your CloudFront distribution and then
+checked by your API Gateway. This provides an additional layer of security on
+top of IP address restrictions and prevents any unauthorized traffic from
+hitting your API Gateway - regardless of the source.
+
+In Zuplo, you can utilize the Header Restriction policy to limit traffic to only
+those requests that include the custom header and secret value.
+
+```json
+{
+  "name": "allow-cloudfront-custom-header",
+  "policyType": "require-header-inbound",
+  "handler": {
+    "export": "RequireHeaderInboundPolicyOptions",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "headerName": "secure-header",
+      "allowedValues": ["$env(MY_SECRET_HEADER_VALUE)"]
+    }
+  }
+}
+```
+
+With this policy in place, only requests that include the custom header with the
+secret value will be allowed to hit your Zuplo API Gateway.
+
+### Identity Based Options
+
+Unfortunately, AWS WAF + Shield don't offer identity-based options like IAM or
+network based options for securing your API Gateway. This is true for
+[both AWS](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/restrict-access-to-load-balancer.html)
+and non-AWS API Gateway products. If you require these options, you will need to
+use a different WAF product in front of your Zuplo API Gateway.

package/docs/articles/waf-ddos-fastly.mdx

@@ -0,0 +1,251 @@
+---
+title: Configuring Zuplo with Fastly Next-Gen WAF
+sidebar_label: Fastly Next-Gen WAF
+---
+
+Fastly Next-Gen WAF runs at Fastly edge locations. Zuplo can be configured to
+run as a host behind Fastly.
+
+Refer to Zuplo's documentation on
+[how to configure Zuplo as a Fastly host](./fastly-zuplo-host-setup.mdx).
+
+## Securing Zuplo from Direct Access
+
+With any WAF product, you will want to ensure that network traffic can't bypass
+your WAF and hit your API Gateway directly. Fastly offers several ways to ensure
+that your API Gateway is only accessible through the WAF.
+
+The information below is a summary of Fastly's own recommendations for securing
+your backend - regardless of whether you are using Zuplo, another API Gateway,
+or Fastly origins. You can reference the
+[Fastly documentation](https://www.fastly.com/documentation/guides/integrations/non-fastly-services/developer-guide-backends/).
+
+### IP Address Restrictions
+
+Fastly maintains a list of IP addresses that you can use to restrict access to
+your API Gateway. This is a good way to ensure that only Fastly can access your
+API Gateway. However, as Fastly is a multi-tenant service, this method isn't
+sufficient to protect unauthorized traffic from hitting your API Gateway.
+
+In Zuplo, you can utilize the IP Address Restriction policy to limit traffic to
+only the Fastly IP addresses. You don't need to provide the address list
+manually, instead you can utilize the built-in list as shown below.
+
+```json
+{
+  "name": "allow-fastly-only",
+  "policyType": "ip-address-restriction-inbound",
+  "handler": {
+    "export": "IPAddressRestrictionInbound",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "allowedIpAddresses": ["list:fastly"]
+    }
+  }
+}
+```
+
+With this policy in place, only Fastly traffic will be allowed to hit your Zuplo
+API Gateway.
+
+### Signed Headers
+
+Another way to ensure that traffic is coming from Fastly is to use signed
+headers. Signed headers can be added using a
+[VLC Snippet](https://docs.fastly.com/en/guides/about-vcl-snippets) and then
+checked by your API Gateway. This provides an additional layer of security on
+top of IP address restrictions and prevents any unauthorized traffic from
+hitting your API Gateway - regardless of the source.
+
+In Fastly, you will need to create a VCL snippet that adds a signed header as
+shown below. This example uses the `shared_secret` value stored in an
+[Edge Dictionary](https://www.fastly.com/documentation/guides/concepts/edge-state/dynamic-config/#edge-dictionaries).
+
+```txt
+declare local var.zuplo_auth_secret STRING;
+set var.zuplo_auth_secret = table.lookup(Zuplo, "shared_secret");
+declare local var.data STRING;
+set var.data = strftime({"%s"}, now) + "," + server.datacenter;
+set bereq.http.X-Signature = var.data + "," + digest.hmac_sha256(var.zuplo_auth_secret, var.data);
+```
+
+In Zuplo, you can utilize a custom code inbound policy to limit traffic to only
+those requests that include the signed header.
+
+```json title="/config/policies.json"
+{
+  "name": "fastly-auth-inbound",
+  "policyType": "custom-code-inbound",
+  "handler": {
+    "export": "default",
+    "module": "$import(./modules/fastly-auth-inbound)",
+    "options": {
+      "secret": "$env(FASTLY_SECRET)",
+      "headerName": "x-signature"
+    }
+  }
+}
+```
+
+```ts title="/modules/fastly-auth-inbound.ts"
+import { HttpProblems, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+interface PolicyOptions {
+  secret: string;
+  headerName: string;
+  requestOffset?: number;
+}
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: PolicyOptions,
+  policyName: string,
+) {
+  // Validate the policy options
+  if (typeof options.secret !== "string") {
+    throw new Error(
+      `The option 'secret' on policy '${policyName}' must be a string. Received ${typeof options.secret}.`,
+    );
+  }
+  if (typeof options.headerName !== "string") {
+    throw new Error(
+      `The option 'headerName' on policy '${policyName}' must be a string. Received ${typeof options.headerName}.`,
+    );
+  }
+
+  // Get the authorization header
+  const headerValue = request.headers.get(options.headerName);
+
+  // No auth header, unauthorized
+  if (!headerValue) {
+    return HttpProblems.unauthorized(request, context);
+  }
+
+  const encoder = new TextEncoder();
+
+  // Split the header into the parts
+  const [timestamp, datacenter, hash] = headerValue.split(",");
+
+  context.log.info({ timestamp, datacenter, hash });
+
+  // Convert the timestamp to milliseconds
+  const timestampInMilliseconds = parseInt(timestamp) * 1000;
+  const currentTimeInMilliseconds = new Date().getTime();
+  const differenceInSeconds =
+    Math.abs(currentTimeInMilliseconds - timestampInMilliseconds) / 1000;
+  const offset = options.requestOffset ?? 30;
+  if (differenceInSeconds > offset) {
+    context.log.error("The request is old than 30 seconds.");
+    return HttpProblems.unauthorized(request, context);
+  }
+
+  // Convert the hex HMAC to an ArrayBuffer
+  const signature = new Uint8Array(
+    hash
+      .slice(2)
+      .match(/.{1,2}/g)
+      .map((byte) => parseInt(byte, 16)),
+  );
+
+  // Get the hash value and encode it
+  const hashValue = `${timestamp},${datacenter}`;
+  const hashData = encoder.encode(hashValue);
+
+  // Create the secret from the policy options
+  const encodedSecret = encoder.encode(options.secret);
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encodedSecret,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"],
+  );
+
+  // Verify that the data
+  const verified = await crypto.subtle.verify("HMAC", key, signature, hashData);
+
+  // Check if the data is verified, if not return unauthorized
+  if (!verified) {
+    return HttpProblems.unauthorized(request, context);
+  }
+
+  // Request is authorized, continue
+  return request;
+}
+```
+
+With this policy in place, only requests that include a valid sign header will
+be allowed to hit your Zuplo API Gateway.
+
+### JWT Header
+
+Another way to ensure that traffic is coming from Fastly is to add a JWT header
+to the outgoing request. JWT headers can be added using a
+[VLC Snippet](https://docs.fastly.com/en/guides/about-vcl-snippets) and then
+checked by your API Gateway. This provides an additional layer of security on
+top of IP address restrictions and prevents any unauthorized traffic from
+hitting your API Gateway - regardless of the source.
+
+:::tip
+
+This demo shows using a shared secret for generating and verifying the JWT.
+However, you could also use public/private keys for this purpose. Additionally,
+you could use a third-party identity provider (Auth0, Cognito) to issue machine
+to machine tokens.
+
+:::
+
+In Fastly, you will need to create a VCL snippet that adds a JWT header as shown
+below. This example uses the `shared_secret` value stored in an
+[Edge Dictionary](https://www.fastly.com/documentation/guides/concepts/edge-state/dynamic-config/#edge-dictionaries).
+
+```txt
+declare local var.jwt_secret STRING;
+declare local var.jwt_audience STRING;
+declare local var.jwt_issued STRING;
+declare local var.jwt_expires STRING;
+declare local var.jwt_header STRING;
+declare local var.jwt_payload STRING;
+declare local var.jwt_signature STRING;
+
+
+set var.jwt_secret = table.lookup(Zuplo, "shared_secret");
+set var.jwt_audience = "my-api.example.com";
+set var.jwt_issued = now.sec;
+set var.jwt_expires = strftime({"%s"}, time.add(now, 60s));
+
+set var.jwt_header = digest.base64url_nopad({"{"alg":"HS256","typ":"JWT""}{"}"});
+set var.jwt_payload = digest.base64url_nopad({"{"audience":""} var.jwt_audience {"","exp":"} var.jwt_expires {","iat":"} var.jwt_issued {","iss":"Fastly""}{"}"});
+set var.jwt_signature = digest.base64url_nopad(digest.hmac_sha256(var.jwt_secret, var.jwt_header "." var.jwt_payload));
+
+set bereq.http.X-JWT = var.jwt_header "." var.jwt_payload "." var.jwt_signature;
+```
+
+To verify the JWT header in Zuplo, you can utilize the JWT Auth Inbound policy.
+
+```json
+{
+  "name": "verify-fastly-jwt",
+  "policyType": "open-id-jwt-auth-inbound",
+  "handler": {
+    "export": "OpenIdJwtInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "authHeader": "x-jwt",
+      "issuer": "Fastly",
+      "audience": "my-api.example.com",
+      "secret": "$env(FASTLY_SECRET)"
+    }
+  }
+}
+```
+
+### mTLS Authentication
+
+Fastly supports mTLS authentication for backend services. This is a good way to
+ensure that only Fastly can access your API Gateway. For documentation on
+configuring Fastly with mTLS, see the
+[Fastly documentation](https://docs.fastly.com/en/guides/working-with-hosts#advanced-tls-options).
+To configure Zuplo to accept mTLS connections, see the
+[Zuplo mTLS Policy documentation](/docs/policies/mtls-auth-inbound).

package/docs/articles/waf-ddos.mdx

@@ -0,0 +1,140 @@
+---
+title: Zuplo + WAF/DDoS Services
+---
+
+Many customers using Zuplo (or any other API Gateway) often choose to deploy WAF
+and DDoS protection in front of their gateway. You can use any WAF - we have
+customers today using Azure, AWS, Akamai, CloudFlare and many other options.
+
+However, there are some things to consider depending on how you host Zuplo
+(edge, dedicated, or self-hosted).
+
+If for some reason these don't work for you - we can also offer a managed WAF as
+part of your Zuplo Enterprise agreement; contact sales to discuss.
+
+More details on some third-party WAF solutions are included below.
+
+## Managed Edge Deployments
+
+Zuplo when running on the managed edge is running in over 300 data centers
+around the world. If you care about worldwide presence, be sure to choose a WAF
+that is globally distributed as all traffic will be routed through your WAF.
+
+## Managed Dedicated and Self-hosted Deployments
+
+Customers typically use a WAF offered by their selected hosting platform (e.g.
+Azure, Akamai, AWS, etc.) to simplify management, improve latency and reduce
+bandwidth costs.
+
+## Zuplo Managed WAF
+
+Zuplo offers different WAF solutions based on your deployment model:
+
+**Managed Edge Deployment:** Customers on Zuplo's enterprise plans using our
+managed edge deployment can use Zuplo Managed WAF. This provides
+enterprise-grade protection for your API Gateway with minimal configuration
+required, including OWASP Core Ruleset, OFAC sanctions compliance, DDoS
+protection, and custom rule capabilities.
+
+**Managed Dedicated Deployment:** Customers using Zuplo's managed dedicated
+deployment model can leverage custom WAF and DDoS configurations based on the
+capabilities of their chosen cloud provider (AWS, Azure, GCP). Our team will
+work with you to configure the appropriate security services available in your
+cloud environment.
+
+For detailed information about Zuplo Managed WAF for managed edge deployments,
+see our [Zuplo Managed WAF guide](./zuplo-waf.mdx).
+
+:::tip
+
+Many common WAF functions can be implemented directly in Zuplo using policies,
+without the need for a separate WAF service:
+
+- **IP Restriction** - Block or allow requests from specific IP addresses using
+  the [IP Restriction policy](../policies/ip-restriction-inbound.mdx)
+- **Geolocation Blocking** - Route or block requests based on country using
+  [custom policies](../guides/geolocation-backend-routing.mdx)
+- **Rate Limiting** - Protect against abuse with built-in
+  [rate limiting policies](../policies/rate-limit-inbound.mdx)
+- **Custom Rules** - Create any custom security logic with
+  [custom code policies](../policies/custom-code-inbound.mdx)
+
+These policies run at the edge with your API, ensuring no additional latency
+while providing powerful security capabilities.
+
+:::
+
+Contact our [sales team](mailto:sales@zuplo.com) to discuss which WAF solution
+is right for your deployment model.
+
+## Third-Party WAF Solutions
+
+If you require the ability to finely control your WAF Rules or are using a
+third-party WAF provider, Zuplo integrates seamlessly with popular edge-based
+WAF solutions.
+
+### Akamai App & API Protector
+
+Akamai's App & API Protector provides comprehensive WAF and DDoS protection with
+a global edge network. Akamai offers advanced bot management, API security, and
+DDoS mitigation that works well with Zuplo's edge-deployed architecture. With
+over 4,000 edge locations worldwide, Akamai ensures minimal latency when
+protecting your Zuplo API Gateway.
+
+Key features include:
+
+- Advanced bot detection and mitigation
+- API-specific security rules and rate limiting
+- Real-time threat intelligence
+- Automatic protection against OWASP Top 10 vulnerabilities
+- DDoS protection across all layers
+
+Akamai's extensive edge network ensures that security checks happen close to
+your users, maintaining the low-latency benefits of Zuplo's edge deployment.
+
+- [Akamai Edge Locations](https://www.akamai.com/why-akamai/our-edge-platform)
+
+### Cloudflare WAF + DDoS
+
+Cloudflare is the easiest solution for custom WAF + DDoS in front of your Zuplo
+API Gateway deployed as managed-edge. Because managed-edge is already terminated
+with Cloudflare, the integration is seamless and requires virtually zero
+configuration. Simply point your Cloudflare managed domain to Zuplo and you are
+protected. You can fully customize your WAF, firewall, DDoS or any other
+security configuration offered by Cloudflare. When a request comes into
+Cloudflare, it will be routed first through your account's configuration, then
+will be sent to your Zuplo API Gateway. The same thing happens on the outbound
+as well.
+
+A custom domain configured on Zuplo that utilizes Cloudflare DNS is completely
+protected from requests bypassing your WAF and hitting Zuplo directly.
+Additionally, because your WAF and DDoS are in the same edge locations that
+Zuplo uses to terminate our endpoints, there will be no additional latency.
+
+[Cloudflare Edge Locations](https://www.cloudflare.com/network/)
+
+### Fastly Next-Gen WAF (powered by Signal Sciences)
+
+Fastly's next-gen WAF is another good edge-based solution for WAF/DDoS
+protection. Fastly can be configured with minimal setup to work with Zuplo.
+Because Fastly is most of the same edge locations as Cloudflare (while they
+don't disclose this, we suspect that in many cases they're often in the same
+physical colo data centers) there will be virtually no additional latency using
+the two products together.
+
+- [Configuring Zuplo + Fastly](./waf-ddos-fastly.mdx)
+- [Fastly Edge Locations](https://www.fastly.com/network-map/)
+
+### AWS Shield + AWS WAF + CloudFront
+
+AWS offers DDoS (Shield) and WAF products that run at CloudFront edge locations.
+This is another good option for edge-based WAF/DDoS protection in front of your
+Zuplo API Gateway. AWS CloudFront is also in hundreds of edge locations that are
+very close to Cloudflare locations (again, this isn't something either company
+discloses, but we suspect there is significant overlap in the physical locations
+used by AWS and Cloudflare).
+
+For more information on AWS Shield and WAF, see the following links:
+
+- [Configuring Zuplo + AWS WAF & Shield](./waf-ddos-aws-waf-shield.mdx)
+- [AWS CloudFront Locations](https://aws.amazon.com/cloudfront/features/?whats-new-cloudfront&whats-new-cloudfront.sort-by=item.additionalFields.postDateTime&whats-new-cloudfront.sort-order=desc)