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 test_to_comma_list(self):
# pylint: disable=invalid-name
the_list = ['foo', 'bar', 'baz']
comma_string = to_comma_list(the_list)
self.assertEqual('foo,bar,baz', comma_string)
def test_to_comma_list(self):
# pylint: disable=invalid-name
the_list = ["foo", "bar", "baz"]
comma_string = to_comma_list(the_list)
self.assertEqual("foo,bar,baz", comma_string)
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 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 create_group(
self,
name: str,
*,
comment: Optional[str] = None,
special: Optional[bool] = False,
users: Optional[List[str]] = None,
) -> Any:
"""Create a new group
Arguments:
name: Name of the new group
comment: Comment for the group
special: Create permission giving members full access to each
other's entities
users: List of user names to be in the group
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not name:
raise RequiredArgument(function=self.create_group.__name__,
argument="name")
cmd = XmlCommand("create_group")
cmd.add_element("name", name)
if comment:
cmd.add_element("comment", comment)
if special:
_xmlspecial = cmd.add_element("specials")
_xmlspecial.add_element("full")
if users:
cmd.add_element("users", to_comma_list(users))
return self._send_xml_command(cmd)
def modify_group(
self,
group_id: str,
*,
comment: Optional[str] = None,
name: Optional[str] = None,
users: Optional[List[str]] = None,
) -> Any:
"""Modifies an existing group.
Arguments:
group_id: UUID of group to modify.
comment: Comment on group.
name: Name of group.
users: List of user names to be in the group
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not group_id:
raise RequiredArgument(function=self.modify_group.__name__,
argument="group_id")
cmd = XmlCommand("modify_group")
cmd.set_attribute("group_id", group_id)
if comment:
cmd.add_element("comment", comment)
if name:
cmd.add_element("name", name)
if users:
cmd.add_element("users", to_comma_list(users))
return self._send_xml_command(cmd)
def modify_role(
self,
role_id: str,
*,
comment: Optional[str] = None,
name: Optional[str] = None,
users: Optional[List[str]] = None,
) -> Any:
"""Modifies an existing role.
Arguments:
role_id: UUID of role to modify.
comment: Name of role.
name: Comment on role.
users: List of user names.
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not role_id:
raise RequiredArgument(function=self.modify_role.__name__,
argument="role_id argument")
cmd = XmlCommand("modify_role")
cmd.set_attribute("role_id", role_id)
if comment:
cmd.add_element("comment", comment)
if name:
cmd.add_element("name", name)
if users:
cmd.add_element("users", to_comma_list(users))
return self._send_xml_command(cmd)
def create_override(
self,
text: str,
nvt_oid: str,
*,
days_active: Optional[int] = None,
hosts: Optional[List[str]] = None,
port: Optional[str] = None,
result_id: Optional[str] = None,
severity: Optional[Severity] = None,
new_severity: Optional[Severity] = None,
task_id: Optional[str] = None,
threat: Any = None,
new_threat: Any = None,
) -> Any:
"""Create a new override
Arguments:
text: Text of the new override
nvt_id: OID of the nvt to which override applies
days_active: Days override will be active. -1 on always, 0 off
hosts: A list of host addresses
port: Port to which the override applies, needs to be a string
in the form {number}/{protocol}
result_id: UUID of a result to which override applies
severity: Severity to which override applies
new_severity: New severity for result
task_id: UUID of task to which override applies
threat: deprecated
new_threat: deprecated
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not text:
raise RequiredArgument(function=self.create_override.__name__,
argument="text")
if not nvt_oid:
raise RequiredArgument(function=self.create_override.__name__,
argument="nvt_oid")
cmd = XmlCommand("create_override")
cmd.add_element("text", text)
cmd.add_element("nvt", attrs={"oid": nvt_oid})
if days_active is not None:
cmd.add_element("active", str(days_active))
if hosts:
cmd.add_element("hosts", to_comma_list(hosts))
if port:
if check_port(port):
cmd.add_element("port", str(port))
else:
raise InvalidArgument(function=self.create_override.__name__,
argument="port")
if result_id:
cmd.add_element("result", attrs={"id": result_id})
if severity is not None:
cmd.add_element("severity", str(severity))
if new_severity is not None:
cmd.add_element("new_severity", str(new_severity))
if task_id:
cmd.add_element("task", attrs={"id": task_id})
if threat is not None:
major, minor = self.get_protocol_version()
deprecation("The threat parameter has been removed in GMP"
f" version {major}{minor}")
if new_threat is not None:
major, minor = self.get_protocol_version()
deprecation("The new_threat parameter has been removed in GMP"
f" version {major}{minor}")
return self._send_xml_command(cmd)
def modify_note(
self,
note_id: str,
text: str,
*,
days_active: Optional[int] = None,
hosts: Optional[List[str]] = None,
port: Optional[int] = None,
result_id: Optional[str] = None,
severity: Optional[Severity] = None,
task_id: Optional[str] = None,
threat: Any = None,
) -> Any:
"""Modifies an existing note.
Arguments:
note_id: UUID of note to modify.
text: The text of the note.
days_active: Days note will be active. -1 on always, 0 off.
hosts: A list of hosts addresses
port: Port to which the override applies, needs to be a string
in the form {number}/{protocol}
result_id: Result to which note applies.
severity: Severity to which note applies.
task_id: Task to which note applies.
threat: deprecated
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not note_id:
raise RequiredArgument(
function=self.modify_note.__name__, argument="note_id"
)
if not text:
raise RequiredArgument(
function=self.modify_note.__name__, argument="text"
)
cmd = XmlCommand("modify_note")
cmd.set_attribute("note_id", note_id)
cmd.add_element("text", text)
if days_active is not None:
cmd.add_element("active", str(days_active))
if hosts:
cmd.add_element("hosts", to_comma_list(hosts))
if port:
if check_port(port):
cmd.add_element("port", str(port))
else:
raise InvalidArgument(
function=self.modify_note.__name__, argument="port"
)
if result_id:
cmd.add_element("result", attrs={"id": result_id})
if severity is not None:
cmd.add_element("severity", str(severity))
if task_id:
cmd.add_element("task", attrs={"id": task_id})
if threat is not None:
major, minor = self.get_protocol_version()
deprecation(
"The threat parameter has been removed in GMP"
f" version {major}{minor}"
)
return self._send_xml_command(cmd)
def create_note(
self,
text: str,
nvt_oid: str,
*,
days_active: Optional[int] = None,
hosts: Optional[List[str]] = None,
port: Optional[str] = None,
result_id: Optional[str] = None,
severity: Optional[Severity] = None,
task_id: Optional[str] = None,
threat: Optional[SeverityLevel] = None,
) -> Any:
"""Create a new note
Arguments:
text: Text of the new note
nvt_id: OID of the nvt to which note applies
days_active: Days note will be active. -1 on
always, 0 off
hosts: A list of hosts addresses
port: Port to which the override applies, needs to be a string
in the form {number}/{protocol}
result_id: UUID of a result to which note applies
severity: Severity to which note applies
task_id: UUID of task to which note applies
threat: Severity level to which note applies. Will be converted to
severity.
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not text:
raise RequiredArgument(
function=self.create_note.__name__, argument="text"
)
if not nvt_oid:
raise RequiredArgument(
function=self.create_note.__name__, argument="nvt_oid"
)
cmd = XmlCommand("create_note")
cmd.add_element("text", text)
cmd.add_element("nvt", attrs={"oid": nvt_oid})
if days_active is not None:
cmd.add_element("active", str(days_active))
if hosts:
cmd.add_element("hosts", to_comma_list(hosts))
if port:
if check_port(port):
cmd.add_element("port", str(port))
else:
raise InvalidArgument(
function=self.create_note.__name__, argument="port"
)
if result_id:
cmd.add_element("result", attrs={"id": result_id})
if severity is not None:
cmd.add_element("severity", str(severity))
if task_id:
cmd.add_element("task", attrs={"id": task_id})
if threat is not None:
if not isinstance(threat, SeverityLevel):
raise InvalidArgumentType(
function="create_note",
argument="threat",
arg_type=SeverityLevel.__name__,
)
cmd.add_element("threat", threat.value)
return self._send_xml_command(cmd)
def create_task(
self,
name: str,
config_id: str,
target_id: str,
scanner_id: str,
*,
alterable: Optional[bool] = None,
hosts_ordering: Optional[HostsOrdering] = None,
schedule_id: Optional[str] = None,
alert_ids: Optional[List[str]] = None,
comment: Optional[str] = None,
schedule_periods: Optional[int] = None,
observers: Optional[List[str]] = None,
preferences: Optional[dict] = None,
) -> Any:
"""Create a new scan task
Arguments:
name: Name of the new task
config_id: UUID of config to use by the task
target_id: UUID of target to be scanned
scanner_id: UUID of scanner to use for scanning the target
comment: Comment for the task
alterable: Whether the task should be alterable
alert_ids: List of UUIDs for alerts to be applied to the task
hosts_ordering: The order hosts are scanned in
schedule_id: UUID of a schedule when the task should be run.
schedule_periods: A limit to the number of times the task will be
scheduled, or 0 for no limit
observers: List of names or ids of users which should be allowed to
observe this task
preferences: Name/Value pairs of scanner preferences.
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not name:
raise RequiredArgument(function=self.create_task.__name__,
argument="name")
if not config_id:
raise RequiredArgument(function=self.create_task.__name__,
argument="config_id")
if not target_id:
raise RequiredArgument(function=self.create_task.__name__,
argument="target_id")
if not scanner_id:
raise RequiredArgument(function=self.create_task.__name__,
argument="scanner_id")
# don't allow to create a container task with create_task
if target_id == "0":
raise InvalidArgument(function=self.create_task.__name__,
argument="target_id")
cmd = XmlCommand("create_task")
cmd.add_element("name", name)
cmd.add_element("usage_type", "scan")
cmd.add_element("config", attrs={"id": config_id})
cmd.add_element("target", attrs={"id": target_id})
cmd.add_element("scanner", attrs={"id": scanner_id})
if comment:
cmd.add_element("comment", comment)
if alterable is not None:
cmd.add_element("alterable", to_bool(alterable))
if hosts_ordering:
if not isinstance(hosts_ordering, HostsOrdering):
raise InvalidArgumentType(
function=self.create_task.__name__,
argument="hosts_ordering",
arg_type=HostsOrdering.__name__,
)
cmd.add_element("hosts_ordering", hosts_ordering.value)
if alert_ids is not None:
if not is_list_like(alert_ids):
raise InvalidArgumentType(
function=self.modify_task.__name__,
argument="alert_ids",
arg_type="list",
)
if not len(alert_ids) == 0:
for alert in alert_ids:
cmd.add_element("alert", attrs={"id": str(alert)})
if schedule_id:
cmd.add_element("schedule", attrs={"id": schedule_id})
if schedule_periods is not None:
if (not isinstance(schedule_periods, Integral)
or schedule_periods < 0):
raise InvalidArgument(
"schedule_periods must be an integer greater or equal "
"than 0")
cmd.add_element("schedule_periods", str(schedule_periods))
if observers is not None:
if not is_list_like(observers):
raise InvalidArgumentType(
function=self.create_task.__name__,
argument="observers",
arg_type="list",
)
# gvmd splits by comma and space
# gvmd tries to lookup each value as user name and afterwards as
# user id. So both user name and user id are possible
cmd.add_element("observers", to_comma_list(observers))
if preferences is not None:
if not isinstance(preferences, Mapping):
raise InvalidArgumentType(
function=self.create_task.__name__,
argument="preferences",
arg_type=Mapping.__name__,
)
_xmlprefs = cmd.add_element("preferences")
for pref_name, pref_value in preferences.items():
_xmlpref = _xmlprefs.add_element("preference")
_xmlpref.add_element("scanner_name", pref_name)
_xmlpref.add_element("value", str(pref_value))
return self._send_xml_command(cmd)
def modify_task(
self,
task_id: str,
*,
name: Optional[str] = None,
config_id: Optional[str] = None,
target_id: Optional[str] = None,
scanner_id: Optional[str] = None,
alterable: Optional[bool] = None,
hosts_ordering: Optional[HostsOrdering] = None,
schedule_id: Optional[str] = None,
schedule_periods: Optional[int] = None,
comment: Optional[str] = None,
alert_ids: Optional[List[str]] = None,
observers: Optional[List[str]] = None,
preferences: Optional[dict] = None,
) -> Any:
"""Modifies an existing task.
Arguments:
task_id: UUID of task to modify.
name: The name of the task.
config_id: UUID of scan config to use by the task
target_id: UUID of target to be scanned
scanner_id: UUID of scanner to use for scanning the target
comment: The comment on the task.
alert_ids: List of UUIDs for alerts to be applied to the task
hosts_ordering: The order hosts are scanned in
schedule_id: UUID of a schedule when the task should be run.
schedule_periods: A limit to the number of times the task will be
scheduled, or 0 for no limit.
observers: List of names or ids of users which should be allowed to
observe this task
preferences: Name/Value pairs of scanner preferences.
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not task_id:
raise RequiredArgument(function=self.modify_task.__name__,
argument="task_id argument")
cmd = XmlCommand("modify_task")
cmd.set_attribute("task_id", task_id)
if name:
cmd.add_element("name", name)
if comment:
cmd.add_element("comment", comment)
if config_id:
cmd.add_element("config", attrs={"id": config_id})
if target_id:
cmd.add_element("target", attrs={"id": target_id})
if alterable is not None:
cmd.add_element("alterable", to_bool(alterable))
if hosts_ordering:
if not isinstance(hosts_ordering, HostsOrdering):
raise InvalidArgumentType(
function=self.modify_task.__name__,
argument="hosts_ordering",
arg_type=HostsOrdering.__name__,
)
cmd.add_element("hosts_ordering", hosts_ordering.value)
if scanner_id:
cmd.add_element("scanner", attrs={"id": scanner_id})
if schedule_id:
cmd.add_element("schedule", attrs={"id": schedule_id})
if schedule_periods is not None:
if (not isinstance(schedule_periods, Integral)
or schedule_periods < 0):
raise InvalidArgument(
"schedule_periods must be an integer greater or equal "
"than 0")
cmd.add_element("schedule_periods", str(schedule_periods))
if alert_ids is not None:
if not is_list_like(alert_ids):
raise InvalidArgumentType(
function=self.modify_task.__name__,
argument="alert_ids",
arg_type="list",
)
if len(alert_ids) == 0:
cmd.add_element("alert", attrs={"id": "0"})
else:
for alert in alert_ids:
cmd.add_element("alert", attrs={"id": str(alert)})
if observers is not None:
if not is_list_like(observers):
raise InvalidArgumentType(
function=self.modify_task.__name__,
argument="observers",
arg_type="list",
)
cmd.add_element("observers", to_comma_list(observers))
if preferences is not None:
if not isinstance(preferences, Mapping):
raise InvalidArgumentType(
function=self.modify_task.__name__,
argument="preferences",
arg_type=Mapping.__name__,
)
_xmlprefs = cmd.add_element("preferences")
for pref_name, pref_value in preferences.items():
_xmlpref = _xmlprefs.add_element("preference")
_xmlpref.add_element("scanner_name", pref_name)
_xmlpref.add_element("value", str(pref_value))
return self._send_xml_command(cmd)
def create_task(
self,
name: str,
config_id: str,
target_id: str,
scanner_id: str,
*,
alterable: Optional[bool] = None,
hosts_ordering: Optional[HostsOrdering] = None,
schedule_id: Optional[str] = None,
alert_ids: Optional[List[str]] = None,
comment: Optional[str] = None,
schedule_periods: Optional[int] = None,
observers: Optional[List[str]] = None,
preferences: Optional[dict] = None,
) -> Any:
if not name:
raise RequiredArgument(function=self.create_task.__name__,
argument='name')
if not config_id:
raise RequiredArgument(function=self.create_task.__name__,
argument='config_id')
if not target_id:
raise RequiredArgument(function=self.create_task.__name__,
argument='target_id')
if not scanner_id:
raise RequiredArgument(function=self.create_task.__name__,
argument='scanner_id')
# don't allow to create a container task with create_task
if target_id == '0':
raise InvalidArgument(function=self.create_task.__name__,
argument='target_id')
cmd = XmlCommand("create_task")
cmd.add_element("name", name)
cmd.add_element("usage_type", "scan")
cmd.add_element("config", attrs={"id": config_id})
cmd.add_element("target", attrs={"id": target_id})
cmd.add_element("scanner", attrs={"id": scanner_id})
if comment:
cmd.add_element("comment", comment)
if alterable is not None:
cmd.add_element("alterable", to_bool(alterable))
if hosts_ordering:
if not isinstance(hosts_ordering, self.types.HostsOrdering):
raise InvalidArgumentType(
function=self.create_task.__name__,
argument='hosts_ordering',
arg_type=HostsOrdering.__name__,
)
cmd.add_element("hosts_ordering", hosts_ordering.value)
if alert_ids:
if is_list_like(alert_ids):
# parse all given alert id's
for alert in alert_ids:
cmd.add_element("alert", attrs={"id": str(alert)})
if schedule_id:
cmd.add_element("schedule", attrs={"id": schedule_id})
if schedule_periods is not None:
if (not isinstance(schedule_periods, Integral)
or schedule_periods < 0):
raise InvalidArgument(
"schedule_periods must be an integer greater or equal "
"than 0")
cmd.add_element("schedule_periods", str(schedule_periods))
if observers is not None:
if not is_list_like(observers):
raise InvalidArgumentType(
function=self.create_task.__name__,
argument='observers',
arg_type='list',
)
# gvmd splits by comma and space
# gvmd tries to lookup each value as user name and afterwards as
# user id. So both user name and user id are possible
cmd.add_element("observers", to_comma_list(observers))
if preferences is not None:
if not isinstance(preferences, Mapping):
raise InvalidArgumentType(
function=self.create_task.__name__,
argument='preferences',
arg_type=Mapping.__name__,
)
_xmlprefs = cmd.add_element("preferences")
for pref_name, pref_value in preferences.items():
_xmlpref = _xmlprefs.add_element("preference")
_xmlpref.add_element("scanner_name", pref_name)
_xmlpref.add_element("value", str(pref_value))
return self._send_xml_command(cmd)
def create_note(
self,
text: str,
nvt_oid: str,
*,
days_active: Optional[int] = None,
hosts: Optional[List[str]] = None,
port: Optional[int] = None,
result_id: Optional[str] = None,
severity: Optional[Severity] = None,
task_id: Optional[str] = None,
threat: Optional[SeverityLevel] = None,
) -> Any:
"""Create a new note
Arguments:
text: Text of the new note
nvt_id: OID of the nvt to which note applies
days_active: Days note will be active. -1 on
always, 0 off
hosts: A list of hosts addresses
port: Port to which the note applies
result_id: UUID of a result to which note applies
severity: Severity to which note applies
task_id: UUID of task to which note applies
threat: Severity level to which note applies. Will be converted to
severity.
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not text:
raise RequiredArgument(function=self.create_note.__name__,
argument='text')
if not nvt_oid:
raise RequiredArgument(function=self.create_note.__name__,
argument='nvt_oid')
cmd = XmlCommand("create_note")
cmd.add_element("text", text)
cmd.add_element("nvt", attrs={"oid": nvt_oid})
if days_active is not None:
cmd.add_element("active", str(days_active))
if hosts:
cmd.add_element("hosts", to_comma_list(hosts))
if port:
cmd.add_element("port", str(port))
if result_id:
cmd.add_element("result", attrs={"id": result_id})
if severity:
cmd.add_element("severity", str(severity))
if task_id:
cmd.add_element("task", attrs={"id": task_id})
if threat is not None:
deprecation("The threat parameter has been removed in GMP"
" version {}{}".format(
self.get_protocol_version()[0],
self.get_protocol_version()[1],
))
return self._send_xml_command(cmd)
def modify_override(
self,
override_id: str,
text: str,
*,
days_active: Optional[int] = None,
hosts: Optional[List[str]] = None,
port: Optional[int] = None,
result_id: Optional[str] = None,
severity: Optional[Severity] = None,
new_severity: Optional[Severity] = None,
task_id: Optional[str] = None,
threat: Optional[SeverityLevel] = None,
new_threat: Optional[SeverityLevel] = None,
) -> Any:
"""Modifies an existing override.
Arguments:
override_id: UUID of override to modify.
text: The text of the override.
days_active: Days override will be active. -1 on always,
0 off.
hosts: A list of host addresses
port: Port to which override applies.
result_id: Result to which override applies.
severity: Severity to which override applies.
new_severity: New severity score for result.
task_id: Task to which override applies.
threat: Threat level to which override applies.
Will be converted to severity.
new_threat: New threat level for results. Will be converted to
new_severity.
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not override_id:
raise RequiredArgument(function=self.modify_override.__name__,
argument='override_id')
if not text:
raise RequiredArgument(function=self.modify_override.__name__,
argument='text')
cmd = XmlCommand("modify_override")
cmd.set_attribute("override_id", override_id)
cmd.add_element("text", text)
if days_active is not None:
cmd.add_element("active", str(days_active))
if hosts:
cmd.add_element("hosts", to_comma_list(hosts))
if port:
cmd.add_element("port", str(port))
if result_id:
cmd.add_element("result", attrs={"id": result_id})
if severity:
cmd.add_element("severity", str(severity))
if new_severity:
cmd.add_element("new_severity", str(new_severity))
if task_id:
cmd.add_element("task", attrs={"id": task_id})
if threat is not None:
deprecation("The threat parameter has been removed in GMP"
" version {}{}".format(
self.get_protocol_version()[0],
self.get_protocol_version()[1],
))
if new_threat is not None:
deprecation("The new_threat parameter has been removed in GMP"
" version {}{}".format(
self.get_protocol_version()[0],
self.get_protocol_version()[1],
))
return self._send_xml_command(cmd)
def modify_target(
self,
target_id: str,
*,
name: Optional[str] = None,
comment: Optional[str] = None,
hosts: Optional[List[str]] = None,
exclude_hosts: Optional[List[str]] = None,
ssh_credential_id: Optional[str] = None,
ssh_credential_port: Optional[bool] = None,
smb_credential_id: Optional[str] = None,
esxi_credential_id: Optional[str] = None,
snmp_credential_id: Optional[str] = None,
alive_test: Optional[AliveTest] = None,
allow_simultaneous_ips: Optional[bool] = None,
reverse_lookup_only: Optional[bool] = None,
reverse_lookup_unify: Optional[bool] = None,
port_list_id: Optional[str] = None,
) -> Any:
"""Modifies an existing target.
Arguments:
target_id: ID of target to modify.
comment: Comment on target.
name: Name of target.
hosts: List of target hosts.
exclude_hosts: A list of hosts to exclude.
ssh_credential_id: UUID of SSH credential to use on target.
ssh_credential_port: The port to use for ssh credential
smb_credential_id: UUID of SMB credential to use on target.
esxi_credential_id: UUID of ESXi credential to use on target.
snmp_credential_id: UUID of SNMP credential to use on target.
port_list_id: UUID of port list describing ports to scan.
alive_test: Which alive tests to use.
allow_simultaneous_ips: Whether to scan multiple IPs of the
same host simultaneously
reverse_lookup_only: Whether to scan only hosts that have names.
reverse_lookup_unify: Whether to scan only one IP when multiple IPs
have the same name.
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not target_id:
raise RequiredArgument(function=self.modify_target.__name__,
argument="target_id")
cmd = XmlCommand("modify_target")
cmd.set_attribute("target_id", target_id)
if comment:
cmd.add_element("comment", comment)
if name:
cmd.add_element("name", name)
if hosts:
cmd.add_element("hosts", to_comma_list(hosts))
if exclude_hosts is None:
exclude_hosts = [""]
if exclude_hosts:
cmd.add_element("exclude_hosts", to_comma_list(exclude_hosts))
if alive_test:
if not isinstance(alive_test, AliveTest):
raise InvalidArgumentType(
function=self.modify_target.__name__,
argument="alive_test",
arg_type=AliveTest.__name__,
)
cmd.add_element("alive_tests", alive_test.value)
if ssh_credential_id:
_xmlssh = cmd.add_element("ssh_credential",
attrs={"id": ssh_credential_id})
if ssh_credential_port:
_xmlssh.add_element("port", str(ssh_credential_port))
if smb_credential_id:
cmd.add_element("smb_credential", attrs={"id": smb_credential_id})
if esxi_credential_id:
cmd.add_element("esxi_credential",
attrs={"id": esxi_credential_id})
if snmp_credential_id:
cmd.add_element("snmp_credential",
attrs={"id": snmp_credential_id})
if allow_simultaneous_ips is not None:
cmd.add_element("allow_simultaneous_ips",
to_bool(allow_simultaneous_ips))
if reverse_lookup_only is not None:
cmd.add_element("reverse_lookup_only",
to_bool(reverse_lookup_only))
if reverse_lookup_unify is not None:
cmd.add_element("reverse_lookup_unify",
to_bool(reverse_lookup_unify))
if port_list_id:
cmd.add_element("port_list", attrs={"id": port_list_id})
return self._send_xml_command(cmd)
def create_target(
self,
name: str,
*,
asset_hosts_filter: Optional[str] = None,
hosts: Optional[List[str]] = None,
comment: Optional[str] = None,
exclude_hosts: Optional[List[str]] = None,
ssh_credential_id: Optional[str] = None,
ssh_credential_port: Optional[int] = None,
smb_credential_id: Optional[str] = None,
esxi_credential_id: Optional[str] = None,
snmp_credential_id: Optional[str] = None,
alive_test: Optional[AliveTest] = None,
allow_simultaneous_ips: Optional[bool] = None,
reverse_lookup_only: Optional[bool] = None,
reverse_lookup_unify: Optional[bool] = None,
port_range: Optional[str] = None,
port_list_id: Optional[str] = None,
) -> Any:
"""Create a new target
Arguments:
name: Name of the target
asset_hosts_filter: Filter to select target host from assets hosts
hosts: List of hosts addresses to scan
exclude_hosts: List of hosts addresses to exclude from scan
comment: Comment for the target
ssh_credential_id: UUID of a ssh credential to use on target
ssh_credential_port: The port to use for ssh credential
smb_credential_id: UUID of a smb credential to use on target
snmp_credential_id: UUID of a snmp credential to use on target
esxi_credential_id: UUID of a esxi credential to use on target
alive_test: Which alive test to use
allow_simultaneous_ips: Whether to scan multiple IPs of the
same host simultaneously
reverse_lookup_only: Whether to scan only hosts that have names
reverse_lookup_unify: Whether to scan only one IP when multiple IPs
have the same name.
port_range: Port range for the target
port_list_id: UUID of the port list to use on target
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not name:
raise RequiredArgument(function=self.create_target.__name__,
argument="name")
cmd = XmlCommand("create_target")
cmd.add_element("name", name)
if asset_hosts_filter:
cmd.add_element("asset_hosts",
attrs={"filter": str(asset_hosts_filter)})
elif hosts:
cmd.add_element("hosts", to_comma_list(hosts))
else:
raise RequiredArgument(
function=self.create_target.__name__,
argument="hosts or asset_hosts_filter",
)
if comment:
cmd.add_element("comment", comment)
if exclude_hosts:
cmd.add_element("exclude_hosts", to_comma_list(exclude_hosts))
if ssh_credential_id:
_xmlssh = cmd.add_element("ssh_credential",
attrs={"id": ssh_credential_id})
if ssh_credential_port:
_xmlssh.add_element("port", str(ssh_credential_port))
if smb_credential_id:
cmd.add_element("smb_credential", attrs={"id": smb_credential_id})
if esxi_credential_id:
cmd.add_element("esxi_credential",
attrs={"id": esxi_credential_id})
if snmp_credential_id:
cmd.add_element("snmp_credential",
attrs={"id": snmp_credential_id})
if alive_test:
if not isinstance(alive_test, AliveTest):
raise InvalidArgumentType(
function=self.create_target.__name__,
argument="alive_test",
arg_type=AliveTest.__name__,
)
cmd.add_element("alive_tests", alive_test.value)
if allow_simultaneous_ips is not None:
cmd.add_element("allow_simultaneous_ips",
to_bool(allow_simultaneous_ips))
if reverse_lookup_only is not None:
cmd.add_element("reverse_lookup_only",
to_bool(reverse_lookup_only))
if reverse_lookup_unify is not None:
cmd.add_element("reverse_lookup_unify",
to_bool(reverse_lookup_unify))
if port_range:
cmd.add_element("port_range", port_range)
if port_list_id:
cmd.add_element("port_list", attrs={"id": port_list_id})
return self._send_xml_command(cmd)
def modify_user(
self,
user_id: str = None,
*,
name: Optional[str] = None,
comment: Optional[str] = None,
password: Optional[str] = None,
auth_source: Optional[UserAuthType] = None,
role_ids: Optional[List[str]] = None,
hosts: Optional[List[str]] = None,
hosts_allow: Optional[bool] = False,
ifaces: Any = None,
ifaces_allow: Any = None,
group_ids: Optional[List[str]] = None,
) -> Any:
"""Modifies an existing user.
Most of the fields need to be supplied
for changing a single field even if no change is wanted for those.
Else empty values are inserted for the missing fields instead.
Arguments:
user_id: UUID of the user to be modified.
name: The new name for the user.
comment: Comment on the user.
password: The password for the user.
auth_source: Source allowed for authentication for this user.
roles_id: List of roles UUIDs for the user.
hosts: User access rules: List of hosts.
hosts_allow: Defines how the hosts list is to be interpreted.
If False (default) the list is treated as a deny list.
All hosts are allowed by default except those provided by
the hosts parameter. If True the list is treated as a
allow list. All hosts are denied by default except those
provided by the hosts parameter.
ifaces: deprecated
ifaces_allow: deprecated
group_ids: List of group UUIDs for the user.
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not user_id:
raise RequiredArgument(function=self.modify_user.__name__,
argument="user_id")
cmd = XmlCommand("modify_user")
cmd.set_attribute("user_id", user_id)
if name:
cmd.add_element("new_name", name)
if role_ids:
for role in role_ids:
cmd.add_element("role", attrs={"id": role})
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 comment:
cmd.add_element("comment", comment)
if password:
cmd.add_element("password", password)
if auth_source:
_xmlauthsrc = cmd.add_element("sources")
_xmlauthsrc.add_element("source", auth_source.value)
if group_ids:
_xmlgroups = cmd.add_element("groups")
for group_id in group_ids:
_xmlgroups.add_element("group", attrs={"id": group_id})
return self._send_xml_command(cmd)
def modify_override(
self,
override_id: str,
text: str,
*,
days_active: Optional[int] = None,
hosts: Optional[List[str]] = None,
port: Optional[str] = None,
result_id: Optional[str] = None,
severity: Optional[Severity] = None,
new_severity: Optional[Severity] = None,
task_id: Optional[str] = None,
threat: Optional[SeverityLevel] = None,
new_threat: Optional[SeverityLevel] = None,
) -> Any:
"""Modifies an existing override.
Arguments:
override_id: UUID of override to modify.
text: The text of the override.
days_active: Days override will be active. -1 on always,
0 off.
hosts: A list of host addresses
port: Port to which the override applies, needs to be a string
in the form {number}/{protocol}
result_id: Result to which override applies.
severity: Severity to which override applies.
new_severity: New severity score for result.
task_id: Task to which override applies.
threat: Threat level to which override applies.
Will be converted to severity.
new_threat: New threat level for results. Will be converted to
new_severity.
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not override_id:
raise RequiredArgument(function=self.modify_override.__name__,
argument="override_id")
if not text:
raise RequiredArgument(function=self.modify_override.__name__,
argument="text")
cmd = XmlCommand("modify_override")
cmd.set_attribute("override_id", override_id)
cmd.add_element("text", text)
if days_active is not None:
cmd.add_element("active", str(days_active))
if hosts:
cmd.add_element("hosts", to_comma_list(hosts))
if port:
if check_port(port):
cmd.add_element("port", str(port))
else:
raise InvalidArgument(function=self.modify_override.__name__,
argument="port")
if result_id:
cmd.add_element("result", attrs={"id": result_id})
if severity is not None:
cmd.add_element("severity", str(severity))
if new_severity is not None:
cmd.add_element("new_severity", str(new_severity))
if task_id:
cmd.add_element("task", attrs={"id": task_id})
if threat is not None:
if not isinstance(threat, SeverityLevel):
raise InvalidArgumentType(
function=self.modify_override.__name__,
argument="threat",
arg_type=SeverityLevel.__name__,
)
cmd.add_element("threat", threat.value)
if new_threat is not None:
if not isinstance(new_threat, SeverityLevel):
raise InvalidArgumentType(
function=self.modify_override.__name__,
argument="new_threat",
arg_type=SeverityLevel.__name__,
)
cmd.add_element("new_threat", new_threat.value)
return self._send_xml_command(cmd)
