@humansecurity/netlify-enforcer v1.1.0

human-security-netlify-enforcer

If your organization uses Netlify, you can use HUMAN's Netlify Edge Function Enforcer to protect against malicious behavior. The Netlify Edge Function is deployed to your content delivery network (CDN) and dictates how traffic should be handled per your organization's standards.

You can learn how to install the Netlify Edge Function Enforcer with this article.

Prerequisites

• A Netlify account with permissions to edit an existing Edge Function and function file. Learn more with Netlify's article Get started with Edge Functions.
• A command-line interface (CLI).
• A text editor.
• Node Version Manager (nvm) installed on your device. See nvm's GitHub repository to learn how to install it.
• The latest version of Node.js. After installing nvm, enter nvm install stable in your CLI to install it.
• Your unique HUMAN information:
  • Your Application ID. You can find this under Platform Settings > Applications > Select an application > Application Settings > Application ID in the HUMAN console. If you have multiple environments, you will also have multiple Application IDs, so be sure to choose the correct ID for the environment you want to install on.
  • Your Server Token. You can find this under Platform Settings > Applications > Status & Settings > Server Token.
  • Your Risk Cookie Key. You can find this under Bot Defender > Policies > Policy Settings > Policy Information.

Install the Enforcer

There are two parts to the integration. Be sure to complete each part in order.

1. Install dependencies: Install the Enforcer package from HUMAN.
2. Use the package: Import the package into your Edge Function and deploy.

Install dependencies

1. Navigate to your directory that has the Edge Function project you want to integrate the Enforcer on.
2. Enter npm install perimeterx-node-core-ts to install the Enforcer package.

🚧 Note

Do not import the package using the npm: prefix in an import statement. Netlify does not support this syntax, and it will not install the package properly if you use it.

Your Netlify Edge Function project directory should now have the package installed. Next, move on to Use the package to complete your integration.

Use the package

1. Open the project's function file.
2. At the top of your function file, add the following import statements:

import { PXEnforcer, PXRawConfig } from "perimeterx-node-core-ts";
import type { Config, Context } from "@netlify/edge-functions";

3. At the beginning of your function, add the HUMAN configurations using the PXRawConfig object as shown.

   • PX_APP_ID corresponds to your Application ID.
   • PX_COOKIE_SECRET corresponds to your Risk Cookie Key.
   • PX_AUTH_TOKEN corresponds to your Server Token.

📘 Note

While you can add PX_APP_ID, PX_COOKIE_SECRET, and PX_AUTH_TOKEN directly, we recommend using Netlify environment variables so your configuration is more flexible and secure. See Netlify's help documentation for more information.

const config: PXRawConfig = {
        px_app_id: Netlify.env.get("PX_APP_ID"),
        px_cookie_secret: Netlify.env.get("PX_COOKIE_SECRET"),
        px_auth_token: Netlify.env.get("PX_AUTH_TOKEN"),
        px_extract_user_ip: (request) => {
            return context.ip;
        },
    };

4. Add any additional custom configurations your organization wants to include in the PXRawConfig object. You can find all available configurations in our help article.

🚧 Note

While all other custom configurations are optional, you must include the px_extract_user_ip property as shown in Step 3. This lets HUMAN extract the correct end user IP.

5. After the PXRawConfig object, add the following lines of code. These let HUMAN evaluate the request as soon as it hits the function.

const config: PXRawConfig = {
   // HUMAN configurations
   ...
   };
const px = new PXEnforcer(config);
const resp = await px.enforce(request); // verifies the response from HUMAN
if (resp.pxResponse) { // if the request is suspicious, return the Challenge page
    return new Response(resp.pxResponse.body, {
        headers: resp.pxResponse.headers as HeadersInit,
        status: resp.pxResponse.status,
    });
} else { // if the request is valid, continue the execution flow
    return await context.next();
}

6. If you would like to exclude Enforcer monitoring on specific paths, then you must configure the function to do so using either the TOML file or Netlify's Config object. Otherwise, move on to Step 7. By default, the Enforcer will run on all requests.

[[edge_functions]]
pattern = "/(.*)"
excludedPattern = [
  "/api/(.*)",
  "/fapi/(.*)",
  "(.*).(png|svg|map|woff2|ico|css)"
]
function = "human-enforcer"

7. Save your changes and deploy the function to Netlify.

Your Netlify Edge Function has now been integrated with the HUMAN Enforcer. Once you complete your installation, be sure to contact HUMAN to complete your Tuning process.

Additional S2S Activity Configuration

Basic Configuration

Set the following environment variables in your Netlify site:

PX_APP_ID=your_app_id
PX_COOKIE_SECRET=your_cookie_secret
PX_AUTH_TOKEN=your_auth_token

Credentials Intelligence and Additional S2S Activity

To enable credentials intelligence and additional_s2s activity reporting:

PX_LOGIN_CREDENTIALS_EXTRACTION_ENABLED=true
PX_AUTOMATIC_ADDITIONAL_S2S_ACTIVITY_ENABLED=true
PX_SEND_RAW_USERNAME_ON_ADDITIONAL_S2S_ACTIVITY=false
PX_ADDITIONAL_S2S_ACTIVITY_HEADER_ENABLED=false
PX_COMPROMISED_CREDENTIALS_HEADER=px-compromised-credentials

Configure credential endpoints:

PX_LOGIN_CREDENTIALS_EXTRACTION=[
  {
    "path": "/login",
    "path_type": "exact",
    "method": "post",
    "sent_through": "body",
    "user_field": "username",
    "pass_field": "password",
    "protocol": "v2",
    "login_successful_reporting_method": "status",
    "login_successful_statuses": [200]
  }
]

Additional S2S Activity Modes

The enforcer supports three modes for handling additional_s2s activities:

1. Automatic Mode (default): Activities are sent automatically after response analysis

   • Set PX_AUTOMATIC_ADDITIONAL_S2S_ACTIVITY_ENABLED=true

2. Header Mode: Activity payload is added as headers for manual sending

   • Set PX_ADDITIONAL_S2S_ACTIVITY_HEADER_ENABLED=true
   • Set PX_AUTOMATIC_ADDITIONAL_S2S_ACTIVITY_ENABLED=false
   • Headers added: px-additional-activity and px-additional-activity-url

3. Manual Mode: Use custom activity handler

   • Implement px_additional_activity_handler callback

Login Success Detection

Configure how the enforcer determines login success:

• Status Code: Based on HTTP response status
• Header: Based on response header presence/value
• Body: Based on regex match in response body
• Custom: Using a custom callback function

Features

• ✅ Risk API integration
• ✅ Cookie validation (v3)
• ✅ Block page rendering
• ✅ First-party endpoints
• ✅ Credentials Intelligence
• ✅ Additional S2S Activity reporting
• ✅ GraphQL support
• ✅ JWT extraction
• ✅ Custom parameters
• ✅ Telemetry

License

This project is licensed under the MIT License.