psengine 2.2.0__tar.gz → 2.3.0__tar.gz

{psengine-2.2.0 → psengine-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: psengine
-Version: 2.2.0
+Version: 2.3.0
 Summary: psengine is a simple, yet elegant, library for rapid development of integrations with Recorded Future.
 Author-email: Moise Medici <moise.medici@recordedfuture.com>, Patrick Kinsella <patrick.kinsella@recordedfuture.com>, Ernest Bartosevic <ernest.bartosevic@recordedfuture.com>
 License-Expression: MIT
@@ -50,6 +50,8 @@ Requires-Dist: griffe-typingdoc~=0.2.8; extra == "docs"
 Requires-Dist: mkdocs-codeinclude-plugin~=0.2.1; extra == "docs"
 Requires-Dist: markdown-include~=0.8.1; extra == "docs"
 Requires-Dist: mkdocs-exclude~=1.0.2; extra == "docs"
+Requires-Dist: rich; extra == "docs"
+Requires-Dist: logging-tree; extra == "docs"
 Dynamic: license-file
 
 **Documentation**: <https://recordedfuture-professionalservices.github.io/psengine/>
@@ -83,21 +85,24 @@ PSEngine is ready for the demands of building robust and reliable integrations.
 
 It can easily interact with the following Recorded Future datasets:
 
-* Analyst Notes
-* Collective Insights
-* Classic & Playbook Alerts
-* Detection Rules
+- Analyst Notes
+- Collective Insights
+- Classic & Playbook Alerts
+- Detection Rules
+- Fusion File management
 - Identity Exposures management
-* List management
-* On demand IOC enrichment
-* Risklists
+- List management
+- Malware Sandbox reports download
+- On demand IOC enrichment
+- Risklists
+- Risk History
 - STIX conversion
 
 
 And facilitate the development with features like:
 
-* Built-in logging
-* Easy configuration management
+- Built-in logging
+- Easy configuration management
 - Markdown creation from certain data types
-* Proxy support
+- Proxy support
 

{psengine-2.2.0 → psengine-2.3.0}/README.md

@@ -29,21 +29,24 @@ PSEngine is ready for the demands of building robust and reliable integrations.
 
 It can easily interact with the following Recorded Future datasets:
 
-* Analyst Notes
-* Collective Insights
-* Classic & Playbook Alerts
-* Detection Rules
+- Analyst Notes
+- Collective Insights
+- Classic & Playbook Alerts
+- Detection Rules
+- Fusion File management
 - Identity Exposures management
-* List management
-* On demand IOC enrichment
-* Risklists
+- List management
+- Malware Sandbox reports download
+- On demand IOC enrichment
+- Risklists
+- Risk History
 - STIX conversion
 
 
 And facilitate the development with features like:
 
-* Built-in logging
-* Easy configuration management
+- Built-in logging
+- Easy configuration management
 - Markdown creation from certain data types
-* Proxy support
+- Proxy support
 

{psengine-2.2.0 → psengine-2.3.0}/psengine/_version.py

@@ -11,4 +11,4 @@
 # accessed from any third party API.                                                         #
 ##############################################################################################
 
-__version__ = '2.2.0'
+__version__ = '2.3.0'

{psengine-2.2.0 → psengine-2.3.0}/psengine/analyst_notes/errors.py

@@ -19,24 +19,24 @@ class AnalystNoteError(RecordedFutureError):
 
 
 class AnalystNoteLookupError(RecordedFutureError):
-    """Error raise when cannot lookup an analyst note."""
+    """Raised when an analyst note cannot be retrieved."""
 
 
 class AnalystNoteSearchError(RecordedFutureError):
-    """Error raise when cannot search analyst notes."""
+    """Raised when an analyst note cannot be searched."""
 
 
 class AnalystNoteAttachmentError(RecordedFutureError):
-    """Error raise when cannot lookup an analyst note."""
+    """Raised when an analyst note attachment cannot be retrieved."""
 
 
 class AnalystNoteDeleteError(RecordedFutureError):
-    """Error raise when cannot delete an analyst note."""
+    """Raised when an analyst note cannot be deleted."""
 
 
 class AnalystNotePreviewError(RecordedFutureError):
-    """Error raise when cannot post to preview endpoint."""
+    """Raised when an analyst note cannot be previewed."""
 
 
 class AnalystNotePublishError(RecordedFutureError):
-    """Error raise when cannot post to publish endpoint."""
+    """Raised when an analyst note cannot be published."""

{psengine-2.2.0 → psengine-2.3.0}/psengine/base_http_client.py

@@ -97,7 +97,7 @@ class BaseHTTPClient:
         self,
         method: Annotated[str, Doc('An HTTP method.')],
         url: Annotated[str, Doc('A URL to make the request to.')],
-        data: Annotated[Union[dict, list[dict], None], Doc('A request body.')] = None,
+        data: Annotated[Union[dict, list[dict], bytes, None], Doc('A request body.')] = None,
         *,
         params: Annotated[Union[dict, None], Doc('HTTP query parameters.')] = None,
         headers: Annotated[
@@ -124,7 +124,8 @@ class BaseHTTPClient:
         if 'User-Agent' not in headers:
             headers['User-Agent'] = self._get_user_agent_header()
 
-        data = json.dumps(data) if data is not None else None
+        if not isinstance(data, bytes):
+            data = json.dumps(data) if data is not None else None
 
         try:
             response = method_func(

{psengine-2.2.0 → psengine-2.3.0}/psengine/endpoints.py

@@ -45,6 +45,9 @@ EP_CLASSIC_ALERTS_ID = EP_CLASSIC_ALERTS_V3 + '/alerts/{}'
 EP_RISKLIST = f'{BASE_URL}/{API_VERSION}/' + '{}/risklist'
 EP_FUSION_FILES = CONNECT_API_BASE_URL + '/fusion/files'
 
+EP_FUSION_FILES_V3 = f'{BASE_URL}/fusion/v3/files/'
+EP_FUSION_DIR_V3 = f'{BASE_URL}/fusion/v3/files/directory/'
+
 ###############################################################################
 # Playbook Alert Endpoints
 ###############################################################################
@@ -111,3 +114,15 @@ EP_IDENTITY_IP_LOOKUP = EP_IDENTITY + 'ip/lookup'
 EP_IDENTITY_CREDENTIALS_SEARCH = EP_IDENTITY + 'credentials/search'
 EP_IDENTITY_CREDENTIALS_LOOKUP = EP_IDENTITY + 'credentials/lookup'
 EP_IDENTITY_DUMP_SEARCH = EP_IDENTITY + 'metadata/dump/search'
+
+###############################################################################
+# Malware Intelligence API Endpoints
+###############################################################################
+EP_MALWARE_INTELLIGENCE = BASE_URL + '/malware-intelligence/v1/'
+EP_MALWARE_INTEL_REPORTS = EP_MALWARE_INTELLIGENCE + 'reports'
+
+###############################################################################
+# Risk History API Endpoints
+###############################################################################
+EP_RISK_HISTORY_BASE = BASE_URL + '/risk'
+EP_RISK_HISTORY = EP_RISK_HISTORY_BASE + '/history'

psengine-2.3.0/psengine/fusion/__init__.py

@@ -0,0 +1,22 @@
+##################################### TERMS OF USE ###########################################
+# The following code is provided for demonstration purpose only, and should not be used      #
+# without independent verification. Recorded Future makes no representations or warranties,  #
+# express, implied, statutory, or otherwise, regarding any aspect of this code or of the     #
+# information it may retrieve, and provides it both strictly “as-is” and without assuming    #
+# responsibility for any information it may retrieve. Recorded Future shall not be liable    #
+# for, and you assume all risk of using, the foregoing. By using this code, Customer         #
+# represents that it is solely responsible for having all necessary licenses, permissions,   #
+# rights, and/or consents to connect to third party APIs, and that it is solely responsible  #
+# for having all necessary licenses, permissions, rights, and/or consents to any data        #
+# accessed from any third party API.                                                         #
+##############################################################################################
+
+from .errors import (
+    FusionDeleteFileError,
+    FusionGetFileError,
+    FusionHeadFileError,
+    FusionListDirError,
+    FusionPostFileError,
+)
+from .fusion_mgr import FusionMgr
+from .models import DirectoryListOut, FileDeleteOut, FileGetOut, FileHeadOut, FileInfoOut

psengine-2.3.0/psengine/fusion/errors.py

@@ -0,0 +1,34 @@
+##################################### TERMS OF USE ###########################################
+# The following code is provided for demonstration purpose only, and should not be used      #
+# without independent verification. Recorded Future makes no representations or warranties,  #
+# express, implied, statutory, or otherwise, regarding any aspect of this code or of the     #
+# information it may retrieve, and provides it both strictly “as-is” and without assuming    #
+# responsibility for any information it may retrieve. Recorded Future shall not be liable    #
+# for, and you assume all risk of using, the foregoing. By using this code, Customer         #
+# represents that it is solely responsible for having all necessary licenses, permissions,   #
+# rights, and/or consents to connect to third party APIs, and that it is solely responsible  #
+# for having all necessary licenses, permissions, rights, and/or consents to any data        #
+# accessed from any third party API.                                                         #
+##############################################################################################
+
+from ..errors import RecordedFutureError
+
+
+class FusionGetFileError(RecordedFutureError):
+    """Error raise when the get file operation fails."""
+
+
+class FusionHeadFileError(RecordedFutureError):
+    """Error raise when the head file operation fails."""
+
+
+class FusionPostFileError(RecordedFutureError):
+    """Error raise when the post file operation fails."""
+
+
+class FusionDeleteFileError(RecordedFutureError):
+    """Error raise when the delete file operation fails."""
+
+
+class FusionListDirError(RecordedFutureError):
+    """Error raise when the list dir operation fails."""

psengine-2.3.0/psengine/fusion/fusion_mgr.py

@@ -0,0 +1,197 @@
+##################################### TERMS OF USE ###########################################
+# The following code is provided for demonstration purpose only, and should not be used      #
+# without independent verification. Recorded Future makes no representations or warranties,  #
+# express, implied, statutory, or otherwise, regarding any aspect of this code or of the     #
+# information it may retrieve, and provides it both strictly “as-is” and without assuming    #
+# responsibility for any information it may retrieve. Recorded Future shall not be liable    #
+# for, and you assume all risk of using, the foregoing. By using this code, Customer         #
+# represents that it is solely responsible for having all necessary licenses, permissions,   #
+# rights, and/or consents to connect to third party APIs, and that it is solely responsible  #
+# for having all necessary licenses, permissions, rights, and/or consents to any data        #
+# accessed from any third party API.                                                         #
+##############################################################################################
+
+import logging
+from pathlib import Path
+from typing import Annotated, Union
+from urllib.parse import quote
+
+from pydantic import validate_call
+from typing_extensions import Doc
+
+from ..endpoints import EP_FUSION_DIR_V3, EP_FUSION_FILES_V3
+from ..helpers import debug_call
+from ..helpers.helpers import connection_exceptions
+from ..rf_client import RFClient
+from .errors import (
+    FusionDeleteFileError,
+    FusionGetFileError,
+    FusionHeadFileError,
+    FusionListDirError,
+    FusionPostFileError,
+)
+from .models import DirectoryListOut, FileDeleteOut, FileGetOut, FileHeadOut, FileInfoOut
+
+
+class FusionMgr:
+    """Manages requests for Recorded Future Fusion files."""
+
+    def __init__(self, rf_token: str = None):
+        """Initializes the `FusionMgr` object.
+
+        Args:
+            rf_token (str, optional): Recorded Future API token.
+        """
+        self.log = logging.getLogger(__name__)
+        self.rf_client = RFClient(api_token=rf_token) if rf_token else RFClient()
+
+    @debug_call
+    @validate_call
+    @connection_exceptions(ignore_status_code=[], exception_to_raise=FusionGetFileError)
+    def get_files(
+        self, file_paths: Annotated[Union[str, list[str]], Doc('One or more paths to fetch')]
+    ) -> Annotated[list[FileGetOut], Doc('A FusionFile object with name and content of the file')]:
+        """Get one or more files.
+
+        Endpoint:
+            `/fusion/v3/files/`
+
+        Raises:
+            ValidationError: If any supplied parameter is of incorrect type.
+            FusionGetFileError: If API error occurs.
+        """
+        returned_files = []
+        file_paths = file_paths if isinstance(file_paths, list) else [file_paths]
+        file_paths = [f'/{p}' if not p.startswith('/') else p for p in file_paths]
+
+        for file in file_paths:
+            data = self._get_file(file)
+            if data:
+                returned_files.append(
+                    FileGetOut.model_validate(
+                        {'path': file, 'content': data.content, 'exists': True}
+                    )
+                )
+            else:
+                returned_files.append(
+                    FileGetOut.model_validate({'path': file, 'content': '', 'exists': False})
+                )
+
+        return returned_files
+
+    @debug_call
+    @validate_call
+    @connection_exceptions(ignore_status_code=[], exception_to_raise=FusionPostFileError)
+    def post_file(
+        self,
+        file_path: Annotated[Path, Doc('Path of the local file')],
+        fusion_path: Annotated[str, Doc('Path of the fusion file')],
+    ) -> Annotated[list[FileInfoOut], Doc('Info of the file that have been posted')]:
+        """Post a file.
+
+        Endpoint:
+            `/fusion/v3/files/`
+
+        Raises:
+            ValidationError: If any supplied parameter is of incorrect type.
+            FusionPostFileError: If API error occurs or the input file cannot be read.
+        """
+        if not file_path.exists():
+            raise FusionPostFileError(f'The file {file_path} does not exist')
+
+        data = file_path.read_bytes()
+
+        headers = 'application/octet-stream'
+        returned_data = self.rf_client.request(
+            'post',
+            EP_FUSION_FILES_V3 + quote(fusion_path, safe='.'),
+            data=data,
+            content_type_header=headers,
+        ).json()
+
+        return FileInfoOut.model_validate(returned_data)
+
+    @debug_call
+    @validate_call
+    def delete_files(
+        self, file_paths: Annotated[Union[str, list[str]], Doc('One or more paths to delete')]
+    ) -> Annotated[list[FileDeleteOut], Doc('A list of deleted files.')]:
+        """Delete one or more files.
+
+        Endpoint:
+            `/fusion/v3/files/`
+
+        Raises:
+            ValidationError: If any supplied parameter is of incorrect type.
+            FusionDeleteFileError: If API error occurs.
+        """
+        returned_files = []
+        file_paths = file_paths if isinstance(file_paths, list) else [file_paths]
+        file_paths = [f'/{p}' if not p.startswith('/') else p for p in file_paths]
+
+        for file in file_paths:
+            data = self._delete_file(file)
+            returned_files.append(
+                FileDeleteOut.model_validate({'path': file, 'deleted': bool(data)})
+            )
+
+        return returned_files
+
+    @debug_call
+    @validate_call
+    def head_files(
+        self, file_paths: Annotated[Union[str, list[str]], Doc('One or more paths to check')]
+    ) -> Annotated[list[FileHeadOut], Doc('List of headers info for the requested files.')]:
+        """Head of one or more files.
+
+        Endpoint:
+            `/fusion/v3/files/`
+
+        Raises:
+            ValidationError: If any supplied parameter is of incorrect type.
+            FusionHeadFileError: If API error occurs.
+        """
+        returned_files = []
+        file_paths = file_paths if isinstance(file_paths, list) else [file_paths]
+        file_paths = [f'/{p}' if not p.startswith('/') else p for p in file_paths]
+
+        for file in file_paths:
+            data = self._head_file(file)
+            if data:
+                returned_files.append(
+                    FileHeadOut.model_validate({'path': file, 'exists': True, **data.headers})
+                )
+            else:
+                returned_files.append(FileHeadOut.model_validate({'path': file, 'exists': False}))
+
+        return returned_files
+
+    @debug_call
+    @validate_call
+    @connection_exceptions(ignore_status_code=[], exception_to_raise=FusionListDirError)
+    def list_dir(
+        self, file_path: Annotated[str, Doc('Directory to list')]
+    ) -> Annotated[DirectoryListOut, Doc('The tree structure.')]:
+        """Get directory, subdirectory and file information of a path.
+
+        Endpoint:
+            `/fusion/v3/files/directory`
+
+        Raises:
+            ValidationError: If any supplied parameter is of incorrect type.
+            FusionListDirError: If API error occurs.
+        """
+        data = self.rf_client.request('get', EP_FUSION_DIR_V3 + quote(file_path, safe='.')).json()
+        return DirectoryListOut.model_validate(data)
+
+    @connection_exceptions(ignore_status_code=[404], exception_to_raise=FusionHeadFileError)
+    def _head_file(self, file):
+        return self.rf_client.request('head', EP_FUSION_FILES_V3 + quote(file, safe='.'))
+
+    @connection_exceptions(ignore_status_code=[404], exception_to_raise=FusionDeleteFileError)
+    def _delete_file(self, file):
+        return self.rf_client.request('delete', EP_FUSION_FILES_V3 + quote(file, safe='.'))
+
+    @connection_exceptions(ignore_status_code=[404], exception_to_raise=FusionGetFileError)
+    def _get_file(self, file):
+        return self.rf_client.request('get', EP_FUSION_FILES_V3 + quote(file, safe='.'))

psengine-2.3.0/psengine/fusion/models.py

@@ -0,0 +1,59 @@
+##################################### TERMS OF USE ###########################################
+# The following code is provided for demonstration purpose only, and should not be used      #
+# without independent verification. Recorded Future makes no representations or warranties,  #
+# express, implied, statutory, or otherwise, regarding any aspect of this code or of the     #
+# information it may retrieve, and provides it both strictly “as-is” and without assuming    #
+# responsibility for any information it may retrieve. Recorded Future shall not be liable    #
+# for, and you assume all risk of using, the foregoing. By using this code, Customer         #
+# represents that it is solely responsible for having all necessary licenses, permissions,   #
+# rights, and/or consents to connect to third party APIs, and that it is solely responsible  #
+# for having all necessary licenses, permissions, rights, and/or consents to any data        #
+# accessed from any third party API.                                                         #
+##############################################################################################
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import Field
+
+from ..common_models import RFBaseModel
+
+
+class FileInfoOut(RFBaseModel):
+    type_: str = Field(alias='type')
+    name: str
+    path: str
+    format: Optional[str] = None
+    hash: Optional[str] = None
+    created: Optional[datetime] = None
+    size: Optional[int] = None
+    flow: Optional[str] = None
+    owner: Optional[str] = None
+
+
+class DirectoryListOut(RFBaseModel):
+    name: str
+    path: str
+    files: list[FileInfoOut]
+    type_: str = Field(alias='type')
+
+
+class FileGetOut(RFBaseModel):
+    path: str
+    content: bytes
+    exists: bool
+
+
+class FileDeleteOut(RFBaseModel):
+    path: str
+    deleted: bool
+
+
+class FileHeadOut(RFBaseModel):
+    path: str
+    exists: bool
+    content_disposition: Optional[str] = Field(alias='content-disposition', default=None)
+    content_length: Optional[int] = Field(alias='Content-Length', default=None)
+    content_type: Optional[str] = Field(alias='content-type', default=None)
+    etag: Optional[str] = None
+    last_modified: Optional[str] = Field(alias='last-modified', default=None)

psengine-2.3.0/psengine/malware_intel/__init__.py

@@ -0,0 +1,16 @@
+##################################### TERMS OF USE ###########################################
+# The following code is provided for demonstration purpose only, and should not be used      #
+# without independent verification. Recorded Future makes no representations or warranties,  #
+# express, implied, statutory, or otherwise, regarding any aspect of this code or of the     #
+# information it may retrieve, and provides it both strictly “as-is” and without assuming    #
+# responsibility for any information it may retrieve. Recorded Future shall not be liable    #
+# for, and you assume all risk of using, the foregoing. By using this code, Customer         #
+# represents that it is solely responsible for having all necessary licenses, permissions,   #
+# rights, and/or consents to connect to third party APIs, and that it is solely responsible  #
+# for having all necessary licenses, permissions, rights, and/or consents to any data        #
+# accessed from any third party API.                                                         #
+##############################################################################################
+
+from .errors import MalwareIntelReportError
+from .malware_intel import SandboxReport
+from .malware_intel_mgr import MalwareIntelMgr

psengine-2.3.0/psengine/malware_intel/errors.py

@@ -0,0 +1,18 @@
+##################################### TERMS OF USE ###########################################
+# The following code is provided for demonstration purpose only, and should not be used      #
+# without independent verification. Recorded Future makes no representations or warranties,  #
+# express, implied, statutory, or otherwise, regarding any aspect of this code or of the     #
+# information it may retrieve, and provides it both strictly “as-is” and without assuming    #
+# responsibility for any information it may retrieve. Recorded Future shall not be liable    #
+# for, and you assume all risk of using, the foregoing. By using this code, Customer         #
+# represents that it is solely responsible for having all necessary licenses, permissions,   #
+# rights, and/or consents to connect to third party APIs, and that it is solely responsible  #
+# for having all necessary licenses, permissions, rights, and/or consents to any data        #
+# accessed from any third party API.                                                         #
+##############################################################################################
+
+from ..errors import RecordedFutureError
+
+
+class MalwareIntelReportError(RecordedFutureError):
+    """Error raise when the reports operation fails."""

psengine-2.3.0/psengine/malware_intel/malware_intel.py

@@ -0,0 +1,107 @@
+##################################### TERMS OF USE ###########################################
+# The following code is provided for demonstration purpose only, and should not be used      #
+# without independent verification. Recorded Future makes no representations or warranties,  #
+# express, implied, statutory, or otherwise, regarding any aspect of this code or of the     #
+# information it may retrieve, and provides it both strictly “as-is” and without assuming    #
+# responsibility for any information it may retrieve. Recorded Future shall not be liable    #
+# for, and you assume all risk of using, the foregoing. By using this code, Customer         #
+# represents that it is solely responsible for having all necessary licenses, permissions,   #
+# rights, and/or consents to connect to third party APIs, and that it is solely responsible  #
+# for having all necessary licenses, permissions, rights, and/or consents to any data        #
+# accessed from any third party API.                                                         #
+##############################################################################################
+
+from functools import total_ordering
+from typing import Annotated, Optional
+
+from pydantic import AfterValidator, BeforeValidator, Field
+
+from ..common_models import RFBaseModel
+from ..helpers.helpers import Validators
+from .models import DynamicInfo, Metadata, PEInfo, SampleInfo, StaticInfo
+
+
+@total_ordering
+class SandboxReport(RFBaseModel):
+    """Validate data received from the `/v1/reports` endpoint.
+
+    This class supports hashing, equality comparison, string representation, and total ordering
+    of `SandboxReport` instances.
+
+    Hashing:
+        Returns a hash value based on the report `file`, `task`, `sample.completed`.
+
+    Equality:
+        Checks equality between two `SandboxReport` instances by `id_` when both are present;
+        otherwise falls back to comparing (`file`, `task`, `sample.completed`).
+
+    Greater-than Comparison:
+        Defines a greater-than comparison between two `SandboxReport` instances based on the sample
+        completed time, then created time, and finally the `file` name.
+
+    String Representation:
+        Returns a string representation of the `SandboxReport` instance including the `file`,
+        `score`, `task`, and created timestamp.
+
+
+        ```python
+        >>> print(report)
+        Sandbox Report of: sample.exe, Score: 85, Task: behavioural1, Submitted: 2024-05-21 10:42:30
+        ```
+    Ordering:
+        The ordering of `SandboxReport` instances is determined primarily by the sample completed
+        time. If two instances have the same completed time, the created time is used as a secondary
+        criterion, followed by the report `file` name.
+    """
+
+    file: str
+    id_: Optional[str] = None
+    task: str
+    dynamic: DynamicInfo
+    metadata: Metadata
+    pe: Optional[PEInfo] = None
+    sample: SampleInfo
+    static: StaticInfo
+
+    def __hash__(self):
+        return hash((self.file, self.task, self.sample.completed))
+
+    def __eq__(self, other: 'SandboxReport'):
+        return (self.file, self.task, self.sample.completed) == (
+            other.file,
+            other.task,
+            other.sample.completed,
+        )
+
+    def __gt__(self, other: 'SandboxReport'):
+        if self.sample.completed and other.sample.completed:
+            return self.sample.completed > other.sample.completed
+
+        if self.sample.created and other.sample.created:
+            return self.sample.created > other.sample.created
+
+        return self.file > other.file
+
+    def __str__(self):
+        return 'Sandbox Report of: {}, Score: {}, Task: {}, Submitted: {}'.format(
+            self.file, self.sample.score or 'N/A', self.task, self.sample.created or 'N/A'
+        )
+
+
+def _split_time(value: str):
+    return value.split('T')[0]
+
+
+class MalwareReportIn(RFBaseModel):
+    """Validate data sent to the `/v1/reports` endpoint."""
+
+    query: str
+    sha256: str
+    start_date: Annotated[
+        str, BeforeValidator(Validators.convert_relative_time), AfterValidator(_split_time)
+    ]
+    end_date: Annotated[
+        str, BeforeValidator(Validators.convert_relative_time), AfterValidator(_split_time)
+    ]
+    my_enterprise: bool
+    limit: int = Field(ge=1, le=10)