Source code for tenable.tenableone.inventory.findings.api

"""
Findings
========

Methods described in this section relate to the inventory findings API.
These methods can be accessed at ``TenableExposureManagement.inventory.findings``.

.. rst-class:: hide-signature
.. autoclass:: FindingsAPI
    :members:

"""

from typing import Optional
from urllib.parse import urlencode

from tenable.base.endpoint import APIEndpoint
from tenable.tenableone.inventory.findings.schema import Findings
from tenable.tenableone.inventory.schema import Field, Properties, QueryMode, PropertyFilter, SortDirection




class FindingsAPI(APIEndpoint):


    def list_properties(self) -> list[Field]:
        """
        Retrieve finding properties

        Returns:
            The finding properties.

        Examples:
            >>> properties = tenable_inventory.finding.list_properties()
            >>> for finding_property in properties:
            ...     pprint(finding_property)

        """
        finding_properties_response: dict[str, list[dict]] = self._get(
            path="api/v1/t1/inventory/findings/properties"
        )
        return Properties(**finding_properties_response).data




    def list(
            self,
            query_text: Optional[str] = None,
            query_mode: Optional[QueryMode] = None,
            filters: Optional[list[PropertyFilter]] = None,
            extra_properties: Optional[list[str]] = None,
            offset: Optional[int] = None,
            limit: Optional[int] = None,
            sort_by: Optional[str] = None,
            sort_direction: Optional[SortDirection] = None,
    ) -> Findings:
        """
        Retrieve findings

        Args:
           query_text (str, optional):
               The text to search for.
           query_mode (QueryMode, optional):
               The search mode. Defaults to QueryMode.SIMPLE.
           filters (list, optional):
               A list of filters to apply. Defaults to None.
           extra_properties (list, optional):
               Additional properties to include in the response. Defaults to None.
           offset (int, optional):
               Number of records to skip. Defaults to 0.
           limit (int, optional):
               Maximum number of records per page. Defaults to 1000.
           sort_by (str, optional):
               Field to sort by.
           sort_direction (SortDirection, optional):
               Sorting direction, either SortDirection.ASC or SortDirection.DESC.

        Returns:
           The request assets.

        Example:
           >>> tenable_inventory_findings = tenable_inventory.finding.list()
           >>> for finding in tenable_inventory_findings:
           ...     pprint(finding)

        """
        payload = {}

        # TODO: check what is the actual contract
        if query_text is not None and query_mode is not None and filters is not None:
            payload = {
                "query": {"text": query_text, "mode": query_mode.value},
                "filters": [filter_.model_dump(mode="json") for filter_ in filters]
                if filters is not None
                else [],
            }
        base_path = "api/v1/t1/inventory/findings/search"
        query_params = {}

        if extra_properties is not None:
            query_params["extra_properties"] = ",".join(extra_properties)
        if offset is not None:
            query_params["offset"] = offset
        if limit is not None:
            query_params["limit"] = limit
        if sort_by is not None and sort_direction is not None:
            query_params["sort"] = f"{sort_by}:{sort_direction}"

        if query_params:
            query_string = urlencode(query_params)
            path = f"{base_path}?{query_string}"
        else:
            path = base_path

        findings_response: dict = self._post(path=path, json=payload)
        return Findings(**findings_response)