psengine 2.7.0__tar.gz → 2.8.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: psengine
-Version: 2.7.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
@@ -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.7.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.7.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.7.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.7.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.7.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.7.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.7.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.7.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
 ################################################################################

{psengine-2.7.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.7.0 → psengine-2.8.0}/psengine/helpers/helpers.py

@@ -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

psengine-2.8.0/psengine/links/links_mgr.py

@@ -0,0 +1,214 @@
+##################################### 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 typing import Annotated
+
+from pydantic import AfterValidator, Field, validate_call
+from typing_extensions import Doc
+
+from ..common_models import IdName
+from ..endpoints import (
+    EP_LINKS_METADATA_ENTITIES,
+    EP_LINKS_METADATA_EVENTS,
+    EP_LINKS_METADATA_SECTIONS,
+    EP_LINKS_SEARCH,
+)
+from ..helpers import connection_exceptions, debug_call
+from ..helpers.helpers import Validators
+from ..rf_client import RFClient
+from .errors import LinksMetadataError, LinksSearchError
+from .links import (
+    EntityLinks,
+    LinksSearchIn,
+)
+from .models import (
+    FilterTechnical,
+    LinksFilterObjects,
+    LinksLimitsObjects,
+    LinkSource,
+    SearchScope,
+)
+
+
+class LinksMgr:
+    """Manager for interacting with the Recorded Future Links API."""
+
+    def __init__(
+        self,
+        rf_token: Annotated[str | None, Doc('Recorded Future API token.')] = None,
+    ):
+        """Initialize the `LinksMgr` object."""
+        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=LinksMetadataError)
+    def list_sections(
+        self,
+    ) -> Annotated[list[IdName], Doc('List of section objects with id and name.')]:
+        """List all sections that can be used to filter a Link search.
+
+        Sections are the high-level categories the Links API groups results into,
+        for example *Actors, Tools & TTPs* or *Indicators & Detection Rules*.
+
+        Endpoint:
+            `/links/metadata/sections`
+
+        Raises:
+            ValidationError: If any supplied parameter is of incorrect type.
+            LinksMetadataError: If an API or connection error occurs.
+        """
+        response = self.rf_client.request(method='GET', url=EP_LINKS_METADATA_SECTIONS)
+        return [IdName.model_validate(item) for item in response.json()['data']]
+
+    @debug_call
+    @validate_call
+    @connection_exceptions(ignore_status_code=[], exception_to_raise=LinksMetadataError)
+    def list_events(
+        self,
+    ) -> Annotated[list[IdName], Doc('List of event objects with id and name.')]:
+        """List all event types that can be used to filter technical Link searches.
+
+        Event types describe the kind of analytical evidence that produced a
+        technical link (for example `TTPAnalysis` or `InfrastructureAnalysis`).
+
+        Endpoint:
+            `/links/metadata/events`
+
+        Raises:
+            ValidationError: If any supplied parameter is of incorrect type.
+            LinksMetadataError: If an API or connection error occurs.
+        """
+        response = self.rf_client.request(method='GET', url=EP_LINKS_METADATA_EVENTS)
+        return [IdName.model_validate(item) for item in response.json()['data']]
+
+    @debug_call
+    @validate_call
+    @connection_exceptions(ignore_status_code=[], exception_to_raise=LinksMetadataError)
+    def list_entity_types(
+        self,
+    ) -> Annotated[list[IdName], Doc('List of entity-type objects with id and name.')]:
+        """List all entity types that can be used to filter a Link search.
+
+        The returned values are the supported types for connected entities
+        (for example `Malware`, `Company`, `IpAddress`).
+
+        Endpoint:
+            `/links/metadata/entities`
+
+        Raises:
+            ValidationError: If any supplied parameter is of incorrect type.
+            LinksMetadataError: If an API or connection error occurs.
+        """
+        response = self.rf_client.request(method='GET', url=EP_LINKS_METADATA_ENTITIES)
+        return [IdName.model_validate(item) for item in response.json()['data']]
+
+    @debug_call
+    @validate_call
+    @connection_exceptions(ignore_status_code=[], exception_to_raise=LinksSearchError)
+    def search(
+        self,
+        entities: Annotated[
+            Annotated[str | list[str], AfterValidator(Validators.convert_str_to_list)],
+            Doc('One or more Recorded Future entity IDs to look up links for.'),
+        ],
+        sections: Annotated[
+            str | list[str] | None, Doc('Filter results to these link section IDs.')
+        ] = None,
+        entity_types: Annotated[
+            str | list[str] | None,
+            Doc('Restrict linked entities to these entity types (e.g. "type:IpAddress").'),
+        ] = None,
+        sources: Annotated[
+            str | list[LinkSource] | None,
+            Doc('Limit to source type(s): "technical", "insikt", or both if argument omitted.'),
+        ] = None,
+        timeframe: Annotated[
+            str | None,
+            Doc('Technical-link timeframe (e.g. "-30d", default "-30d", max "-90d").'),
+        ] = None,
+        events: Annotated[
+            str | list[str] | None,
+            Doc('Restrict technical links to these event types (e.g. "type:MalwareAnalysis").'),
+        ] = None,
+        connected_entities: Annotated[
+            str | list[str] | None,
+            Doc('Only return technical links that connect to these entities.'),
+        ] = None,
+        search_scope: Annotated[
+            SearchScope | None,
+            Doc('Result-volume scope: "small", "medium" (default), or "large".'),
+        ] = 'medium',
+        per_entity_type: Annotated[
+            int | None,
+            Field(ge=1, le=1_000_000_000),
+            Doc('Max linked entities returned per entity type (>= 1 <= 1,000,000,000).'),
+        ] = None,
+    ) -> Annotated[
+        list[EntityLinks],
+        Doc('A list of EntityLinks objects'),
+    ]:
+        """Search for technically validated relationships between threat intelligence
+        entities in the Recorded Future Intelligence Cloud — connections established
+        through sandbox analysis, infrastructure analysis, network traffic analysis,
+        and Insikt Group research.
+
+        Issues a single batched request: the response contains one
+        `EntityLinks` per entity in `entities`, in the same order. If the
+        API failed for a specific entity, that result's `error` is populated
+        and `links` is empty — the rest of the batch still succeeds.
+
+        Entities must be supplied as Recorded Future entity IDs; if you only have
+        a name, resolve it with `EntityMatchMgr` first.
+
+        Endpoint:
+            `/links/search`
+
+        If the API failed for a specific entity in the batch, its result looks like:
+        ```python
+            EntityLinks(
+                entity=IdNameType(id_='QCwdoU', name='...', type_='...'),
+                links=[],
+                error=EntitySearchError(message='...', status_code=404),
+            )
+        ```
+
+        Raises:
+            ValidationError: If any supplied parameter is of incorrect type.
+            LinksSearchError: If an API or connection error occurs at the request level.
+        """
+        technical_filters = FilterTechnical(
+            timeframe=timeframe, events=events, connected_entities=connected_entities
+        ).json()
+
+        filters = LinksFilterObjects(
+            sections=sections,
+            entity_types=entity_types,
+            sources=sources,
+            technical=technical_filters or None,
+        ).json()
+        limits = LinksLimitsObjects(
+            search_scope=search_scope, per_entity_type=per_entity_type
+        ).json()
+        payload = LinksSearchIn(
+            entities=entities,
+            filters=filters or None,
+            limits=limits or None,
+        ).json()
+
+        self.log.info(f'Executing links search for {len(entities)} entities.')
+
+        response = self.rf_client.request(method='POST', url=EP_LINKS_SEARCH, data=payload)
+        return [EntityLinks.model_validate(item) for item in response.json()['data']]