device_manager.scanner package¶

Submodules¶

device_manager.scanner.nmap module¶

The nmap wrapper is used to easily and efficiently perform nmap scans with python-nmap.

It wraps the relevant scan functions of nmap’s PortScanner. The scan results are stored locally to make them accessable later if needed. And this class also provides a way to scan asynchronously for network devices at a specific address or subnet.

class device_manager.scanner.nmap.NMAPWrapper(notify_parent_done: Optional[Callable[[bool], Any]] = None, **kwargs)[source]¶

Bases: object

Wrapper class for nmap.PortScanner. It class manages network scans via nmap and converts the results in `Device`s.

Parameters

notify_parent_done – An optional function object which is called after this scan is performed. The function needs to accept one argument of type bool. This argument will be True, if the scan succeeded and False, if not.
**kwargs –
- nmap_search_path: One or multiple paths where to search for the nmap executable.

property valid¶: Returns True, if the nmap.PortScanner could be instantiated

property raw_devices¶: The raw search results as they are returned by a scan with nmap. The results of all previous scans are included.

property devices¶: The results of all previous scans with namp. The raw results are converted into Device- objects.

clear_devices() → None[source]¶: Deletes all previous scan results.

scan(hosts: Union[str, Iterable[str]]) → bool[source]¶

Performs a network scan with nmap (synchronously).

Parameters: hosts – One host as string or multiple hosts as iterable of strings. Multiple hosts can also be written as single string with a space as separator. A host can use one of the following formats to scan a single host: - ip address (e.g. 192.168.1.10) - hostname (e.g. localhost) - domain (e.g. mydevice.company.com) Or to scan a whole subnet of a local network: - ip subnet (e.g. 192.168.1.0/24 for a 24bit netmask)

scan_async(hosts: Union[str, Iterable[str]], on_done: Optional[Callable[[bool], None]] = None) → bool[source]¶

Performs a network scan with nmap asynchronously.

Parameters

hosts – One host as string or multiple hosts as iterable of strings. Multiple hosts can also be written as single string with a space as separator. A host can use one of the following formats to scan a single host: - ip address (e.g. 192.168.1.10) - hostname (e.g. localhost) - domain (e.g. mydevice.company.com) Or to scan a whole subnet of a local network: - ip subnet (e.g. 192.168.1.0/24 for a 24bit netmask)
on_done – An optional function object which is called after this scan is performed. The function needs to accept one argument of type bool. This argument will be True, if the scan succeeded and False, if not.

Returns

True, if the asynchronous scan was started. False, if a scan is already running.

Return type

bool

is_scan_alive() → bool[source]¶

Checks if an asynchronous scan is still running.

Returns: True, if an asynchronous scan is running. Otherwise, false.
Return type: bool

wait_for_scan(timeout: Optional[float] = None) → bool[source]¶

If an asynchronous scan is running, this function waits until the scan is finished.

Parameters

timeout – A floating point number specifying a timeout (maximum time to wait) in seconds. If timeout is None, this function will block until the scan is completed.

Returns

True, if the scan is completed or not running at all. False, if the timeout: happened.

Return type

bool

_scan(hosts: Union[str, Iterable[str]], on_done: Optional[Callable[[bool], None]]) → bool[source]¶

Performs a network scan with nmap (synchronously).

Parameters

hosts – One host as string or multiple hosts as iterable of strings. Multiple hosts can also be written as single string with a space as separator. A host can use one of the following formats to scan a single host: - ip address (e.g. 192.168.1.10) - hostname (e.g. localhost) - domain (e.g. mydevice.company.com) Or to scan a whole subnet of a local network: - ip subnet (e.g. 192.168.1.0/24 for a 24bit netmask)
on_done – An optional function object which is called after this scan is performed. The function needs to accept one argument of type bool. This argument will be True, if the scan succeeded and False, if not.

device_manager.scanner._base module¶

Base classes for device scanners.

class device_manager.scanner._base.BaseDeviceScanner[source]¶

Bases: abc.ABC

Base class for device scanners. Device scanners are used to scan specific protocols (like usb or ip). You can get a list of all connected devices or search with a user-defined filter.

list_devices(rescan: bool = False) → Sequence[device_manager.device.Device][source]¶

Lists all connected devices.

Parameters: rescan – True, if the protocol should be scanned again. False, if you only want to scan, if there are no results from a previous scan.
Returns: A sequence of all connected devices.
Return type: tuple

find_devices(rescan: bool = False, **filters) → Sequence[device_manager.device.Device][source]¶

Lists all connected devices that match the filter.

Parameters

rescan – True, if the protocol should be scanned again. False, if you only want to scan, if there are no results from a previous scan.
**filters – User-defined filters. Only devices that match these filters will be returned.

Returns

A sequence of all connected devices that match the filter.

Return type

tuple

abstract _scan(rescan: bool) → Sequence[device_manager.device.Device][source]¶

Scans the specific protocol for devices.

Subclasses must override this function and fill the _devices attribute.

Parameters: rescan – True, if the protocol should be scanned again. False, if you only want to scan, if there are no results from a previous scan.

static _match_filters(device: device_manager.device.Device, **filters) → bool[source]¶

Checks if the device matches the user-defined filters.

Parameters

device – The device object, that is about to be checked against the filters.
**filters – User-defined filters. Only devices that match these filters will be returned.

Returns

True, if the device matches the filters.

Return type

bool

class device_manager.scanner._base.BaseLANDeviceScanner(**kwargs)[source]¶

Bases: device_manager.scanner._base.BaseDeviceScanner, abc.ABC

A device scanner that scans the local network for ethernet devices.

Parameters

**kwargs –

nmap_search_path: One or multiple paths where to search for the nmap executable.

property nmap¶

Wrapper for a nmap port scanner.

May be None, if nmap could not be imported.

_scan(rescan: bool) → Sequence[device_manager.device.LANDevice][source]¶

Scans the arp cache for ip and mac addresses.

Parameters: rescan – True, to scan again. False, if you only want to scan, if there are no results from a previous scan.

abstract _get_arp_cache() → Dict[str, device_manager.device.LANDevice][source]¶

Runs the arp command and extracts ip and mac addresses from the command’s output.

A subclass must override this function because this function is platform dependent.

Returns

A dictionary, mapping strings to `LANDevice`s. The dictionary contains all results: of the arp command, that contain a valid ip and mac address.

Return type

dict

device_manager.scanner._linux module¶

Device scanners working on linux systems.

class device_manager.scanner._linux.LinuxUSBDeviceScanner[source]¶

Bases: device_manager.scanner._base.BaseDeviceScanner

A device scanner that scans for usb devices on linux systems. It scans all usb ports for devices.

static _device_from_raw(raw_device: pyudev.device._device.Device) → device_manager.device.USBDevice [source]¶

Converts a raw device provided from pyudev into a USBDevice-object.

Parameters: raw_device – A device provided from pyudev as result of scanning all usb ports.
Returns: The raw_device converted into a USBDevice-object.
Return type: USBDevice

_scan(rescan: bool) → Sequence[device_manager.device.USBDevice][source]¶

Scans all usb ports for devices.

Parameters: rescan – True, if the ports should be scanned again. False, if you only want to scan, if there are no results from a previous scan.

class device_manager.scanner._linux.LinuxLANDeviceScanner(**kwargs)[source]¶

Bases: device_manager.scanner._base.BaseLANDeviceScanner

A device scanner that scans the local network for ethernet devices.

Parameters

**kwargs –

nmap_search_path: One or multiple paths where to search for the nmap executable.

_get_arp_cache() → Dict[str, device_manager.device.LANDevice][source]¶

Runs the arp command and extracts ip and mac addresses from the command’s output.

Returns

A dictionary, mapping strings to `LANDevice`s. The dictionary contains all results: of the arp command, that contain a valid ip and mac address.

Return type

dict

device_manager.scanner._win32 module¶

Device scanners working on windows systems.

class device_manager.scanner._win32.Win32USBDeviceScanner(**kwargs)[source]¶

Bases: device_manager.scanner._base.BaseDeviceScanner

A device scanner that scans for usb devices on linux systems. It scans all usb ports for devices.

static _device_from_raw(raw_device) → device_manager.device.USBDevice [source]¶

Converts a raw device provided from the windows device manager into a USBDevice-object.

Parameters: raw_device – A device provided from the windows device manager as result of scanning all known PNP devices.
Returns: The raw_device converted into a USBDevice-object.
Return type: USBDevice

_scan(rescan: bool) → Sequence[device_manager.device.USBDevice][source]¶

Scans all PNP devices from the windows device manager and filters the USB devices.

Parameters: rescan – True, to scan again. False, if you only want to scan, if there are no results from a previous scan.

class device_manager.scanner._win32.Win32LANDeviceScanner(**kwargs)[source]¶

Bases: device_manager.scanner._base.BaseLANDeviceScanner

A device scanner that scans the local network for ethernet devices.

Parameters

**kwargs –

nmap_search_path: One or multiple paths where to search for the nmap executable.

_get_arp_cache() → Dict[str, device_manager.device.LANDevice][source]¶

Runs the arp command and extracts ip and mac addresses from the command’s output.

Returns

A dictionary, mapping strings to `LANDevice`s. The dictionary contains all results: of the arp command, that contain a valid ip and mac address.

Return type

dict

Module contents¶

The device scanners are useful to scan for connected devices of different types.

There are special device scanners (like USBDeviceScanner and LANDeviceScanner). These are used to scan a specific protocol for connected devices. They are implemented for windows and linux to make them work on the most common platforms. The windows and linux specific classes are imported automatically depending on your system. Additionally, there is the general DeviceScanner that uses the specific device scanners inside. So this class can be used to scan for different device types if the type is unknown or if the user specifies a specific type, the scan is focused on this type.

Examples

Creating a general device scanner:

>>> s = DeviceScanner()

Listing all connected devices that can be found directly:

>>> devices = s.list_devices()

Finding devices by their identifiers

>>> usb_device = s.find_devices(serial="1234567890AB")
>>> lan_device = s.find_devices(mac_address="12:34:56:78:90:AB")

To only search for a specific device type, you can access the specific DeviceScanner`s by using the `__getitem__ operator. This speeds up the search for the device.

>>> usb_device = s["usb"].find_devices(serial="1234567890AB")
>>> lan_devices = s["lan"].list_devices()

For better results when searching for ethernet devices, nmap can be used to scan the network. For more information take a look at the NMAPWrapper.

>>> s["lan"].nmap.scan(...)

device_manager.scanner.USBDeviceScanner¶: alias of device_manager.scanner._linux.LinuxUSBDeviceScanner

device_manager.scanner.LANDeviceScanner¶: alias of device_manager.scanner._linux.LinuxLANDeviceScanner

class device_manager.scanner.DeviceScanner(**kwargs)[source]¶

Bases: device_manager.scanner._base.BaseDeviceScanner

A general device scanner that contains all supported specific device scanners.

Calling the BaseDeviceScanner-functions on this object causes the scanner to search in all protocols. If only a specific device type required, use the __getitem__-operator to specify the device type.

_scan(rescan: bool) → Sequence[device_manager.device.Device][source]¶

Scans all connected devices of all supported types (usb and ethernet).

Parameters: rescan – True, if the ports should be scanned again. False, if you only want to scan, if there are no results from a previous scan.

device_manager.scanner package¶

Submodules¶

device_manager.scanner.nmap module¶

device_manager.scanner._base module¶

device_manager.scanner._linux module¶

device_manager.scanner._win32 module¶

Module contents¶

Table of Contents

Previous topic

This Page