psengine 2.6.0__tar.gz → 2.7.0__tar.gz

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

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

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

@@ -147,3 +147,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.7.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
 
 

{psengine-2.6.0 → psengine-2.7.0}/psengine/stix2/complex_entity.py

@@ -225,7 +225,7 @@ class IndicatorEntity(BaseStixEntity):
         """
         if not create_indicator and not create_obs:
             raise STIX2TransformError(
-                'Inidcator must create at least one of "Observable" or "Indicator"',
+                'Indicator must create at least one of "Observable" or "Indicator"',
             )
 
         type_ = CONVERTED_TYPES.get(type_, type_)

{psengine-2.6.0 → psengine-2.7.0}/psengine/stix2/enriched_indicator.py

@@ -126,7 +126,7 @@ class EnrichedIndicator(IndicatorEntity):
         """Creates relationship between object and indicator/observabe.
 
         Raises:
-            STIX2TransformError: Generic transofmr error
+            STIX2TransformError: Generic transform error
         """
         if isinstance(obj, IndicatorEntity):
             sources = []

psengine-2.7.0/psengine/threat_maps/__init__.py

@@ -0,0 +1,30 @@
+##################################### 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 (
+    ThreatActorSearchError,
+    ThreatMapCategoriesError,
+    ThreatMapFetchError,
+    ThreatMapInfoError,
+    ThreatMapsError,
+)
+from .threat_map import (
+    EntityCategory,
+    ThreatActorAttributes,
+    ThreatActorProfile,
+    ThreatMap,
+    ThreatMapEntity,
+    ThreatMapFetchIn,
+    ThreatMapInfo,
+)
+from .threat_map_mgr import ThreatMapMgr

psengine-2.7.0/psengine/threat_maps/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 ThreatMapsError(RecordedFutureError):
+    """Error raised when there was an issue with the threat maps API."""
+
+
+class ThreatMapFetchError(ThreatMapsError):
+    """Error raised when there was an issue fetching a threat map."""
+
+
+class ThreatMapInfoError(ThreatMapsError):
+    """Error raised when there was an error fetching available threat maps."""
+
+
+class ThreatMapCategoriesError(ThreatMapsError):
+    """Error raised when there was an error searching threat categories."""
+
+
+class ThreatActorSearchError(ThreatMapsError):
+    """Error raised when there was an error searching threat actors."""

psengine-2.7.0/psengine/threat_maps/models.py

@@ -0,0 +1,56 @@
+##################################### 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 enum import Enum
+
+from ..common_models import IdName, RFBaseModel
+
+
+class ThreatMapAxis(Enum):
+    opportunity = 'opportunity'
+    intent = 'intent'
+
+
+class ThreatMapType(Enum):
+    actors = 'actors'
+    malware = 'malware'
+
+    @property
+    def category_slug(self) -> str:
+        """Return the URL slug used by the categories endpoint.
+
+        The map endpoint uses `actors`/`malware` (this enum's value), but the
+        categories endpoint uses the singular `actor`/`malware` — see api.md.
+        """
+        return 'actor' if self is ThreatMapType.actors else 'malware'
+
+
+class LogEntry(RFBaseModel):
+    watchlist: IdName | None = None
+    entity: IdName
+    severity: int
+    axis: str
+    date: datetime
+
+
+class EntityAttributes(RFBaseModel):
+    name: str
+    alias: list[str] = []
+
+
+class ThreatActorAttributes(RFBaseModel):
+    name: str
+    common_names: list[str] = []
+    alias: list[str] = []
+    categories: list[IdName] = []

psengine-2.7.0/psengine/threat_maps/threat_map.py

@@ -0,0 +1,134 @@
+##################################### 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
+
+from pydantic import BeforeValidator, Field
+
+from ..common_models import IdName, RFBaseModel
+from ..helpers.helpers import Validators
+from .models import EntityAttributes, LogEntry, ThreatActorAttributes
+
+
+@total_ordering
+class ThreatMapEntity(RFBaseModel):
+    """Model to validate data received from the `threat/map/{type}` endpoint.
+
+    This class supports string representation, equality comparison, and hashing of `ThreatMapEntity`
+    instances.
+
+    Hashing:
+        Defines uniqueness of a `ThreatMapEntity` object by the entity ID.
+
+    Equality:
+        Validates equality between two `ThreatMapEntity` objects based on the entity ID.
+
+    Greater-than Comparison:
+        Defines a greater-than comparison between two `ThreatMapEntity` instances based on
+        `opportunity`, `intent` and `prevalence`. Lastly on `id_`
+
+    String Representation:
+        Returns a string representation of the `ThreatMapEntity` instance including the
+        entity match name, ID, opportunity, and intent or prevalence depending on category.
+
+        ```python
+        >>> print(entity)
+        Entity Name: BlueDelta, ID: L37nw-, Opportunity: 65, Intent: 65'
+        ```
+    Ordering:
+        The ordering of `ThreatMapEntity` instances is determined primarily by the `opportunity`
+        score followed by the `intent` and `prevalence`.
+        If two instances have the same scores, the `id_` is used as a last criterion.
+    """
+
+    id_: str = Field(alias='id')
+    name: str
+    alias: list[str]
+    categories: list[IdName]
+    intent: int | None = None
+    prevalence: int | None = None
+    opportunity: int
+    log_entries: list[LogEntry]
+
+    def __hash__(self):
+        return hash(self.id_)
+
+    def __eq__(self, other: 'ThreatMapEntity'):
+        return self.id_ == other.id_
+
+    def __gt__(self, other: 'ThreatMapEntity'):
+        return (self.opportunity, self.intent or 0, self.prevalence or 0, self.id_) > (
+            other.opportunity or 0,
+            other.intent or 0,
+            other.prevalence or 0,
+            other.id_,
+        )
+
+    def __str__(self):
+        key = 'intent' if self.intent is not None else 'prevalence'
+        score = getattr(self, key)
+        return (
+            f'Entity Name: {self.name}, ID: {self.id_}, '
+            f'Opportunity: {self.opportunity}, {key.capitalize()}: {score}'
+        )
+
+
+class ThreatMap(RFBaseModel):
+    """Model for payload received by POST `/threat/map/{type}` endpoint."""
+
+    threat_map: list[ThreatMapEntity]
+    date: datetime = Field(description='Threat map generation timestamp')
+
+    def __str__(self):
+        return '\n'.join(str(entity) for entity in sorted(self.threat_map))
+
+
+class ThreatMapInfo(RFBaseModel):
+    """Model for payload received by GET `/threat/maps` endpoint."""
+
+    name: str
+    type_: str = Field(alias='type')
+    organization: IdName
+    url: str
+
+
+class EntityCategory(RFBaseModel):
+    """Model for payload received by GET `threat/{type}/categories` endpoint."""
+
+    id_: str = Field(alias='id')
+    type_: str = Field(alias='type')
+    attributes: EntityAttributes
+
+
+class ThreatActorProfile(RFBaseModel):
+    """Model for payload received by POST `threat/actor/search` endpoint."""
+
+    id_: str = Field(alias='id')
+    type_: str = Field(alias='type')
+    attributes: ThreatActorAttributes
+
+    def __str__(self):
+        attr = self.attributes
+        common = f', Common Names: {", ".join(attr.common_names)}' if attr.common_names else ''
+        return f'ID: {self.id_} Name: {attr.name}' + common
+
+
+class ThreatMapFetchIn(RFBaseModel):
+    """Model to validate `threat/map/{org}/{type}` endpoint payload sent."""
+
+    malware: Annotated[list[str] | None, BeforeValidator(Validators.convert_str_to_list)] = None
+    actors: Annotated[list[str] | None, BeforeValidator(Validators.convert_str_to_list)] = None
+    categories: Annotated[list[str] | None, BeforeValidator(Validators.convert_str_to_list)] = None
+    watchlists: Annotated[list[str] | None, BeforeValidator(Validators.convert_str_to_list)] = None

psengine-2.7.0/psengine/threat_maps/threat_map_mgr.py

@@ -0,0 +1,173 @@
+##################################### 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, Literal
+
+from pydantic import Field, validate_call
+from typing_extensions import Doc
+
+from ..constants import DEFAULT_LIMIT
+from ..endpoints import (
+    EP_ACTOR_SEARCH,
+    EP_CATEGORIES,
+    EP_THREAT_MAP,
+    EP_THREAT_MAP_ORG,
+    EP_THREAT_MAPS_LIST,
+)
+from ..helpers import debug_call
+from ..helpers.helpers import connection_exceptions
+from ..rf_client import RFClient
+from .errors import (
+    ThreatActorSearchError,
+    ThreatMapCategoriesError,
+    ThreatMapFetchError,
+    ThreatMapInfoError,
+)
+from .models import ThreatMapType
+from .threat_map import (
+    EntityCategory,
+    ThreatActorProfile,
+    ThreatMap,
+    ThreatMapFetchIn,
+    ThreatMapInfo,
+)
+
+MAP_TYPE = Literal['actors', 'malware']
+
+
+class ThreatMapMgr:
+    """Manages requests for Recorded Future Threat Maps API."""
+
+    def __init__(
+        self,
+        rf_token: Annotated[str | None, Doc('Recorded Future API token.')] = None,
+    ):
+        """Initialize the `ThreatMapMgr` 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=ThreatMapInfoError)
+    def fetch_available_maps(
+        self,
+    ) -> Annotated[list[ThreatMapInfo], Doc('A list of available threat maps.')]:
+        """Fetch available threat maps for the organization.
+
+        Endpoint:
+            `threat/maps`
+
+        Raises:
+            ValidationError: If any supplied parameter is of incorrect type.
+            ThreatMapInfoError: If connection error occurs.
+        """
+        maps_response = self.rf_client.request(method='get', url=EP_THREAT_MAPS_LIST).json()['data']
+        return [ThreatMapInfo.model_validate(entry) for entry in maps_response]
+
+    @debug_call
+    @validate_call
+    @connection_exceptions(ignore_status_code=[], exception_to_raise=ThreatMapCategoriesError)
+    def fetch_entity_categories(
+        self,
+        map_type: Annotated[MAP_TYPE, Doc('Type of threat map.')],
+    ) -> Annotated[list[EntityCategory], Doc('A list of threat map taxonomy categories.')]:
+        """Fetch the entity category taxonomy used to filter threat maps.
+
+        Endpoint:
+            `threat/{type}/categories`
+
+        Raises:
+            ValidationError: If any supplied parameter is of incorrect type.
+            ThreatMapCategoriesError: If connection error occurs.
+        """
+        map_type = ThreatMapType(map_type)
+        url = EP_CATEGORIES.format(map_type.category_slug)
+        cat_response = self.rf_client.request(method='get', url=url).json()['data']
+        return [EntityCategory.model_validate(ent) for ent in cat_response]
+
+    @debug_call
+    @validate_call
+    @connection_exceptions(ignore_status_code=[], exception_to_raise=ThreatActorSearchError)
+    def search_threat_actor(
+        self,
+        name: Annotated[
+            str | None, Doc('Free text search of threat actor names, common names, or aliases.')
+        ] = None,
+        max_results: Annotated[
+            int | None, Doc('Limit the total number of results returned.')
+        ] = DEFAULT_LIMIT,
+        actors_per_page: Annotated[
+            int | None, Doc('The number of threat actors per page for pagination.')
+        ] = Field(ge=1, le=10_000, default=DEFAULT_LIMIT),
+    ) -> Annotated[
+        list[ThreatActorProfile], Doc('A list of threat actors matching the search criteria.')
+    ]:
+        """Search Recorded Future's threat actor database by name, alias, or classification.
+
+        Endpoint:
+            `threat/actor/search`
+
+        Raises:
+            ValidationError: If any supplied parameter is of incorrect type.
+            ThreatActorSearchError: If connection error occurs.
+        """
+        data = {
+            'name': name,
+            'limit': min(max_results or DEFAULT_LIMIT, actors_per_page or DEFAULT_LIMIT),
+        }
+        search_response = self.rf_client.request_paged(
+            method='post',
+            url=EP_ACTOR_SEARCH,
+            data=data,
+            results_path='data',
+            offset_key='offset',
+            max_results=max_results or DEFAULT_LIMIT,
+        )
+        return [ThreatActorProfile.model_validate(ta) for ta in search_response]
+
+    @debug_call
+    @validate_call
+    @connection_exceptions(ignore_status_code=[], exception_to_raise=ThreatMapFetchError)
+    def fetch_map(
+        self,
+        map_type: Annotated[MAP_TYPE, Doc('Type of threat map.')],
+        org_id: Annotated[str | None, Doc('Organization ID.')] = None,
+        malware: Annotated[str | list[str] | None, Doc('Filter by malware entity ID(s).')] = None,
+        actors: Annotated[str | list[str] | None, Doc('Filter by threat actor ID(s).')] = None,
+        categories: Annotated[str | list[str] | None, Doc('Filter by category ID(s).')] = None,
+        watchlists: Annotated[str | list[str] | None, Doc('Filter by watch list ID(s).')] = None,
+    ) -> Annotated[ThreatMap, Doc('Threat map with entities matching filter criteria.')]:
+        """Fetch a threat map with optional entity, category, and watchlist filters.
+
+        Endpoint:
+            `threat/map/{type}` or `threat/map/{org_id}/{type}`
+
+        Raises:
+            ValidationError: If any supplied parameter is of incorrect type.
+            ThreatMapFetchError: If connection error occurs.
+        """
+        body = {'categories': categories, 'watchlists': watchlists}
+        map_type = ThreatMapType(map_type).value
+        if map_type is ThreatMapType.actors:
+            body['actors'] = actors
+        else:
+            body['malware'] = malware
+
+        url = (
+            EP_THREAT_MAP_ORG.format(org_id, map_type) if org_id else EP_THREAT_MAP.format(map_type)
+        )
+
+        data = ThreatMapFetchIn.model_validate(body).json()
+        map_response = self.rf_client.request(method='post', url=url, data=data).json()['data']
+        return ThreatMap.model_validate(map_response)

{psengine-2.6.0 → psengine-2.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "psengine"
-version = "2.6.0"
+version = "2.7.0"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10, <3.15"
@@ -26,15 +26,15 @@ classifiers=[
         "Programming Language :: Python :: 3.14"
 ]
 
-dependencies = [
-    "typing_extensions >= 4.8.0",
+dependencies = [ 
+    "typing_extensions >= 4.8.0", 
     "requests>=2.27.1",
-    "jsonpath_ng>=1.5.3, <=1.6.1",
+    "jsonpath_ng>=1.5.3, <=1.8.0",
     "stix2~=3.0.1",
     "python-dateutil>=2.7.0",
-    "more-itertools>=9.0.0, <=10.2.0",
+    "more-itertools>=9.0.0, <=11.0.2",
     "pydantic>=2.7, <3.0.0",
-    "pydantic-settings[toml]>=2.12.2,<2.13.1",
+    "pydantic-settings[toml]>=2.12.2,<2.14.1",
     "markdown-strings==3.4.0"
 ]
 
@@ -51,24 +51,24 @@ dev = [
     "pytest-mock==3.15.1",
     "pytest-md==0.2.0",
     "pytest-random-order==1.2.0",
-    "pytest-httpdbg==0.10.1",
+    "pytest-httpdbg==0.10.2",
     "ruff~=0.15.8",
     "mimesis>=19.1.0",
     "freezegun>=1.5.5",
 ]
 
 docs = [
-    "mike~=2.1.4",
+    "mike>=2.1.4,<2.3.0",
     "mkdocs~=1.6.1",
-    "mkdocs-material~=9.6.18",
+    "mkdocs-material>=9.6.18,<9.8.0",
     "mkdocstrings[python]>=0.18",
-    "griffe-typingdoc~=0.2.8",
+    "griffe-typingdoc>=0.2.8,<0.4.0",
     "mkdocs-codeinclude-plugin~=0.2.1",
     "markdown-include~=0.8.1",
     "mkdocs-exclude~=1.0.2",
 
     # Tools for examples
-    "rich==14.3.3",
+    "rich==15.0.0",
     "logging-tree==1.10",
 ]
 
@@ -78,6 +78,7 @@ build-backend = "uv_build"
 
 [tool.uv]
 default-groups = "all"
+exclude-newer = "7 days"
 
 [tool.uv.build-backend]
 module-root = ""