def get_schedule(self,
schedule_id: str,
*,
tasks: Optional[bool] = None) -> Any:
"""Request a single schedule
Arguments:
schedule_id: UUID of an existing schedule
tasks: Whether to include tasks using the schedules
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_schedules")
if not schedule_id:
raise RequiredArgument(function=self.get_schedule.__name__,
argument="schedule_id")
cmd.set_attribute("schedule_id", schedule_id)
if tasks is not None:
cmd.set_attribute("tasks", to_bool(tasks))
return self._send_xml_command(cmd)
def get_scan_config_preferences(self,
*,
nvt_oid: Optional[str] = None,
config_id: Optional[str] = None) -> Any:
"""Request a list of scan_config preferences
When the command includes a config_id attribute, the preference element
includes the preference name, type and value, and the NVT to which the
preference applies.
If the command includes a config_id and an nvt_oid, the preferences for
the given nvt in the config will be shown.
Arguments:
nvt_oid: OID of nvt
config_id: UUID of scan config of which to show preference values
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_preferences")
if nvt_oid:
cmd.set_attribute("nvt_oid", nvt_oid)
if config_id:
cmd.set_attribute("config_id", config_id)
return self._send_xml_command(cmd)
def get_overrides(
self,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
details: Optional[bool] = None,
result: Optional[bool] = None,
) -> Any:
"""Request a list of overrides
Arguments:
filter_string: Filter term to use for the query
filter_id: UUID of an existing filter to use for the query
details: Whether to include full details
result: Whether to include results using the override
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_overrides")
add_filter(cmd, filter_string, filter_id)
if details is not None:
cmd.set_attribute("details", to_bool(details))
if result is not None:
cmd.set_attribute("result", to_bool(result))
return self._send_xml_command(cmd)
def get_target(self,
target_id: str,
*,
tasks: Optional[bool] = None) -> Any:
"""Request a single target
Arguments:
target_id: UUID of an existing target
tasks: Whether to include list of tasks that use the target
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_targets")
if not target_id:
raise RequiredArgument(function=self.get_target.__name__,
argument="target_id")
cmd.set_attribute("target_id", target_id)
if tasks is not None:
cmd.set_attribute("tasks", to_bool(tasks))
return self._send_xml_command(cmd)
def modify_scan_config_set_name(self, config_id: str, name: str) -> Any:
"""Modifies the name of an existing scan config
Arguments:
config_id: UUID of scan config to modify.
name: New name for the config.
"""
if not config_id:
raise RequiredArgument(
function=self.modify_scan_config_set_name.__name__,
argument="config_id",
)
if not name:
raise RequiredArgument(
function=self.modify_scan_config_set_name.__name__,
argument="name",
)
cmd = XmlCommand("modify_config")
cmd.set_attribute("config_id", str(config_id))
cmd.add_element("name", name)
return self._send_xml_command(cmd)
def __get_config(self, config_id: str, usage_type: UsageType) -> Any:
if not config_id:
raise RequiredArgument(
function=self.get_config.__name__, argument='config_id'
)
cmd = XmlCommand("get_configs")
cmd.set_attribute("config_id", config_id)
cmd.set_attribute("usage_type", usage_type.value)
# for single entity always request all details
cmd.set_attribute("details", "1")
return self._send_xml_command(cmd)
def get_scanners(
self,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
trash: Optional[bool] = None,
details: Optional[bool] = None,
) -> Any:
"""Request a list of scanners
Arguments:
filter_string: Filter term to use for the query
filter_id: UUID of an existing filter to use for the query
trash: Whether to get the trashcan scanners instead
details: Whether to include extra details like tasks using this
scanner
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_scanners")
add_filter(cmd, filter_string, filter_id)
if trash is not None:
cmd.set_attribute("trash", to_bool(trash))
if details is not None:
cmd.set_attribute("details", to_bool(details))
return self._send_xml_command(cmd)
def __create_config(
self, config_id: str, name: str, usage_type: UsageType, function: str
) -> Any:
if not name:
raise RequiredArgument(function=function, argument='name')
if not config_id:
raise RequiredArgument(function=function, argument='config_id')
cmd = XmlCommand("create_config")
cmd.add_element("copy", config_id)
cmd.add_element("name", name)
cmd.add_element("usage_type", usage_type.value)
return self._send_xml_command(cmd)
def help(
self,
*,
help_format: Optional[HelpFormat] = None,
brief: Optional[bool] = None,
) -> Any:
"""Get the help text
Arguments:
help_format: Format of of the help:
"html", "rnc", "text" or "xml
brief: If True help is brief
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("help")
help_type = ""
if brief:
help_type = "brief"
cmd.set_attribute("type", help_type)
if help_format:
if not isinstance(help_format, HelpFormat):
raise InvalidArgumentType(
function=self.help.__name__,
argument="feed_type",
arg_type=HelpFormat.__name__,
)
cmd.set_attribute("format", help_format.value)
return self._send_xml_command(cmd)
def get_nvt_preference(
self,
name: str,
*,
nvt_oid: Optional[str] = None,
) -> Any:
"""Request a nvt preference
Arguments:
name: name of a particular preference
nvt_oid: OID of nvt
config_id: UUID of scan config of which to show preference values
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_preferences")
if not name:
raise RequiredArgument(function=self.get_nvt_preference.__name__,
argument="name")
cmd.set_attribute("preference", name)
if nvt_oid:
cmd.set_attribute("nvt_oid", nvt_oid)
return self._send_xml_command(cmd)
def get_notes(
self,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
details: Optional[bool] = None,
result: Optional[bool] = None,
) -> Any:
"""Request a list of notes
Arguments:
filter_string: Filter term to use for the query
filter_id: UUID of an existing filter to use for the query
details: Add info about connected results and tasks
result: Return the details of possible connected results.
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_notes")
add_filter(cmd, filter_string, filter_id)
if details is not None:
cmd.set_attribute("details", to_bool(details))
if result is not None:
cmd.set_attribute("result", to_bool(result))
return self._send_xml_command(cmd)
def get_tags(
self,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
trash: Optional[bool] = None,
names_only: Optional[bool] = None,
) -> Any:
"""Request a list of tags
Arguments:
filter_string: Filter term to use for the query
filter_id: UUID of an existing filter to use for the query
trash: Whether to get tags from the trashcan instead
names_only: Whether to get only distinct tag names
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_tags")
add_filter(cmd, filter_string, filter_id)
if trash is not None:
cmd.set_attribute("trash", to_bool(trash))
if names_only is not None:
cmd.set_attribute("names_only", to_bool(names_only))
return self._send_xml_command(cmd)
def get_tls_certificates(
self,
*,
filter: Optional[str] = None,
filter_id: Optional[str] = None,
include_certificate_data: Optional[bool] = None,
details: Optional[bool] = None
) -> Any:
"""Request a list of TLS certificates
Arguments:
filter: Filter term to use for the query
filter_id: UUID of an existing filter to use for the query
include_certificate_data: Whether to include the certificate data in
the response
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_tls_certificates")
_add_filter(cmd, filter, filter_id)
if details is not None:
cmd.set_attribute("details", _to_bool(details))
if include_certificate_data is not None:
cmd.set_attribute(
"include_certificate_data", _to_bool(include_certificate_data)
)
return self._send_xml_command(cmd)
def modify_scan_config_set_comment(self,
config_id: str,
*,
comment: Optional[str] = None) -> Any:
"""Modifies the comment of an existing scan config
Arguments:
config_id: UUID of scan config to modify.
comment: Comment to set on a config. Default is an
empty comment and the previous comment will be
removed.
"""
if not config_id:
raise RequiredArgument(
function=self.modify_scan_config_set_comment.__name__,
argument="config_id argument",
)
cmd = XmlCommand("modify_config")
cmd.set_attribute("config_id", str(config_id))
if not comment:
comment = ""
cmd.add_element("comment", comment)
return self._send_xml_command(cmd)
def get_results(
self,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
task_id: Optional[str] = None,
note_details: Optional[bool] = None,
override_details: Optional[bool] = None,
details: Optional[bool] = None,
) -> Any:
"""Request a list of results
Arguments:
filter_string: Filter term to use for the query
filter_id: UUID of an existing filter to use for the query
task_id: UUID of task for note and override handling
note_details: If notes are included, whether to include note details
override_details: If overrides are included, whether to include
override details
details: Whether to include additional details of the results
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_results")
add_filter(cmd, filter_string, filter_id)
if task_id:
cmd.set_attribute("task_id", task_id)
if details is not None:
cmd.set_attribute("details", to_bool(details))
if note_details is not None:
cmd.set_attribute("note_details", to_bool(note_details))
if override_details is not None:
cmd.set_attribute("override_details", to_bool(override_details))
return self._send_xml_command(cmd)
def get_filter(
self, filter_id: str, *, alerts: Optional[bool] = None
) -> Any:
"""Request a single filter
Arguments:
filter_id: UUID of an existing filter
alerts: Whether to include list of alerts that use the filter.
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_filters")
if not filter_id:
raise RequiredArgument(
function=self.get_filter.__name__, argument="filter_id"
)
cmd.set_attribute("filter_id", filter_id)
if alerts is not None:
cmd.set_attribute("alerts", to_bool(alerts))
return self._send_xml_command(cmd)
def get_filters(
self,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
trash: Optional[bool] = None,
alerts: Optional[bool] = None,
) -> Any:
"""Request a list of filters
Arguments:
filter_string: Filter term to use for the query
filter_id: UUID of an existing filter to use for the query
trash: Whether to get the trashcan filters instead
alerts: Whether to include list of alerts that use the filter.
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_filters")
add_filter(cmd, filter_string, filter_id)
if trash is not None:
cmd.set_attribute("trash", to_bool(trash))
if alerts is not None:
cmd.set_attribute("alerts", to_bool(alerts))
return self._send_xml_command(cmd)
def get_alerts(
self,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
trash: Optional[bool] = None,
tasks: Optional[bool] = None,
) -> Any:
"""Request a list of alerts
Arguments:
filter: Filter term to use for the query
filter_id: UUID of an existing filter to use for the query
trash: True to request the alerts in the trashcan
tasks: Whether to include the tasks using the alerts
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_alerts")
add_filter(cmd, filter_string, filter_id)
if trash is not None:
cmd.set_attribute("trash", to_bool(trash))
if tasks is not None:
cmd.set_attribute("tasks", to_bool(tasks))
return self._send_xml_command(cmd)
def modify_operating_system(self,
operating_system_id: str,
*,
comment: Optional[str] = None) -> Any:
"""Modifies an existing operating system.
Arguments:
operating_system_id: UUID of the operating_system to be modified.
comment: Comment for the operating_system. Not passing a comment
arguments clears the comment for this operating system.
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not operating_system_id:
raise RequiredArgument(
function=self.modify_operating_system.__name__,
argument="operating_system_id",
)
cmd = XmlCommand("modify_asset")
cmd.set_attribute("asset_id", operating_system_id)
if not comment:
comment = ""
cmd.add_element("comment", comment)
return self._send_xml_command(cmd)
def __create_config_from_osp_scanner(
self,
scanner_id: str,
name: str,
usage_type: UsageType,
function: str,
*,
comment: Optional[str] = None
) -> Any:
if not name:
raise RequiredArgument(function=function, argument='name')
if not scanner_id:
raise RequiredArgument(function=function, argument='scanner_id')
cmd = XmlCommand("create_config")
if comment is not None:
cmd.add_element("comment", comment)
cmd.add_element("scanner", scanner_id)
cmd.add_element("name", name)
cmd.add_element("usage_type", usage_type.value)
return self._send_xml_command(cmd)
def get_nvt_preferences(
self,
*,
nvt_oid: Optional[str] = None,
) -> Any:
"""Request a list of preferences
The preference element includes just the
name and value, with the NVT and type built into the name.
Arguments:
nvt_oid: OID of nvt
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_preferences")
if nvt_oid:
cmd.set_attribute("nvt_oid", nvt_oid)
return self._send_xml_command(cmd)
def determine_remote_gmp_version(self) -> str:
"""Determine the supported GMP version of the remote daemon"""
self.connect()
resp = self._send_xml_command(XmlCommand("get_version"))
self.disconnect()
version_el = resp.find('version')
if version_el is None:
raise GvmError(
'Invalid response from manager daemon while requesting the '
'version information.')
return version_el.text
def get_scan_config_nvt(self, nvt_oid: str):
"""Request a single nvt
Arguments:
nvt_oid: OID of an existing nvt
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_nvts")
if not nvt_oid:
raise RequiredArgument(function=self.get_scan_config_nvt.__name__,
argument="nvt_oid")
cmd.set_attribute("nvt_oid", nvt_oid)
# for single entity always request all details
cmd.set_attribute("details", "1")
cmd.set_attribute("preferences", "1")
cmd.set_attribute("preference_count", "1")
return self._send_xml_command(cmd)
def create_filter(
self,
name: str,
*,
filter_type: Optional[FilterType] = None,
comment: Optional[str] = None,
term: Optional[str] = None,
) -> Any:
"""Create a new filter
Arguments:
name: Name of the new filter
filter_type: Filter for entity type
comment: Comment for the filter
term: Filter term e.g. 'name=foo'
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not name:
raise RequiredArgument(
function=self.create_filter.__name__, argument="name"
)
cmd = XmlCommand("create_filter")
_xmlname = cmd.add_element("name", name)
if comment:
cmd.add_element("comment", comment)
if term:
cmd.add_element("term", term)
if filter_type:
if not isinstance(filter_type, FilterType):
raise InvalidArgumentType(
function=self.create_filter.__name__,
argument="filter_type",
arg_type=FilterType.__name__,
)
cmd.add_element("type", filter_type.value)
return self._send_xml_command(cmd)
def create_tls_certificate(self,
name: str,
certificate: str,
*,
comment: Optional[str] = None,
trust: Optional[bool] = None) -> Any:
"""Create a new TLS certificate
Arguments:
name: Name of the TLS certificate, defaulting to the MD5
fingerprint.
certificate: The Base64 encoded certificate data (x.509 DER or PEM).
comment: Comment for the TLS certificate.
trust: Whether the certificate is trusted.
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not name:
raise RequiredArgument(
function=self.create_tls_certificate.__name__, argument='name')
if not certificate:
raise RequiredArgument(
function=self.create_tls_certificate.__name__,
argument='certificate',
)
cmd = XmlCommand("create_tls_certificate")
if comment:
cmd.add_element("comment", comment)
cmd.add_element("name", name)
cmd.add_element("certificate", certificate)
if trust:
cmd.add_element("trust", _to_bool(trust))
return self._send_xml_command(cmd)
def modify_tls_certificate(
self,
tls_certificate_id: str,
*,
name: Optional[str] = None,
comment: Optional[str] = None,
trust: Optional[bool] = None
) -> Any:
"""Modifies an existing TLS certificate.
Arguments:
tls_certificate_id: UUID of the TLS certificate to be modified.
name: Name of the TLS certificate, defaulting to the MD5 fingerprint
comment: Comment for the TLS certificate.
trust: Whether the certificate is trusted.
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not tls_certificate_id:
raise RequiredArgument(
function=self.modify_tls_certificate.__name__,
argument='tls_certificate_id',
)
cmd = XmlCommand("modify_tls_certificate")
cmd.set_attribute("tls_certificate_id", str(tls_certificate_id))
if comment:
cmd.add_element("comment", comment)
if name:
cmd.add_element("name", name)
if trust:
cmd.add_element("trust", _to_bool(trust))
return self._send_xml_command(cmd)
def create_scan_config_from_osp_scanner(self,
scanner_id: str,
name: str,
*,
comment: Optional[str] = None
) -> Any:
"""Create a new scan config from an ospd scanner.
Create config by retrieving the expected preferences from the given
scanner via OSP.
Arguments:
scanner_id: UUID of an OSP scanner to get config data from
name: Name of the new scan config
comment: A comment on the config
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not name:
raise RequiredArgument(
function=self.create_scan_config_from_osp_scanner.__name__,
argument="name",
)
if not scanner_id:
raise RequiredArgument(
function=self.create_scan_config_from_osp_scanner.__name__,
argument="scanner_id",
)
cmd = XmlCommand("create_config")
if comment is not None:
cmd.add_element("comment", comment)
cmd.add_element("scanner", scanner_id)
cmd.add_element("name", name)
cmd.add_element("usage_type", "scan")
return self._send_xml_command(cmd)
def delete_user(
self,
user_id: str = None,
*,
name: Optional[str] = None,
inheritor_id: Optional[str] = None,
inheritor_name: Optional[str] = None,
) -> Any:
"""Deletes an existing user
Either user_id or name must be passed.
Arguments:
user_id: UUID of the task to be deleted.
name: The name of the user to be deleted.
inheritor_id: The ID of the inheriting user or "self". Overrides
inheritor_name.
inheritor_name: The name of the inheriting user.
"""
if not user_id and not name:
raise RequiredArgument(function=self.delete_user.__name__,
argument="user_id or name")
cmd = XmlCommand("delete_user")
if user_id:
cmd.set_attribute("user_id", user_id)
if name:
cmd.set_attribute("name", name)
if inheritor_id:
cmd.set_attribute("inheritor_id", inheritor_id)
if inheritor_name:
cmd.set_attribute("inheritor_name", inheritor_name)
return self._send_xml_command(cmd)
def get_tickets(self,
*,
trash: Optional[bool] = None,
filter: Optional[str] = None,
filter_id: Optional[str] = None) -> Any:
"""Request a list of tickets
Arguments:
filter: Filter term to use for the query
filter_id: UUID of an existing filter to use for the query
trash: True to request the tickets in the trashcan
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_tickets")
_add_filter(cmd, filter, filter_id)
if trash is not None:
cmd.set_attribute("trash", _to_bool(trash))
return self._send_xml_command(cmd)
def modify_scan_config_set_scanner_preference(self,
config_id: str,
name: str,
*,
value: Optional[str] = None
) -> Any:
"""Modifies the scanner preferences of an existing scan config
Arguments:
config_id: UUID of scan config to modify.
name: Name of the scanner preference to change
value: New value for the preference. None to delete the preference
and to use the default instead.
"""
if not config_id:
raise RequiredArgument(
function=(
self.modify_scan_config_set_scanner_preference.__name__),
argument="config_id",
)
if not name:
raise RequiredArgument(
function=(
self.modify_scan_config_set_scanner_preference.__name__),
argument="name argument",
)
cmd = XmlCommand("modify_config")
cmd.set_attribute("config_id", str(config_id))
_xmlpref = cmd.add_element("preference")
_xmlpref.add_element("name", name)
if value:
_xmlpref.add_element("value", to_base64(value))
return self._send_xml_command(cmd)