From: Russ Combs (rucombs) <rucombs@cisco.com>
Date: Wed, 24 Nov 2021 17:42:22 +0000 (+0000)
Subject: Pull request #3182: doc: updated module usage and inspector types in the dev guide
X-Git-Tag: 3.1.18.0~11
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4c25dd2545bb029604d7266492310ac860ac659e;p=thirdparty%2Fsnort3.git

Pull request #3182: doc: updated module usage and inspector types in the dev guide

Merge in SNORT/snort3 from ~RUCOMBS/snort3:doc_devel to master

Squashed commit of the following:

commit 23d309942fa1c44dffeed965b4ffa4fee4c15e3d
Author: Russ Combs <rucombs@cisco.com>
Date:   Tue Nov 23 16:09:34 2021 -0500

    doc: updated module usage and inspector types in the dev guide
---

diff --git a/doc/devel/extending.txt b/doc/devel/extending.txt
index 5861d1f75..76ac5b349 100644
--- a/doc/devel/extending.txt
+++ b/doc/devel/extending.txt
@@ -46,31 +46,47 @@ Note that there is at most one instance of a given Module, even if multiple
 plugin instances are created which use that Module.  (Multiple instances
 require Snort binding configuration.)
 
+A module's usage determines how it may be configured:
+
+* Global: configured at most once, outside any policy.
+
+* Context: configured at most once in a network policy, eg event_queue.
+
+* Inspect: configured in an inspection policy aka network analysis
+  policy (NAP); stream and service inspectors like stream_tcp and smtp are
+  multitons, ie they may be configured more than once in a policy, while
+  others like binder are singletons and can be configured at most once per
+  policy.
+
+* Detect: configured at most once in an IPS policy, eg ips.
 
 === Inspectors
 
 There are several types of inspector, which determines which inspectors are
 executed when:
 
-* IT_BINDER - determines which inspectors apply to given flows
+* IT_CONTROL - process all packets before detection
 
-* IT_WIZARD - determines which service inspector to use if none explicitly
-  bound
-
-* IT_PACKET - used to process all packets before session and service processing
-  (e.g. normalize)
+* IT_FIRST - analyze 1st pkt of new flow and 1st pkt after reload of
+  ongoing flow (eg reputation)
 
 * IT_NETWORK - processes packets w/o service (e.g. arp_spoof, back_orifice)
 
-* IT_STREAM - for flow tracking, ip defrag, and tcp reassembly
+* IT_PACKET - used to process raw packets only (e.g. normalizer)
 
-* IT_SERVICE - for http, ftp, telnet, etc.
+* IT_PASSIVE - for configuration only or for handling inspection events (eg
+  ftp_client and binder)
 
-* IT_PROBE - process all packets after all the above (e.g. perf_monitor,
+* IT_PROBE - process all packets after all the detection (e.g. perf_monitor,
   port_scan)
 
-* IT_PASSIVE - for configuration only or data consuming
+* IT_SERVICE - for analyzing PDUs eg http_inspect, ftp_server, telnet, etc.
 
+* IT_STREAM - for flow tracking, ip defrag, and TCP reassembly; also for
+  processing files directly or TCP payload-only streams
+
+* IT_WIZARD - determines which service inspector to use if none explicitly
+  bound by matching start-of-flow patterns
 
 === Codecs