def test_xml_escaping(self):
cmd = XmlCommand('foo')
cmd.add_element('bar', 'Foo & Bar')
self.assertEqual(cmd.to_string(), '<foo><bar>Foo & Bar</bar></foo>')
cmd = XmlCommand('foo')
cmd.set_attribute('bar', 'Foo & Bar')
self.assertEqual(cmd.to_string(), '<foo bar="Foo & Bar"/>')
cmd = XmlCommand('foo')
cmd.set_attribute('bar', 'Foo "Bar"')
self.assertEqual(cmd.to_string(), '<foo bar="Foo "Bar""/>')
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 get_roles(
self,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
trash: Optional[bool] = None,
) -> Any:
"""Request a list of roles
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 roles instead
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_roles")
add_filter(cmd, filter_string, filter_id)
if trash is not None:
cmd.set_attribute("trash", to_bool(trash))
return self._send_xml_command(cmd)
def get_scans(self, scan_id=None, details=True, pop_results=False):
"""Get the stored scans.
Arguments:
scan_id (str, optional): UUID identifier for a scan.
details (boolean, optional): Whether to get full scan reports.
Default: True
pop_results (boolean, optional) Whether to remove the fetched
results. Default: False
Returns:
str: Response from server.
"""
cmd = XmlCommand("get_scans")
if scan_id:
cmd.set_attribute("scan_id", scan_id)
if details:
cmd.set_attribute("details", "1")
else:
cmd.set_attribute("details", "0")
if pop_results:
cmd.set_attribute("pop_results", "1")
else:
cmd.set_attribute("pop_results", "0")
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) -> 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 include_certificate_data is not None:
cmd.set_attribute("include_certificate_data",
_to_bool(include_certificate_data))
return self._send_xml_command(cmd)
def create_scan_config(self,
config_id: str,
name: str,
*,
comment: Optional[str] = None) -> Any:
"""Create a new scan config
Arguments:
config_id: UUID of the existing scan config
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.__name__,
argument="name")
if not config_id:
raise RequiredArgument(function=self.create_scan_config.__name__,
argument="config_id")
cmd = XmlCommand("create_config")
if comment is not None:
cmd.add_element("comment", comment)
cmd.add_element("copy", config_id)
cmd.add_element("name", name)
cmd.add_element("usage_type", "scan")
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_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_tls_certificate(self, tls_certificate_id: str) -> Any:
"""Request a single TLS certificate
Arguments:
tls_certificate_id: UUID of an existing TLS certificate
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_tls_certificates")
if not tls_certificate_id:
raise RequiredArgument(
function=self.get_tls_certificate.__name__,
argument='tls_certificate_id',
)
cmd.set_attribute("tls_certificate_id", tls_certificate_id)
# for single tls certificate always request cert data
cmd.set_attribute("include_certificate_data", "1")
# for single entity always request all details
cmd.set_attribute("details", "1")
return self._send_xml_command(cmd)
def __get_tasks(
self,
usage_type: UsageType,
*,
filter: Optional[str] = None,
filter_id: Optional[str] = None,
trash: Optional[bool] = None,
details: Optional[bool] = None,
schedules_only: Optional[bool] = None
) -> Any:
cmd = XmlCommand("get_tasks")
cmd.set_attribute("usage_type", usage_type.value)
_add_filter(cmd, filter, 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))
if schedules_only is not None:
cmd.set_attribute("schedules_only", _to_bool(schedules_only))
return self._send_xml_command(cmd)
def __enter__(self):
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.'
)
version = version_el.text
major_version = int(version[0])
if major_version == 7:
gmp_class = Gmpv7
elif major_version == 8:
gmp_class = Gmpv8
elif major_version >= 9:
gmp_class = Gmpv9
else:
raise GvmError(
'Remote manager daemon uses an unsupported version of GMP. '
'The GMP version was {}.'.format(version)
)
gmp = gmp_class(self._connection, transform=self._gmp_transform)
gmp.connect()
return gmp
def modify_ticket(
self,
ticket_id: str,
*,
status: Optional[TicketStatus] = None,
note: Optional[str] = None,
assigned_to_user_id: Optional[str] = None,
comment: Optional[str] = None
) -> Any:
"""Modify a single ticket
Arguments:
ticket_id: UUID of an existing ticket
status: New status for the ticket
note: Note for the status change. Required if status is set.
assigned_to_user_id: UUID of the user the ticket should be assigned
to
comment: Comment for the ticket
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not ticket_id:
raise RequiredArgument(
function=self.modify_ticket.__name__, argument='ticket_id'
)
if status and not note:
raise RequiredArgument(
function=self.modify_ticket.__name__, argument='note',
)
if note and not status:
raise RequiredArgument(
function=self.modify_ticket.__name__, argument='status',
)
cmd = XmlCommand("modify_ticket")
cmd.set_attribute("ticket_id", ticket_id)
if assigned_to_user_id:
_assigned = cmd.add_element("assigned_to")
_user = _assigned.add_element("user")
_user.set_attribute("id", assigned_to_user_id)
if status:
if not isinstance(status, TicketStatus):
raise InvalidArgumentType(
function=self.modify_ticket.__name__,
argument='status',
arg_type=TicketStatus.__name__,
)
cmd.add_element('status', status.value)
cmd.add_element('{}_note'.format(status.name.lower()), note)
if comment:
cmd.add_element("comment", comment)
return self._send_xml_command(cmd)
def test_add_filter_id(self):
cmd = XmlCommand("test")
filter_id = "foo"
add_filter(cmd, filter_string=None, filter_id=filter_id)
self.assertEqual(cmd.to_string(), '<test filt_id="foo"/>')
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 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_policy(self,
policy_id: str,
*,
audits: Optional[bool] = None) -> Any:
"""Request a single policy
Arguments:
policy_id: UUID of an existing policy
audits: Whether to get audits using this policy
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not policy_id:
raise RequiredArgument(function=self.get_policy.__name__,
argument="policy_id")
cmd = XmlCommand("get_configs")
cmd.set_attribute("config_id", policy_id)
cmd.set_attribute("usage_type", "policy")
if audits is not None:
cmd.set_attribute("tasks", to_bool(audits))
# for single entity always request all details
cmd.set_attribute("details", "1")
return self._send_xml_command(cmd)
def get_scan_config(self,
config_id: str,
*,
tasks: Optional[bool] = None) -> Any:
"""Request a single scan config
Arguments:
config_id: UUID of an existing scan config
tasks: Whether to get tasks using this config
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not config_id:
raise RequiredArgument(function=self.get_scan_config.__name__,
argument="config_id")
cmd = XmlCommand("get_configs")
cmd.set_attribute("config_id", config_id)
cmd.set_attribute("usage_type", "scan")
if tasks is not None:
cmd.set_attribute("tasks", to_bool(tasks))
# for single entity always request all details
cmd.set_attribute("details", "1")
return self._send_xml_command(cmd)
def modify_policy_set_family_selection(
self,
policy_id: str,
families: List[Tuple[str, bool, bool]],
*,
auto_add_new_families: Optional[bool] = True,
) -> Any:
"""
Selected the NVTs of a policy at a family level.
Arguments:
policy_id: UUID of policy to modify.
families: A list of tuples with the first entry being the name
of the NVT family selected, second entry a boolean indicating
whether new NVTs should be added to the family automatically,
and third entry a boolean indicating whether all nvts from
the family should be included.
auto_add_new_families: Whether new families should be added to the
policy automatically. Default: True.
"""
if not policy_id:
raise RequiredArgument(
function=self.modify_policy_set_family_selection.__name__,
argument="policy_id",
)
if not is_list_like(families):
raise InvalidArgumentType(
function=self.modify_policy_set_family_selection.__name__,
argument="families",
arg_type="list",
)
cmd = XmlCommand("modify_config")
cmd.set_attribute("config_id", str(policy_id))
_xmlfamsel = cmd.add_element("family_selection")
_xmlfamsel.add_element("growing", to_bool(auto_add_new_families))
for family in families:
_xmlfamily = _xmlfamsel.add_element("family")
_xmlfamily.add_element("name", family[0])
if len(family) != 3:
raise InvalidArgument(
"Family must be a tuple of 3. (str, bool, bool)")
if not isinstance(family[1], bool) or not isinstance(
family[2], bool):
raise InvalidArgumentType(
function=(
self.modify_policy_set_family_selection.__name__),
argument="families",
arg_type="[tuple(str, bool, bool)]",
)
_xmlfamily.add_element("all", to_bool(family[2]))
_xmlfamily.add_element("growing", to_bool(family[1]))
return self._send_xml_command(cmd)
def get_scan_config_preference(
self,
name: str,
*,
nvt_oid: Optional[str] = None,
config_id: 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_scan_config_preference.__name__,
argument="name",
)
cmd.set_attribute("preference", name)
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 create_policy(self,
name: str,
*,
policy_id: str = None,
comment: Optional[str] = None) -> Any:
"""Create a new policy
Arguments:
name: Name of the new policy
policy_id: UUID of an existing policy as base. By default the empty
policy is used.
comment: A comment on the policy
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("create_config")
if policy_id is None:
policy_id = _EMPTY_POLICY_ID
if not name:
raise RequiredArgument(function=self.create_policy.__name__,
argument="name")
if comment is not None:
cmd.add_element("comment", comment)
cmd.add_element("copy", policy_id)
cmd.add_element("name", name)
cmd.add_element("usage_type", "policy")
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_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 sync_scan_config(self) -> Any:
"""Request an OSP config synchronization with scanner
Returns:
The response. See :py:meth:`send_command` for details.
"""
return self._send_xml_command(XmlCommand("sync_config"))
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_configs(self,
usage_type: UsageType,
*,
filter: Optional[str] = None,
filter_id: Optional[str] = None,
trash: Optional[bool] = None,
details: Optional[bool] = None,
families: Optional[bool] = None,
preferences: Optional[bool] = None,
tasks: Optional[bool] = None) -> Any:
cmd = XmlCommand("get_configs")
cmd.set_attribute("usage_type", usage_type.value)
_add_filter(cmd, filter, 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))
if families is not None:
cmd.set_attribute("families", _to_bool(families))
if preferences is not None:
cmd.set_attribute("preferences", _to_bool(preferences))
if tasks is not None:
cmd.set_attribute("tasks", _to_bool(tasks))
return self._send_xml_command(cmd)
def create_container_task(self,
name: str,
*,
comment: Optional[str] = None) -> Any:
"""Create a new container task
A container task is a "meta" task to import and view reports from other
systems.
Arguments:
name: Name of the task
comment: Comment for the task
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not name:
raise RequiredArgument(
function=self.create_container_task.__name__, argument="name")
cmd = XmlCommand("create_task")
cmd.add_element("name", name)
cmd.add_element("target", attrs={"id": "0"})
if comment:
cmd.add_element("comment", comment)
return self._send_xml_command(cmd)
def create_role(
self,
name: str,
*,
comment: Optional[str] = None,
users: Optional[List[str]] = None,
) -> Any:
"""Create a new role
Arguments:
name: Name of the role
comment: Comment for the role
users: List of user names to add to the role
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not name:
raise RequiredArgument(function=self.create_role.__name__,
argument="name")
cmd = XmlCommand("create_role")
cmd.add_element("name", name)
if comment:
cmd.add_element("comment", comment)
if users:
cmd.add_element("users", to_comma_list(users))
return self._send_xml_command(cmd)
def get_info(self, info_id: str, info_type: InfoType) -> Any:
"""Request a single secinfo
Arguments:
info_id: UUID of an existing secinfo
info_type: Type must be either CERT_BUND_ADV, CPE, CVE,
DFN_CERT_ADV, OVALDEF, NVT
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not info_type:
raise RequiredArgument(function=self.get_info.__name__,
argument='info_type')
if not isinstance(info_type, InfoType):
raise InvalidArgumentType(
function=self.get_info.__name__,
argument='info_type',
arg_type=InfoType.__name__,
)
if not info_id:
raise RequiredArgument(function=self.get_info.__name__,
argument='info_id')
cmd = XmlCommand("get_info")
cmd.set_attribute("info_id", info_id)
cmd.set_attribute("type", info_type.value)
# for single entity always request all details
cmd.set_attribute("details", "1")
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 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)
