-
Notifications
You must be signed in to change notification settings - Fork 6
/
Copy pathREADME
136 lines (94 loc) · 4.13 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
capsan
======
Packet capture sanitizer/anonymizer. Modifies packet headers to remove
link-layer addresses, anonymize IP addresses, and shuffle UDP/TCP ports.
Dependencies
------------
* CMake
* libpcap and headers
* OpenSSL libraries and headers
Redhat/RPM family Linux::
yum install cmake libpcap-devel openssl-devel
Debian/DEB family Linux::
apt-get install cmake libpcap-dev libssl-dev
Mac OS X:
Compiling source code on Macs requires first downloading/installing
Xcode and its "Command Line Tools". Then check in to whether any
of the dependencies are missing and install them via a preferred
package manager (e.g. MacPorts, Fink, or Homebrew).
Compiling
---------
git clone https://github.com/jsiwek/capsan.git capsan
mkdir capsan-build
cd capsan-build
cmake ../capsan
make
./capsan --help
IP Anonymization
----------------
The IP anonymization algorithm is based on Crypto-PAn [1] with features:
* Prefixes are preserved.
* The mapping is one-to-one.
* Anonymizations are reproducible and reversible via the use of a
consistent 256-bit key.
* The mapping is pseudo-random and based on AES.
[1] http://www.cc.gatech.edu/computing/Telecomm/projects/cryptopan/
Port Anonymization
------------------
Port anonymization uses a random permutation of the 16-bit port space.
* The mapping is one-to-one.
* A given port number always anonymized to a different port number.
* Anonymizations are reproducible and reversible via the use of a
consistent 16-bit seed.
Checksums
---------
IPv4, UDP, and TCP checksums are automatically corrected. If the
original packet had any incorrect checksums, they are forced to also be
incorrect in the sanitized packet.
Limitations
-----------
Link-layer support: only a few common link layers are supported and the
sanitization is trivial -- addresses (e.g. MACs) are just zeroed out.
IPv4 only: the anonymization algorithm is extensible to IPv6, and the
headers are parsable w/ some effort (IPv6 extension headers can make
things awkward), but it just wasn't necessary for the use-case at time
of writing. Also, anything that's not at IP packet (e.g. ARP) is
skipped (omitted from the output).
No fragments: IP fragments are always skipped (omitted from output) because
it's not trivial to deal w/ them correctly (especially w/ the checksum
auto-correcting feature).
UDP/TCP only: Any packet that doesn't carry UDP or TCP is skipped
(omitted from output).
Headers only: UDP/TCP payloads are left untouched. Sanitizing the
information in higher layer protocols is outside the scope of this tool
(e.g. despite anonymizing IPs/ports in headers, the same or others may
be embedded in the payload, depending on the protocol).
Tunnels: If the traces you want to sanitize may contain tunnels that are
not trivial to detect (e.g. they're encapsulated in UDP, like Teredo),
this tool does nothing to sanitize or even warn about the inner IP
packets. If unsure, running the trace through Bro (available at
http://bro.org) may help point out in the tunnels.log output which flows
may need to be pre-filtered out to prevent leaking addrs/ports.
Examples
--------
Sanitize a packet capture using a given key file::
capsan -r in.pcap -w out.pcap -k my_capsan_key
If the key file does not exist it will be created and may be re-used
later to produce consistent addr/port mappings. Both the key for IP
anonymization and seed for the port anonymization live in this file.
If reproducibility or reversibility aren't requirements, don't specify a
key file argument::
capsan -r in.pcap -w out.pcap
Reverse an anonymized IP::
capsan -n 1.2.3.4 -k my_capsan_key --reverse
Reverse an anonymized port::
capsan -t 1234 -k my_capsan_key --reverse
Dump mappings to plain text files::
capsan -r in.pcap -w out.pcap -a addr_map -p port_map
Mappings are written in the format "anonymous: original" with one
addr/port per line. These can also be written in conjuction with a key,
but note that just the key is sufficient for reversing an addr/port (and
much more space-efficient). Existing files are clobbered when writing
mapping files.
Don't anonymize ports::
capsan -r in.pcap -w out.pcap -k my_capsan_key --no-ports