NGINX Modern Apps > Class 5 - NGINX App Protect WAF & DoS > Module 5 - Advanced Tools and Features Source | Edit on

BIG-IP User Defined Signatures Converter¶

User-Defined Signature Definitions¶

A useful expansion to the customization capabilities of NGINX App Protect is the ability to create user-defined signatures. This capability allows the user to define new signatures, configure how they behave in terms of enforcement, and categorize them in user-defined signature sets (using tags) for ease of management.

The process of creating and implementing a user policy that contains user-defined signatures is a three-fold process:

Creating the user-defined signature definitions in separate JSON files.
Adding the relevant references (names, tags, signature sets) to the user-defined signatures in the policy file.
Adding the definitions and referencing the relevant policy file in the nginx.conf file.

The user-defined signature definition file is a JSON file where the signatures themselves are defined and given their properties and tags. The format of the user-defined signature definition is as follows:

{
   "name": "unique_name",
   "description": "Add your description here",
   "rule": "content:\"string\"; nocase;",
   "signatureType": "request",
   "attackType": {
      "name": "Buffer Overflow"
   },
   "systems": [
      {
            "name": "Microsoft Windows"
      },
      {
            "name": "Unix/Linux"
      }
   ],
   "risk": "medium",
   "accuracy": "medium"
}

Here is a brief explanation about each of the above items in the signature definition:

name - is the unique name to be given to the user-defined signature.
description - is an optional item where you can add a human-readable text to describe the functionality or purpose of the signature.
rule - is the rule by which the enforcement will be done. The rule uses Snort syntax: a keyword to look for in a certain context, such as URL, header, parameter, content, and optionally one or more regular expressions. For full details on how to create a rule and the possible permutations, check the Rule Syntax page.
signatureType - defines whether the signature is relevant to the request or the response.
attackType - this field gives an indication of the attack type the signature is intended to prevent. This field is mostly useful for signature set enforcement and logging purposes. A full list of the available attack types can be found in the Attack Types document.
systems - is a list of systems (operating systems, programming languages, etc.) that the signature should be applicable for. Note that systems have the same meaning and use as server technologies although the overlap between both terms is not perfect. For more information, review the Server Technologies documentation.
risk - defines the risk level associated with this signature. Possible values are: low, medium, high.
accuracy - defines the accuracy level of the signature. Note that the value of this field contributes to the value of the Violation Rating. Possible values are: low, medium, high.

While you can create signatures in your NGINX App Protect environment, many users migrating or augmenting existing BIG-IP WAF policies with NGINX App Protect need to convert their existing signatures.

User Defined Signatures Converter¶

For those that have Advanced WAF/ASM deployed on BIG-IP, the User Defined Signatures Converter tool takes a User Defined Signatures XML file, exported from a BIG-IP, as input and exports the content as a JSON file suitable for use in an NGINX App Protect WAF environment.

The tool can optionally accept a tag argument as an input. Otherwise, the default tag value user-defined-signatures is assigned to the exported JSON file.

Note

A hands-on example of converting user defined signatures is not yet included in this lab.

The usage of the utility is as follows:

USAGE:
   /opt/app_protect/bin/convert-signatures

Required arguments:
   --outfile|o='/path/to/signatures.json'
      File name to write JSON format export
      Can also be set via an environment variable: EXPORT_FILE
   --infile|i='/path/to/signatures.xml'
      Advanced WAF/ASM User Defined Signatures file to Convert
      Can also be set via an environment variable: IMPORT_FILE

Optional arguments:
   --tag|t='mytag'
      Signature Tag to associate with User Defined Signatures.
      If no tag is specified in the XML file, a default tag of 'user-defined-signatures' will be assigned.
      Can also be set via an environment variable: TAG
   --format|f='json'
      Desired output format for signature file. Default 'json'
      Supported formats: 'json'

To perform the conversion, use the following command syntax:

/opt/app_protect/bin/convert-signatures -i /path/to/signatures.xml -o /path/to/signatures.json | jq

You may observe output similar to the following, which displays a list of settings and unsupported entities that the tool removed.

{
   "file_size": 1003,
   "filename": "/path/to/signatures.json",
   "completed_successfully": true
}

An example of the contents of the output:

{
   "signatures": [
      {
            "attackType": {
               "name": "Buffer Overflow"
            },
            "name": "my_first_sig",
            "lastUpdateMicros": 1606014750000000,
            "rule": "content:\"first_sig\"; nocase;",
            "description": "This is the first user defined signature",
            "revision": "1",
            "systems": [
               {
                  "name": "Microsoft Windows"
               }
            ],
            "accuracy": "low",
            "signatureId": "300000002",
            "signatureType": "request",
            "risk": "low"
      },
      {
            "attackType": {
               "name": "Command Execution"
            },
            "name": "my_second_sig",
            "lastUpdateMicros": 1606014818000000,
            "rule": "uricontent:\"second_sig\"; nocase; objonly;",
            "description": "Short description of the signature",
            "revision": "1",
            "systems": [
               {
                  "name": "Unix/Linux"
               }
            ],
            "accuracy": "medium",
            "signatureId": "300000003",
            "signatureType": "request",
            "risk": "medium"
      }
   ],
   "tag": "user-defined-signatures"
}

Using this tool can help SecOps teams keep track of the signature sets in use by policies without the need to access production instances.

Previous Next