psengine 2.6.0__tar.gz → 2.8.0__tar.gz

{psengine-2.6.0 → psengine-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: psengine
-Version: 2.6.0
+Version: 2.8.0
 Summary: psengine is a simple, yet elegant, library for rapid development of integrations with Recorded Future.
 Keywords: API,Recorded Future,Cyber Security Engineering,Threat Intelligence
 Author: Moise Medici, Patrick Kinsella, Ernest Bartosevic
@@ -18,12 +18,12 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: typing-extensions>=4.8.0
 Requires-Dist: requests>=2.27.1
-Requires-Dist: jsonpath-ng>=1.5.3,<=1.6.1
+Requires-Dist: jsonpath-ng>=1.5.3,<=1.8.0
 Requires-Dist: stix2~=3.0.1
 Requires-Dist: python-dateutil>=2.7.0
-Requires-Dist: more-itertools>=9.0.0,<=10.2.0
+Requires-Dist: more-itertools>=9.0.0,<=11.0.2
 Requires-Dist: pydantic>=2.7,<3.0.0
-Requires-Dist: pydantic-settings[toml]>=2.12.2,<2.13.1
+Requires-Dist: pydantic-settings[toml]>=2.12.2,<2.14.1
 Requires-Dist: markdown-strings==3.4.0
 Requires-Python: >=3.10, <3.15
 Project-URL: Homepage, https://recordedfuture-professionalservices.github.io/psengine/latest/
@@ -42,7 +42,7 @@ PSEngine is a simple, yet elegant, library for rapid development of integrations
 
 PSEngine allows you to interact with the Recorded Future API extremely easily. There’s no need to manually build the URLs and query parameters, just use the modules dedicated to individual API endpoints.
 
-PSEngine is a Python package solely built and maintained by the Recorded Future Cyber Security Engineering team powering a number of high profile integrations, such as: [Banshee](https://recordedfuture-professionalservices.github.io/banshee); [Recorded Future Alerts for QRadar](https://apps.xforce.ibmcloud.com/extension/b36efdf42b7bf5e3759d036dbcdbf606); Anomali ThreatStream: [Alerts](https://support.recordedfuture.com/hc/en-us/articles/29255683708691-Recorded-Future-Alerts-for-Anomali-ThreatStream) and [Analyst Notes](https://support.recordedfuture.com/hc/en-us/articles/12928414947475-Recorded-Future-Analyst-Notes-for-Anomali-ThreatStream) integrations; [Google SecOps](https://app.recordedfuture.com/portal/integration-center/detail/google-chronicle-nbfi?organization=uhash%3A5cJsHMHeSM&filter_tab=all) and many more.
+PSEngine is a Python package solely built and maintained by the Recorded Future Cyber Security Engineering team powering a number of high profile integrations, such as: [PS Banshee](https://recordedfuture-professionalservices.github.io/ps-banshee/latest/); [Recorded Future Alerts for QRadar](https://apps.xforce.ibmcloud.com/extension/b36efdf42b7bf5e3759d036dbcdbf606); Anomali ThreatStream: [Alerts](https://support.recordedfuture.com/hc/en-us/articles/29255683708691-Recorded-Future-Alerts-for-Anomali-ThreatStream) and [Analyst Notes](https://support.recordedfuture.com/hc/en-us/articles/12928414947475-Recorded-Future-Analyst-Notes-for-Anomali-ThreatStream) integrations; [Google SecOps](https://app.recordedfuture.com/portal/integration-center/detail/google-chronicle-nbfi?organization=uhash%3A5cJsHMHeSM&filter_tab=all) and many more.
 
 
 ## Installation

{psengine-2.6.0 → psengine-2.8.0}/README.md

@@ -10,7 +10,7 @@ PSEngine is a simple, yet elegant, library for rapid development of integrations
 
 PSEngine allows you to interact with the Recorded Future API extremely easily. There’s no need to manually build the URLs and query parameters, just use the modules dedicated to individual API endpoints.
 
-PSEngine is a Python package solely built and maintained by the Recorded Future Cyber Security Engineering team powering a number of high profile integrations, such as: [Banshee](https://recordedfuture-professionalservices.github.io/banshee); [Recorded Future Alerts for QRadar](https://apps.xforce.ibmcloud.com/extension/b36efdf42b7bf5e3759d036dbcdbf606); Anomali ThreatStream: [Alerts](https://support.recordedfuture.com/hc/en-us/articles/29255683708691-Recorded-Future-Alerts-for-Anomali-ThreatStream) and [Analyst Notes](https://support.recordedfuture.com/hc/en-us/articles/12928414947475-Recorded-Future-Analyst-Notes-for-Anomali-ThreatStream) integrations; [Google SecOps](https://app.recordedfuture.com/portal/integration-center/detail/google-chronicle-nbfi?organization=uhash%3A5cJsHMHeSM&filter_tab=all) and many more.
+PSEngine is a Python package solely built and maintained by the Recorded Future Cyber Security Engineering team powering a number of high profile integrations, such as: [PS Banshee](https://recordedfuture-professionalservices.github.io/ps-banshee/latest/); [Recorded Future Alerts for QRadar](https://apps.xforce.ibmcloud.com/extension/b36efdf42b7bf5e3759d036dbcdbf606); Anomali ThreatStream: [Alerts](https://support.recordedfuture.com/hc/en-us/articles/29255683708691-Recorded-Future-Alerts-for-Anomali-ThreatStream) and [Analyst Notes](https://support.recordedfuture.com/hc/en-us/articles/12928414947475-Recorded-Future-Analyst-Notes-for-Anomali-ThreatStream) integrations; [Google SecOps](https://app.recordedfuture.com/portal/integration-center/detail/google-chronicle-nbfi?organization=uhash%3A5cJsHMHeSM&filter_tab=all) and many more.
 
 
 ## Installation

{psengine-2.6.0 → psengine-2.8.0}/psengine/analyst_notes/markdown.py

@@ -36,9 +36,12 @@ EXTRACTED_KEYS = {
 
 def _cleanup_insikt_note_text(note_text: str) -> str:
     """Clean up insikt note text to avoid markdown rendering issues."""
+    note_text = ''.join(
+        line if line.lstrip().startswith('|') else re.sub(r'--+', '', line)
+        for line in note_text.splitlines(keepends=True)
+    )
     translation = {
         r'\•': '+ ',
-        r'--+': '',
         r'>>+': '',
         r'<<+': '',
         r'\*\*': '••',

{psengine-2.6.0 → psengine-2.8.0}/psengine/analyst_notes/note.py

@@ -80,9 +80,9 @@ class AnalystNote(RFBaseModel):
     @property
     def detection_rule_type(self) -> str | None:
         """Returns the attachment type if present, else None. It checks for specific types like
-        `sigma rule`, `yara rule`, and `snort rule` in the topics of the note.
+        `sigma rule`, `yara rule`, `snort rule` and `suricata rule` in the topics of the note.
         """
-        topics_type = ('sigma rule', 'yara rule', 'snort rule')
+        topics_type = ('sigma rule', 'yara rule', 'snort rule', 'suricata rule')
 
         topics = (
             {topic.name.lower() for topic in self.attributes.topic if topic.name}

{psengine-2.6.0 → psengine-2.8.0}/psengine/analyst_notes/note_mgr.py

@@ -53,12 +53,11 @@ from .note import (
 class AnalystNoteMgr:
     """Manages requests for Recorded Future analyst notes."""
 
-    def __init__(self, rf_token: str = None):
-        """Initializes the `AnalystNoteMgr` object.
-
-        Args:
-            rf_token (str, optional): Recorded Future API token.
-        """
+    def __init__(
+        self,
+        rf_token: Annotated[str | None, Doc('Recorded Future API token.')] = None,
+    ):
+        """Initializes the `AnalystNoteMgr` object."""
         self.log = logging.getLogger(__name__)
         self.rf_client = RFClient(api_token=rf_token) if rf_token else RFClient()
 

{psengine-2.6.0 → psengine-2.8.0}/psengine/asi/asi_mgr.py

@@ -95,12 +95,11 @@ _ASSET_SEARCH_QUERY_MAP: dict[str, tuple[str, str, callable]] = {
 class AttackSurfaceMgr:
     """Manages requests for Recorded Future SecurityTrails (ASI) API."""
 
-    def __init__(self, api_token: str = None):
-        """Initializes the `AttackSurfaceMgr` object.
-
-        Args:
-            api_token (str, optional): ASI API token.
-        """
+    def __init__(
+        self,
+        api_token: Annotated[str | None, Doc('ASI API token.')] = None,
+    ):
+        """Initializes the `AttackSurfaceMgr` object."""
         self.log = logging.getLogger(__name__)
         self.asi_client = ASIClient(api_token=api_token) if api_token else ASIClient()
 

{psengine-2.6.0 → psengine-2.8.0}/psengine/classic_alerts/classic_alert_mgr.py

@@ -43,12 +43,11 @@ from .errors import (
 class ClassicAlertMgr:
     """Alert Manager for Classic Alert (v3) API."""
 
-    def __init__(self, rf_token: str = None):
-        """Initializes the ClassicAlertMgr object.
-
-        Args:
-            rf_token (str, optional): Recorded Future API token.
-        """
+    def __init__(
+        self,
+        rf_token: Annotated[str | None, Doc('Recorded Future API token.')] = None,
+    ):
+        """Initializes the ClassicAlertMgr object."""
         self.log = logging.getLogger(__name__)
         self.rf_client = RFClient(api_token=rf_token) if rf_token else RFClient()
 

{psengine-2.6.0 → psengine-2.8.0}/psengine/classic_alerts/models.py

@@ -94,7 +94,7 @@ class AlertCounts(RFBaseModel):
 
 class NotificationSettings(RFBaseModel):
     email_subscribers: list[IdName]
-    mobile_subsribers: list[IdName] | None = None
+    mobile_subscribers: list[IdName] | None = None
 
 
 class Evidence(RFBaseModel):

{psengine-2.6.0 → psengine-2.8.0}/psengine/collective_insights/collective_insights.py

@@ -29,12 +29,11 @@ from .insight import Insight, InsightsIn, InsightsOut
 class CollectiveInsights:
     """Class for interacting with the Recorded Future Collective Insights API."""
 
-    def __init__(self, rf_token: str = None):
-        """Initializes the CollectiveInsights object.
-
-        Args:
-            rf_token (str, optional): Recorded Future API token.
-        """
+    def __init__(
+        self,
+        rf_token: Annotated[str | None, Doc('Recorded Future API token.')] = None,
+    ):
+        """Initializes the CollectiveInsights object."""
         self.log = logging.getLogger(__name__)
         self.rf_client = RFClient(api_token=rf_token) if rf_token else RFClient()
 

{psengine-2.6.0 → psengine-2.8.0}/psengine/endpoints.py

@@ -136,6 +136,16 @@ EP_AUTO_SIGMA_JOB_ID_RETRY = EP_AUTO_SIGMA_JOB_ID + '/retry'
 EP_RISK_HISTORY_BASE = BASE_URL + '/risk'
 EP_RISK_HISTORY = EP_RISK_HISTORY_BASE + '/history'
 
+###############################################################################
+# Links API Endpoints
+###############################################################################
+LINKS_BASE_URL = f'{BASE_URL}/links'
+LINKS_METADATA_URL = f'{LINKS_BASE_URL}/metadata'
+EP_LINKS_SEARCH = f'{LINKS_BASE_URL}/search'
+EP_LINKS_METADATA_SECTIONS = f'{LINKS_METADATA_URL}/sections'
+EP_LINKS_METADATA_EVENTS = f'{LINKS_METADATA_URL}/events'
+EP_LINKS_METADATA_ENTITIES = f'{LINKS_METADATA_URL}/entities'
+
 ################################################################################
 # Attack Surface Intelligence API Endpoints
 ################################################################################
@@ -147,3 +157,13 @@ EP_ASI_ASSET_EXPOSURES = f'{EP_ASI_ASSETS}/{{}}/exposures'
 EP_ASI_ASSETS_SEARCH = f'{EP_ASI_ASSETS}/_search'
 EP_ASI_EXPOSURES = f'{EP_ASI_PROJECTS}/{{}}/exposures'
 EP_ASI_EXPOSURES_BY_SIGNATURE = f'{EP_ASI_EXPOSURES}/{{}}'
+
+################################################################################
+# Threat Map API Endpoints
+################################################################################
+EP_THREAT_MAPS_BASE = BASE_URL + '/threat'
+EP_THREAT_MAPS_LIST = EP_THREAT_MAPS_BASE + '/maps'
+EP_THREAT_MAP = EP_THREAT_MAPS_BASE + '/map/{}'
+EP_THREAT_MAP_ORG = EP_THREAT_MAPS_BASE + '/map/{}/{}'
+EP_ACTOR_SEARCH = EP_THREAT_MAPS_BASE + '/actor/search'
+EP_CATEGORIES = EP_THREAT_MAPS_BASE + '/{}/categories'

{psengine-2.6.0 → psengine-2.8.0}/psengine/fusion/fusion_mgr.py

@@ -36,12 +36,11 @@ from .models import DirectoryListOut, FileDeleteOut, FileGetOut, FileHeadOut, Fi
 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.
-        """
+    def __init__(
+        self,
+        rf_token: Annotated[str | None, Doc('Recorded Future API token.')] = None,
+    ):
+        """Initializes the `FusionMgr` object."""
         self.log = logging.getLogger(__name__)
         self.rf_client = RFClient(api_token=rf_token) if rf_token else RFClient()
 

{psengine-2.6.0 → psengine-2.8.0}/psengine/helpers/helpers.py

@@ -325,10 +325,10 @@ class OSHelpers:
         try:
             path.mkdir(parents=True, exist_ok=True)
         except PermissionError as err:
-            raise WriteFileError(f'Directory {path} is not writeable') from err
-        # In case it already exists, check if it is writeable
+            raise WriteFileError(f'Directory {path} is not writable') from err
+        # In case it already exists, check if it is writable
         if not os.access(path, os.W_OK):
-            raise WriteFileError(f'Directory {path} is not writeable')
+            raise WriteFileError(f'Directory {path} is not writable')
         return path
 
 
@@ -504,6 +504,15 @@ class Validators:
             else input_time
         )
 
+    @staticmethod
+    def is_rel_time_valid(
+        input_time: Annotated[str | None, Doc("Relative time string, e.g., '7d', '3h'.")],
+    ):
+        """Check that a relative time like `-3d` is valid."""
+        if input_time is not None and not TimeHelpers.is_rel_time_valid(input_time):
+            raise ValueError(f'Invalid relative time: {input_time}')
+        return input_time
+
     @staticmethod
     def check_uhash_prefix(
         value: Annotated[str | list, Doc('String or list of strings to check for uhash prefix.')],

psengine-2.8.0/psengine/links/__init__.py

@@ -0,0 +1,38 @@
+##################################### 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 (
+    LinksError,
+    LinksMetadataError,
+    LinksSearchError,
+)
+from .links import (
+    EntityLinks,
+    LinkedEntity,
+    LinkedIOC,
+    LinkedMalware,
+    LinkedTA,
+    LinkedTTP,
+)
+from .links_mgr import LinksMgr
+from .models import (
+    CriticalityAttribute,
+    EntityAttribute,
+    EntitySearchError,
+    GenericAttribute,
+    LinkSource,
+    MitreNameAttribute,
+    RiskAttribute,
+    SearchScope,
+    ThreatActorAttribute,
+)

psengine-2.8.0/psengine/links/errors.py

@@ -0,0 +1,26 @@
+##################################### 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 LinksError(RecordedFutureError):
+    """Base class for all exceptions raised by the Links module."""
+
+
+class LinksSearchError(LinksError):
+    """Error raised when a Links search request fails."""
+
+
+class LinksMetadataError(LinksError):
+    """Error raised when fetching or validating Links metadata fails."""

psengine-2.8.0/psengine/links/links.py

@@ -0,0 +1,152 @@
+##################################### 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 collections import defaultdict
+
+from ..common_models import IdNameType, RFBaseModel
+from .models import EntityAttribute, EntitySearchError, LinksFilterObjects, LinksLimitsObjects
+
+LINK_IOC_TYPE = [
+    'type:InternetDomainName',
+    'type:CyberVulnerability',
+    'type:IpAddress',
+    'type:Hash',
+    'type:Url',
+]
+
+
+class LinkedIOC(IdNameType):
+    """Return linked iocs entities."""
+
+    risk_score: int
+    source: str | None = None
+
+
+class LinkedTTP(IdNameType):
+    """Return linked TTPs entities."""
+
+    display_name: str
+    source: str | None = None
+
+
+class LinkedTA(IdNameType):
+    """Return linked threat actors entities."""
+
+    source: str | None = None
+
+
+class LinkedMalware(IdNameType):
+    """Return linked malware entities."""
+
+    source: str | None = None
+
+
+class LinkedEntity(IdNameType):
+    """An entity connected to the search target."""
+
+    source: str | None = None
+    section: str | None = None
+    attributes: list[EntityAttribute] = []
+
+
+class EntityLinks(RFBaseModel):
+    """The result set for a single entity that was queried."""
+
+    entity: IdNameType | None = None
+    links: list[LinkedEntity] = []
+    error: EntitySearchError | None = None
+
+    def iocs(self) -> list[LinkedIOC]:
+        """Return linked indicators of compromise grouped by IOC type."""
+        iocs = defaultdict(list)
+        for link in self.links:
+            if link.type_ in LINK_IOC_TYPE:
+                ioc_score = next(
+                    (attr.value for attr in link.attributes if attr.id_ == 'risk_score'),
+                    0,
+                )
+                iocs[link.type_].append(
+                    LinkedIOC(
+                        id=link.id_,
+                        type=link.type_,
+                        name=link.name,
+                        risk_score=ioc_score,
+                        source=link.source,
+                    )
+                )
+
+        return iocs
+
+    def ttps(self) -> list[LinkedTTP]:
+        """Return linked MITRE ATT&CK techniques and their display names."""
+        ttps = []
+        for link in self.links:
+            if link.type_ == 'type:MitreAttackIdentifier':
+                display_name = next(
+                    (attr.value for attr in link.attributes if attr.id_ == 'display_name'),
+                    'N/A',
+                )
+                ttps.append(
+                    LinkedTTP(
+                        id=link.id_,
+                        type=link.type_,
+                        name=link.name,
+                        display_name=display_name,
+                        source=link.source,
+                    )
+                )
+
+        return ttps
+
+    def threat_actors(self) -> list[LinkedTA]:
+        """Return linked organizations marked as threat actors."""
+        tas = []
+        for link in self.links:
+            if link.type_ == 'type:Organization':
+                is_threat_actor = next(
+                    (attr.value for attr in link.attributes if attr.id_ == 'threat_actor'),
+                    False,
+                )
+                if is_threat_actor:
+                    tas.append(
+                        LinkedTA(
+                            id=link.id_,
+                            type=link.type_,
+                            name=link.name,
+                            source=link.source,
+                        )
+                    )
+
+        return tas
+
+    def malwares(self) -> list[LinkedMalware]:
+        """Return linked malware entities."""
+        return [
+            LinkedMalware(
+                id=link.id_,
+                type=link.type_,
+                name=link.name,
+                source=link.source,
+            )
+            for link in self.links
+            if link.type_ == 'type:Malware'
+        ]
+
+
+class LinksSearchIn(RFBaseModel):
+    """Model for payload sent to POST `/links/search` endpoint."""
+
+    entities: list[str]
+    filters: LinksFilterObjects | None = None
+    limits: LinksLimitsObjects | None = None