Added Scapy doc (!) (Thanks to D. Loss)

doc/scapy/Makefile

+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html      to make standalone HTML files"
+	@echo "  pickle    to make pickle files (usable by e.g. sphinx-web)"
+	@echo "  htmlhelp  to make HTML files and a HTML help project"
+	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  changes   to make an overview over all changed/added/deprecated items"
+	@echo "  linkcheck to check all external links for integrity"
+
+clean:
+	-rm -rf _build/*
+
+html:
+	mkdir -p _build/html _build/doctrees
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
+	@echo
+	@echo "Build finished. The HTML pages are in _build/html."
+
+pickle:
+	mkdir -p _build/pickle _build/doctrees
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files or run"
+	@echo "  sphinx-web _build/pickle"
+	@echo "to start the sphinx-web server."
+
+web: pickle
+
+htmlhelp:
+	mkdir -p _build/htmlhelp _build/doctrees
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in _build/htmlhelp."
+
+latex:
+	mkdir -p _build/latex _build/doctrees
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in _build/latex."
+	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+	      "run these through (pdf)latex."
+
+changes:
+	mkdir -p _build/changes _build/doctrees
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
+	@echo
+	@echo "The overview file is in _build/changes."
+
+linkcheck:
+	mkdir -p _build/linkcheck _build/doctrees
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in _build/linkcheck/output.txt."

doc/scapy/backmatter.rst

+
+*********
+Credits
+*********
+
+- Philippe Biondi is Scapy's author. He has also written most of the documentation.
+- Fred Raynal wrote the chapter on building and dissecting packets.
+- Sebastien Martini added some details in "Handling default values: automatic computation".
+- Dirk Loss integrated and restructured the existing docs to make this book. 
+  He has also written the installation instructions for Windows.
+
+   

doc/scapy/conf.py

+# -*- coding: utf-8 -*-
+#
+# Scapy documentation build configuration file, created by
+# sphinx-quickstart on Mon Sep  8 19:37:39 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default value; values that are commented out
+# serve to show the default value.
+
+import sys, os
+
+# If your extensions are in another directory, add it here. If the directory
+# is relative to the documentation root, use os.path.abspath to make it
+# absolute, like shown here.
+#sys.path.append(os.path.abspath('some/directory'))
+
+# General configuration
+# ---------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General substitutions.
+project = 'Scapy'
+copyright = '2008, Philippe Biondi and the Scapy community'
+
+# The default replacements for |version| and |release|, also used in various
+# other places throughout the built documents.
+#
+# The short X.Y version.
+version = '2.0.0'
+# The full version, including alpha/beta/rc tags.
+release = '2.0.0'
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directories, that shouldn't be searched
+# for source files.
+#exclude_dirs = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# Options for HTML output
+# -----------------------
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+html_style = 'default.css'
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (within the static path) to place at the top of
+# the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+html_use_modindex = False
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, the reST sources are included in the HTML build as _sources/<name>.
+#html_copy_source = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Scapydoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+latex_paper_size = 'a4'
+
+# The font size ('10pt', '11pt' or '12pt').
+latex_font_size = '11pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+  ('index', 'Scapy.tex', 'Scapy Documentation',
+   'Philippe Biondi and the Scapy community', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+latex_use_modindex = False

doc/scapy/development.rst

+*****************
+Scapy development
+*****************
+
+Project organization
+====================
+
+Scapy development uses the Mercurial version control system.
+Scapy's reference repository is at http://hg.secdev.org/scapy/. 
+
+Project management is done with `Trac <http://trac.secdev.org/scapy>`_. Trac works on Scapy's reference repository.
+It provides a freely editable `Wiki <http://trac.secdev.org/scapy/wiki/>`_ (please contribute!) that can 
+reference tickets, changesets, files from the project. It also provides 
+a ticket management service that is used to avoid forgetting patches or bugs.
+
+Mercurial's distributed way of working enables Philippe to provide two repositories
+where anybody can commit stuff: 
+the Scapy `community repository <http://hg.secdev.org/scapy-com>`_ and the Scapy `Windows port repository <http://hg.secdev.org/scapy-com>`_. 
+
+
+How to contribute
+=================
+
+* Found a bug in Scapy? `Add a ticket <http://trac.secdev.org/scapy/newticket>`_.
+* Improve this documentation.
+* Program a new layer and share it on the mailing list. Or add it as an enhancement on the bugtracker. 
+* Contribute new `regression tests <http://trac.secdev.org/scapy/wiki/RegressionTests>`_.
+* Upload packet samples for new protocols on the `packet samples page <http://trac.secdev.org/scapy/wiki/PacketsSamples>`_.
+
+
+Testing with UTScapy
+====================
+
+What is UTScapy?
+----------------
+
+UTScapy is a small Python program that reads a campaign of tests, runs the campaign with Scapy and generates a report indicating test status. The report may be in one of four formats, text, ansi, HTML or LaTeX.
+
+Three basic test containers exist with UTScapy, a unit test, a test set and a test campaign. A unit test is a list of Scapy commands that will be run by Scapy or a derived work of Scapy. Evaluation of the last command in the unit test will determine the end result of the individual unit test. A test set is a group of unit tests with some association. A test campaign consists of one or more test sets. Test sets and unit tests can be given keywords to form logical groupings. When running a campaign, tests may be selected by keyword. This allows the user to run tests within a desired grouping.
+
+For each unit test, test set and campaign, a CRC32 of the test is calculated and displayed as a signature of that test. This test signature is sufficient to determine that the actual test run was the one expected and not one that has been modified. In case your dealing with evil people that try to modify or corrupt the file without changing the CRC32, a global SHA1 is computed on the whole file.
+
+Syntax of a Test Campaign
+-------------------------
+
+Table 1 shows the syntax indicators that UTScapy is looking for. The syntax specifier must appear as the first character of each line of the text file that defines the test. Text descriptions that follow the syntax specifier are arguments interpreted by UTScapy. Lines that appear without a leading syntax specifier will be treated as Python commands, provided they appear in the context of a unit test. Lines without a syntax specifier that appear outside the correct context will be rejected by UTScapy and a warning will be issued. 
+
+================   =================
+Syntax Specifier   Definition
+================   =================
+‘%’                Give the test campaign's name.
+‘+’                Announce a new test set.
+‘=’                Announce a new unit test.
+‘~’                Announce keywords for the current unit test.
+‘*’                Denotes a comment that will be included in the report.
+‘#’                Testcase annotations that are discarded by the interpreter.
+================   =================
+
+Table 1 - UTScapy Syntax Specifiers
+
+Comments placed in the test report have a context. Each comment will be associated to the last defined test container - be it a individual unit test, a test set or a test campaign. Multiple comments associated with a particular container will be concatenated together and will appear in the report directly after the test container announcement. General comments for a test file should appear before announcing a test campaign. For comments to be associated with a test campaign, they must appear after declaration of the test campaign but before any test set or unit test. Comments for a test set should appear before definition of the set’s first unit test.
+
+The generic format for a test campaign is shown in the following table::
+
+    % Test Campaign Name
+    * Comment describing this campaign
+
+    
+    + Test Set 1
+    * comments for test set 1
+    
+    = Unit Test 1
+    ~ keywords
+    * Comments for unit test 1
+    # Python statements follow
+    a = 1
+    print a
+    a == 1
+
+
+Python statements are identified by the lack of a defined UTScapy syntax specifier. The Python statements are fed directly to the Python interpreter as if one is operating within the interactive Scapy shell (``interact``). Looping, iteration and conditionals are permissible but must be terminated by a blank line. A test set may be comprised of multiple unit tests and multiple test sets may be defined for each campaign. It is even possible to have multiple test campaigns in a particular test definition file. The use of keywords allows testing of subsets of the entire campaign. For example, during development of a test campaign, the user may wish to mark new tests under development with the keyword “debug”. Once the tests run successfully to their desired conclusion, the keyword “debug” could be removed. Keywords such as “regression” or “limited” could be used as well.
+
+It is important to note that UTScapy uses the truth value from the last Python statement as the indicator as to whether a test passed or failed. Multiple logical tests may appear on the last line. If the result is 0 or False, the test fails. Otherwise, the test passes. Use of an assert() statement can force evaluation of intermediate values if needed.
+
+The syntax for UTScapy is shown in Table 3 - UTScapy command line syntax::
+
+    [root@localhost scapy]# ./UTscapy.py –h
+    Usage: UTscapy [-m module] [-f {text|ansi|HTML|LaTeX}] [-o output_file]
+                   [-t testfile] [-k keywords [-k ...]] [-K keywords [-K ...]]
+                   [-l] [-d|-D] [-F] [-q[q]]
+    -l              : generate local files
+    -F              : expand only failed tests
+    -d              : dump campaign
+    -D              : dump campaign and stop
+    -C              : don't calculate CRC and SHA
+    -q              : quiet mode
+    -qq             : [silent mode]
+    -n <testnum>    : only tests whose numbers are given (eg. 1,3-7,12)
+    -m <module>     : additional module to put in the namespace
+    -k <kw1>,<kw2>,...      : include only tests with one of those keywords (can be used many times)
+    -K <kw1>,<kw2>,...      : remove tests with one of those keywords (can be used many times)
+
+Table 3 - UTScapy command line syntax
+
+All arguments are optional. Arguments that have no associated argument value may be strung together (i.e. ``–lqF``). If no testfile is specified, the test definition comes from <STDIN>. Similarly, if no output file is specified it is directed to <STDOUT>. The default output format is “ansi”. Table 4 lists the arguments, the associated argument value and their meaning to UTScapy.
+
+==========  ==============  =============================================================================
+Argument    Argument Value  Meaning to UTScapy
+==========  ==============  =============================================================================
+-t          testfile        Input test file defining test campaign (default = <STDIN>)
+-o          output_file     File for output of test campaign results (default = <STDOUT>)
+-f          test            ansi, HTML, LaTeX, Format out output report (default = ansi)
+-l                          Generate report associated files locally. For HTML, generates JavaScript 
+                            and the style sheet
+-F                          Failed test cases will be initially expanded by default in HTML output
+-d                          Print a terse listing of the campaign before executing the campaign
+-D                          Print a terse listing of the campaign and stop. Do not execute campaign
+-C                          Do not calculate test signatures
+-q                          Do not update test progress to the screen as tests are executed
+-qq                         Silent mode
+-n          testnum         Execute only those tests listed by number. Test numbers may be
+                            retrieved using –d or –D. Tests may be listed as a comma
+                            separated list and may include ranges (e.g. 1, 3-7, 12)
+-m          module          Load module before executing tests. Useful in testing derived works of Scapy.
+                            Note: Derived works that are intended to execute as "__main__" will not be
+                            invoked by UTScapy as “__main__”.
+-k          kw1, kw2, ...   Include only tests with keyword “kw1”. Multiple keywords may be specified.
+-K          kw1, kw2, ...   Exclude tests with keyword “kw1”. Multiple keywords may be specified.  
+==========  ==============  =============================================================================
+
+Table 4 - UTScapy parameters
+
+Table 5 shows a simple test campaign with multiple test set definitions. Additionally, keywords are specified that allow a limited number of test cases to be executed. Notice the use of the ``assert()`` statement in test 3 and 5 used to check intermediate results. Tests 2 and 5 will fail by design.
+
+:: 
+
+    % Example Test Campaign
+    
+    # Comment describing this campaign
+    #
+    # To run this campaign, try:
+    #   ./UTscapy.py -t example_campaign.txt -f html -o example_campaign.html -F
+    #
+    
+    * This comment is associated with the test campaign and will appear 
+    * in the produced output.
+    
+    + Test Set 1
+    
+    = Unit Test 1
+    ~ test_set_1 simple
+    a = 1
+    print a
+    
+    = Unit test 2
+    ~ test_set_1 simple
+    * this test will fail
+    b = 2
+    a == b
+    
+    = Unit test 3
+    ~ test_set_1 harder
+    a = 1
+    b = 2
+    c = "hello"
+    assert (a != b)
+    c == "hello"
+    
+    + Test Set 2
+    
+    = Unit Test 4
+    ~ test_set_2 harder
+    b = 2
+    d = b
+    d is b
+    
+    = Unit Test 5
+    ~ test_set_2 harder hardest
+    a = 2
+    b = 3
+    d = 4
+    e = (a * b)**d
+    # The following statement evaluates to False but is not last; continue
+    e == 6
+    # assert evaluates to False; stop test and fail
+    assert (e == 7)
+    e == 1296
+    
+    = Unit Test 6
+    ~ test_set_2 hardest
+    print e
+    e == 1296
+
+To see an example that is targeted to Scapy, go to http://www.secdev.org/projects/UTscapy. Cut and paste the example at the bottom of the page to the file ``demo_campaign.txt`` and run UTScapy against it::
+
+./UTscapy.py -t demo_campaign.txt -f html -o demo_campaign.html –F -l
+
+Examine the output generated in file ``demo_campaign.html``.

doc/scapy/extending.rst

+********************
+Build your own tools
+********************
+
+You can use Scapy to make your own automated tools. You can also extend Scapy without having to edit its source file.
+
+If you have built some interesting tools, please contribute back to the mailing-list!
+
+    
+Using Scapy in your tools
+=========================
+You can easily use Scapy in your own tools. Just import what you need and do it.
+
+This first example take an IP or a name as first parameter, send an ICMP echo request packet and display the completely dissected return packet::
+
+    #! /usr/bin/env python
+    
+    import sys
+    from scapy.all import sr1,IP,ICMP
+    
+    p=sr1(IP(dst=sys.argv[1])/ICMP())
+    if p:
+        p.show()
+
+This is a more complex example which does an ARP ping and reports what it found with LaTeX formating::
+
+    #! /usr/bin/env python
+    # arping2tex : arpings a network and outputs a LaTeX table as a result
+    
+    import sys
+    if len(sys.argv) != 2:
+        print "Usage: arping2tex <net>\n  eg: arping2tex 192.168.1.0/24"
+        sys.exit(1)
+    
+    from scapy.all import srp,Ether,ARP,conf
+    conf.verb=0
+    ans,unans=srp(Ether(dst="ff:ff:ff:ff:ff:ff")/ARP(pdst=sys.argv[1]),
+                  timeout=2)
+    
+    print r"\begin{tabular}{|l|l|}"
+    print r"\hline"
+    print r"MAC & IP\\"
+    print r"\hline"
+    for snd,rcv in ans:
+        print rcv.sprintf(r"%Ether.src% & %ARP.psrc%\\")
+    print r"\hline"
+    print r"\end{tabular}"
+
+Here is another tool that will constantly monitor all interfaces on a machine and print all ARP request it sees, even on 802.11 frames from a Wi-Fi card in monitor mode. Note the store=0 parameter to sniff() to avoid storing all packets in memory for nothing::
+
+    #! /usr/bin/env python
+    from scapy.all import *
+    
+    def arp_monitor_callback(pkt):
+        if ARP in pkt and pkt[ARP].op in (1,2): #who-has or is-at
+            return pkt.sprintf("%ARP.hwsrc% %ARP.psrc%")
+    
+    sniff(prn=arp_monitor_callback, filter="arp", store=0)
+
+For a real life example, you can check `Wifitap <http://sid.rstack.org/index.php/Wifitap_EN>`_.
+
+
+Extending Scapy with add-ons
+============================
+
+If you need to add some new protocols, new functions, anything, you can write it directly into Scapy source file. But this is not very convenient. Even if those modifications are to be integrated into Scapy, it can be more convenient to write them in a separate file.
+
+Once you've done that, you can launch Scapy and import your file, but this is still not very convenient. Another way to do that is to make your file executable and have it call the Scapy function named interact()::
+
+    #! /usr/bin/env python
+    
+    # Set log level to benefit from Scapy warnings
+    import logging
+    logging.getLogger("scapy").setLevel(1)
+    
+    from scapy.all import *
+    
+    class Test(Packet):
+        name = "Test packet"
+        fields_desc = [ ShortField("test1", 1),
+                        ShortField("test2", 2) ]
+    
+    def make_test(x,y):
+        return Ether()/IP()/Test(test1=x,test2=y)
+    
+    if __name__ == "__main__":
+        interact(mydict=globals(), mybanner="Test add-on v3.14")
+
+
+If you put the above listing in the test_interact.py file and make it executable, you'll get::
+
+    # ./test_interact.py 
+    Welcome to Scapy (0.9.17.109beta)
+    Test add-on v3.14
+    >>> make_test(42,666)
+    <Ether type=0x800 |<IP |<Test test1=42 test2=666 |>>>
+    
+