Netzob Interactive Session Controller (IssueId #444).
[netzob.git] / README.rst
1 ==========================================
2 Netzob : Inferring Communication Protocols
3 ==========================================
4
5 About Netzob
6 ============
7
8 Functional Description
9 -----------------------
10
11 Netzob is an opensource tool for reverse engineering, traffic generation 
12 and fuzzing of communication protocols. This tool allows to infer the message format (vocabulary) 
13 and the state machine (grammar) of a protocol through passive and active processes. 
14 Its objective is to bring state of art academic researches to the operational field, 
15 by leveraging bio-informatic and grammatical inferring algorithms in a semi-automatic manner.
16
17 Netzob is suitable for reversing network protocols, structured files and system and 
18 process flows (IPC and communication with drivers and devices). 
19 Dedicated modules are provided to capture and import data in multiple contexts (network, file and process data acquisition). 
20 Once inferred, a protocol model can afterward be exported to third party tools (Peach, Scapy, Wireshark, etc.) 
21 or used in the traffic generation engine, to allow simulation of realistic and controllable communication endpoints and flows.
22
23 Netzob handles different types of protocols: text protocols (like HTTP and IRC), delimiter-based protocols, 
24 fixed fields protocols (like IP and TCP) and variable-length fields protocols (like TLV-based protocols).
25
26 Technical Description
27 ---------------------
28
29 Netzob's source code is mostly made of Python (90%) with some specific
30 extensions in C (6%). It includes a graphical interface based on GTK3.
31
32 The tool is made of a core (officially maintained) and of bunch of
33 plugins (exporters, importers, ...). Some plugins are provided by the team while others are
34 created and managed directly by users.
35
36 More Information
37 ---------------- 
38
39 :Website: `http://www.netzob.org <http://www.netzob.org>`_
40 :Email: `contact@netzob.org <contact@netzob.org>`_
41 :Mailing list: Two lists are available, use the `SYMPA web interface <https://lists.netzob.org/wws>`_ to register.
42 :IRC: You can hang-out with us on Freenode's IRC channel #netzob @ freenode.org.
43 :Wiki: Discuss strategy on `Netzob's wiki <https://dev.netzob.org/projects/netzob/wiki>`_
44 :Twitter: Follow Netzob's official accounts (@Netzob)
45
46 Get Started with Netzob
47 =======================
48
49 Install it
50 ----------
51
52 There are two main ways of installing Netzob. The first one is based on 
53 per-OS installers while the other one is more 'pythonic'.
54
55 We recommend the per-OS installers for 'normal' users while
56 testers, developers and python experts might prefer the 'pythonic' way.
57
58 Per-OS Installers:
59 ^^^^^^^^^^^^^^^^^^
60
61 Please follow the specification documentations for each supported platform:
62
63 :Debian/Ubuntu: `Installation documentation on Debian (wiki) <https://dev.netzob.org/projects/netzob/wiki/Installation_documentation_on_Debian>`_
64 :Gentoo: `Installation documentation on Gentoo (wiki) <https://dev.netzob.org/projects/netzob/wiki/Installation_documentation_on_Gentoo>`_
65
66 Pythonic Installer:
67 ^^^^^^^^^^^^^^^^^^^
68
69 As a 'classic' python project, Netzob is provided with its
70 ``setup.py``. This file defines what and how to install the project on a
71 python hosting OS.
72
73 This file depends on ``setuptools`` which like few other modules cannot be
74 automatically installed. The reason why, you have to manually install the 
75 following bunch of prerequisites before initiating Netzob's install process.
76
77 * python
78 * python-dev
79 * libxml2-dev
80 * libxslt-dev
81 * python-setuptools
82 * gtk3
83
84 We also highly recommend to install the following additional dependencies:
85
86 * python-babel (for the translations)
87 * python-sphinx (for the documentation)
88
89 Once the required dependencies are installed, you can test (developer mode) Netzob::
90
91   python setup.py build
92   python setup.py develop
93
94 and install it::
95
96   $ python setup.py install
97
98 Start it
99 --------
100
101 Once installed, running Netzob is as simple as executing the provided script::
102
103   $ ./netzob
104
105 This script is in Python's path if you've installed Netzob, otherwise
106 (in developer mode), its located in the top distribution directory.
107
108
109 Miscellaneous
110 -------------
111
112 Configuration requirements for Network and PCAP input::
113
114   $ sudo setcap cap_net_raw=ep /usr/bin/python2.XX
115
116 Configuration requirements for IPC input on Ubuntu::
117
118   $ sudo bash -c "echo 0 > /proc/sys/kernel/yama/ptrace_scope"
119
120 Documentation
121 =============
122
123 The folder ``doc/documentation`` contains all the documentation of Netzob. 
124
125 The user manual can be generated based on RST sources located in folder
126 ``doc/documentation/source`` with the following command::
127
128   $ sphinx-build -b html doc/documentation/source/ doc/documentation/build/
129
130 Contributing
131 ============
132
133 There are multiple ways to help-us.
134
135 Defects and Features  Requests
136 ------------------------------
137
138 Help-us by reporting bugs and requesting features using the `Bug Tracker <https://dev.netzob.org/projects/netzob/issues>`_.
139
140 Translation
141 -----------
142
143 Netzob has `support <https://dev.netzob.org/projects/netzob/wiki/Translation_support>`_ for translation. 
144 Currently English and French languages are supported. New languages are welcome.
145
146 Join the Development Team
147 -------------------------
148
149 To participate in the development, you need to get the latest version,
150 modify it and submit your changes. 
151
152 These operations are detailed on Netzob's wiki through the following
153 pages:
154
155 * `Accessing and using Git Repositories for Netzob development <https://dev.netzob.org/projects/netzob/wiki/Accessing_and_using_Git_Repositories_for_Netzob_development>`_
156 * `First steps for a new developer <https://dev.netzob.org/projects/netzob/wiki/First_steps_for_a_new_developer>`_
157
158 You're interested in joining, please contact-us !
159
160 Authors, Contributors and Sponsors
161 ==================================
162
163 See the top distribution file ``AUTHORS.txt`` for the detailed and updated list 
164 of authors, contributors and sponsors.
165
166 License
167 =======
168
169 This software is licensed under the GPLv3 License. See the ``COPYING.txt`` file
170 in the top distribution directory for the full license text.