psengine 2.0.6__tar.gz → 2.1.0__tar.gz

{psengine-2.0.6 → psengine-2.1.0}/PKG-INFO

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

{psengine-2.0.6 → psengine-2.1.0}/psengine/_version.py

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

{psengine-2.0.6 → psengine-2.1.0}/psengine/classic_alerts/markdown/markdown.py

@@ -94,7 +94,8 @@ def _process_hit_fragment(
         content.append(f'{blockquote(fragment)}\n')
     else:
         content.append(
-            f'_Reference text is missing, check the Recorded Future {link("Portal", str(classic_alert.url.portal))} for more information._\n'  # noqa: E501
+            '_Reference text is missing, check the Recorded Future '
+            f'{link("Portal", str(classic_alert.url.portal))} for more information._\n'
         )
 
     if include_triggered_by:

{psengine-2.0.6 → psengine-2.1.0}/psengine/common_models.py

@@ -15,7 +15,7 @@ import os
 from enum import Enum
 from typing import Optional
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, Secret
 
 
 class RFBaseModel(BaseModel):
@@ -50,7 +50,6 @@ class RFBaseModel(BaseModel):
             else kwargs['exclude_unset']
         )
         kwargs['exclude_unset'] = exclude_unset
-
         return self.model_dump(mode='json', by_alias=by_alias, exclude_none=exclude_none, **kwargs)
 
 
@@ -87,3 +86,13 @@ class DetectionRuleType(Enum):
     sigma = 'sigma'
     yara = 'yara'
     snort = 'snort'
+
+
+class ClearTextPassword(Secret[str]):
+    """Model to hide passwords while logging.
+
+    To view the clear text password do ``value.get_secret_value()``
+    """
+
+    def _display(self) -> str:
+        return self.get_secret_value()[:4] + '********'

{psengine-2.0.6 → psengine-2.1.0}/psengine/endpoints.py

@@ -98,3 +98,16 @@ EP_ANALYST_NOTE_PREVIEW = EP_ANALYST_NOTE + 'preview'
 EP_ANALYST_NOTE_PUBLISH = EP_ANALYST_NOTE + 'publish'
 EP_ANALYST_NOTE_DELETE = EP_ANALYST_NOTE + 'delete/{}'
 EP_ANALYST_NOTE_ATTACHMENT = EP_ANALYST_NOTE + 'attachment/{}'
+
+###############################################################################
+# Identity API Endpoints
+###############################################################################
+EP_IDENTITY = BASE_URL + '/identity/'
+EP_IDENTITY_DETECTIONS = EP_IDENTITY + 'detections'
+EP_IDENTITY_INCIDENT_REPORT = EP_IDENTITY + 'incident/report'
+EP_IDENTITY_HOSTNAME_LOOKUP = EP_IDENTITY + 'hostname/lookup'
+EP_IDENTITY_PASSWORD_LOOKUP = EP_IDENTITY + 'password/lookup'
+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'

{psengine-2.0.6 → psengine-2.1.0}/psengine/entity_lists/entity_list.py

@@ -314,7 +314,8 @@ class EntityList(RFBaseModel):
         response = self.rf_client.request('get', url)
         validated_status = ListStatusOut.model_validate(response.json())
         self.log.debug(
-            f"List '{self.name}' status: {validated_status.status}, entities: {validated_status.size}"  # noqa: E501
+            f"List '{self.name}' status: {validated_status.status}, "
+            f'entities: {validated_status.size}'
         )
 
         return validated_status

{psengine-2.0.6 → psengine-2.1.0}/psengine/helpers/__init__.py

@@ -17,6 +17,7 @@ from .helpers import (
     MultiThreadingHelper,
     OSHelpers,
     TimeHelpers,
+    Validators,
     connection_exceptions,
     debug_call,
     dump_models,

{psengine-2.0.6 → psengine-2.1.0}/psengine/helpers/helpers.py

@@ -156,7 +156,7 @@ class TimeHelpers:
     """Helpers for time related functions."""
 
     @staticmethod
-    def rel_time_to_date(relative_time) -> str:
+    def rel_time_to_date(relative_time: str) -> str:
         """Convert a relative time to a date. Minutes not supported.
 
         Example:
@@ -193,7 +193,7 @@ class TimeHelpers:
         return subtracted
 
     @staticmethod
-    def is_rel_time_valid(rel_time) -> bool:
+    def is_rel_time_valid(rel_time: str) -> bool:
         """Helper function to determine if relative time expression is valid.
 
         Args:
@@ -202,7 +202,7 @@ class TimeHelpers:
         Returns:
             bool: True if valid, False otherwise
         """
-        if rel_time is None:
+        if rel_time is None or not isinstance(rel_time, str):
             return False
 
         return bool(re.match(VALID_TIME_REGEX, rel_time))
@@ -468,3 +468,39 @@ class MultiThreadingHelper:
             futures = [pool.submit(func, element, **kwargs) for element in iterator]
 
         return [f.result() for f in futures]
+
+
+class Validators:
+    """Common validators for pydantic models."""
+
+    @staticmethod
+    def convert_str_to_list(value: Union[str, list]) -> list:
+        """Convert value from str to list and remove None values."""
+        value = value if isinstance(value, list) else [value]
+        return [v for v in value if v is not None]
+
+    @staticmethod
+    def convert_relative_time(input_time: str) -> str:
+        """Covert relative time to datetime string if possible."""
+        return (
+            TimeHelpers.rel_time_to_date(input_time)
+            if TimeHelpers.is_rel_time_valid(input_time)
+            else input_time
+        )
+
+    @staticmethod
+    def check_uhash_prefix(value: Union[str, list]) -> Union[str, list]:
+        """Validates that the field contains fields starting with uhash and add it otherwise."""
+        uhash = 'uhash:'
+        if isinstance(value, str):
+            return f'{uhash}{value}' if not value.startswith(uhash) else value
+
+        if isinstance(value, list):
+            new_values = []
+            for h in value:
+                if h:
+                    complete_value = f'{uhash}{h}' if not h.startswith(uhash) else h
+                    new_values.append(complete_value)
+            return new_values
+
+        return value

psengine-2.1.0/psengine/identity/__init__.py

@@ -0,0 +1,31 @@
+##################################### 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 IdentityError
+from .identity import (
+    Credential,
+    CredentialSearch,
+    CredentialsLookupIn,
+    CredentialsSearchIn,
+    Detection,
+    Detections,
+    DetectionsIn,
+    DumpSearchIn,
+    HostnameLookupIn,
+    IncidentReportIn,
+    IncidentReportOut,
+    IPLookupIn,
+    LeakedIdentity,
+    PasswordLookup,
+)
+from .identity_mgr import IdentityMgr

psengine-2.1.0/psengine/identity/constants.py

@@ -0,0 +1,15 @@
+##################################### 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.                                                         #
+##############################################################################################
+
+DETECTIONS_PER_PAGE = 20
+MAXIMUM_IDENTITIES = 500

psengine-2.1.0/psengine/identity/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 IdentityError(RecordedFutureError):
+    """Error raised when there is an error with the Identity API."""
+
+
+class DetectionsFetchError(IdentityError):
+    """Error raised when there is an issue searching for detections."""
+
+
+class IncidentReportFetchError(IdentityError):
+    """Error raised when there is an issue fetching an incident report."""
+
+
+class IdentityLookupError(IdentityError):
+    """Error raised when there is an issue looking up identities."""
+
+
+class IdentitySearchError(IdentityError):
+    """Error raised when there is an issue searching identities."""

psengine-2.1.0/psengine/identity/identity.py

@@ -0,0 +1,396 @@
+##################################### 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 functools import total_ordering
+from typing import Annotated, Optional
+
+from pydantic import AfterValidator, BeforeValidator, Field, field_validator
+
+from ..common_models import IdName, RFBaseModel
+from ..constants import TIMESTAMP_STR
+from ..helpers import Validators
+from .models.common_models import (
+    BaseIdentityIn,
+    Cookie,
+    DomainTypes,
+    DumpSearchOut,
+    FilterIn,
+    IdentityOrgIn,
+    PasswordHash,
+)
+from .models.detections import AuthorizationService, DetectionsCreated, DetectionsFilterIn, Password
+from .models.incident_report import IncidentReportCredentials, IncidentReportDetails
+from .models.lookup import IdentityDetails, IPRange, SecretDetails
+
+
+@total_ordering
+class Detection(RFBaseModel):
+    """Model to validate output of the ``/identity/detections`` endpoint.
+
+    Methods:
+        __hash__:
+            Returns hash value based on Detection ``id_`` and created time.
+
+        __eq__:
+            Checks equality between two Detection instances based on ``id_`` and created time.
+
+        __gt__:
+            Defines a greater-than comparison between two Detection instances based on
+            created timestamp and ``id_``.
+
+        __str__:
+            Returns a string representation of the Detection instance with:
+            ``id_``, created timestamp, type, and novel.
+
+            .. code-block:: python
+
+                >>> print(detection)
+                ID: detection123, Created: 2025-01-01 05:00:30AM, Type: Workforce, Novel: True
+
+
+    Total Ordering:
+            The ordering of Detection instances is determined primarily by the created timestamp
+            of the detection. If two instances have the same created timestamp, their
+            ``id_`` is used as a secondary criterion for ordering.
+    """
+
+    id_: str = Field(alias='id')
+    organization_id: Annotated[
+        Optional[list[str]], BeforeValidator(Validators.check_uhash_prefix)
+    ] = None
+    novel: bool
+    type_: str = Field(alias='type')
+    subject: str
+    password: Password
+    authorization_service: Optional[AuthorizationService] = None
+    cookies: list[Cookie]
+    malware_family: Optional[IdName] = None
+    dump: DumpSearchOut
+    created: datetime
+
+    def __hash__(self):
+        return hash((self.id_, self.created))
+
+    def __eq__(self, other: 'Detection'):
+        return (self.id_, self.created) == (other.id_, other.created)
+
+    def __gt__(self, other: 'Detection'):
+        return (self.created, self.id_) > (other.created, other.id_)
+
+    def __str__(self):
+        return (
+            f'Detection ID: {self.id_}, '
+            f'Created: {self.created.strftime(TIMESTAMP_STR)}, '
+            f'Type: {self.type_}, '
+            f'Novel: {self.novel}'
+        )
+
+
+@total_ordering
+class CredentialSearch(RFBaseModel):
+    """Model to validate output of the ``/identity/credentials/search`` endpoint.
+
+    Methods:
+        __hash__:
+            Returns hash value based on CredentialSearch ``login`` and ``domain``.
+
+        __eq__:
+            Checks equality between two CredentialSearch based on ``login`` and ``domain``.
+
+        __gt__:
+            Defines a greater-than comparison between two CredentialSearch instances based on
+            ``login`` and ``domain``.
+
+        __str__:
+            Returns a string representation of the CredentialSearch instance with:
+            ``login`` and ``domain``.
+
+            .. code-block:: python
+
+                >>> print(credential)
+                Login: example Domain: norsegods.online
+
+    Total Ordering:
+            The ordering of CredentialSearch instances is determined primarily by the ``login`` of
+            the detection. If two instances have the same ``login, their ``domain`` is used as a
+            secondary criterion for ordering.
+
+    """
+
+    login: str
+    login_sha1: Optional[str] = None  # This is used only by CredentialLookupIn.subject_login
+    domain: str
+
+    def __hash__(self):
+        return hash((self.login, self.domain))
+
+    def __eq__(self, other: 'CredentialSearch'):
+        return (self.login, self.domain) == (other.login, other.domain)
+
+    def __gt__(self, other: 'CredentialSearch'):
+        return (self.login, self.domain) > (other.login, other.domain)
+
+    def __str__(self):
+        return f'Login: {self.login}, Domain: {self.domain}'
+
+
+class Detections(RFBaseModel):
+    """Model for payload received by POST ``/identity/detections`` endpoint."""
+
+    total: int
+    detections: list[Detection]
+
+    def __str__(self):
+        data = '\n'.join(str(d) for d in self.detections)
+        return f'[{data}]'
+
+
+@total_ordering
+class PasswordLookup(RFBaseModel):
+    """Model to validate output of the ``/identity/credentials/lookup`` endpoint.
+
+    Methods:
+        __hash__:
+            Returns hash value based on ``password.hash_`` (or ``hash_prefix``) and ``algorithm``.
+
+        __eq__:
+            Checks equality between two PasswordLookup instances based on ``password.hash_`` (or
+            ``hash_prefix``) and ``algorithm``.
+
+        __gt__:
+            Defines a greater-than comparison between two PasswordLookup instances based on
+            ``password.hash_`` (or ``hash_prefix``) and ``algorithm``.
+
+        __str__:
+            Returns a string representation of the PasswordLookup instance with:
+            ``password.hash_`` (or ``hash_prefix``), ``algorithm``, and ``exposure_status``.
+
+            .. code-block:: python
+
+                >>> print(lookup)
+                Hash: abc123 Algorithm: sha1 Exposure Status: Common
+
+    Total Ordering:
+            The ordering of PasswordLookup instances is determined primarily by the
+            ``password.hash_`` (or ``hash_prefix``). If two instances have the same hash, their
+            ``algorithm`` is used as a secondary criterion for ordering.
+
+    """
+
+    password: PasswordHash
+    exposure_status: str
+
+    def __hash__(self):
+        return hash(
+            ((self.password.hash_ or self.password.hash_prefix), self.password.algorithm.value)
+        )
+
+    def __eq__(self, other: 'PasswordLookup'):
+        return (
+            (self.password.hash_ or self.password.hash_prefix),
+            self.password.algorithm.value,
+        ) == ((other.password.hash_ or other.password.hash_prefix), other.password.algorithm.value)
+
+    def __gt__(self, other: 'PasswordLookup'):
+        return (
+            (self.password.hash_ or self.password.hash_prefix),
+            self.password.algorithm.value,
+        ) > ((other.password.hash_ or other.password.hash_prefix), other.password.algorithm.value)
+
+    def __str__(self):
+        return (
+            f'Hash: {(self.password.hash_ or self.password.hash_prefix)}, '
+            f'Algorithm: {self.password.algorithm.value}, '
+            f'Exposure Status: {self.exposure_status}'
+        )
+
+
+class Credential(RFBaseModel):
+    """Detection model to validate output of the ``/identity/credentials/search`` endpoint.
+
+    Methods:
+        __hash__:
+            Returns hash value based on ``subject``, ``first_downloaded``, the exposed secret's
+            ``hashes``, and the ``authorization_service`` URL (if present).
+
+        __eq__:
+            Checks equality between two Credential instances based on ``subject``,
+            ``first_downloaded``, the exposed secret's ``hashes``, and the
+            ``authorization_service`` URL.
+
+        __gt__:
+            Defines a greater-than comparison between two Credential instances based on
+            ``subject``, ``first_downloaded``, the exposed secret's ``hashes``, and the
+            ``authorization_service`` URL.
+
+        __str__:
+            Returns a string representation of the Credential instance with:
+            ``subject``, ``first_downloaded``, exposed secret ``hashes``, and
+            ``authorization_service``.
+
+            .. code-block:: python
+
+                >>> print(credential)
+                Subject: admin@example.com, First Downloaded: 2024-03-01T12:00:00,
+                Hashes: [abc123, def456], Authorization Service: login.service.com
+
+    Total Ordering:
+            The ordering of Credential instances is determined primarily by the ``subject`` and
+            ``first_downloaded`` timestamp. If those are equal, the ``hashes`` and then the
+            ``authorization_service`` URL are used as secondary criteria.
+    """
+
+    subject: str
+    dumps: list[DumpSearchOut]
+    first_downloaded: datetime
+    latest_downloaded: datetime
+    exposed_secret: SecretDetails
+    compromise: Optional[dict[str, datetime]] = None
+    malware_family: Optional[IdName] = None
+    authorization_service: Optional[AuthorizationService] = None
+    cookies: Optional[list[Cookie]] = None
+
+    def __hash__(self):
+        hashes = ', '.join(sorted(a.hash_ or a.hash_prefix for a in self.exposed_secret.hashes))
+        auth = self.authorization_service.url if self.authorization_service else ''
+        return hash((self.subject, self.first_downloaded, hashes, auth))
+
+    def __eq__(self, other: 'Credential'):
+        hashes_self = sorted(a.hash_ or a.hash_prefix for a in self.exposed_secret.hashes)
+        hashes_other = sorted(a.hash_ or a.hash_prefix for a in other.exposed_secret.hashes)
+        auth_self = self.authorization_service.url if self.authorization_service else ''
+        auth_other = other.authorization_service.url if other.authorization_service else ''
+        return (
+            self.subject == other.subject
+            and self.first_downloaded == other.first_downloaded
+            and hashes_self == hashes_other
+            and auth_self == auth_other
+        )
+
+    def __gt__(self, other: 'Credential'):
+        hashes_self = ', '.join(
+            sorted(a.hash_ or a.hash_prefix for a in self.exposed_secret.hashes)
+        )
+        hashes_other = ', '.join(
+            sorted(a.hash_ or a.hash_prefix for a in other.exposed_secret.hashes)
+        )
+        auth_self = self.authorization_service.url if self.authorization_service else ''
+        auth_other = other.authorization_service.url if other.authorization_service else ''
+        return (self.subject, self.first_downloaded, hashes_self, auth_self) > (
+            other.subject,
+            other.first_downloaded,
+            hashes_other,
+            auth_other,
+        )
+
+    def __str__(self):
+        hashes = ', '.join(sorted(a.hash_ or a.hash_prefix for a in self.exposed_secret.hashes))
+        auth = self.authorization_service.url if self.authorization_service else 'None'
+        return (
+            f'Subject: {self.subject}, '
+            f'First Downloaded: {self.first_downloaded.strftime(TIMESTAMP_STR)}, '
+            f'Hashes: [{hashes}], '
+            f'Authorization Service: {auth}'
+        )
+
+
+class LeakedIdentity(RFBaseModel):
+    """Model to validate output of several endpoints.
+
+    ``/identity/ip/lookup``, ``/identity/credentials/lookup``, ``/identity/hostname/lookup``
+    """
+
+    identity: IdentityDetails
+    count: int
+    credentials: list[Credential]
+
+
+class DetectionsIn(RFBaseModel):
+    """Model for payload sent to POST ``/identity/detections`` endpoint."""
+
+    organization_id: Annotated[
+        Optional[list[str]],
+        BeforeValidator(Validators.convert_str_to_list),
+        AfterValidator(Validators.check_uhash_prefix),
+    ] = []
+    include_enterprise_level: Optional[bool] = None
+    filter: Optional[DetectionsFilterIn] = Field(default_factory=DetectionsFilterIn)
+    limit: int
+    offset: Optional[str] = None
+    created: Optional[DetectionsCreated] = Field(default_factory=DetectionsCreated)
+
+
+class IncidentReportIn(IdentityOrgIn):
+    """Model for payload sent to POST ``/identity/detections`` endpoint."""
+
+    source: str
+    include_details: bool
+
+
+class IncidentReportOut(RFBaseModel):
+    """Model for payload received by POST ``/identity/incident/report`` endpoint."""
+
+    details: Optional[IncidentReportDetails] = None
+    credentials: list[IncidentReportCredentials]
+
+    @field_validator('details', mode='before')
+    @classmethod
+    def transform_details(cls, value):
+        """Paged request returns lists only so transforming by extracting the first one."""
+        if isinstance(value, list) and len(value):
+            return value.pop(0)
+
+        return None
+
+
+class HostnameLookupIn(BaseIdentityIn):
+    """Model for payload sent to POST ``/identity/incident/report` endpoint."""
+
+    hostname: str
+
+
+class IPLookupIn(BaseIdentityIn):
+    """Model for payload sent to POST ``/identity/ip/lookup`` endpoint."""
+
+    ip: Optional[str] = None
+    range_: Optional[IPRange] = Field(alias='range', default=None)
+
+
+class CredentialsLookupIn(BaseIdentityIn):
+    """Model for payload sent to POST ``/identity/credentials/lookup`` endpoint."""
+
+    subjects: Annotated[Optional[list[str]], BeforeValidator(Validators.convert_str_to_list)] = None
+    subjects_sha1: Annotated[
+        Optional[list[str]], BeforeValidator(Validators.convert_str_to_list)
+    ] = None
+    subjects_login: Optional[list[CredentialSearch]] = None
+    filter: Optional[FilterIn] = None
+
+
+class CredentialsSearchIn(BaseIdentityIn):
+    """Model for payload sent to POST ``/identity/credentials/search`` endpoint."""
+
+    domains: Annotated[list[str], BeforeValidator(Validators.convert_str_to_list)]
+    domain_types: Annotated[
+        Optional[list[DomainTypes]], BeforeValidator(Validators.convert_str_to_list)
+    ] = None
+
+    filter: Optional[FilterIn] = None
+
+
+class DumpSearchIn(RFBaseModel):
+    """Model for payload sent to POST ``/identity/metadata/dump/search`` endpoint."""
+
+    names: Annotated[list[str], BeforeValidator(Validators.convert_str_to_list)]
+    limit: Optional[int] = None