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_vts(self, vt_id=None):
"""Return information about vulnerability tests,
if offered by scanner.
Arguments:
vt_id (str, optional): UUID identifier for a vulnerability test.
Returns:
str: Response from server.
"""
cmd = XmlCommand("get_vts")
if vt_id:
cmd.set_attribute("vt_id", vt_id)
return self._send_xml_command(cmd)
def delete_scan(self, scan_id=None):
"""Delete a finished scan.
Arguments:
scan_id (str): UUID identifier for a finished scan.
Returns:
str: Response from server.
"""
if not scan_id:
raise ValueError("delete_scan requires a scan_id element")
cmd = XmlCommand("delete_scan")
cmd.set_attribute("scan_id", scan_id)
return self._send_xml_command(cmd)
def modify_schedule(
self,
schedule_id: str,
*,
name: Optional[str] = None,
icalendar: Optional[str] = None,
timezone: Optional[str] = None,
comment: Optional[str] = None,
) -> Any:
"""Modifies an existing schedule
Arguments:
schedule_id: UUID of the schedule to be modified
name: Name of the schedule
icalendar: `iCalendar`_ (RFC 5545) based data.
timezone: Timezone to use for the icalender events e.g
Europe/Berlin. If the datetime values in the icalendar data are
missing timezone information this timezone gets applied.
Otherwise the datetime values from the icalendar data are
displayed in this timezone
commenhedule.
Returns:
The response. See :py:meth:`send_command` for details.
.. _iCalendar:
https://tools.ietf.org/html/rfc5545
"""
if not schedule_id:
raise RequiredArgument(function=self.modify_schedule.__name__,
argument='schedule_id')
cmd = XmlCommand("modify_schedule")
cmd.set_attribute("schedule_id", schedule_id)
if name:
cmd.add_element("name", name)
if icalendar:
cmd.add_element("icalendar", icalendar)
if timezone:
cmd.add_element("timezone", timezone)
if comment:
cmd.add_element("comment", comment)
return self._send_xml_command(cmd)
def modify_filter(
self,
filter_id: str,
*,
comment: Optional[str] = None,
name: Optional[str] = None,
term: Optional[str] = None,
filter_type: Optional[FilterType] = None,
) -> Any:
"""Modifies an existing filter.
Arguments:
filter_id: UUID of the filter to be modified
comment: Comment on filter.
name: Name of filter.
term: Filter term.
filter_type: Resource type filter applies to.
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not filter_id:
raise RequiredArgument(
function=self.modify_filter.__name__, argument="filter_id"
)
cmd = XmlCommand("modify_filter")
cmd.set_attribute("filter_id", filter_id)
if comment:
cmd.add_element("comment", comment)
if name:
cmd.add_element("name", name)
if term:
cmd.add_element("term", term)
if filter_type:
if not isinstance(filter_type, FilterType):
raise InvalidArgumentType(
function=self.modify_filter.__name__,
argument="filter_type",
arg_type=FilterType.__name__,
)
cmd.add_element("type", filter_type.value)
return self._send_xml_command(cmd)
def delete_port_range(self, port_range_id: str) -> Any:
"""Deletes an existing port range
Arguments:
port_range_id: UUID of the port range to be deleted.
"""
if not port_range_id:
raise RequiredArgument(
function=self.delete_port_range.__name__,
argument="port_range_id",
)
cmd = XmlCommand("delete_port_range")
cmd.set_attribute("port_range_id", port_range_id)
return self._send_xml_command(cmd)
def get_ticket(self, ticket_id: str) -> Any:
"""Request a single ticket
Arguments:
ticket_id: UUID of an existing ticket
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not ticket_id:
raise RequiredArgument(function=self.get_ticket.__name__,
argument='ticket_id')
cmd = XmlCommand("get_tickets")
cmd.set_attribute("ticket_id", ticket_id)
return self._send_xml_command(cmd)
def delete_host(self, host_id: str) -> Any:
"""Deletes an existing host
Arguments:
host_id: UUID of the single host to delete.
"""
if not host_id:
raise RequiredArgument(
function=self.delete_host.__name__,
argument="host_id",
)
cmd = XmlCommand("delete_asset")
cmd.set_attribute("asset_id", host_id)
return self._send_xml_command(cmd)
def stop_scan(self, scan_id):
"""Stop a currently running scan.
Args:
scan_id (str): UUID identifier for a running scan.
Returns:
str: Response from server.
"""
if not scan_id:
raise RequiredArgument("stop_scan requires a scan_id argument")
cmd = XmlCommand("stop_scan")
cmd.set_attribute("scan_id", scan_id)
return self._send_xml_command(cmd)
def delete_tls_certificate(self, tls_certificate_id: str) -> Any:
"""Deletes an existing tls certificate
Arguments:
tls_certificate_id: UUID of the tls certificate to be deleted.
"""
if not tls_certificate_id:
raise RequiredArgument(
function=self.delete_tls_certificate.__name__,
argument="tls_certificate_id",
)
cmd = XmlCommand("delete_tls_certificate")
cmd.set_attribute("tls_certificate_id", tls_certificate_id)
return self._send_xml_command(cmd)
def get_role(self, role_id: str) -> Any:
"""Request a single role
Arguments:
role_id: UUID of an existing role
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not role_id:
raise RequiredArgument(function=self.get_role.__name__,
argument="role_id")
cmd = XmlCommand("get_roles")
cmd.set_attribute("role_id", role_id)
return self._send_xml_command(cmd)
def get_vulnerability(self, vulnerability_id: str) -> Any:
"""Request a single vulnerability
Arguments:
vulnerability_id: ID of an existing vulnerability
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not vulnerability_id:
raise RequiredArgument(function="get_vulnerability",
argument="vulnerability_id")
cmd = XmlCommand("get_vulns")
cmd.set_attribute("vuln_id", vulnerability_id)
return self._send_xml_command(cmd)
def modify_scan_config_set_nvt_preference(
self,
config_id: str,
name: str,
nvt_oid: str,
*,
value: Optional[str] = None,
) -> Any:
"""Modifies the nvt preferences of an existing scan config.
Arguments:
config_id: UUID of scan config to modify.
name: Name for nvt preference to change.
nvt_oid: OID of the NVT associated with preference to modify
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_nvt_preference.__name__,
argument="config_id",
)
if not nvt_oid:
raise RequiredArgument(
function=self.modify_scan_config_set_nvt_preference.__name__,
argument="nvt_oid",
)
if not name:
raise RequiredArgument(
function=self.modify_scan_config_set_nvt_preference.__name__,
argument="name",
)
cmd = XmlCommand("modify_config")
cmd.set_attribute("config_id", str(config_id))
_xmlpref = cmd.add_element("preference")
_xmlpref.add_element("nvt", attrs={"oid": nvt_oid})
_xmlpref.add_element("name", name)
if value:
_xmlpref.add_element("value", to_base64(value))
return self._send_xml_command(cmd)
def get_tag(self, tag_id: str) -> Any:
"""Request a single tag
Arguments:
tag_id: UUID of an existing tag
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_tags")
if not tag_id:
raise RequiredArgument(function=self.get_tag.__name__,
argument="tag_id")
cmd.set_attribute("tag_id", tag_id)
return self._send_xml_command(cmd)
def stop_task(self, task_id: str) -> Any:
"""Stop an existing running task
Arguments:
task_id: UUID of the task to be stopped
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not task_id:
raise RequiredArgument(function=self.stop_task.__name__,
argument="task_id")
cmd = XmlCommand("stop_task")
cmd.set_attribute("task_id", task_id)
return self._send_xml_command(cmd)
def get_group(self, group_id: str) -> Any:
"""Request a single group
Arguments:
group_id: UUID of an existing group
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_groups")
if not group_id:
raise RequiredArgument(function=self.get_group.__name__,
argument="group_id")
cmd.set_attribute("group_id", group_id)
return self._send_xml_command(cmd)
def start_audit(self, audit_id: str) -> Any:
"""Start an existing audit
Arguments:
audit_id: UUID of the audit to be started
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not audit_id:
raise RequiredArgument(function=self.start_audit.__name__,
argument="audit_id")
cmd = XmlCommand("start_task")
cmd.set_attribute("task_id", audit_id)
return self._send_xml_command(cmd)
def get_user(self, user_id: str) -> Any:
"""Request a single user
Arguments:
user_id: UUID of an existing user
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_users")
if not user_id:
raise RequiredArgument(function=self.get_user.__name__,
argument="user_id")
cmd.set_attribute("user_id", user_id)
return self._send_xml_command(cmd)
def trigger_alert(
self,
alert_id: str,
report_id: str,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
report_format_id: Optional[Union[str, ReportFormatType]] = None,
delta_report_id: Optional[str] = None,
) -> Any:
"""Run an alert by ignoring its event and conditions
The alert is triggered to run immediately with the provided filtered
report by ignoring the even and condition settings.
Arguments:
alert_id: UUID of the alert to be run
report_id: UUID of the report to be provided to the alert
filter: Filter term to use to filter results in the report
filter_id: UUID of filter to use to filter results in the report
report_format_id: UUID of report format to use
or ReportFormatType (enum)
delta_report_id: UUID of an existing report to compare report to.
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not alert_id:
raise RequiredArgument(
function=self.trigger_alert.__name__,
argument="alert_id argument",
)
if not report_id:
raise RequiredArgument(
function=self.trigger_alert.__name__,
argument="report_id argument",
)
cmd = XmlCommand("get_reports")
cmd.set_attribute("report_id", report_id)
cmd.set_attribute("alert_id", alert_id)
add_filter(cmd, filter_string, filter_id)
if report_format_id:
if isinstance(report_format_id, ReportFormatType):
report_format_id = report_format_id.value
cmd.set_attribute("format_id", report_format_id)
if delta_report_id:
cmd.set_attribute("delta_report_id", delta_report_id)
return self._send_xml_command(cmd)
def get_permission(self, permission_id: str) -> Any:
"""Request a single permission
Arguments:
permission_id: UUID of an existing permission
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_permissions")
if not permission_id:
raise RequiredArgument(
function=self.get_permission.__name__, argument="permission_id"
)
cmd.set_attribute("permission_id", permission_id)
return self._send_xml_command(cmd)
def test_alert(self, alert_id: str) -> Any:
"""Run an alert
Invoke a test run of an alert
Arguments:
alert_id: UUID of the alert to be tested
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not alert_id:
raise InvalidArgument("test_alert requires an alert_id argument")
cmd = XmlCommand("test_alert")
cmd.set_attribute("alert_id", alert_id)
return self._send_xml_command(cmd)
def delete_policy(self,
policy_id: str,
*,
ultimate: Optional[bool] = False) -> Any:
"""Deletes an existing policy
Arguments:
policy_id: UUID of the policy to be deleted.
ultimate: Whether to remove entirely, or to the trashcan.
"""
if not policy_id:
raise RequiredArgument(function=self.delete_policy.__name__,
argument="policy_id")
cmd = XmlCommand("delete_config")
cmd.set_attribute("config_id", policy_id)
cmd.set_attribute("ultimate", to_bool(ultimate))
return self._send_xml_command(cmd)
def restore_from_trashcan(self, entity_id: str) -> Any:
"""Restore an entity from the trashcan
Arguments:
entity_id: ID of the entity to be restored from the trashcan
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not entity_id:
raise RequiredArgument(
function=self.restore_from_trashcan.__name__,
argument="entity_id",
)
cmd = XmlCommand("restore")
cmd.set_attribute("id", entity_id)
return self._send_xml_command(cmd)
def delete_role(self,
role_id: str,
*,
ultimate: Optional[bool] = False) -> Any:
"""Deletes an existing role
Arguments:
role_id: UUID of the role to be deleted.
ultimate: Whether to remove entirely, or to the trashcan.
"""
if not role_id:
raise RequiredArgument(function=self.delete_role.__name__,
argument="role_id")
cmd = XmlCommand("delete_role")
cmd.set_attribute("role_id", role_id)
cmd.set_attribute("ultimate", to_bool(ultimate))
return self._send_xml_command(cmd)
def delete_ticket(self,
ticket_id: str,
*,
ultimate: Optional[bool] = False):
"""Deletes an existing ticket
Arguments:
ticket_id: UUID of the ticket to be deleted.
ultimate: Whether to remove entirely, or to the trashcan.
"""
if not ticket_id:
raise RequiredArgument(function=self.delete_ticket.__name__,
argument='ticket_id')
cmd = XmlCommand("delete_ticket")
cmd.set_attribute("ticket_id", ticket_id)
cmd.set_attribute("ultimate", _to_bool(ultimate))
return self._send_xml_command(cmd)
def delete_audit(self,
audit_id: str,
*,
ultimate: Optional[bool] = False) -> Any:
"""Deletes an existing audit
Arguments:
audit_id: UUID of the audit to be deleted.
ultimate: Whether to remove entirely, or to the trashcan.
"""
if not audit_id:
raise RequiredArgument(function=self.delete_audit.__name__,
argument="audit_id")
cmd = XmlCommand("delete_task")
cmd.set_attribute("task_id", audit_id)
cmd.set_attribute("ultimate", to_bool(ultimate))
return self._send_xml_command(cmd)
def get_host(self, host_id: str) -> Any:
"""Request a single host
Arguments:
host_id: UUID of an existing host
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_assets")
if not host_id:
raise RequiredArgument(function=self.get_host.__name__,
argument="host_id")
cmd.set_attribute("asset_id", host_id)
cmd.set_attribute("type", "host")
return self._send_xml_command(cmd)
def delete_operating_system(
self,
operating_system_id: str,
) -> Any:
"""Deletes an existing operating_system
Arguments:
operating_system_id: UUID of the single operating_system to delete.
"""
if not operating_system_id:
raise RequiredArgument(
function=self.delete_operating_system.__name__,
argument="operating_system_id",
)
cmd = XmlCommand("delete_asset")
cmd.set_attribute("asset_id", operating_system_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.
"""
if not tls_certificate_id:
raise RequiredArgument(
"get_tls_certificate requires tls_certificate_id argument"
)
cmd = XmlCommand("get_tls_certificates")
cmd.set_attribute("tls_certificate_id", tls_certificate_id)
# for single tls certificate always request cert data
cmd.set_attribute("include_certificate_data", "1")
return self._send_xml_command(cmd)
def get_note(self, note_id: str) -> Any:
"""Request a single note
Arguments:
note_id: UUID of an existing note
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not note_id:
raise RequiredArgument(
function=self.get_note.__name__, argument="note_id"
)
cmd = XmlCommand("get_notes")
cmd.set_attribute("note_id", note_id)
# for single entity always request all details
cmd.set_attribute("details", "1")
return self._send_xml_command(cmd)
