updated documentation. fixed sphinx.rst errors.

savon-noir · savon-noir · commit 34e17e9d4d18 · 2014-06-03T00:28:40.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/cpe.rst b/docs/objects/cpe.rst
@@ -1,5 +1,5 @@
-libnmap.objects.service
-=======================
+libnmap.objects.cpe
+===================
 
 Using libnmap.objects.cpe module
 --------------------------------
diff --git a/docs/objects/nmaphost.rst b/docs/objects/nmaphost.rst
diff --git a/docs/objects/nmapreport.rst b/docs/objects/nmapreport.rst
diff --git a/docs/objects/nmapservice.rst b/docs/objects/nmapservice.rst
diff --git a/docs/objects/os.rst b/docs/objects/os.rst
@@ -16,20 +16,17 @@ NmapOSFingerprint methods
 NmapOSMatch methods
 -------------------
 
-.. automodule:: libnmap.objects.os
 .. autoclass:: NmapOSMatch
     :members:
 
 NmapOSClass methods
 -------------------
 
-.. automodule:: libnmap.objects.os
 .. autoclass:: NmapOSClass
     :members:
 
 OSFPPortUsed methods
 --------------------
 
-.. automodule:: libnmap.objects.os
 .. autoclass:: OSFPPortUsed
     :members:
diff --git a/docs/process.rst b/docs/process.rst
@@ -18,11 +18,7 @@ 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:
-.. automodule:: libnmap.process
-.. autoclass:: NmapProcess
-    :members: __init__
-
+To instanciate a NmapProcess instance, call the constructor with appropriate parameters
 
 Processing of events
 --------------------
@@ -118,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
@@ -44,6 +44,7 @@ def __init__(self, name, starttime=0, extrainfo=''):
 class NmapProcess(Thread):
     """
     NmapProcess is a class which wraps around the nmap executable.
+
     Consequently, in order to run an NmapProcess, nmap should be installed
     on the host running the script. By default NmapProcess will produce
     the output of the nmap scan in the nmap XML format. This could be then
@@ -54,23 +55,24 @@ def __init__(self, targets="127.0.0.1",
         """
         Constructor of NmapProcess class.
 
-        :param targets: hosts to be scanned. Could be a string of hosts
+        :param targets: hosts to be scanned. Could be a string of hosts \
         separated with a coma or a python list of hosts/ip.
         :type targets: string or list
 
-        :param options: list of nmap options to be applied to scan.
+        :param options: list of nmap options to be applied to scan. \
         These options are all documented in nmap's man pages.
 
-        :param event_callback: callable function which will be ran
-        each time nmap process outputs data. This function will receive
+        :param event_callback: callable function which will be ran \
+        each time nmap process outputs data. This function will receive \
         two parameters:
+
             1. the nmap process object
             2. the data produced by nmap process. See readme for examples.
 
-        :param safe_mode: parameter to protect unsafe options like -oN, -oG,
+        :param safe_mode: parameter to protect unsafe options like -oN, -oG, \
         -iL, -oA,...
 
-        :param fqp: full qualified path, if None, nmap will be searched
+        :param fqp: full qualified path, if None, nmap will be searched \
         in the PATH
 
         :return: NmapProcess object
