psengine 2.2.0__tar.gz → 2.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: psengine
-Version: 2.2.0
+Version: 2.3.1
 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.1}/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.1}/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.1}/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.1}/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.1}/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.2.0 → psengine-2.3.1}/psengine/enrich/lookup.py

@@ -21,6 +21,7 @@ from .models.base_enriched_entity import BaseEnrichedEntity
 from .models.lookup import (
     CVSS,
     CVSSV3,
+    CVSSV4,
     CVSSRating,
     DnsPortCert,
     EnterpriseList,
@@ -103,6 +104,7 @@ class EnrichedVulnerability(BaseEnrichedEntity):
     cvss: Optional[CVSS] = None
     cvss_ratings: list[CVSSRating] = Field(alias='cvssRatings', default=None)
     cvssv3: Optional[CVSSV3] = None
+    cvssv4: Optional[CVSSV4] = None
     nvd_description: Optional[str] = Field(alias='nvdDescription', default=None)
     nvd_references: Optional[list[NvdReference]] = Field(alias='nvdReferences', default=None)
     raw_risk: Optional[list[RawRisk]] = Field(alias='rawrisk', default=None)

{psengine-2.2.0 → psengine-2.3.1}/psengine/enrich/models/lookup.py

@@ -206,6 +206,50 @@ class CVSSV3(RFBaseModel):
     availability_impact: Optional[str] = Field(alias='availabilityImpact', default=None)
 
 
+class CVSSV4(RFBaseModel):
+    subsequent_system_integrity: Optional[str] = Field(
+        alias='subsequentSystemIntegrity', default=None
+    )
+    provider_urgency: Optional[str] = Field(alias='providerUrgency', default=None)
+    attack_requirements: Optional[str] = Field(alias='attackRequirements', default=None)
+    vulnerable_system_confidentiality: Optional[str] = Field(
+        alias='vulnerableSystemConfidentiality', default=None
+    )
+    vulnerability_response_effort: Optional[str] = Field(
+        alias='vulnerabilityResponseEffort', default=None
+    )
+    threat_score: Optional[float] = Field(alias='threatScore', default=None)
+    subsequent_system_availability: Optional[str] = Field(
+        alias='subsequentSystemAvailability', default=None
+    )
+    base_severity: Optional[str] = Field(alias='baseSeverity', default=None)
+    base_score: Optional[float] = Field(alias='baseScore', default=None)
+    user_interaction: Optional[str] = Field(alias='userInteraction', default=None)
+    attack_vector: Optional[str] = Field(alias='attackVector', default=None)
+    source: Optional[str] = None
+    vulnerable_system_integrity: Optional[str] = Field(
+        alias='vulnerableSystemIntegrity', default=None
+    )
+    vulnerable_system_availability: Optional[str] = Field(
+        alias='vulnerableSystemAvailability', default=None
+    )
+    modified: Optional[datetime] = None
+    vector_string: Optional[str] = Field(alias='vectorString', default=None)
+    recovery: Optional[str] = None
+    version: Optional[str] = None
+    threat_severity: Optional[str] = Field(alias='threatSeverity', default=None)
+    privileges_required: Optional[str] = Field(alias='privilegesRequired', default=None)
+    exploit_maturity: Optional[str] = Field(alias='exploitMaturity', default=None)
+    safety: Optional[str] = None
+    subsequent_system_confidentiality: Optional[str] = Field(
+        alias='subsequentSystemConfidentiality', default=None
+    )
+    automatable: Optional[str] = None
+    value_density: Optional[str] = Field(alias='valueDensity', default=None)
+    attack_complexity: Optional[str] = Field(alias='attackComplexity', default=None)
+    created: Optional[datetime] = None
+
+
 ###########################################################
 # Raw Risk
 ###########################################################

psengine-2.3.1/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.1/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.1/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.1/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.1/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.1/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."""