From: Bhagya Tholpady (bbantwal) Date: Tue, 25 Aug 2020 16:02:59 +0000 (+0000) Subject: Merge pull request #2421 in SNORT/snort3 from ~OSHUMEIK/snort3:doc_dump_config to... X-Git-Tag: 3.0.2-6~42 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=92266f903c0dc8adfc9afc491f1a4fd504bed099;p=thirdparty%2Fsnort3.git Merge pull request #2421 in SNORT/snort3 from ~OSHUMEIK/snort3:doc_dump_config to master Squashed commit of the following: commit 5c61850d9548f38433bad7adf1b1e2b8da730762 Author: Oleksii Shumeiko Date: Fri Aug 21 16:12:24 2020 +0300 doc: update the config dump in JSON format (main policy) commit 8584173190dc92a07e381dcf84083c1ca46e030c Author: Serhii Vlasiuk Date: Tue Aug 11 17:27:11 2020 +0300 doc: update the config dump in JSON format (all policies) --- diff --git a/doc/user/CMakeLists.txt b/doc/user/CMakeLists.txt index f9ffde53e..426827e13 100644 --- a/doc/user/CMakeLists.txt +++ b/doc/user/CMakeLists.txt @@ -11,7 +11,7 @@ set ( byte_test.txt concepts.txt connectors.txt - consolidated_config.txt + dump_config.txt daq.txt dcerpc.txt errors.txt diff --git a/doc/user/consolidated_config.txt b/doc/user/consolidated_config.txt deleted file mode 100644 index 12d4ef918..000000000 --- a/doc/user/consolidated_config.txt +++ /dev/null @@ -1,55 +0,0 @@ -Using Consolidated Config output enables troubleshooting of configuration issues. -The output contains applied configurations ( defaults and configured ) and is -printed for the main config and all included policies. -So far, Snort supports output in text format. - -==== Text Format - -The --dump-config-text option verifies the configuration and dumps it to stdout in text format. - -Example: - - consolidated config for snort.lua - binder[0].when.ips_policy_id=0 - binder[0].when.role='any' - binder[0].when.nets='10.1.2.0/24' - binder[0].use.action='inspect' - binder[1].when.ips_policy_id=0 - binder[1].when.role='any' - binder[1].when.nets='192.168.2.0/24' - binder[1].use.action='inspect' - host_cache.memcap=8.38861e+06 - network.checksum_drop='none' - network.checksum_eval='all' - network.max_ip_layers=0 - process.daemon=false - process.dirty_pig=false - process.utc=false - stream_tcp.flush_factor=0 - stream_tcp.max_window=0 - stream_tcp.overlap_limit=0 - stream_tcp.max_pdu=16384 - stream.footprint=0 - stream.ip_frags_only=false - trace.modules.appid.all=1 - trace.modules.detection.opt_tree=2 - trace.modules.detection.fp_search=4 - trace.modules.detection.rule_eval=1 - trace.modules.wizard.all=1 - trace.constraints.match=true - trace.constraints.dst_ip='10.1.1.2' - trace.constraints.dst_port=200 - trace.constraints.src_port=100 - trace.constraints.ip_proto=17 - trace.output='stdout' - wizard.spells[0].proto='tcp' - wizard.spells[0].client_first=true - wizard.spells[0].service='http' - wizard.spells[0].to_client[0].spell='HTTP/' - wizard.spells[0].to_server[0].spell='GET' - wizard.spells[1].proto='tcp' - wizard.spells[1].client_first=true - wizard.spells[1].service='sip' - wizard.spells[1].to_server[0].spell='INVITE' - -For lists, the index next to the option name designates an element parsing order. \ No newline at end of file diff --git a/doc/user/dump_config.txt b/doc/user/dump_config.txt new file mode 100644 index 000000000..c63d4183c --- /dev/null +++ b/doc/user/dump_config.txt @@ -0,0 +1,295 @@ +Config dump mode generates a consolidated dump of the config passed to Snort. +This output consists of the configured values as well as the module defaults +for the values that aren't configured. + +In the dump mode Snort validates the config (similar to option -T) +and suppresses unrelated messages going to stdout +(but not stderr one like ParseWarnings). + +The dump mode is activated by the following options: +--dump-config-text, --dump-config=all, --dump-config=top. +They are described in detail below. + +The simple configuration is used in examples. +The output contains applied configurations (defaults and configured). +To simplify the output we show a brief list of default options. + +snort.lua + + stream = + { + max_flows = 2 + } + + stream_tcp = + { + show_rebuilt_packets = true + } + + binder = + { + { when = { nets = '10.1.2.0/24' }, use = { inspection_policy = 'http.lua' } }, + { when = { nets = '192.168.2.0/24' }, use = { inspection_policy = 'sip.lua' } }, + } + +http.lua + + wizard = + { + spells = + { + { service = 'http', proto = 'tcp', client_first = true, to_server = { 'GET' }, to_client = { 'HTTP/' } }, + } + } + +sip.lua + + wizard = + { + spells = + { + { service = 'sip', to_server = { 'INVITE' } }, + } + } + +==== Text Format + +The --dump-config-text option verifies the configuration and dumps it to stdout in text format. +The output contains a config of the main policy and all other included sub-policies. + +Example: + snort -c snort.lua --dump-config-text + + consolidated config for snort.lua + alerts.order="pass reset block drop alert log" + alerts.rate_filter_memcap=1048576 + binder[0].when.ips_policy_id=0 + binder[0].when.role="any" + binder[0].when.nets="10.1.2.0/24" + binder[0].use.action="inspect" + binder[0].use.inspection_policy="http.lua" + binder[1].when.ips_policy_id=0 + binder[1].when.role="any" + binder[1].when.nets="192.168.2.0/24" + binder[1].use.action="inspect" + binder[1].use.inspection_policy="sip.lua" + output.obfuscate=false + output.wide_hex_dump=true + packets.address_space_agnostic=false + packets.limit=0 + search_engine.split_any_any=true + search_engine.queue_limit=128 + stream.file_cache.idle_timeout=180 + stream.file_cache.cap_weight=32 + stream.max_flows=2 + stream_tcp.small_segments.maximum_size=0 + stream_tcp.session_timeout=30 + stream_tcp.track_only=false + stream_tcp.show_rebuilt_packets=true + consolidated config for http.lua + wizard.spells[0].proto="tcp" + wizard.spells[0].client_first=true + wizard.spells[0].service="http" + wizard.spells[0].to_client[0].spell="HTTP/" + wizard.spells[0].to_server[0].spell="GET" + consolidated config for sip.lua + wizard.spells[0].proto="tcp" + wizard.spells[0].client_first=true + wizard.spells[0].service="sip" + wizard.spells[0].to_server[0].spell="INVITE" + +For lists, the index next to the option name designates an element parsing order. + +==== JSON Format + +The --dump-config=all command-line option verifies the configuration and dumps it to +stdout in JSON format. The output contains a config of the main policy and all other +included sub-policies. Snort dumps output in a one-line format. + +There is 3rd party tool 'jq' for converting to a pretty printed format. + +Example: + snort -c snort.lua --dump-config=all | jq '.' + + [ + { + "filename": "snort.lua", + "config": { + "alerts": { + "order": "pass reset block drop alert log", + "rate_filter_memcap": 1048576 + }, + "binder": [ + { + "when": { + "ips_policy_id": 0, + "role": "any", + "nets": "10.1.2.0/24" + }, + "use": { + "action": "inspect", + "inspection_policy": "http.lua" + } + }, + { + "when": { + "ips_policy_id": 0, + "role": "any", + "nets": "192.168.2.0/24" + }, + "use": { + "action": "inspect", + "inspection_policy": "sip.lua" + } + } + ], + "output": { + "obfuscate": false, + "wide_hex_dump": true + }, + "packets": { + "address_space_agnostic": false, + "limit": 0 + }, + "process": { + "daemon": false, + "dirty_pig": false, + "utc": false + }, + "search_engine": { + "split_any_any": true, + "queue_limit": 128 + }, + "stream": { + "file_cache": { + "idle_timeout": 180, + "cap_weight": 32 + }, + "max_flows": 2 + }, + "stream_tcp": { + "small_segments": { + "maximum_size": 0 + }, + "session_timeout": 30, + "track_only": false, + "show_rebuilt_packets": true + } + } + }, + { + "filename": "http.lua", + "config": { + "wizard": { + "spells": [ + { + "proto": "tcp", + "client_first": true, + "service": "http", + "to_client": [ + { + "spell": "HTTP/" + } + ], + "to_server": [ + { + "spell": "GET" + } + ] + } + ] + } + } + }, + { + "filename": "sip.lua", + "config": { + "wizard": { + "spells": [ + { + "proto": "tcp", + "client_first": true, + "service": "sip", + "to_server": [ + { + "spell": "INVITE" + } + ] + } + ] + } + } + } + ] + +The --dump-config=top command-line option is similar to --dump-config=all, +except it produces dump for the main policy only. +It verifies the configuration and dumps the main policy configuration to +stdout in JSON format. + +Example: + snort -c snort.lua --dump-config=top | jq '.' + + { + "alerts": { + "order": "pass reset block drop alert log", + "rate_filter_memcap": 1048576, + }, + "binder": [ + { + "when": { + "ips_policy_id": 0, + "role": "any", + "nets": "10.1.2.0/24" + }, + "use": { + "action": "inspect", + "inspection_policy": "http.lua" + } + }, + { + "when": { + "ips_policy_id": 0, + "role": "any", + "nets": "192.168.2.0/24" + }, + "use": { + "action": "inspect", + "inspection_policy": "sip.lua" + } + } + ], + "output": { + "obfuscate": false, + "wide_hex_dump": true + }, + "packets": { + "address_space_agnostic": false, + "limit": 0, + }, + "process": { + "daemon": false, + "dirty_pig": false, + "utc": false + }, + "search_engine": { + "split_any_any": true, + "queue_limit": 128 + }, + "stream": { + "file_cache": { + "idle_timeout": 180, + "cap_weight": 32 + } + "max_flows": 2 + }, + "stream_tcp": { + "small_segments": { + "count": 0, + "maximum_size": 0 + }, + "session_timeout": 30, + "track_only": false, + "show_rebuilt_packets": true + }, + } diff --git a/doc/user/features.txt b/doc/user/features.txt index 453d03102..cd2d735a4 100644 --- a/doc/user/features.txt +++ b/doc/user/features.txt @@ -34,7 +34,7 @@ include::byte_options.txt[] === Consolidated Config -include::consolidated_config.txt[] +include::dump_config.txt[] === DCE Inspectors