source: README.wiki @ 25

Last change on this file since 25 was 25, checked in by tim, 8 years ago

.

File size: 4.8 KB
Line 
1<h2>Nanown</h2>
2<p>
3A tool for identifying, evaluating, and exploiting timing
4vulnerabilities remotely.  This is part of the output from a research
5effort <a href="https://www.blackhat.com/us-15/briefings.html#web-timing-attacks-made-practical">discussed at BlackHat 2015</a>.
6This project is still highly experimental and not particularly easy to
7use at this point.
8</p>
9
10<h2> Prerequisites</h2>
11<p>
12Linux and Python 3.4+ are required.  Yes, really, your Python needs to
13be that new.  You will also need to install the following modules for
14this version of Python:
15</p>
16<pre>
17  requests
18  numpy
19  netifaces
20  matplotlib
21</pre>
22<p>
23On Debian unstable, you can get these by running:
24</p>
25<pre>
26  apt-get install python3-requests python3-numpy python3-netifaces python3-matplotlib
27</pre>
28<p>
29If you can't get the appropriate packages from your distro, resort to <code>pip3</code>.
30</p><p>
31In addition, you'll need to have a C compiler and the development
32package for libpcap installed.  Under Debian this is probably sufficient:
33</p>
34<pre>
35  apt-get install libpcap-dev gcc
36</pre>
37
38
39<h2> Installation</h2>
40<p>
41Hah! Funny.
42</p><p>
43Currently there's no installation script...
44</p><p>
45To attempt to use this code, clone the repository and build the
46<code>nanown-listen</code> tool with:
47</p>
48<pre>
49  cd nanown/trunk/src && ./compile.sh
50</pre>
51<p>
52That will drop the <code>nanown-listen</code> binary under <code>nanown/trunk/bin</code>.  You
53must then put this directory in your <code>$PATH</code> in order to perform any
54data collection.
55</p><p>
56To run any of the other scripts, change to the nanown/trunk directory
57and run them directly from there.  E.g.:
58</p>
59<pre>
60  bin/train ...args...
61  bin/graph ...args...
62</pre>
63
64
65<h2> Usage</h2>
66<p>
67Our goal for a usage workflow is this:
68</p>
69<ol>
70<li>Based on example HTTP requests, and test cases supplied by the user,
71   a script generator creates a new script.  This new script serves
72   as the sample collection script, customized for your web
73   application.
74</li>
75<li>After collecting samples using the script from step 1, you run a
76   mostly automated script to train and test various classifiers on your
77   samples.  This will then tell you how many samples you need to
78   reliably detect the timing difference.
79</li>
80<li>Given the output from step 3 and inputs to step 1, a second script
81   generator creates an attack script for you as a starting point.  You
82   customize this and run your attacks.
83</li>
84</ol>
85<p>
86Sounds great, yeah?  Well steps 1 and 3 aren't quite implemented yet. =\
87</p><p>
88If you are really dying to use this code right now, just make a copy of
89the <code>trunk/bin/sampler</code> script and hack on it until it sends HTTP requests
90that your targeted web application expects.  Be sure to define the test
91cases appropriately.  Then run it to collect at least
9250,000 samples for each of the train, test and train_null data sets
93(150,000 samples total).  NOTE: Your sampler script must be run as <code>root</code>
94so it can tweak local networking settings and sniff packets.
95</p><p>
96Next you can move on to step 2, where you simply run the train script
97against the database created by your sampler script:
98</p>
99<pre>
100  bin/train mysamples.db
101</pre>
102<p>
103This will run for a while.  If you cancel out and re-run it, it will
104pick up where it left off.  Pay special attention to the final results
105it prints out.  This will tell you how many samples are needed to
106distinguish between the test cases.  Do a little math on your own to
107decide how feasible your overall attack will be.
108</p><p>
109Finally, we come to step 3.  If you choose to carry out an attack, you
110will need to implement your own attack script that collects batches of
111samples, distinguishes between them using the best classifier available
112(from step 2) and then repeats as needed.  Consider starting with the
113sample script at <code>test/blackhat-demo/jregistrate-attack</code>.
114</p><p>
115Any questions?  See the source, watch our <a href="https://www.youtube.com/watch?v=k-Pv3sf3G2A">BlackHat presentation</a>, read
116our <a href="https://www.blackhat.com/docs/us-15/materials/us-15-Morgan-Web-Timing-Attacks-Made-Practical-wp.pdf">research paper</a>),
117or <a href="https://code.blindspotsecurity.com/trac/nanown/newticket">post a ticket</a>.
118</p>
119
120<h2> License</h2>
121<p>
122Unless otherwise indicated in the source code, this software is licensed under the GNU GPL version 3.  See the LICENSE file for details.
123</p>
124
125<h2> Contributing</h2>
126<p>
127We certainly welcome and encourage code contributions, no matter how
128small.  To submit a patch, please check out the latest revision with:
129</p>
130<pre>  svn co https://code.blindspotsecurity.com/dav/nanown/</pre>
131<p>
132Then apply your changes and run "<code>svn diff</code>".  Save the resulting diff and attach it to a <a href="https://code.blindspotsecurity.com/trac/nanown/newticket">ticket</a>.
133</p>
Note: See TracBrowser for help on using the repository browser.