def test_raise_with_argument_and_function(self):
with self.assertRaises(RequiredArgument) as cm:
raise RequiredArgument(argument='foo', function='bar')
ex = cm.exception
self.assertEqual(ex.argument, 'foo')
self.assertEqual(ex.function, 'bar')
def test_raise_with_function(self):
with self.assertRaises(RequiredArgument) as cm:
raise RequiredArgument(function='foo')
ex = cm.exception
self.assertEqual(ex.function, 'foo')
self.assertIsNone(ex.argument)
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 modify_scan_config_set_family_selection(
self,
config_id: str,
families: List[Tuple[str, bool, bool]],
*,
auto_add_new_families: Optional[bool] = True,
) -> Any:
"""
Selected the NVTs of a scan config at a family level.
Arguments:
config_id: UUID of scan config to modify.
families: A list of tuples (str, bool, bool):
str: the name of the NVT family selected,
bool: add new NVTs to the family automatically,
bool: include all NVTs from the family
auto_add_new_families: Whether new families should be added to the
scan config automatically. Default: True.
"""
if not config_id:
raise RequiredArgument(
function=self.modify_scan_config_set_family_selection.__name__,
argument="config_id",
)
if not is_list_like(families):
raise InvalidArgumentType(
function=self.modify_scan_config_set_family_selection.__name__,
argument="families",
arg_type="list",
)
cmd = XmlCommand("modify_config")
cmd.set_attribute("config_id", str(config_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_scan_config_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 create_ticket(self,
*,
result_id: str,
assigned_to_user_id: str,
note: str,
comment: Optional[str] = None) -> Any:
"""Create a new ticket
Arguments:
result_id: UUID of the result the ticket applies to
assigned_to_user_id: UUID of a user the ticket should be assigned to
note: A note about opening the ticket
comment: Comment for the ticket
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not result_id:
raise RequiredArgument(function=self.create_ticket.__name__,
argument='result_id')
if not assigned_to_user_id:
raise RequiredArgument(
function=self.create_ticket.__name__,
argument='assigned_to_user_id',
)
if not note:
raise RequiredArgument(function=self.create_ticket.__name__,
argument='note')
cmd = XmlCommand("create_ticket")
_result = cmd.add_element("result")
_result.set_attribute("id", result_id)
_assigned = cmd.add_element("assigned_to")
_user = _assigned.add_element("user")
_user.set_attribute("id", assigned_to_user_id)
_note = cmd.add_element("open_note", note)
if comment:
cmd.add_element("comment", comment)
return self._send_xml_command(cmd)
def create_user(
self,
name: str,
*,
password: Optional[str] = None,
hosts: Optional[List[str]] = None,
hosts_allow: Optional[bool] = False,
ifaces: Any = None,
ifaces_allow: Any = None,
role_ids: Optional[List[str]] = None,
) -> Any:
"""Create a new user
Arguments:
name: Name of the user
password: Password of the user
hosts: A list of host addresses (IPs, DNS names)
hosts_allow: If True allow only access to passed hosts otherwise
deny access. Default is False for deny hosts.
ifaces: deprecated
ifaces_allow: deprecated
role_ids: A list of role UUIDs for the user
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not name:
raise RequiredArgument(function=self.create_user.__name__,
argument="name")
cmd = XmlCommand("create_user")
cmd.add_element("name", name)
if password:
cmd.add_element("password", password)
if hosts:
cmd.add_element(
"hosts",
to_comma_list(hosts),
attrs={"allow": to_bool(hosts_allow)},
)
if ifaces is not None:
major, minor = self.get_protocol_version()
deprecation("The ifaces parameter has been removed in GMP"
f" version {major}{minor}")
if ifaces_allow is not None:
major, minor = self.get_protocol_version()
deprecation("The ifaces_allow parameter has been removed in GMP"
f" version {major}{minor}")
if role_ids:
for role in role_ids:
cmd.add_element("role", attrs={"id": role})
return self._send_xml_command(cmd)
def test_message_precedence(self):
with self.assertRaisesRegex(RequiredArgument, "^foo bar$") as cm:
raise RequiredArgument("foo bar", argument="foo", function="bar")
ex = cm.exception
self.assertEqual(ex.argument, "foo")
self.assertEqual(ex.function, "bar")
self.assertEqual(str(ex), "foo bar")
def test_message_precedence(self):
with self.assertRaisesRegex(RequiredArgument, '^foo bar$') as cm:
raise RequiredArgument('foo bar', argument='foo', function='bar')
ex = cm.exception
self.assertEqual(ex.argument, 'foo')
self.assertEqual(ex.function, 'bar')
self.assertEqual(str(ex), 'foo bar')
def create_user(
self,
name: str,
*,
password: Optional[str] = None,
hosts: Optional[List[str]] = None,
hosts_allow: Optional[bool] = False,
ifaces: Optional[List[str]] = None,
ifaces_allow: Optional[bool] = False,
role_ids: Optional[List[str]] = None,
) -> Any:
"""Create a new user
Arguments:
name: Name of the user
password: Password of the user
hosts: A list of host addresses (IPs, DNS names)
hosts_allow: If True allow only access to passed hosts otherwise
deny access. Default is False for deny hosts.
ifaces: A list of interface names
ifaces_allow: If True allow only access to passed interfaces
otherwise deny access. Default is False for deny interfaces.
role_ids: A list of role UUIDs for the user
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not name:
raise RequiredArgument(function=self.create_user.__name__,
argument="name")
cmd = XmlCommand("create_user")
cmd.add_element("name", name)
if password:
cmd.add_element("password", password)
if hosts:
cmd.add_element(
"hosts",
to_comma_list(hosts),
attrs={"allow": to_bool(hosts_allow)},
)
if ifaces:
cmd.add_element(
"ifaces",
to_comma_list(ifaces),
attrs={"allow": to_bool(ifaces_allow)},
)
if role_ids:
for role in role_ids:
cmd.add_element("role", attrs={"id": role})
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_scan_config_set_nvt_selection(self, config_id: str, family: str,
nvt_oids: List[str]) -> Any:
"""Modifies the selected nvts of an existing scan config
The manager updates the given family in the config to include only the
given NVTs.
Arguments:
config_id: UUID of scan config to modify.
family: Name of the NVT family to include NVTs from
nvt_oids: List of NVTs to select for the family.
"""
if not config_id:
raise RequiredArgument(
function=self.modify_scan_config_set_nvt_selection.__name__,
argument="config_id",
)
if not family:
raise RequiredArgument(
function=self.modify_scan_config_set_nvt_selection.__name__,
argument="family argument",
)
if not is_list_like(nvt_oids):
raise InvalidArgumentType(
function=self.modify_scan_config_set_nvt_selection.__name__,
argument="nvt_oids",
arg_type="list",
)
cmd = XmlCommand("modify_config")
cmd.set_attribute("config_id", str(config_id))
_xmlnvtsel = cmd.add_element("nvt_selection")
_xmlnvtsel.add_element("family", family)
for nvt in nvt_oids:
_xmlnvtsel.add_element("nvt", attrs={"oid": nvt})
return self._send_xml_command(cmd)
def get_report(
self,
report_id: str,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
delta_report_id: Optional[str] = None,
report_format_id: Optional[Union[str, ReportFormatType]] = None,
ignore_pagination: Optional[bool] = None,
details: Optional[bool] = True,
) -> Any:
"""Request a single report
Arguments:
report_id: UUID of an existing report
filter_string: Filter term to use to filter results in the report
filter_id: UUID of filter to use to filter results in the report
delta_report_id: UUID of an existing report to compare report to.
report_format_id: UUID of report format to use
or ReportFormatType (enum)
ignore_pagination: Whether to ignore the filter terms "first" and
"rows".
details: Request additional report information details
defaults to True
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_reports")
if not report_id:
raise RequiredArgument(function=self.get_report.__name__,
argument="report_id")
cmd.set_attribute("report_id", report_id)
add_filter(cmd, filter_string, filter_id)
if delta_report_id:
cmd.set_attribute("delta_report_id", delta_report_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 ignore_pagination is not None:
cmd.set_attribute("ignore_pagination", to_bool(ignore_pagination))
cmd.set_attribute("details", to_bool(details))
return self._send_xml_command(cmd)
def __get_task(self, task_id: str, usage_type: UsageType) -> Any:
if not task_id:
raise RequiredArgument(function=self.get_task.__name__,
argument='task_id')
cmd = XmlCommand("get_tasks")
cmd.set_attribute("task_id", task_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 import_report(
self,
report: str,
*,
task_id: Optional[str] = None,
in_assets: Optional[bool] = None,
) -> Any:
"""Import a Report from XML
Arguments:
report: Report XML as string to import. This XML must contain
a :code:`<report>` root element.
task_id: UUID of task to import report to
in_asset: Whether to create or update assets using the report
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not report:
raise RequiredArgument(function=self.import_report.__name__,
argument="report")
cmd = XmlCommand("create_report")
if task_id:
cmd.add_element("task", attrs={"id": task_id})
else:
raise RequiredArgument(function=self.import_report.__name__,
argument="task_id")
if in_assets is not None:
cmd.add_element("in_assets", to_bool(in_assets))
try:
cmd.append_xml_str(report)
except XMLSyntaxError as e:
raise InvalidArgument(
f"Invalid xml passed as report to import_report {e}") from None
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 modify_user_setting(
self,
setting_id: Optional[str] = None,
name: Optional[str] = None,
value: Optional[str] = None,
) -> Any:
"""Modifies an existing user setting.
Arguments:
setting_id: UUID of the setting to be changed.
name: The name of the setting. Either setting_id or name must be
passed.
value: The value of the setting.
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not setting_id and not name:
raise RequiredArgument(
function=self.modify_user_setting.__name__,
argument="setting_id or name argument",
)
if value is None:
raise RequiredArgument(
function=self.modify_user_setting.__name__,
argument="value argument",
)
cmd = XmlCommand("modify_setting")
if setting_id:
cmd.set_attribute("setting_id", setting_id)
else:
cmd.add_element("name", name)
cmd.add_element("value", to_base64(value))
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_report(self, report_id: str) -> Any:
"""Deletes an existing report
Arguments:
report_id: UUID of the report to be deleted.
"""
if not report_id:
raise RequiredArgument(function=self.delete_report.__name__,
argument="report_id")
cmd = XmlCommand("delete_report")
cmd.set_attribute("report_id", report_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 test_string_conversion(self):
with self.assertRaises(RequiredArgument) as cm:
raise RequiredArgument("foo bar")
ex = cm.exception
self.assertEqual(str(ex), "foo bar")
with self.assertRaises(RequiredArgument) as cm:
raise RequiredArgument(argument="foo")
ex = cm.exception
self.assertEqual(str(ex), "Required argument foo")
with self.assertRaises(RequiredArgument) as cm:
raise RequiredArgument(function="foo")
ex = cm.exception
self.assertEqual(str(ex), "Required argument missing for foo")
with self.assertRaises(RequiredArgument) as cm:
raise RequiredArgument(argument="foo", function="bar")
ex = cm.exception
self.assertEqual(str(ex), "bar requires a foo argument")
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 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="get_ticket", argument="ticket_id")
cmd = XmlCommand("get_tickets")
cmd.set_attribute("ticket_id", ticket_id)
return self._send_xml_command(cmd)
def test_string_conversion(self):
with self.assertRaises(RequiredArgument) as cm:
raise RequiredArgument('foo bar')
ex = cm.exception
self.assertEqual(str(ex), 'foo bar')
with self.assertRaises(RequiredArgument) as cm:
raise RequiredArgument(argument='foo')
ex = cm.exception
self.assertEqual(str(ex), 'Required argument foo')
with self.assertRaises(RequiredArgument) as cm:
raise RequiredArgument(function='foo')
ex = cm.exception
self.assertEqual(str(ex), 'Required argument missing for foo')
with self.assertRaises(RequiredArgument) as cm:
raise RequiredArgument(argument='foo', function='bar')
ex = cm.exception
self.assertEqual(str(ex), 'bar requires a foo argument')
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 clone_role(self, role_id: str) -> Any:
"""Clone an existing role
Arguments:
role_id: UUID of an existing role to clone from
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not role_id:
raise RequiredArgument(function=self.clone_role.__name__,
argument="role_id")
cmd = XmlCommand("create_role")
cmd.add_element("copy", role_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 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 clone_policy(self, policy_id: str) -> Any:
"""Clone a policy from an existing one
Arguments:
policy_id: UUID of the existing policy
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not policy_id:
raise RequiredArgument(function=self.clone_policy.__name__,
argument='policy_id')
cmd = XmlCommand("create_config")
cmd.add_element("copy", policy_id)
return self._send_xml_command(cmd)
def clone_audit(self, audit_id: str) -> Any:
"""Clone an existing audit
Arguments:
audit_id: UUID of existing audit to clone from
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not audit_id:
raise RequiredArgument(function=self.clone_audit.__name__,
argument='audit_id')
cmd = XmlCommand("create_task")
cmd.add_element("copy", audit_id)
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)
