added documentation for NmapTask

savon-noir · savon-noir · commit 6be7a979fbd7 · 2014-05-30T16:34:39.000+02:00
diff --git a/docs/index.rst b/docs/index.rst
@@ -10,7 +10,7 @@ libnmap is a python toolkit for manipulating nmap. It currently offers the follo
 - parse: enables you to parse nmap reports or scan results (only XML so far) from a file, a string,...
 - 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
-- common: contains basic nmap objects like NmapHost and NmapService. It is to note that each object can be "diff()ed" with another similar object.
+- objects: contains basic nmap objects like NmapHost and NmapService. It is to note that each object can be "diff()ed" with another similar object.
 - 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
diff --git a/docs/process.rst b/docs/process.rst
@@ -1,6 +1,50 @@
 libnmap.process
 ===============
 
+Purpose of libnmap.process
+--------------------------
+
+The purpose of this module is to enable the lib users to launch and control nmap scans. This module will consequently fire the nmap command following the specified parameters provided in the constructor.
+
+It is to note that this module will not perform a full inline parsing of the data. Only specific events are parsed and exploitable via either a callback function defined by the user and provided in the constructor; either by running the process in the background and accessing the NmapProcess attributes will the scan is running.
+
+To run an nmap scan, you need to:
+
+- instanciate NmapProcess
+- call the run*() methods
+
+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
+
+Processing of events
+--------------------
+
+While Nmap is running, some events are process and parsed. This would enable you to:
+
+- evaluate estimated time to completion and progress in percentage
+- find out which task is running and how many nmap task have been executed
+- know the start time and nmap version
+
+As you may know, depending on the nmap options you specified, nmap will execute several tasks like "DNS Resolve", "Ping Scan", "Connect Scan", "NSE scripts",... This is of course independent from libnmap but the lib is able to parse these tasks and will instanciate a NmapTask object for any task executed. The list of executed task is available via the following properties:
+
+- NmapProcess.tasks: list of NmapTask object (executed nmap tasks)
+- NmapProcess.current_task: returns the currently running NmapTask
+
+You will find below the list of attributes you can use when dealing with NmapTask:
+
+- name: task name (check nmap documentation for the complete list)
+- etc: unix timestamp of estimated time to completion
+- progress: estimated percentage of task completion
+- percent: estimated percentage of task completion (same as progress)
+- remaining: estimated number of seconds to completion
+- status: status of the task ('started' or 'ended')
+- starttime: unix timestamp of when the task started
+- endtime: unix timestamp of when the task ended, 0 if not completed yet
+- extrainfo: extra information stored for specific tasks
+- updated: unix timestamp of last data update for this task
+
 Using libnmap.process
 ---------------------
 
@@ -67,3 +111,10 @@ NmapProcess methods
 .. automodule:: libnmap.process
 .. autoclass:: NmapProcess
     :members:
+
+NmapTask methods
+-------------------
+
+.. automodule:: libnmap.process
+.. autoclass:: NmapTask
+    :members:
