Merge pull request #3056 in SNORT/snort3 from ~VHORBATO/snort3:replace_doc_update...

Squashed commit of the following:

commit 442c4df5290bb247cbca8082017a07aef5ca1f6b
Author: Vitalii <vhorbato@cisco.com>
Date:   Mon Sep 13 11:41:16 2021 +0300

    doc: update the documentation of "replace" option and "rewrite" action

diff --git a/doc/user/active.txt b/doc/user/active.txt
index 2acaf189b190260b1cc7644ae5054ef4d5f149f0..54aad7cd905cedf10a282dba400e2e50f17b0a18 100644 (file)
--- a/doc/user/active.txt
+++ b/doc/user/active.txt
@@ -161,8 +161,10 @@ To turn it on:
 
 ==== Rewrite
 
-IPS action rewrite enables overwrite packet contents based on "replace" 
-option in the rules.
+IPS action "rewrite" enables overwrite packet contents based on "replace"
+option in the rules. Note that using "rewrite" action without "replace"
+option will raise corresponding rule alert, but will not overwrite the
+packet payload.
 
 For example:
 
@@ -182,5 +184,62 @@ For example:
         rules = local_rules,
     }
 
-this rule replaces "index.php" with "indax.php", and rewrite action 
-updates that packet.
+this rule replaces the first occurrence of "index.php" with "indax.php",
+and "rewrite" action updates that packet.
+
+Content and replacement are aligned to the right side of the matching
+content and are limited not by the size of the matching content, but
+by the boundaries of the packet.
+
+  Example:
+
+    rewrite http any any -> any any
+    (
+        msg:"Small replace";
+        content:"content";
+        replace:"text";
+        sid:1000002;
+    )
+
+  this rule replaces "malicious content" to "malicious context".
+
+  Example:
+
+    rewrite http any any -> any any
+    (
+        msg:"Big replace";
+        content:"content";
+        replace:"y favorite page!";
+        sid:1000002;
+    )
+
+  this rule replaces "malicious content" to "my favorite page!".
+
+Be aware that after the match there should be enough room left for the
+"replace" content in the matched packet. If there is not enough space
+for the "replace" content the rule will not match.
+
+"replace" works for raw packets only. So, TCP data must either fit
+under the "pkt_data" buffer requirements or one should enable detection
+on TCP payload before reassembly: search_engine.detect_raw_tcp=true.
+For example:
+
+  Rule that does not require search_engine.detect_raw_tcp=true:
+    
+    rewrite udp any any -> any any
+    (
+        msg:"TEST 1";
+        sid:1000002;
+        content:"attack";
+        replace:"abc123";
+    )
+
+  Rule that does require search_engine.detect_raw_tcp=true:
+    
+    rewrite http any any -> any any
+    (
+        msg:"TEST 2";
+        content:"/content.html";
+        replace:"/replace.html";
+        sid:1000002;
+    )
\ No newline at end of file

diff --git a/src/actions/act_replace.cc b/src/actions/act_replace.cc
index ccf525a8ca3c90f69e098aa91e9e376f374fce07..73697d328b71f2826dadff224c5412e91ac70b2a 100644 (file)
--- a/src/actions/act_replace.cc
+++ b/src/actions/act_replace.cc
@@ -34,7 +34,7 @@ using namespace snort;
 #define s_name "rewrite"
 
 #define s_help \
-    "overwrite packet contents"
+    "overwrite packet contents with the \"replace\" option content"
 
 //--------------------------------------------------------------------------
 // queue foo

diff --git a/src/actions/dev_notes.txt b/src/actions/dev_notes.txt
index a8f7026bc4820748af6b9d4178529940d0debbc2..8baae9c432fd996629087851c478a80de225a90d 100644 (file)
--- a/src/actions/dev_notes.txt
+++ b/src/actions/dev_notes.txt
@@ -18,7 +18,9 @@ It is using payload_injector utilty. payload_injector should be configured when
 react is used.
 
 Rewrite enables overwrite packet contents based on "replace" option in the
-rules.
+rules. Note that using "rewrite" action without "replace" option will raise
+the appropriate rule alert but will not overwrite the packet payload.
+Rewrite/replace works for raw packets only.
 
 Ips actions are all pluggable and implemented as subclasses of IpsAction action.
 Each ips action instance has an instance of the active action that is used to

diff --git a/src/ips_options/dev_notes.txt b/src/ips_options/dev_notes.txt
index 25629f2455685d62580b32398b42fc04f1429d08..8aa54518ea522bc693665945f2beeef3d7107a3a 100644 (file)
--- a/src/ips_options/dev_notes.txt
+++ b/src/ips_options/dev_notes.txt
@@ -19,3 +19,15 @@ https://intel.github.io/hyperscan/dev-reference
 
 The "sd_pattern" will be used as a fast pattern in the future (like "regex")
 for performance. 
+
+"replace" option has the following restrictions:
+- Content and replacement are aligned to the right side of the matching
+content and are limited not by the size of the matching content, but
+by the boundaries of the packet.
+- Be aware that after the match there should be enough room left for the
+"replace" content in the matched packet. If there is not enough space
+for the "replace" content the rule will not match.
+- Only the first occurrence of the content will be replaced.
+- "replace" works for raw packets only. So, TCP data must either fit
+under the "pkt_data" buffer requirements or one should enable detection
+on TCP payload before reassembly: search_engine.detect_raw_tcp=true.
\ No newline at end of file

diff --git a/src/ips_options/ips_replace.cc b/src/ips_options/ips_replace.cc
index 9c21be9da37e0f149f7eca7f08cb1c95afe5d4c4..fd7645029582da28621d64d4f58de2e0eff8fa3a 100644 (file)
--- a/src/ips_options/ips_replace.cc
+++ b/src/ips_options/ips_replace.cc
@@ -188,7 +188,7 @@ static const Parameter s_params[] =
 };
 
 #define s_help \
-    "rule option to overwrite payload data; use with rewrite action"
+    "rule option to overwrite payload data; use with \"rewrite\" action; works for raw packets only"
 
 class ReplModule : public Module
 {