Bring Your Own NGINX App Protect Policy

Learn how to use your own NGINX App Protect policies with NGINX Controller

This topic explains how to bring your own NGINX App Protect (NAP) policy to use with NGINX Controller. This is a beta feature introduced in NGINX Controller App Security v3.17. We don’t recommend using beta features in Production environments.


The App Security Add-on for NGINX Controller ADC lets you bring your own NGINX App Protect (NAP) declarative JSON policies (also called a BYO NAP policy) and use them with NGINX Controller to protect your app components.

A BYO NAP policy lets you to maintain consistent security policies with your F5 WAF and NGINX WAF deployments. For example, suppose you’re an F5 BIG-IP Application Security Manager (ASM) or maybe you’re an F5 Advanced WAF customer adopting NGINX Controller App Security. Now you can convert your XML security policies into an NGINX App Protect policy by using the NGINX App Protect Policy Converter tool .

To export a policy from F5 Advanced WAF or ASM, take the following steps:

  1. Convert your F5 XML security policy to an NGINX App Protect declarative JSON policy using NGINX App Protect Policy Converter tool .
  2. Use the NGINX App Protect declarative JSON policy as the WAF policy in NGINX Controller for your app component(s).


With a BYO NAP policy, you can also provide customized security by crafting an NGINX App Protect policy that specifies the security controls appropriate for your apps. For more information on how to configure an NGINX App Protect policy, refer to NGINX App Protect Configuration Guide .

Security Strategy for BYO NAP Policy

The BYO NAP policy introduces the concept of a Security Strategy. A Security Strategy is a set security elements – for example, a NAP policy, compliance profile, and risk profile – that defines the sets of security controls that you can apply to your app components.

A Security Strategy lets you represent a security risk profile that each app component can reference. For example, you can map risk profile classifications used by your organization to low- or high-risk security strategies.

With the BYO NAP policy feature, you can specify the exact NGINX App Protect policy for the Security Strategy. Then this strategy can be shared across and referenced by multiple app components.

App Component –references–> Security Strategy –references–> NGINX App Protect policy

Refer to the topic Enable WAF for a Component Using Your Own NGINX App Protect Policy to get started.


The beta implementation for bringing your own NAP policies has the following limitations:

  • API only – at this time, you cannot use the NGINX Controller browser interface to configure BYO NAP policies
  • If you use the browser interface to change an app component that’s configured with a BYO NAP policy – for example, changing settings for Monitor Only, Disable WAF, Disable Signatures – the change will not update the security policy
  • The size of the BYO NAP policy that’s referenced by app components may affect app performance.
  • Updating the BYO NAP policy doesn’t automatically update the referenced app components. You must use the API to update the app component with the reference to the corresponding security strategy by sending a PUT request to /services/environment/<%env%>/app/<%app%>/component/<%component%>.
  • References to external files, such as the following, in the NAP JSON declarative policy are not supported:
    • User Defined Signatures
    • Security controls in external references
    • Referenced OpenAPI spec files
  • Cookie modification (VIOL_COOKIE_MODIFIED) is not supported.
  • gRPC protection is not supported.
  • Protection with partial security visibility:
    • Not all attributes or dimensions are available for the following:
      • Bot violations
      • CSRF origin validation violations
      • User-defined browser violations -The policy name is visible in the Security Events only from the NGINX Controller API (the /analytics/events endpoint), and not in the browser interface.

This documentation applies to the following versions of NGINX Controller Documentation: 3.17 and 3.18.