From 72dd4a5f92bc5507b97eb3b48f0d6f1c1a50ec31 Mon Sep 17 00:00:00 2001
From: Victor Julien <victor@inliniac.net>
Date: Wed, 17 Oct 2018 09:45:56 +0200
Subject: [PATCH] doc/rules: initial transforms documentation

---
 doc/userguide/rules/index.rst      |  1 +
 doc/userguide/rules/transforms.rst | 51 ++++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+)
 create mode 100644 doc/userguide/rules/transforms.rst

diff --git a/doc/userguide/rules/index.rst b/doc/userguide/rules/index.rst
index ed1cdaceb3..e8b45cf8dd 100644
--- a/doc/userguide/rules/index.rst
+++ b/doc/userguide/rules/index.rst
@@ -7,6 +7,7 @@ Suricata Rules
    meta
    header-keywords
    payload-keywords
+   transforms
    prefilter-keywords
    flow-keywords
    http-keywords
diff --git a/doc/userguide/rules/transforms.rst b/doc/userguide/rules/transforms.rst
new file mode 100644
index 0000000000..3b47bf19f7
--- /dev/null
+++ b/doc/userguide/rules/transforms.rst
@@ -0,0 +1,51 @@
+Transformations
+===============
+
+Transformation keywords turn the data at a sticky buffer into something else.
+
+Example::
+
+    alert http any any -> any any (file_data; strip_whitespace; \
+        content:"window.navigate("; sid:1;)
+
+This example will match on traffic even if there are one or more spaces between
+the ``navigate`` and ``(``.
+
+The transforms can be chained. They are processed in the order in which they
+appear in a rule. Each transforms output acts as input for the next one.
+
+Example::
+
+    alert http any any -> any any (http_request_line; compress_whitespace; to_sha256; \
+        content:"|54A9 7A8A B09C 1B81 3725 2214 51D3 F997 F015 9DD7 049E E5AD CED3 945A FC79 7401|"; sid:1;)
+
+.. note:: not all sticky buffers support transformations yet
+
+strip_whitespace
+----------------
+
+Strips all whitespace as considered by the ``isspace()`` call in C.
+
+Example::
+
+    alert http any any -> any any (file_data; strip_whitespace; \
+        content:"window.navigate("; sid:1;)
+
+compress_whitespace
+-------------------
+
+Compresses all consecutive whitespace into a single space.
+
+to_sha256
+---------
+
+Takes the buffer, calculates the SHA-256 hash and passes the raw hash value
+on.
+
+Example::
+
+    alert http any any -> any any (http_request_line; to_sha256; \
+        content:"|54A9 7A8A B09C 1B81 3725 2214 51D3 F997 F015 9DD7 049E E5AD CED3 945A FC79 7401|"; sid:1;)
+
+.. note:: depends on libnss being compiled into Suricata
+