-
Notifications
You must be signed in to change notification settings - Fork 28
/
README
143 lines (109 loc) · 4.72 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
Introduction
============
pynids is a python wrapper for libnids, a Network Intrusion Detection System
library offering sniffing, IP defragmentation, TCP stream reassembly and TCP
port scan detection.
pynids is free software, copyright (C) 2003, 2004, 2005 Michael J. Pomraning
<mjp{AT}pilcrow{DOT}madison{DOT}wi{DOT}us>. See the file COPYING for
license information.
Changes since 2013 copyright (c) The MITRE Corporation.
libnids is (c) 1999 Rafal Wojtczuk <[email protected]> and licensed under the
GNU GPL. See http://www.packetfactory.net/projects/libnids/ for more
information.
Installation
============
Prerequisites
-------------
Python >= 2.2 (www.python.org)
libpcap (www.tcpdump.org)
libnet (www.packetfactory.net/libnet)
tar(1) and patch(1)
libnids itself is supplied in the pynids distribution.
Build and Install
-----------------
$ python setup.py build
$ python setup.py install
API Translation
===============
General
-------
#include <nids.h> import nids
extern nids_params nids.param(what [, new_val])
extern char nids_errbuf[] nids.error Exception instance
struct tcp_stream TcpStream type
nids_killtcp(tcp_s) tcpStreamObj.kill()
nids_discard(tcp_s, 0) tcpStreamObj.discard(0)
struct half_stream HalfStream type
struct tuple4 ((src, sport), (dst, dport))
Callback Arguments
------------------
Packets and payloads are string buffers, whereas libnids-specific structs
are their own types. Either bound methods or plain functions may be
registered as callbacks -- their call signature differs only in the presence
or absence of an initial 'self' argument.
Examples of plain function callbacks:
def ip_callback(pkt):
pass
def frag_callback(pkt):
pass
def udp_callback(addrs, payload, pkt):
((sip, sport), (dip, dport)) = addrs
....
def tcp_callback(tcpStreamObj):
clientHlf = tcpStreamObj.client
serverHlf = tcpStreamObj.server
Significant Differences
-----------------------
- error handling (global nids_errbuf[], python exceptions)
No function returns an error code; instead, a nids.error exception is
raised for init() and getfd(). Unlike libnids, our next() function can
detect pcap errors (again raised as nids.error). Exceptions in user
callbacks will break either next() or run() calls.
- nids_params (global settings)
nids.param() handles accessing and changing libnet state variables; there
is no object corresponding to a struct nids_prm. Some parameters are
unimplemented -- see BUGS below.
- half_stream members
Only "collect" and "collect_urg" are mutable attributes.
- Only one handler per register_* type
Successive calls to, e.g., register_tcp() will simply replace the
user-defined handle slotted for TCP packets. If you want multiple
functions to process packet, implement your own:
for f in tcp_func_list:
f(tcp_s)
- user_tcp_func(..., void **param)
The user-controlled pointer has no analog in pynids. Programmers may
store connection-specific data in a global dict, for example, keyed on
tcpStream.addr. A bound methods registered as callbacks may of course
access members of its corresponding object.
- tuple4 structs
IP addresses are represented as dotted quad strings, and tuple4 members
are (re)arranged into a pair of two-tuples suitable for use as AF_INET
addresses in the socket module.
Significant Likenesses
----------------------
- pynids use, like libnids use, should be restricted to one and only one
thread (static variables under the hood). See also "threads and GIL" in
BUGS, below.
- pcap_close() is apparently only called when nids_run() returns in libnids
1.18; beware fd leaks and inheritance. More generally, there is no way
to de-initialize the underlying nids library (reclaiming memory allocated
for stream reassembly, for instance).
BUGS
====
- nids.param()
. missing function hooks (syslog, no_mem, ip_filter)
Should we just nail no_mem() down to throw nids.error and invalidate
subsequent nids calls?
. cannot distinguish between invalid members and char * members set to NULL;
param("foo") and param("pcap_filter") could both return None, e.g.
. missing type checking
. implementation is awkward, comparable to old tp_getattr; better/easier as
a module object with members/getsets.
. invocation constrained; perhaps introduce a keyword function?
- testing
. generally insufficient (ip_fragments, tcpO.kill(), etc.)
. memory profiling
- threads and GIL
libnids/libpcap routines have no knowledge of the python GIL, so pynids
method calls will block other python threads.