Important

The Nessus Package is currently a Technology Preview

Scans¶

Methods described in this section relate to the scans API. These methods can be accessed at Nessus.scans.

class ScansAPI(api: APISession)[source]¶

attachment(scan_id: int, attachment_id: int, key: str, fobj: BytesIO | None = None) → BytesIO[source]¶

Returns the requested attachment file

Parameters:

scan_id (int) – The Scan to fetch from
attachment_id (int) – The id of the scan attachment
key (str) – The access token for the attachment
fobj (BytesIO, optional) – File object to write to

Returns:

The file object requested

Return type:

BytesIO

Example

>>> with open('example.png', 'wb') as image_file:
...     nessus.scans.attachment(1, 1, 'something', image_file)

configure(scan_id: int, **kwargs) → None[source]¶

Reconfigures an existing scan.

Parameters:

scan_id (int) – Id of the scan to modify
**kwargs – the various settings to pass

Returns:

The updated scan object

Return type:

Dict

Example

>>> nessus.scans.configure(1, settings={
...     'name': 'Example Scan',
...     'enabled': True,
...     'text_targets': '192.168.1.1'
... })

copy(scan_id: int, folder_id: int | None = None, name: str | None = None) → Dict[source]¶

Copies the scan object

Parameters:

scan_id (int) – Id of the scan to copy
folder_id (int, optional) – Id of the destination folder
name (str, optional) – Name of the copied scan

Returns:

The copied scan object

Return type:

Dict

Example

>>> nessus.scans.copy(1)

create(**kwargs) → Dict[source]¶

Creates a new scan

Parameters:: **kwargs – The parameters to pass to the API to create the scan. For information on what to pass here, consult the API documentation
Returns:: The created scan object
Return type:: Dict

Example

>>> nessus.scans.create(uuid='abcdef12345667890abcdef',
                        settings={
                            'name': 'Example Scan',
                            'enabled': False,
                            'text_targets': '192.168.1.1'
                        })

delete(scan_id: int) → None[source]¶

Deletes the specified scan object

Parameters:: scan_id (int) – Id of the scan to delete

Example

>>> nessus.scans.delete(1)

delete_history(scan_id: int, history_id: int) → None[source]¶

Deletes the specified history object within a scan.

Parameters:

scan_id (int) – The scan to modify
history_id (int) – Id of the history object to remove

Example

>>> nessus.scans.delete_history(1, 1)

delete_many(scan_ids: List[int]) → List[source]¶

Deletes multiple scan objects

Parameters:: scan_ids (List[int]) – List of scan ids to delete
Returns:: list of deleted scans
Return type:: List

Example

>>> nessus.scans.delete_many([1, 2, 3])

details(scan_id: int) → Dict[source]¶

Returns the details for the specified scan.

Parameters:: scan_id (int) – Id of the scan to retrieve

Example

>>> nessus.scans.details(1)

export_formats(scan_id: int, schedule_id: int | None = None) → Dict[source]¶

Returns the available export formats and report options.

Parameters:

scan_id (int) – The scan to export
schedule_id (int, optional) – The schedule id associated with the scan

Returns:

The available export and report options

Return type:

Dict

Example

>>> nessus.scans.export_formats(1)

export_scan(scan_id: int, history_id: int | None = None, fobj: BytesIO | None = None, **kwargs) → BytesIO[source]¶

Generate a scan export or report and download it.

Parameters:

scan_id (int) – The id of the scan to export.
history_id (int, optional) – The history id of the specific point in time to export.
fobj (BytexIO, optional) – The file object to write the exported file to. If none is specified then a BytesIO object is written to in memory.
filters (list[tuple], optional) – The filters to apply to the exported data.
format (str, optional) – The exported scan format. Supported values are nessus, html, csv, and db. If unspecified, the default is nessus.
password (str, optional) – The password to apply to the exported data (required for db).
template_id (int, optional) – When exporting in HTML or PDF, what report definition should the exported data be represented within.
chunk_size (int, optional) – The chunk sizing for the download itself.
stream_hook (callable, optional) – Overload the default downloading behavior with a custom stream hook.
hook_kwargs (dict, optional) – keyword arguments to pass to the stream_hook callable in addition to the default passed params.

import_scan(fobj: BytesIO | None = None, file_id: str | None = None, folder_id: int | None = None, password: str | None = None) → Dict[source]¶

Import a scan report into the Tenable Nessus scanner. Either a file object or a file_id must be specified.

Parameters:

fobj (BytesIO, optional) – The file object to import.
file_id (str, optional) – The id of the already uploaded file object to import.
folder_id (int, optional) – The folder that the imported scan should reside within.
password (str, optional) – If the file object is encrypted, this password will be used to decrypt.

Example

>>> with open('Example.nessus', 'rb') as reportfile:
...     nessus.scans.import_scan(reportfile)

kill(scan_id: int) → None[source]¶

Forcefully terminate the currently running scan.

Parameters:: scan_id (int) – The id of the scan to terminate.

Example

>>> nessus.scans.kill(1)

launch(scan_id: int, alt_targets: List[str] | None = None) → str[source]¶

Launch a configured scan.

Parameters:

scan_id (int) – The id of the scan to launch.
alt_targets (list[str], optional) – A List of alternative targets to run the scan against.

Example

>>> nessus.scan.launch(1)

list(folder_id: int | None = None, last_modification_date: int | None = None) → Dict[source]¶

List of the available scan objects.

Parameters:

folder_id (int, optional) – Restrict the results to only the specified folder id.
last_modification_date (int, optional) – Restrict the results to only scans modified after the specified timestamp.

Example

>>> for scan in nessus.scans.list():
...     print(scan)

pause(scan_id: int) → None[source]¶

Pauses a currently running scans.

Parameters:: scan_id (int) – The id of the scan to pause.

Example

>>> nessus.scans.pause(1)

plugin_output(scan_id: int, host_id: int, plugin_id: int, history_id: int | None = None) → Dict[source]¶

Returns the plugin output for a specific finding within a scan.

Parameters:

scan_id (int) – The id of the scan
host_id (int) – The id of the host within the scan
plugin_id (int) – The plugin id of the finding on the host
history_id (int, optional) – The id of the history object within the scan.

Returns:

The restuls of the specific finding specified.

Return type:

Dict

Example

>>> nessus.scans.plugin_output(1, 1, 19506)

read_status(scan_id: int, read: bool) → None[source]¶

Sets the read status for the given scan.

Parameters:

scan_id (int) – The id of the scan to modify
read (bool) – Is the scan read?

Example

>>> nessus.scans.read_status(1, True)

resume(scan_id: int) → None[source]¶

Resumes a paused scan.

Parameters:: scan_id (int) – The id of the scan to resume.

Example

>>> nessus.scans.resume(1)

schedule(scan_id: int, enabled: bool) → Dict[source]¶

Enables/Disables the scan schedule for the given scan.

Parameters:

scan_id (int) – The id of the scan to modify
enabled (bool) – Should the scan schedule be enabled?

Returns:

The scan schedule settings.

Return type:

Dict

stop(scan_id: int) → None[source]¶

Stops a running scan

Parameters:: scan_id (int) – The id of the scan to stop.

Example

>>> nessus.scans.stop(1)

timezones() → List[Dict][source]¶

Returns the currently configured timezone data

Returns:: List of timezone objects
Return type:: List[Dict]

Example

>>> nessus.scans.timezones()