From f31c851505a6433fa4367a4130b9b08cb9deddce Mon Sep 17 00:00:00 2001
From: mouraddmeiri <67323028+mouraddmeiri@users.noreply.github.com>
Date: Mon, 27 Jan 2025 15:47:13 +0200
Subject: [PATCH 01/22] Add documentation for UDS converter in NAP5 (#110)
---
.../v5/configuration-guide/configuration.md | 177 +++++++++++++++++-
1 file changed, 174 insertions(+), 3 deletions(-)
diff --git a/content/nap-waf/v5/configuration-guide/configuration.md b/content/nap-waf/v5/configuration-guide/configuration.md
index 472b547a8..e6b8ed194 100644
--- a/content/nap-waf/v5/configuration-guide/configuration.md
+++ b/content/nap-waf/v5/configuration-guide/configuration.md
@@ -931,7 +931,11 @@ In the cases where decompression fails, NGINX App Protect WAF will continue wit
---
-## Policy Converter
+## Converter Tools
+
+NGINX App Protect WAF includes a number of tools that can be used to facilitate the process of porting existing resources or configuration files from the BIG-IP for use in the NGINX App Protect WAF environment. Note that these tools are available in the compiler package, and do not require a full installation of NGINX App Protect WAF or NGINX Plus.
+
+### Policy Converter
The NGINX App Protect WAF v5 Policy Converter tool `/opt/app_protect/bin/convert-policy` is used to convert XML policies to JSON format. The converted JSON policy is based on the NGINX App Protect WAF policy base template and contains the minimal differences to it in JSON declarative policy format.
@@ -943,7 +947,7 @@ Using the tool:
/opt/app_protect/bin/convert-policy
```
-### Convert Policy using Command Line Interface (CLI Usage)
+#### Convert Policy using Command Line Interface (CLI Usage)
The input policy can also be converted using convert-policy as a CLI tool from within NGINX App Protect WAF Converter container by using the following commands:
@@ -957,7 +961,7 @@ docker run -it --rm \
--full-export
```
-### Command Line Options
+#### Command Line Options
{{}}
|Field Name | Notes |
@@ -969,6 +973,173 @@ docker run -it --rm \
| --dos-profile | Filename of JSON DoS Profile (pre-converted to JSON from tmsh syntax) |
| --full-export | If specified, the full policy with all entities will be exported. Otherwise, only entities that differ from the template will be included.
Default for the CLI is not specific (only differing entities).
Default for the REST endpoint above is "--full-export" (you can not override this).|{{}}
+### User Defined Signatures Converter
+
+The User Defined Signatures Converter tool `/opt/app_protect/bin/convert-signatures` takes a User Defined Signatures XML file 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 that the User Defined signatures XML file can be obtained by exporting the signatures from a BIG-IP device.
+
+Using the tool:
+```shell
+/opt/app_protect/bin/convert-signatures
+```
+
+Output:
+```shell
+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'
+
+Optionally, using --help will issue this help message.
+```
+
+Example of generating a user defined signature JSON file (with default tag):
+```shell
+docker run -v `pwd`:`pwd` -w `pwd` --entrypoint /opt/app_protect/bin/convert-signatures docker_img:latest -i /path/to/signatures.xml -o /path/to/signatures.json | jq
+```
+
+Output:
+```json
+{
+ "filename": "/path/to/signatures.json",
+ "file_size": 1602,
+ "completed_successfully": true
+}
+```
+
+Example of the contents of the output file (displayed and piped into `jq`):
+```json
+{
+ "tag": "user-defined-signatures",
+ "signatures": [
+ {
+ "accuracy": "high",
+ "risk": "high",
+ "systems": [],
+ "rule": "content:\"header1\"; nocase;",
+ "description": "",
+ "signatureType": "request",
+ "signatureId": "300000000",
+ "revision": "1",
+ "lastUpdateMicros": 1731425468000000,
+ "name": "sig_1_header",
+ "attackType": {
+ "name": "Abuse of Functionality"
+ }
+ },
+ {
+ "signatureId": "300000002",
+ "signatureType": "request",
+ "attackType": {
+ "name": "Cross Site Scripting (XSS)"
+ },
+ "name": "sig_3_uri",
+ "lastUpdateMicros": 1731425631000000,
+ "revision": "1",
+ "risk": "high",
+ "accuracy": "high",
+ "description": "",
+ "rule": "uricontent:\"