1LIBNIDS(3) Library Functions Manual LIBNIDS(3)
2
6 libnids - network intrusion detection system E-box library
7
9 #include <nids.h>
10 extern struct nids_prm nids_params;
12 extern char nids_errbuf[];
13 int
15 nids_init(void);
16 void
18 nids_register_ip_frag(void (*ip_frag_func)(struct ip *pkt, int len));
19 void
21 nids_unregister_ip_frag(void (*ip_frag_func)(struct ip *pkt, int len));
22 void
24 nids_register_ip(void (*ip_func)(struct ip *pkt, int len));
25 void
27 nids_unregister_ip(void (*ip_func)(struct ip *pkt, int len));
28 void
30 nids_register_udp(void (*udp_func)(struct tuple4 *addr, u_char *data, int len, struct ip *pkt));
31 void
33 nids_unregister_udp(void (*udp_func)(struct tuple4 *addr, u_char *data, int len, struct ip *pkt));
34 void
36 nids_register_tcp(void (*tcp_func)(struct tcp_stream *ts, void **param));
37 void
39 nids_unregister_tcp(void (*tcp_func)(struct tcp_stream *ts, void **param));
40 void
42 nids_killtcp(struct tcp_stream *ts);
43 void
45 nids_discard(struct tcp_stream *ts, int numbytes);
46 void
48 nids_run(void);
49 int
51 nids_dispatch(int cnt);
52 int
54 nids_next(void);
55 int
57 nids_getfd(void);
58 int
60 nids_register_chksum_ctl(struct nids_chksum_ctl *, int);
61 void
63 nids_pcap_handler(u_char *par, struct pcap_pkthdr *hdr, u_char *data);
64 struct tcp_stream *
66 nids_find_tcp_stream(struct tuple4 *addr);
67
70 libnids provides the functionality of a network intrusion detection
71 system (NIDS) E-box component. It currently performs:
72 1. IP defragmentation
74 2. TCP stream reassembly
75 3. TCP port scan detection
76 libnids performs TCP/IP reassembly in exactly the same way as Linux
78 2.0.36 kernels, and correctly handles all of the attacks implemented in
79 fragrouter(8) (plus many other attacks as well).
80
82 nids_init() initializes the application for sniffing, based on the val‐
83 ues set in the global variable nids_params, declared as follows:
84 struct nids_prm {
86 int n_tcp_streams;
87 int n_hosts;
88 char *device;
89 char *filename;
90 int sk_buff_size;
91 int dev_addon;
92 void (*syslog)(int type, int err, struct ip *iph, void *data);
93 int syslog_level;
94 int scan_num_hosts;
95 int scan_num_ports;
96 int scan_delay;
97 void (*no_mem)(void);
98 int (*ip_filter)(struct ip *iph);
99 char *pcap_filter;
100 int promisc;
101 int one_loop_less;
102 int pcap_timeout;
103 int multiproc;
104 int queue_limit;
105 int tcp_workarounds;
106 pcap_t *pcap_desc;
107 } nids_params;
108 The members of this structure are:
110 n_tcp_streams
112 Size of the hash table used for storing TCP connection informa‐
113 tion ( a maximum of 3/4 * n_tcp_streams TCP connections will be
114 followed simultaneously). Default value: 1024
115 n_hosts
117 Size of the hash table used for storing IP defragmentation
118 information. Default value: 256
119 filename
121 It this variable is set, libnids will call pcap_open_offline
122 with this variable as the argument (instead of
123 pcap_open_live()). Default value: NULL
124 device Interface to monitor. Default value: NULL (in which case an
126 appropriate device is determined automatically). If this vari‐
127 able is assigned value all, libnids will attempt to capture
128 packets on all interfaces (which works on Linux only)
129 sk_buff_size
131 Size of struct sk_buff (used for queuing packets), which should
132 be set to match the value on the hosts being monitored. Default
133 value: 168
134 dev_addon
136 Number of bytes in struct sk_buff reserved for link-layer infor‐
137 mation. Default value: -1 (in which case an appropriate offset
138 if determined automatically based on link-layer type)
139 syslog Syslog callback function, used to report unusual conditions,
141 such as port scan attempts, invalid TCP header flags, etc.
142 Default value: nids_syslog (which logs messages via syslog(3)
143 without regard for message rate per second or free disk space)
144 syslog_level
146 Log level used by nids_syslog for reporting events via sys‐
147 log(3). Default value: LOG_ALERT
148 scan_num_hosts
150 Size of hash table used for storing portscan information (the
151 maximum number portscans that will be detected simultaneously).
152 If set to 0, portscan detection will be disabled. Default value:
153 256
154 scan_num_ports
156 Minimum number of ports that must be scanned from the same
157 source host before it is identifed as a portscan. Default value:
158 10
159 scan_delay
161 Maximum delay (in milliseconds) between connections to different
162 ports for them to be identified as part of a portscan. Default
163 value: 3000
164 no_mem Out-of-memory callback function, used to terminate the calling
166 process gracefully.
167 ip_filter
169 IP filtering callback function, used to selectively discard IP
170 packets, inspected after reassembly. If the function returns a
171 non-zero value, the packet is processed; otherwise, it is dis‐
172 carded. Default value: nids_ip_filter (which always returns 1)
173 pcap_filter
175 pcap(3) filter string applied to the link-layer (raw, unassem‐
176 bled) packets. Note: filters like ``tcp dst port 23'' will NOT
177 correctly handle appropriately fragmented traffic, e.g. 8-byte
178 IP fragments; one should add "or (ip[6:2] & 0x1fff != 0)" at the
179 end of the filter to process reassembled packets. Default value:
180 NULL
181 promisc
183 If non-zero, libnids will set the interface(s) it listens on to
184 promiscuous mode. Default value: 1
185 one_loop_less
187 Disabled by default; see comments in API.html file
188 pcap_timeout
190 Sets the pcap read timeout, which may or may not be supported by
191 your platform. Default value: 1024.
192 multiproc
194 If nonzero, creates a separate thread for packets processing.
195 See API.html. Default value: 0.
196 queue_limit
198 If multiproc is nonzero, this is the maximum number of packets
199 queued in the thread which reads packets from libpcap. Default
200 value: 20000
201 tcp_workarounds
203 Enables extra checks for faulty implementations of TCP such as
204 the ones which allow connections to be closed despite the fact
205 that there should be retransmissions for lost packets first (as
206 stated by RFC 793, section 3.5). If non-zero, libnids will set
207 the NIDS_TIMED_OUT state for savagely closed connections.
208 Default value: 0
209 pcap_desc
211 It this variable is set, libnids will call neither
212 pcap_open_live nor pcap_open_offline, but will use a pre-opened
213 PCAP descriptor; use this with nids_pcap_handler() in order to
214 interactively feed packets to libnids. Default value: NULL
215 Returns 1 on success, 0 on failure (in which case nids_errbuf contains
217 an appropriate error message).
218 nids_register_ip_frag() registers a user-defined callback function to
220 process all incoming IP packets (including IP fragments, packets with
221 invalid checksums, etc.).
222 nids_unregister_ip_frag() unregisters a user-defined callback function
224 to process all incoming IP packets.
225 nids_register_ip() registers a user-defined callback function to
227 process IP packets validated and reassembled by libnids.
228 nids_unregister_ip() unregisters a user-defined callback function to
230 process IP packets.
231 nids_register_udp() registers a user-defined callback function to
233 process UDP packets validated and reassembled by libnids.
234 nids_unregister_udp() unregisters a user-defined callback function to
236 process UDP packets.
237 nids_register_tcp() registers a user-defined callback function to
239 process TCP streams validated and reassembled by libnids. The
240 tcp_stream structure is defined as follows:
241 struct tcp_stream {
243 struct tuple4 {
244 u_short source;
245 u_short dest;
246 u_int saddr;
247 u_int daddr;
248 } addr;
249 char nids_state;
250 struct half_stream {
251 char state;
252 char collect;
253 char collect_urg;
254 char *data;
255 u_char urgdata;
256 int count;
257 int offset;
258 int count_new;
259 char count_new_urg;
260 ...
261 } client;
262 struct half_stream server;
263 ...
264 void *user;
265 };
266 The members of the tuple4 structure identify a unique TCP connection:
268 source, dest
270 Client and server port numbers
271 saddr, daddr
273 Client and server IP addresses
274 The members of the half_stream structure describe each half of a TCP
276 connection (client and server):
277 state Socket state (e.g. TCP_ESTABLISHED).
279 collect
281 A boolean which specifies whether to collect data for this half
282 of the connection in the data buffer.
283 collect_urg
285 A boolean which specifies whether to collect urgent data pointed
286 to by the TCP urgent pointer for this half of the connection in
287 the urgdata buffer.
288 data Buffer for normal data.
290 urgdata
292 One-byte buffer for urgent data.
293 count The number of bytes appended to data since the creation of the
295 connection.
296 offset The current offset from the first byte stored in the data buf‐
298 fer, identifying the start of newly received data.
299 count_new
301 The number of bytes appended to data since the last invocation
302 of the TCP callback function (if 0, no new data arrived).
303 count_new_urg
305 The number of bytes appended to urgdata since the last invoca‐
306 tion of the TCP callback function (if 0, no new urgent data
307 arrived).
308 The value of the nids_state field provides information about the state
310 of the TCP connection, to be used by the TCP callback function:
311 NIDS_JUST_EST
313 Connection just established. Connection parameters in the addr
314 structure are available for inspection. If the connection is
315 interesting, the TCP callback function may specify which data it
316 wishes to receive in the future by setting non-zero values for
317 the collect or collect_urg variables in the appropriate client
318 or server half_stream structure members.
319 NIDS_DATA
321 New data has arrived on a connection. The half_stream structures
322 contain buffers of data.
323 NIDS_CLOSE, NIDS_RESET, NIDS_TIMED_OUT
325 Connection has closed. The TCP callback function should free any
326 resources it may have allocated for this connection.
327 The param pointer passed by libnids as argument to the TCP callback
329 function may be set to save a pointer to user-defined connection-spe‐
330 cific data to pass to subsequent invocations of the TCP callback func‐
331 tion (ex. the current working directory for an FTP control connection,
332 etc.).
333 The user pointer in the tcp_stream structure has the same purpose
335 except it is global to the stream, whereas the param pointer is differ‐
336 ent from one callback function to the other even though they were
337 called for the same stream.
338 nids_unregister_tcp() unregisters a user-defined callback function to
340 process TCP streams.
341 nids_killtcp() tears down the specified TCP connection with symmetric
343 RST packets between client and server.
344 nids_discard() may be called from the TCP callback function to specify
346 the number of bytes to discard from the beginning of the data buffer
347 (updating the offset value accordingly) after the TCP callback function
348 exits. Otherwise, the new data (totalling count_new bytes) will be dis‐
349 carded by default.
350 nids_run() starts the packet-driven application, reading packets in an
352 endless loop, and invoking registered callback functions to handle new
353 data as it arrives. This function does not return.
354 nids_dispatch() attempts to process cnt packets before returning, with
356 a cnt of -1 understood as all packets available in one pcap buffer, or
357 all packets in a file when reading offline. On success, returns the
358 count of packets processed, which may be zero upon EOF (offline read)
359 or upon hitting pcap_timeout (if supported by your platform). On fail‐
360 ure, returns -1, putting an appropriate error message in nids_errbuf.
361 nids_next() process the next available packet before returning.
363 Returns 1 on success, 0 if no packet was processed, setting nids_effbuf
364 appropriately if an error prevented packet processing.
365 nids_getfd() may be used by an application sleeping in select(2) to
367 snoop for a socket file descriptor present in the read fd_set. Returns
368 the file descriptor on success, -1 on failure (in which case
369 nids_errbuf contains an appropriate error message).
370 nids_register_chksum_ctl() takes as arguments an array of struct
372 nids_chksum_ctl elements and the number of elements in the array. A
373 nids_chksum_ctl element is defined as follows:
374 struct nids_chksum_ctl {
376 u_int netaddr;
377 u_int mask;
378 u_int action;
379 /* private members */
380 };
381 Internal checksumming functions will first check elements of this array
383 one by one, and if the source ip SRCIP of the current packet satisfies
384 condition
385 (SRCIP&chksum_ctl_array[i].mask)==chksum_ctl_array[i].netaddr
387 then if the action field is NIDS_DO_CHKSUM, the packet will be check‐
389 summed; if the action field is NIDS_DONT_CHKSUM, the packet will not be
390 checksummed. If the packet matches none of the array elements, the
391 default action is to perform checksumming.
392 nids_pcap_handler() may be used by an application already running a
394 capture with libpcap, in order to pass frames to libnids interactively
395 (frame per frame) instead of having libnids itself do the capture.
396 nids_find_tcp_stream() returns a pointer to the tcp_stream structure
398 corresponding to the tuple passed as argument if libnids knows about
399 this TCP connection already, otherwise it returns NULL.
400 nids_free_tcp_stream() removes the given tcp_stream from the list of
402 streams tracked by libnids. Warning: its usage can result in crashes!
403 See comments in the API.html file.
404
407 pcap(3), libnet(3), fragrouter(8)
408
410 Rafal Wojtczuk <nergal@icm.edu.pl>
411 Manpage by Dug Song <dugsong@monkey.org>, minor updates by Michael Pom‐
413 raning <mjp@pilcrow.madison.wi.us>
414 LIBNIDS(3)