API Management versions 7.5.X and 7.6.X have reached end of support in November 2020.
Check out the latest version of the documentation.

Manage API firewalling

API Gateway provides API firewalling capabilities by embedding Apache ModSecurity. This is a toolkit for real-time HTTP traffic monitoring, logging, and access control. This helps companies to mitigate application-level threats to their APIs. For example, this includes cross-site scripting, SQL injection, command injection, cross-site request forgery, and many others.

API Gateway administrators can configure the embedded ModSecurity engine to protect API Gateway HTTP traffic against threats and monitor reported exceptions. This topic explains how to enable API firewalling on an API Gateway interface in Policy Studio, and how to monitor API firewalling in the API Gateway Manager web console.

For more details on ModSecurity, see Apache ModSecurity documentation.

Configure API firewalling

ModSecurity provides very little protection on its own. However, you can configure the required protection by configuring The ModSecurity rules engine with a threat protection profile. Protecting against specific threats requires specific rules, and different vendors provide rules for specific threat protection capabilities.

The Open Web Application Security Project (OWASP) ModSecurity Core Rule Set (CRS) project provides a popular rule set. For more details on OWASP, see OWASP web page.

For details on how to write security rules yourself, see, for example, How To Write A WAF Rule - Modsecurity Rule Writing.

This section explains how to configure API firewalling by enabling threat protection and configuring threat protection rules.

Enable threat protection

By default, the embedded ModSecurity engine is disabled. To enable ModSecurity on an API Gateway interface, perform the following steps:

  1. In the Policy Studio node tree, click Environment Configuration > Listeners, and select the interface you want to enable (for example, API Gateway > Default Services > Ports).
  2. Right-click the HTTP or HTTPS interface in the window on the right, and select Edit.
  3. Go to the Advanced tab.
  4. Under Threat Protection Settings, browse to the Threat Protection Profile you want to use to protect this interface with ModSecurity rules. For example:

Enable threat protection

When a profile is selected, all traffic is processed by the ModSecurity engine, and threats are rejected based on the selected security rules.

Configure a threat protection profile

If no threat protection profiles have been configured, do the following:

  1. In the Select WAF Profile dialog, right-click the Threat Protection Profiles, and select Add a Threat Protection Profile.
  2. Enter a profile name, and configure the following settings:
  3. Field Description
    Configuration directory Enter the name of the directory that stores the threat protection configuration file. When threat protection has been enabled, the embedded ModSecurity engine looks for threat protection rules configuration in this directory. API Gateway uses the OWASP ModSecurity CRS directory structure. The default is ${environment.VDISTDIR}/system/conf/threat-protection/default.
    Configuration file Enter the threat protection configuration file name. The default value is modsecurity.conf. This file contains the engine global settings. For details on the file format and recommended settings, see Recommended Base Configuration in the ModSecurity documentation.
    Rules directory

    Enter the name of the subdirectory that stores the threat protection rules.

    When you download or create ModSecurity security rules, you must put them in this subdirectory. The embedded ModSecurity engine loads all .conf files in this directory.

    The default is ${environment.VDISTDIR}/system/conf/threat-protection/default/activated_rules.

    Alert policy

    Select an API Gateway policy you have configured that is executed when a threat protection rule is triggered. The policy can, for example, include an Alert filter to send alert notifications to monitoring systems, or call an API. For details on creating policies, see the API Gateway Policy Developer Guide.

    This setting is optional.

  4. Deploy the updated configuration to API Gateway after changing any threat protection settings.

The recommended ModSecurity default configuration sets the engine mode to SecRuleEngine DetectionOnly, which applies the activated rules. This does not interfere with the traffic (does not block any requests).

You can also add threat protection profiles in Environment Configuration > Libraries > Threat Protection Profiles > Add a Threat Protection Profile in the Policy Studio node tree.

Configure modsecurity.conf file

Depending on your environment, you may need to configure the settings in the modsecurity.conf file. For example:

  • To handle an application/xml content type instead of text/xml, add the following line to modsecurity.conf:
  • To configure ModSecurity to start denying requests with threatening content, in modsecurity.conf, change the value of SecRuleEngine from DetectionOnly to On.
  • If you have not included the security action in your security rules, you may need to set SecDefaultAction in modsecurity.conf. See Configure API firewalling. For more details on the SecDefaultAction parameter, see ModSecurity Reference Manual.

For more details on the modsecurity.conf file format and recommended settings, see Recommended Base Configuration in the ModSecurity documentation.

Monitor API firewalling

An API Gateway administrator or operator can use the Traffic > HTTP tab in the API Gateway Manager web console to monitor API firewalling. You can use this tab to show how threat protection affects the HTTP traffic API Gateway serves.

Monitor threat protection

You can filter this tab to display by Threat Protection to quickly locate all passed or failed transactions.

  1. Click Filter + in the search pane.
  2. Select Threat Protection in the list.
  3. Select a threat protection status in the dialog:
    • Pass:
      The ModSecurity engine marks all transactions that pass its rules with this status.
    • Fail:
      Transactions that violate any active ModSecurity engine rules are marked with this status. These transactions should be monitored because they represent a false positive (the protection rules might need to be adjusted), or malicious client traffic. You can view more details about the failure reason and specific rule violation by drilling down a specific transaction and looking at the trace details.
    • Exception:
      Transactions that cause a rule processing or other unknown error are marked with this status. These should not occur and probably indicate some rule configuration problem.
    Click Apply.

For example, the following shows detailed trace output from drilling down a failed transaction:

In addition of being written to trace files, ModSecurity report is also stored in the message attribute modsec.error.message. You can configure an alert policy that, for example, uses an Alert filter with a selector for this message attribute in the default message to pass the threat report to third-party monitoring systems. For more details how to configure the Alert filter, see Alert in the API Gateway Policy Developer Filter Reference.

Further information

For more details on supported security features, see the API Management Security Guide.

Related Links