--- name: azion-install-the-ip-address-reputation-integration description: >- Install IP Address Reputation from Azion Marketplace and run it on a firewall, to score each request IP with IPQualityScore data. --- # Install the IP Address Reputation integration You install the IP Address Reputation integration from Azion Marketplace and run it on a [Firewall](/en/documentation/platform/firewall/), from Azion Console. The integration gets a reputation score for the IP address of each request from IPQualityScore (IPQS). The score comes from several factors: whether the IP address was used for spam or other malicious activity, how often it was reported as suspicious or fraudulent, and other information. Five objects have to exist before a request is scored: the installed function, a firewall carrying the **Functions** module, a function instance holding your IPQS key, a Rules Engine rule with the **Run Function** behavior, and a workload deployment bound to the firewall. Each section below creates one of them. --- ## Prerequisites - An Azion account. To sign in, refer to [How to access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/). - An application served by a [workload](/en/documentation/platform/workloads/), whose deployment you bind to the firewall in the last section. - An IPQualityScore account, with an API key. The next sections show how to get it. - The [Azion CLI](/en/documentation/devtools/cli/) installed and authorized, for the last section. - Turning on a product or a module can generate usage costs. For more information, refer to [Pricing](/en/documentation/fundamentals/pricing/). --- ## Install the integration The function is installed once per account. To install it: 1. **Open Marketplace** Access [Azion Console](https://console.azion.com/) > **Marketplace**. 2. **Find the integration** Enter `IP Address Reputation` in the **Search on Marketplace** field, then select the integration's card. Browsing the cards and the categories reaches the same page. 3. **Select Install** The card shows `Successfully installed!` and `Latest version installed!`, and the function appears in the **Function** list of the **Create Instance** drawer. --- ## Get the IPQualityScore API key The integration needs an API key from IPQualityScore. To get it: 1. **Create an IPQualityScore account** Create an [account at IPQualityScore](https://www.ipqualityscore.com/create-account). 2. **Find the API key in the email** Wait for the email with your personal information. The email carries your API key. Store it: the function instance takes it as an argument. You have the API key that the function instance takes as an argument. --- ## Create the firewall The firewall is where the function is instanced and where the rule that runs it lives. To create one: 1. **Open the Firewalls page** Access [Azion Console](https://console.azion.com/) > **Firewalls**, then create a firewall. 2. **Name the firewall** In the **General** section, enter a **Name**. For example: `ip-reputation-firewall`. 3. **Turn on the Functions module** In the **Modules** section, turn on the **Functions** switch. 4. **Save the firewall** The firewall shows a **Functions Instances** tab while the **Functions** module stays on. To use an existing firewall instead, turn on its **Functions** module and save it. For every setting on this form, refer to [Set a firewall's main settings](/en/documentation/guides/application-security/firewall-and-waf/firewall-configure-main-settings/). --- ## Create the function instance The instance holds your IPQS API key and the options of the lookup. To create it: 1. **Open the Functions Instances tab** In **Firewalls**, select your firewall, then select the **Functions Instances** tab. 2. **Select + Function** A firewall that has no instance shows the same action as **Function Instance**. The **Create Instance** drawer opens. 3. **Name the instance** In **Name**, enter a name. For example: `ip-address-reputation`. 4. **Select the installed function** In **Function**, select the IP Address Reputation function. The list holds only the functions that run on a firewall. 5. **Enter the arguments** In **Arguments**, the editor is prefilled with the integration's default arguments in JSON. Enter your API key and your values, as the next section describes. 6. **Select Save** The instance is listed in the **Functions Instances** tab. ### Arguments The arguments look like this: ```json { "api_key": "XXXXXXXXXXXXXXXXXXXXXXXXXXX", "allow_public_access_points": true, "fast": true, "strictness": 0, "lighter_penalties": true, "user_language": "en-US", "transaction_strictness": 0 } ``` The only argument you must set is `api_key`: the API key you got in the IPQualityScore email. The other arguments are: | Argument | Type | Default | Description | | ---------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `allow_public_access_points` | Boolean | `true` | Allows public connections | | `fast` | Boolean | `true` | Turns on a fast check, which skips some forensic checks | | `strictness` | Integer | `0` | The strictness of the fraud scoring, in the range `0-3`. Values above 2 are more likely to return false positives | | `lighter_penalties` | Boolean | `true` | Lowers the score of proxy IP addresses, to prevent false positives | | `user_language` | String | None | The language header of the user | | `transaction_strictness` | Integer | None | Adjusts the penalty weights for irregularities and fraud patterns found in the order and transaction details you send with each API request. Useful only when you send those details | The prefilled JSON does not carry these arguments, but the function accepts them: | Argument | Type | Default | Description | | ------------------ | ------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `when_score_above` | Integer | None | A score threshold. When the IPQS Risk Score exceeds it, the function performs the action in `execute`. When it is not set, the function takes no action | | `execute` | String | None | The action the function performs when the score exceeds `when_score_above`: `deny`, `drop`, or `add_header` | | `get_data_from` | String | `remote_addr` | Where the function reads the IP: `remote_addr`, `querystring`, `body`, or `header`. With `remote_addr`, the function reads `ngx.var.remote_addr` | | `data_name` | String | `X-Forwarded-For` | The field or argument from which the function extracts the IP to validate. Used only when the parameter `search_in` is different from the parameter `remote_addr` | --- ## Create the rule The instance scores nothing until a rule runs it. A [Rules Engine for Firewall](/en/documentation/platform/firewall/rules-engine/) rule selects the requests that reach the instance, through a **Run Function** behavior. To create the rule: 1. **Open the Rules Engine tab** In **Firewalls**, select your firewall, then select the **Rules Engine** tab. 2. **Select + Rule** 3. **Name the rule** In **Name**, enter a name. For example: `Run IP Address Reputation`. 4. **Set the criterion** In the **Criteria** section, select the domains that run the integration. For example: if `Host` *matches* `yourdomain.com`. 5. **Add the Run Function behavior** In the **Behaviors** section, select **Run Function**, then select the instance by the name you gave it. 6. **Select Save** The firewall runs the instance on every request to the domains in the criterion. --- ## Bind the firewall to the workload The binding is on the workload's deployment, so create a deployment that names both the application and the firewall: ```bash azion create workload-deployment --workload-id --name \ --application-id --firewall-id --strategy-type default \ --active true --current true ``` The command prints the id of the new deployment: ```text Created Workload Deployment with ID 123456 ``` Requests to the workload's domain reach the firewall, and the IP Address Reputation integration runs on each one. --- ## How it works For each field in the IPQS result, the integration adds a request header with the prefix `IPQS`. For example, an `ASN` field in the result adds an `IPQS-ASN` header with the same value. Use these headers to make decisions in Rules Engine. For every field the result carries, refer to the [IPQS Proxy Detection API documentation](https://www.ipqualityscore.com/documentation/proxy-detection-api/overview). Each request to your firewall counts as one IP address lookup on your IPQS API key. To follow the use of your key, open the IPQualityScore dashboard. > **Tip** > > Create an application rule that redirects the request to another URL or origin when the risk score is greater than 85. --- ## Next steps - [Marketplace integrations](/en/documentation/platform/marketplace/integrations.md): Every integration Azion Marketplace offers, and where each one runs. - [Rules Engine for Firewall](/en/documentation/platform/firewall/rules-engine.md): Every criterion and behavior a firewall rule accepts. - [Update an integration](/en/documentation/guides/application-development/integrations/update-an-integration.md): Move an installed integration to its latest version.