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_alerts(
self,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
trash: Optional[bool] = None,
tasks: Optional[bool] = None,
) -> Any:
"""Request a list of alerts
Arguments:
filter: Filter term to use for the query
filter_id: UUID of an existing filter to use for the query
trash: True to request the alerts in the trashcan
tasks: Whether to include the tasks using the alerts
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_alerts")
add_filter(cmd, filter_string, filter_id)
if trash is not None:
cmd.set_attribute("trash", to_bool(trash))
if tasks is not None:
cmd.set_attribute("tasks", to_bool(tasks))
return self._send_xml_command(cmd)
def 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_tls_certificates(
self,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
include_certificate_data: Optional[bool] = None,
details: Optional[bool] = None,
) -> Any:
"""Request a list of TLS certificates
Arguments:
filter_string: 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
details: Whether to include additional details of the
tls certificates
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_tls_certificates")
add_filter(cmd, filter_string, filter_id)
if details is not None:
cmd.set_attribute("details", to_bool(details))
if include_certificate_data is not None:
cmd.set_attribute("include_certificate_data",
to_bool(include_certificate_data))
return self._send_xml_command(cmd)
def 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_port_lists(
self,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
details: Optional[bool] = None,
targets: Optional[bool] = None,
trash: Optional[bool] = None,
) -> Any:
"""Request a list of port lists
Arguments:
filter_string: Filter term to use for the query
filter_id: UUID of an existing filter to use for the query
details: Whether to include full port list details
targets: Whether to include targets using this port list
trash: Whether to get port lists in the trashcan instead
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_port_lists")
add_filter(cmd, filter_string, filter_id)
if details is not None:
cmd.set_attribute("details", to_bool(details))
if targets is not None:
cmd.set_attribute("targets", to_bool(targets))
if trash is not None:
cmd.set_attribute("trash", to_bool(trash))
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_overrides(
self,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
details: Optional[bool] = None,
result: Optional[bool] = None,
) -> Any:
"""Request a list of overrides
Arguments:
filter_string: Filter term to use for the query
filter_id: UUID of an existing filter to use for the query
details: Whether to include full details
result: Whether to include results using the override
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_overrides")
add_filter(cmd, filter_string, filter_id)
if details is not None:
cmd.set_attribute("details", to_bool(details))
if result is not None:
cmd.set_attribute("result", to_bool(result))
return self._send_xml_command(cmd)
def 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_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_scan_configs(
self,
*,
filter_string: 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:
"""Request a list of scan configs
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 scan configs instead
details: Whether to get config families, preferences, nvt selectors
and tasks.
families: Whether to include the families if no details are
requested
preferences: Whether to include the preferences if no details are
requested
tasks: Whether to get tasks using this config
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_configs")
cmd.set_attribute("usage_type", "scan")
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))
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 get_info_list(
self,
info_type: InfoType,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
name: Optional[str] = None,
details: Optional[bool] = None,
) -> Any:
"""Request a list of security information
Arguments:
info_type: Type must be either CERT_BUND_ADV, CPE, CVE,
DFN_CERT_ADV, OVALDEF or NVT
filter_string: Filter term to use for the query
filter_id: UUID of an existing filter to use for the query
name: Name or identifier of the requested information
details: Whether to include information about references to this
information
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not info_type:
raise RequiredArgument(function=self.get_info_list.__name__,
argument="info_type")
if not isinstance(info_type, InfoType):
raise InvalidArgumentType(
function=self.get_info_list.__name__,
argument="info_type",
arg_type=InfoType.__name__,
)
cmd = XmlCommand("get_info")
cmd.set_attribute("type", info_type.value)
add_filter(cmd, filter_string, filter_id)
if name:
cmd.set_attribute("name", name)
if details is not None:
cmd.set_attribute("details", to_bool(details))
return self._send_xml_command(cmd)
def get_vulnerabilities(
self,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
) -> Any:
"""Request a list of vulnerabilities
Arguments:
filter_string: Filter term to use for the query
filter_id: UUID of an existing filter to use for the query
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_vulns")
add_filter(cmd, filter_string, filter_id)
return self._send_xml_command(cmd)
def get_results(
self,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
task_id: Optional[str] = None,
note_details: Optional[bool] = None,
override_details: Optional[bool] = None,
details: Optional[bool] = None,
) -> Any:
"""Request a list of results
Arguments:
filter_string: Filter term to use for the query
filter_id: UUID of an existing filter to use for the query
task_id: UUID of task for note and override handling
note_details: If notes are included, whether to include note details
override_details: If overrides are included, whether to include
override details
details: Whether to include additional details of the results
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_results")
add_filter(cmd, filter_string, filter_id)
if task_id:
cmd.set_attribute("task_id", task_id)
if details is not None:
cmd.set_attribute("details", to_bool(details))
if note_details is not None:
cmd.set_attribute("note_details", to_bool(note_details))
if override_details is not None:
cmd.set_attribute("override_details", to_bool(override_details))
return self._send_xml_command(cmd)
def get_operating_systems(
self,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
) -> Any:
"""Request a list of operating_systems
Arguments:
filter_string: Filter term to use for the query
filter_id: UUID of an existing filter to use for the query
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_assets")
cmd.set_attribute("type", "os")
add_filter(cmd, filter_string, filter_id)
return self._send_xml_command(cmd)
def get_tasks(
self,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
trash: Optional[bool] = None,
details: Optional[bool] = None,
schedules_only: Optional[bool] = None,
) -> Any:
"""Request a list of tasks
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 tasks instead
details: Whether to include full task details
schedules_only: Whether to only include id, name and schedule
details
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_tasks")
cmd.set_attribute("usage_type", "scan")
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))
if schedules_only is not None:
cmd.set_attribute("schedules_only", to_bool(schedules_only))
return self._send_xml_command(cmd)
def get_credentials(
self,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
scanners: Optional[bool] = None,
trash: Optional[bool] = None,
targets: Optional[bool] = None,
) -> Any:
"""Request a list of credentials
Arguments:
filter_string: Filter term to use for the query
filter_id: UUID of an existing filter to use for the query
scanners: Whether to include a list of scanners using the
credentials
trash: Whether to get the trashcan credentials instead
targets: Whether to include a list of targets using the credentials
Returns:
The response. See :py:meth:`send_command` for details.
"""
cmd = XmlCommand("get_credentials")
add_filter(cmd, filter_string, filter_id)
if scanners is not None:
cmd.set_attribute("scanners", to_bool(scanners))
if trash is not None:
cmd.set_attribute("trash", to_bool(trash))
if targets is not None:
cmd.set_attribute("targets", to_bool(targets))
return self._send_xml_command(cmd)
def get_aggregates(
self,
resource_type: EntityType,
*,
filter_string: Optional[str] = None,
filter_id: Optional[str] = None,
sort_criteria: Optional[list] = None,
data_columns: Optional[list] = None,
group_column: Optional[str] = None,
subgroup_column: Optional[str] = None,
text_columns: Optional[list] = None,
first_group: Optional[int] = None,
max_groups: Optional[int] = None,
mode: Optional[int] = None,
**kwargs,
) -> Any:
"""Request aggregated information on a resource / entity type
Additional arguments can be set via the kwargs parameter for backward
compatibility with older versions of python-gvm, but are not validated.
Arguments:
resource_type: The entity type to gather data from
filter_string: Filter term to use for the query
filter_id: UUID of an existing filter to use for the query
sort_criteria: List of sort criteria (dicts that can contain
a field, stat and order)
data_columns: List of fields to aggregate data from
group_column: The field to group the entities by
subgroup_column: The field to further group the entities
inside groups by
text_columns: List of simple text columns which no statistics
are calculated for
first_group: The index of the first aggregate group to return
max_groups: The maximum number of aggregate groups to return,
-1 for all
mode: Special mode for aggregation
Returns:
The response. See :py:meth:`send_command` for details.
"""
if not resource_type:
raise RequiredArgument(function=self.get_aggregates.__name__,
argument="resource_type")
if not isinstance(resource_type, EntityType):
raise InvalidArgumentType(
function=self.get_aggregates.__name__,
argument="resource_type",
arg_type=EntityType.__name__,
)
cmd = XmlCommand("get_aggregates")
_actual_resource_type = resource_type
if resource_type.value == EntityType.AUDIT.value:
_actual_resource_type = EntityType.TASK
cmd.set_attribute("usage_type", "audit")
elif resource_type.value == EntityType.POLICY.value:
_actual_resource_type = EntityType.SCAN_CONFIG
cmd.set_attribute("usage_type", "policy")
elif resource_type.value == EntityType.SCAN_CONFIG.value:
cmd.set_attribute("usage_type", "scan")
elif resource_type.value == EntityType.TASK.value:
cmd.set_attribute("usage_type", "scan")
cmd.set_attribute("type", _actual_resource_type.value)
add_filter(cmd, filter_string, filter_id)
if first_group is not None:
if not isinstance(first_group, int):
raise InvalidArgumentType(
function=self.get_aggregates.__name__,
argument="first_group",
arg_type=int.__name__,
)
cmd.set_attribute("first_group", str(first_group))
if max_groups is not None:
if not isinstance(max_groups, int):
raise InvalidArgumentType(
function=self.get_aggregates.__name__,
argument="max_groups",
arg_type=int.__name__,
)
cmd.set_attribute("max_groups", str(max_groups))
if sort_criteria is not None:
if not isinstance(sort_criteria, list):
raise InvalidArgumentType(
function=self.get_aggregates.__name__,
argument="sort_criteria",
arg_type=list.__name__,
)
for sort in sort_criteria:
if not isinstance(sort, dict):
raise InvalidArgumentType(
function=self.get_aggregates.__name__,
argument="sort_criteria",
)
sort_elem = cmd.add_element("sort")
if sort.get("field"):
sort_elem.set_attribute("field", sort.get("field"))
if sort.get("stat"):
if isinstance(sort["stat"], AggregateStatistic):
sort_elem.set_attribute("stat", sort["stat"].value)
else:
stat = AggregateStatistic.from_string(sort["stat"])
sort_elem.set_attribute("stat", stat.value)
if sort.get("order"):
if isinstance(sort["order"], SortOrder):
sort_elem.set_attribute("order", sort["order"].value)
else:
so = SortOrder.from_string(sort["order"])
sort_elem.set_attribute("order", so.value)
if data_columns is not None:
if not isinstance(data_columns, list):
raise InvalidArgumentType(
function=self.get_aggregates.__name__,
argument="data_columns",
arg_type=list.__name__,
)
for column in data_columns:
cmd.add_element("data_column", column)
if group_column is not None:
cmd.set_attribute("group_column", group_column)
if subgroup_column is not None:
if not group_column:
raise RequiredArgument(
f"{self.get_aggregates.__name__} requires a group_column"
" argument if subgroup_column is given",
function=self.get_aggregates.__name__,
argument="subgroup_column",
)
cmd.set_attribute("subgroup_column", subgroup_column)
if text_columns is not None:
if not isinstance(text_columns, list):
raise InvalidArgumentType(
function=self.get_aggregates.__name__,
argument="text_columns",
arg_type=list.__name__,
)
for column in text_columns:
cmd.add_element("text_column", column)
if mode is not None:
cmd.set_attribute("mode", mode)
# Add additional keyword args as attributes for backward compatibility.
cmd.set_attributes(kwargs)
return self._send_xml_command(cmd)
