libnmap.process.NmapProcess

class documentation

class NmapProcess(Thread): (source)

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 parsed out via the NmapParser class from libnmap.parser module.

Method	`__init__`	Constructor of NmapProcess class.
Method	`get_command_line`	Public method returning the reconstructed command line ran via the lib
Method	`has_failed`	Checks if nmap has failed.
Method	`has_terminated`	Checks if nmap has terminated. Could have failed or succeeded
Method	`is_running`	Checks if nmap is still running.
Method	`is_successful`	Checks if nmap terminated successfully.
Method	`run`	Public method which is usually called right after the constructor of NmapProcess. This method starts the nmap executable's subprocess. It will also bind a Process that will read from subprocess' stdout and stderr and push the lines read in a python queue for futher processing...
Method	`run_background`	run nmap scan in background as a thread. For privileged scans, consider NmapProcess.sudo_run_background()
Method	`stop`	Send KILL -15 to the nmap subprocess and gently ask the threads to stop.
Method	`sudo_run`	Public method enabling the library's user to run the scan with privileges via sudo. The sudo configuration should be set manually on the local system otherwise sudo will prompt for a password. This method alters the command line by prefixing the sudo command to nmap and will then call self...
Method	`sudo_run_background`	Public method enabling the library's user to run in background a nmap scan with privileges via sudo. The sudo configuration should be set manually on the local system otherwise sudo will prompt for a password...
Instance Variable	`CANCELLED`	Undocumented
Instance Variable	`DONE`	Undocumented
Instance Variable	`FAILED`	Undocumented
Instance Variable	`READY`	Undocumented
Instance Variable	`RUNNING`	Undocumented
Property	`command`	return the constructed nmap command or empty string if not constructed yet.
Property	`current_task`	Accessor for the current NmapTask beeing run
Property	`elapsed`	Accessor returning for how long the scan ran (in seconds)
Property	`endtime`	Accessor for time when scan ended
Property	`etc`	Accessor for estimated time to completion
Property	`options`	Provides the list of options for that scan
Property	`progress`	Accessor for progress status in percentage
Property	`rc`	Accessor for nmap execution's return code
Property	`starttime`	Accessor for time when scan started
Property	`state`	Accessor for nmap execution state. Possible states are:
Property	`stderr`	Accessor for nmap standart error
Property	`stdout`	Accessor for nmap standart output
Property	`summary`	Accessor returning a short summary of the scan's results
Property	`targets`	Provides the list of targets to scan
Property	`tasks`	Accessor returning for the list of tasks ran during nmap scan
Property	`version`	Accessor for nmap binary version number
Static Method	`__validate_target`	Check if a provided target is valid. This function was created in order to address CVE-2022-30284
Method	`__build_windows_cmdline`	Undocumented
Method	`__process_event`	Private method called while nmap process is running. It enables the library to handle specific data/events produced by nmap process. So far, the following events are supported:
Method	`__process_nmap_proc_stdout`	Undocumented
Method	`_ensure_user_exists`	Undocumented
Method	`_run_init`	Undocumented
Method	`_whereis`	Protected method enabling the object to find the full path of a binary from its PATH environment variable.
Instance Variable	`__current_task`	Undocumented
Instance Variable	`__elapsed`	Undocumented
Instance Variable	`__endtime`	Undocumented
Instance Variable	`__is_windows`	Undocumented
Instance Variable	`__nmap_binary`	Undocumented
Instance Variable	`__nmap_command_line`	Undocumented
Instance Variable	`__nmap_dynamic_options`	Undocumented
Instance Variable	`__nmap_event_callback`	Undocumented
Instance Variable	`__nmap_fixed_options`	Undocumented
Instance Variable	`__nmap_proc`	Undocumented
Instance Variable	`__nmap_rc`	Undocumented
Instance Variable	`__nmap_targets`	Undocumented
Instance Variable	`__nmap_tasks`	Undocumented
Instance Variable	`__starttime`	Undocumented
Instance Variable	`__state`	Undocumented
Instance Variable	`__stderr`	Undocumented
Instance Variable	`__stdout`	Undocumented
Instance Variable	`__sudo_run`	Undocumented
Instance Variable	`__summary`	Undocumented
Instance Variable	`__version`	Undocumented
Instance Variable	`_nmap_options`	Undocumented

def __init__(self, targets='127.0.0.1', options='-sT', event_callback=None, safe_mode=True, fqp=None): (source) ¶

Constructor of NmapProcess class. :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. 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 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, -iL, -oA,... :param fqp: full qualified path, if None, nmap will be searched in the PATH :return: NmapProcess object

def get_command_line(self): (source) ¶

Public method returning the reconstructed command line ran via the lib :return: the full nmap command line to run :rtype: string

def has_failed(self): (source) ¶

Checks if nmap has failed. :return: True if nmap process errored.

def has_terminated(self): (source) ¶

Checks if nmap has terminated. Could have failed or succeeded :return: True if nmap process is not running anymore.

def is_running(self): (source) ¶

Checks if nmap is still running. :return: True if nmap is still running

def is_successful(self): (source) ¶

Checks if nmap terminated successfully. :return: True if nmap terminated successfully.

def run(self): (source) ¶

Public method which is usually called right after the constructor of NmapProcess. This method starts the nmap executable's subprocess. It will also bind a Process that will read from subprocess' stdout and stderr and push the lines read in a python queue for futher processing. This processing is waken-up each time data is pushed from the nmap binary into the stdout reading routine. Processing could be performed by a user-provided callback. The whole NmapProcess object could be accessible asynchroneously. return: return code from nmap execution

def run_background(self): (source) ¶

run nmap scan in background as a thread. For privileged scans, consider NmapProcess.sudo_run_background()

def stop(self): (source) ¶

Send KILL -15 to the nmap subprocess and gently ask the threads to stop.

def sudo_run(self, run_as='root'): (source) ¶

Public method enabling the library's user to run the scan with privileges via sudo. The sudo configuration should be set manually on the local system otherwise sudo will prompt for a password. This method alters the command line by prefixing the sudo command to nmap and will then call self.run() :param run_as: user name to which the lib needs to sudo to run the scan :return: return code from nmap execution

def sudo_run_background(self, run_as='root'): (source) ¶

Public method enabling the library's user to run in background a nmap scan with privileges via sudo. The sudo configuration should be set manually on the local system otherwise sudo will prompt for a password. This method alters the command line by prefixing the sudo command to nmap and will then call self.run() :param run_as: user name to which the lib needs to sudo to run the scan :return: return code from nmap execution

CANCELLED = (source) ¶

Undocumented

DONE = (source) ¶

Undocumented

FAILED = (source) ¶

Undocumented

READY = (source) ¶

Undocumented

RUNNING = (source) ¶

Undocumented

@property
command = (source) ¶

return the constructed nmap command or empty string if not constructed yet. :return: string

@property
current_task = (source) ¶

Accessor for the current NmapTask beeing run :return: NmapTask or None if no task started yet

@property
elapsed = (source) ¶

Accessor returning for how long the scan ran (in seconds) :return: string

@property
endtime = (source) ¶

Accessor for time when scan ended :return: string. Unix timestamp

@property
etc = (source) ¶

Accessor for estimated time to completion :return: estimated time to completion

@property
options = (source) ¶

Provides the list of options for that scan :return: list of string (nmap options)

@property
progress = (source) ¶

Accessor for progress status in percentage :return: percentage of job processed.

@property
rc = (source) ¶

Accessor for nmap execution's return code :return: nmap execution's return code

@property
starttime = (source) ¶

Accessor for time when scan started :return: string. Unix timestamp

@property
state = (source) ¶

Accessor for nmap execution state. Possible states are: - self.READY - self.RUNNING - self.FAILED - self.CANCELLED - self.DONE :return: integer (from above documented enum)

@property
stderr = (source) ¶

Accessor for nmap standart error :return: output from nmap when errors occured. :rtype: string

@property
stdout = (source) ¶

Accessor for nmap standart output :return: output from nmap scan in XML :rtype: string

@property
summary = (source) ¶

Accessor returning a short summary of the scan's results :return: string

@property
targets = (source) ¶

Provides the list of targets to scan :return: list of string

@property
tasks = (source) ¶

Accessor returning for the list of tasks ran during nmap scan :return: dict of NmapTask object

@property
version = (source) ¶

Accessor for nmap binary version number :return: version number of nmap binary :rtype: string

@staticmethod
def __validate_target(target): (source) ¶

Check if a provided target is valid. This function was created in order to address CVE-2022-30284 See https://nmap.org/book/man-target-specification.html for all the ways targets can be specified This function verifies the following: - matches the user specified target against a list of allowed chars - check if dashes are used at the start or at the end of target FQDN can contain dashes anywhere except at the beginning or end This check also fixes/prevents CVE-2022-30284, which depends on being able to pass options such as --script as a target :return: False if target contains forbidden characters

def __build_windows_cmdline(self): (source) ¶

Undocumented

def __process_event(self, eventdata): (source) ¶

Private method called while nmap process is running. It enables the library to handle specific data/events produced by nmap process. So far, the following events are supported: 1. task progress: updates estimated time to completion and percentage done while scan is running. Could be used in combination with a callback function which could then handle this data while scan is running. 2. nmap run: header of the scan. Usually displayed when nmap is started 3. finished: when nmap scan ends. :return: True is event is known. :todo: handle parsing directly via NmapParser.parse()

def __process_nmap_proc_stdout(self): (source) ¶

Undocumented

def _ensure_user_exists(self, username=''): (source) ¶

Undocumented

def _run_init(self): (source) ¶

Undocumented

def _whereis(self, program): (source) ¶

Protected method enabling the object to find the full path of a binary from its PATH environment variable. :param program: name of a binary for which the full path needs to be discovered. :return: the full path to the binary. :todo: add a default path list in case PATH is empty.

__current_task = (source) ¶

Undocumented

__elapsed: str = (source) ¶

Undocumented

__endtime: int = (source) ¶

Undocumented

__is_windows = (source) ¶

Undocumented

__nmap_binary = (source) ¶

Undocumented

__nmap_command_line = (source) ¶

Undocumented