npm package: @humansecurity/netlify-enforcer
Description: 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 pe
Latest version: 1.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.](https://docs.netlify.com/edge-functions/get-started/)
- A **command-line interface (CLI).**
- A **text editor.**
- **Node Version Manager (nvm)** installed on your device. See [nvm's GitHub repository](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating) 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:](https://edocs.humansecurity.com/docs/install-the-netlify-edge-function-enforcer#install-dependencies) Install the Enforcer package from HUMAN.
2. [Use the package:](https://edocs.humansecurity.com/docs/install-the-netlify-edge-function-enforcer#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](https://edocs.humansecurity.com/docs/install-the-netlify-edge-function-enforcer#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:

```javascript
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](https://docs.netlify.com/environment-variables/get-started/) for more information.

```javascript
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.](https://edocs.humansecurity.com/v1/docs/netlify-edge-function-enforcer-configurations)

> 🚧 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.

```javascript
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();
}
```

<br />

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.**

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

<br />

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.