1<!DOCTYPE refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> 2<refentry> 3 4<refmeta> 5<refentrytitle> 6<application>flow-dscan</application> 7</refentrytitle> 8<manvolnum>1</manvolnum> 9</refmeta> 10 11<refnamediv> 12<refname> 13<application>flow-dscan</application> 14</refname> 15<refpurpose> 16Detect scanning and other suspicious network activity. 17</refpurpose> 18</refnamediv> 19 20<refsynopsisdiv> 21<cmdsynopsis> 22<command>flow-dscan</command> 23<arg>-bBhlmpwW</arg> 24<arg>-d<replaceable> debug_level</replaceable></arg> 25<arg>-D<replaceable> iplist_depth</replaceable></arg> 26<arg>-s<replaceable> state_file</replaceable></arg> 27<arg>-i<replaceable> input_filter</replaceable></arg> 28<arg>-L<replaceable> suppress_list</replaceable></arg> 29<arg>-o<replaceable> output_filter</replaceable></arg> 30<arg>-O<replaceable> excessive_octets</replaceable></arg> 31<arg>-P<replaceable> excessive_flows</replaceable></arg> 32<arg>-S<replaceable> port_scan_trigger</replaceable></arg> 33<arg>-t<replaceable> ager_timeout</replaceable></arg> 34</cmdsynopsis> 35</refsynopsisdiv> 36 37 38<refsect1> 39<title>DESCRIPTION</title> 40<para> 41The <command>flow-dscan</command> utility is used to detect suspicious 42activity such as port scanning, host scanning, and flows with 43unusually high octets or packets. A source and destination suppress 44list is supported to help prevent false alarms due to hosts such as 45nameservers or popular web servers that exchange traffic with a large 46number of hosts. Alarms are logged to syslog or stderr. The internal 47state of flow-dscan can be saved and loaded to allow for interrupted operation. 48</para> 49<para> 50<command>flow-dscan</command> will work best if configured to only watch only inbound or outbound 51traffic by using the input or output interface filter option. 52</para> 53<para> 54The host scanner works by counting the length of the destination IP 55hash chain. If it goes above 64, then the src is considered to 56be scanning. 57</para> 58<para> 59The port scanner works by keeping a bitmap of the destination port 60number < 1024 per destination IP. If it goes above 64, the src is 61considered to be port scanning the destination. 62</para> 63<para> 64When a src has been flagged as scanning it will not be reported again 65until the record is aged out and enough flows trigger it again. 66</para> 67<para> 68A SIGHUP signal will instruct flow-dscan to reload the suppress list. 69</para> 70<para> 71A SIGUSR1 signal will instruct flow-dscan to dump its internal state. 72</para> 73</refsect1> 74 75<refsect1> 76<title>OPTIONS</title> 77<variablelist> 78 79<varlistentry> 80<term>-b</term> 81<listitem> 82<para> 83Do not detach and run in the background. Alerts go to stderr. 84</para> 85</listitem> 86</varlistentry> 87 88<varlistentry> 89<term>-B</term> 90<listitem> 91<para> 92Do not detach and run in the background. Alerts go to syslog. 93</para> 94</listitem> 95</varlistentry> 96 97<varlistentry> 98<term>-d<replaceable> debug_level</replaceable></term> 99<listitem> 100<para> 101Enable debugging. 102</para> 103</listitem> 104</varlistentry> 105 106<varlistentry> 107<term>-D<replaceable> iplist_depth</replaceable></term> 108<listitem> 109<para> 110Depth of IP host list for detecting host scanning. 111</para> 112</listitem> 113</varlistentry> 114 115<varlistentry> 116<term>-h</term> 117<listitem> 118<para> 119Display help. 120</para> 121</listitem> 122</varlistentry> 123 124<varlistentry> 125<term>-i<replaceable> input_filter</replaceable></term> 126<listitem> 127<para> 128Input interface filter list. 129</para> 130</listitem> 131</varlistentry> 132 133<varlistentry> 134<term>-I<replaceable> output_filter</replaceable></term> 135<listitem> 136<para> 137Output interface filter list. 138</para> 139</listitem> 140</varlistentry> 141 142<varlistentry> 143<term>-l</term> 144<listitem> 145<para> 146Load state from <filename>/var/tmp/dscan.state</filename> or the filename 147specified with -s. 148</para> 149</listitem> 150</varlistentry> 151 152<varlistentry> 153<term>-L<replaceable> suppress_list</replaceable></term> 154<listitem> 155<para> 156Basename of suppress files. There are two suppress files for input and 157output traffic. The suppress file syntax is 158</para> 159<para> 160IP_address protocol source_port destination_port 161</para> 162<para> 163A '-' can be used as a wildcard in the protocol, source_port, 164and destination_port fields. Only a single protocol, source_port, and 165destination_port is supported per IP address. 166</para> 167</listitem> 168</varlistentry> 169 170<varlistentry> 171<term>-m</term> 172<listitem> 173<para> 174Multicast address filter. Use to ignore multicast addresses. 175</para> 176</listitem> 177</varlistentry> 178 179<varlistentry> 180<term>-O<replaceable> excessive_octets</replaceable></term> 181<listitem> 182<para> 183Trigger an alert if a flow is processed with the octets field exceeding 184<replaceable>excessive_octets</replaceable>. 185</para> 186</listitem> 187</varlistentry> 188 189<varlistentry> 190<term>-p</term> 191<listitem> 192<para> 193Dump state to <filename>/var/tmp/dscan.state</filename> or the filename 194specified with -s. 195</para> 196</listitem> 197</varlistentry> 198 199<varlistentry> 200<term>-P<replaceable> excessive_packets</replaceable></term> 201<listitem> 202<para> 203Trigger an alert if a flow is processed with the packets field exceeding 204<replaceable>excessive_packets</replaceable>. 205</para> 206</listitem> 207</varlistentry> 208 209<varlistentry> 210<term>-s<replaceable> statefile</replaceable></term> 211<listitem> 212<para> 213State filename. Defaults to <filename>/var/tmp/dscan.state</filename> 214</para> 215</listitem> 216</varlistentry> 217 218<varlistentry> 219<term>-S<replaceable> port_scan_trigger</replaceable></term> 220<listitem> 221<para> 222Number of ports a IP address must have used to be considered scanning. 223</para> 224</listitem> 225</varlistentry> 226 227<varlistentry> 228<term>-t<replaceable> ager_timeout</replaceable></term> 229<listitem> 230<para> 231How long to keep flows around. Default to 90000. This is measured in 232flows processed. 233</para> 234</listitem> 235</varlistentry> 236 237<varlistentry> 238<term>-T<replaceable> excessive_time</replaceable></term> 239<listitem> 240<para> 241Trigger an alert if a flow is processed with the End-Start field exceeding 242<replaceable>excessive_time</replaceable>. 243</para> 244</listitem> 245</varlistentry> 246 247<varlistentry> 248<term>-w</term> 249<listitem> 250<para> 251Filter (ignore) candidate inbound www traffic, ie IP protocol 6, source port 25280, and destination port > 1023. 253</para> 254</listitem> 255</varlistentry> 256 257<varlistentry> 258<term>-W</term> 259<listitem> 260<para> 261Filter (ignore) candidate outbound www traffic, ie IP protocol 6, destination 262port 80, and source port > 1023. 263</para> 264</listitem> 265</varlistentry> 266 267 268</variablelist> 269</refsect1> 270 271<refsect1> 272<title>EXAMPLES</title> 273<informalexample> 274<para> 275In a topology where 25 is the only output interface run flow-dscan over 276the data in <filename>/flows/krc4</filename>. Ignore www and multicast 277traffic, store the internal state in 278<filename>dscan.statefile</filename> on exit. Use empty suppress list 279files <filename>dscan.suppress.src</filename> and 280<filename>dscan.suppress.dst</filename>. The output produced by flow-dscan 281typically must be manually inspected by using flow-filter and flow-print. 282Many of the alerts will be false until the suppress lists are populated 283for the local environment. 284</para> 285<para> 286 <command>flow-cat /flows/krc4 | flow-dscan -I25 -b -m -s dscan.statefile -p -W</command> 287</para> 288</informalexample> 289</refsect1> 290 291<refsect1> 292<title>BUGS</title> 293<para> 294The ager should automatically become more aggressive when a low memory 295condition exists. 296 297There is no upper limit on the number of records that can be allocated. If 298the ager is not running often enough the host will be run out of memory. 299</para> 300</refsect1> 301 302<refsect1> 303<title>AUTHOR</title> 304<para> 305<author> 306<firstname>Mark</firstname> 307<surname>Fullmer</surname> 308</author> 309<email>maf@splintered.net</email> 310</para> 311</refsect1> 312 313<refsect1> 314<title>SEE ALSO</title> 315<para> 316<application>flow-tools</application>(1) 317</para> 318</refsect1> 319 320</refentry> 321