Merge branch 'docupdate'

savon-noir · savon-noir · commit b237a8ad6e18 · 2014-06-03T00:33:12.000+02:00
diff --git a/MANIFEST b/MANIFEST
@@ -0,0 +1,29 @@
+# file GENERATED by distutils, do NOT edit
+CHANGES.txt
+LICENSE.txt
+README.rst
+TODO
+setup.py
+docs/diff.rst
+docs/index.rst
+docs/objects.rst
+docs/parser.rst
+docs/plugins_s3.rst
+docs/process.rst
+libnmap/__init__.py
+libnmap/diff.py
+libnmap/parser.py
+libnmap/process.py
+libnmap/reportjson.py
+libnmap/objects/__init__.py
+libnmap/objects/cpe.py
+libnmap/objects/host.py
+libnmap/objects/os.py
+libnmap/objects/report.py
+libnmap/objects/service.py
+libnmap/plugins/__init__.py
+libnmap/plugins/backendplugin.py
+libnmap/plugins/backendpluginFactory.py
+libnmap/plugins/mongodb.py
+libnmap/plugins/s3.py
+libnmap/plugins/sql.py
diff --git a/docs/index.rst b/docs/index.rst
@@ -11,6 +11,13 @@ libnmap is a python toolkit for manipulating nmap. It currently offers the follo
 - report: enables you to manipulate a parsed scan result and de/serialize scan results in a json format
 - diff: enables you to see what changed between two scans
 - objects: contains basic nmap objects like NmapHost and NmapService. It is to note that each object can be "diff()ed" with another similar object.
+
+  - report: contains NmapReport class definition
+  - host: contains NmapHost class definition
+  - service: contains NmapService class definition
+  - os: contains NmapOSFingerprint class definition and some other classes like NmapOSMatch, NmapOSClass,...
+  - cpe: contains CPE class defdinition
+
 - plugins: enables you to support datastores for your scan results directly in the "NmapReport" object from report module
 
   - mongodb: only plugin implemented so far, ultra basic, for POC purpose only
@@ -35,6 +42,7 @@ The different modules are documented below:
    process
    parser
    objects
+   objects/*
    diff
    plugins_s3
 
diff --git a/docs/objects.rst b/docs/objects.rst
@@ -10,6 +10,11 @@ This module contains the definition and API of all "NmapObjects" which enables u
 2. NmapHost
 3. NmapService
 
+The three objects above are the most common one that one would manipulate. For more advanced usage, the following objects might be useful
+
+1. NmapOSFingerprint (contains: NmapOSMatch, NmapOSClass, OSFPPortUsed)
+2. CPE (Common platform enumeration contained in NmapService or NmapOSClass)
+
 The following structure applies by default:
 
 NmapReport contains:
@@ -33,20 +38,3 @@ of the same type.
 If you read the code you'll see the dirty trick with id() which ensures that proper objects are being compared. The logic of diff will certainly change overtime but the API (i/o) will be kept as is.
 
 For more info on diff, please check the module's `documentation <diff>_`.
-
-NmapReport methods
-------------------
-
-.. automodule:: libnmap.objects
-.. autoclass:: NmapReport
-    :members:
-
-NmapHost methods
-----------------
-.. autoclass:: NmapHost
-    :members:
-
-NmapService methods
--------------------
-.. autoclass:: NmapService
-    :members:
diff --git a/docs/objects/cpe.rst b/docs/objects/cpe.rst
@@ -0,0 +1,14 @@
+libnmap.objects.cpe
+===================
+
+Using libnmap.objects.cpe module
+--------------------------------
+
+TODO
+
+CPE methods
+-----------
+
+.. automodule:: libnmap.objects.cpe
+.. autoclass:: CPE
+    :members:
diff --git a/docs/objects/nmaphost.rst b/docs/objects/nmaphost.rst
@@ -0,0 +1,14 @@
+libnmap.objects.host
+====================
+
+Using libnmap.objects.host module
+---------------------------------
+
+TODO
+
+NmapHost methods
+----------------
+
+.. automodule:: libnmap.objects
+.. autoclass:: NmapHost
+    :members:
diff --git a/docs/objects/nmapreport.rst b/docs/objects/nmapreport.rst
@@ -0,0 +1,14 @@
+libnmap.objects.report
+======================
+
+Using libnmap.objects.report module
+-----------------------------------
+
+TODO
+
+NmapReport methods
+------------------
+
+.. automodule:: libnmap.objects
+.. autoclass:: NmapReport
+    :members:
diff --git a/docs/objects/nmapservice.rst b/docs/objects/nmapservice.rst
@@ -0,0 +1,14 @@
+libnmap.objects.service
+=======================
+
+Using libnmap.objects.service module
+------------------------------------
+
+TODO
+
+NmapService methods
+-------------------
+
+.. automodule:: libnmap.objects
+.. autoclass:: NmapService
+    :members:
diff --git a/docs/objects/os.rst b/docs/objects/os.rst
@@ -0,0 +1,32 @@
+libnmap.objects.os
+==================
+
+Using libnmap.objects.os module
+-------------------------------
+
+TODO
+
+NmapOSFingerprint methods
+-------------------------
+
+.. automodule:: libnmap.objects.os
+.. autoclass:: NmapOSFingerprint
+    :members:
+
+NmapOSMatch methods
+-------------------
+
+.. autoclass:: NmapOSMatch
+    :members:
+
+NmapOSClass methods
+-------------------
+
+.. autoclass:: NmapOSClass
+    :members:
+
+OSFPPortUsed methods
+--------------------
+
+.. autoclass:: OSFPPortUsed
+    :members:
diff --git a/docs/parser.rst b/docs/parser.rst
@@ -1,11 +1,32 @@
 libnmap.parser
 ==============
 
-Using libnmap.parser module
----------------------------
+Purpose of libnmap.parser
+-------------------------
 
 This modules enables you to parse nmap scans' output. For now on, only XML parsing is supported. NmapParser is a factory which will return a NmapReport, NmapHost or NmapService object.
 All these objects' API are documented.
+
+The module is capable of parsing:
+
+- a complete nmap XML scan report
+- an incomplete/interrupted nmap XML scan report
+- partial nmap xml tags: <host>, <ports> and <port>
+
+Input the above capabilities could be either a string or a file path.
+
+Based on the provided data, NmapParse.parse() could return the following:
+
+- NmapReport object: in case a full nmap xml/dict report was prodivded
+- NmapHost object: in case a nmap xml <host> section was provided
+- NmapService object: in case a nmap xml <port> section was provided
+- Python dict with following keys: ports and extraports; python lists.
+
+Using libnmap.parser module
+---------------------------
+
+NmapParser parse the whole data and returns nmap objects usable via their documented API.
+
 The NmapParser should never be instanciated and only the following methods should be called:
 
 - NmapParser.parse(string)
diff --git a/docs/process.rst b/docs/process.rst
@@ -18,6 +18,8 @@ Raw results of the scans will be available in the following properties:
 - NmapProcess.stdout: string, XML output
 - NmapProcess.stderr: string, text error message from nmap process
 
+To instanciate a NmapProcess instance, call the constructor with appropriate parameters
+
 Processing of events
 --------------------
 
@@ -112,9 +114,10 @@ NmapProcess methods
 .. autoclass:: NmapProcess
     :members:
 
+    .. automethod:: __init__
+
 NmapTask methods
 -------------------
 
-.. automodule:: libnmap.process
 .. autoclass:: NmapTask
     :members:
diff --git a/libnmap/objects/os.py b/libnmap/objects/os.py
@@ -294,8 +294,11 @@ def get_osmatch(self, osclass_obj):
             object in order to respect the common interface for
             the nmap xml version < 1.04 and >= 1.04
 
-            :return: an NmapOSMatch object matching with the NmapOSClass
-            provided in parameter (match is performed based on accuracy)
+            This method will return an NmapOSMatch object matching with
+            the NmapOSClass provided in parameter
+            (match is performed based on accuracy)
+
+            :return: NmapOSMatch object
         """
         rval = None
         for _osmatch in self.__osmatches:
diff --git a/libnmap/parser.py b/libnmap/parser.py
@@ -11,22 +11,21 @@ class NmapParser(object):
     def parse(cls, nmap_data=None, data_type='XML', incomplete=False):
         """
             Generic class method of NmapParser class.
+
             The data to be parsed does not need to be a complete nmap
             scan report. You can possibly give <hosts>...</hosts>
             or <port> XML tags.
 
-            :param nmap_data: any portion of nmap scan result.
-
-            nmap_data should always be a string representing a part
+            :param nmap_data: any portion of nmap scan result. \
+            nmap_data should always be a string representing a part \
             or a complete nmap scan report.
-
             :type nmap_data: string
 
             :param data_type: specifies the type of data to be parsed.
             :type data_type: string ("XML"|"JSON"|"YAML").
 
-            :param incomplete: enable you to parse interrupted nmap scans
-            and/or incomplete nmap xml blocks by adding a </nmaprun> at
+            :param incomplete: enable you to parse interrupted nmap scans \
+            and/or incomplete nmap xml blocks by adding a </nmaprun> at \
             the end of the scan.
             :type incomplete: boolean
 
@@ -51,12 +50,12 @@ def _parse_xml(cls, nmap_data=None, incomplete=False):
             In this case: XML. This method is called by cls.parse class
             method and receives nmap scan results data (in XML).
 
-            :param nmap_data: any portion of nmap scan result can be given
-            as argument. nmap_data should always be a string representing
+            :param nmap_data: any portion of nmap scan result can be given \
+            as argument. nmap_data should always be a string representing \
             a part or a complete nmap scan report.
             :type nmap_data: string
 
-            This method checks which portion of a nmap scan is given
+            This method checks which portion of a nmap scan is given \
             as argument.
             It could be:
 
@@ -66,12 +65,12 @@ def _parse_xml(cls, nmap_data=None, incomplete=False):
                 4. a list of hosts: <hosts/> tag (TODO)
                 5. a list of ports: <ports/> tag
 
-            :param incomplete: enable you to parse interrupted nmap scans
-            and/or incomplete nmap xml blocks by adding a </nmaprun> at
+            :param incomplete: enable you to parse interrupted nmap scans \
+            and/or incomplete nmap xml blocks by adding a </nmaprun> at \
             the end of the scan.
-
             :type incomplete: boolean
-            :return: NmapObject (NmapHost, NmapService or NmapReport)
+
+            :return: NmapObject (NmapHost, NmapService or NmapReport) \
                     or a list of NmapObject
         """
 
@@ -140,19 +139,18 @@ def _parse_xml_report(cls, root=None):
     @classmethod
     def parse_fromstring(cls, nmap_data, data_type="XML", incomplete=False):
         """
-            Call generic cls.parse() method and ensure that a string is
+            Call generic cls.parse() method and ensure that a string is \
             passed on as argument. If not, an exception is raised.
 
-            :param nmap_data: Same as for parse(), any portion of nmap scan.
-
+            :param nmap_data: Same as for parse(), any portion of nmap scan. \
             Reports could be passed as argument. Data type _must_ be a string.
 
             :type nmap_data: string
 
             :param data_type: Specifies the type of data passed on as argument.
 
-            :param incomplete: enable you to parse interrupted nmap scans
-            and/or incomplete nmap xml blocks by adding a </nmaprun> at
+            :param incomplete: enable you to parse interrupted nmap scans \
+            and/or incomplete nmap xml blocks by adding a </nmaprun> at \
             the end of the scan.
             :type incomplete: boolean
 
@@ -169,20 +167,18 @@ def parse_fromfile(cls, nmap_report_path,
                        data_type="XML",
                        incomplete=False):
         """
-            Call generic cls.parse() method and ensure that a correct file
+            Call generic cls.parse() method and ensure that a correct file \
             path is given as argument. If not, an exception is raised.
 
-            :param nmap_data: Same as for parse().
-
-            Any portion of nmap scan reports could be passed as argument.
-
-            Data type _must be a valid path to a file containing
+            :param nmap_data: Same as for parse(). \
+            Any portion of nmap scan reports could be passed as argument. \
+            Data type _must be a valid path to a file containing \
             nmap scan results.
 
             :param data_type: Specifies the type of serialization in the file.
 
-            :param incomplete: enable you to parse interrupted nmap scans
-            and/or incomplete nmap xml blocks by adding a </nmaprun> at
+            :param incomplete: enable you to parse interrupted nmap scans \
+            and/or incomplete nmap xml blocks by adding a </nmaprun> at \
             the end of the scan.
             :type incomplete: boolean
 
@@ -200,9 +196,9 @@ def parse_fromfile(cls, nmap_report_path,
     @classmethod
     def parse_fromdict(cls, rdict):
         """
-            Strange method which transforms a python dict
-            representation of a NmapReport and turns it into an
-            NmapReport object.
+            Strange method which transforms a python dict \
+            representation of a NmapReport and turns it into an \
+            NmapReport object. \
             Needs to be reviewed and possibly removed.
 
             :param rdict: python dict representation of an NmapReport
diff --git a/libnmap/plugins/s3.py b/libnmap/plugins/s3.py
@@ -1,11 +1,13 @@
 #!/usr/bin/env python
 """
 :mod:`libnmap.plugin.s3` -- S3 Backend Plugin
-===================================
+=============================================
 
 .. module:: libnmap.plugin.s3
+
 :platform: Linux
 :synopsis: a plugin is representation of a S3 backend using boto
+
 .. moduleauthor:: Ronald Bister
 .. moduleauthor:: Mike Boutillier
 """
diff --git a/libnmap/process.py b/libnmap/process.py
