psengine 2.10.0__tar.gz → 2.11.0__tar.gz

{psengine-2.10.0 → psengine-2.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: psengine
-Version: 2.10.0
+Version: 2.11.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
@@ -25,7 +25,7 @@ Requires-Dist: stix2~=3.0.2
 Requires-Dist: python-dateutil>=2.7.0
 Requires-Dist: more-itertools>=9.0.0,<=11.1.0
 Requires-Dist: pydantic>=2.7,<3.0.0
-Requires-Dist: pydantic-settings[toml]>=2.14.2,<2.15.0
+Requires-Dist: pydantic-settings[toml]>=2.14.2,<2.16.0
 Requires-Python: >=3.10, <3.15
 Project-URL: Homepage, https://recordedfuture-professionalservices.github.io/psengine/latest/
 Project-URL: Changelog, https://recordedfuture-professionalservices.github.io/psengine/latest/CHANGELOG/

{psengine-2.10.0 → psengine-2.11.0}/psengine/common_models.py

@@ -93,6 +93,7 @@ class DetectionRuleType(Enum):
     sigma = 'sigma'
     yara = 'yara'
     snort = 'snort'
+    suricata = 'suricata'
 
 
 class ClearTextPassword(Secret[str]):

{psengine-2.10.0 → psengine-2.11.0}/psengine/endpoints.py

@@ -141,6 +141,11 @@ 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'
 
+###############################################################################
+# Risk Rules API Endpoints
+###############################################################################
+EP_RISK_RULES = CONNECT_API_BASE_URL + '/{}/riskrules'
+
 ###############################################################################
 # Links API Endpoints
 ###############################################################################

psengine-2.11.0/psengine/risk_rules/__init__.py

@@ -0,0 +1,17 @@
+##################################### 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 RiskRuleError, RiskRuleFetchError
+from .models import RiskRuleCategory, RiskRuleEntityType
+from .risk_rule import RiskRule
+from .risk_rule_mgr import RiskRuleMgr

psengine-2.11.0/psengine/risk_rules/errors.py

@@ -0,0 +1,22 @@
+##################################### TERMS OF USE ###########################################
+# The following code is provided for demonstration purpose only, and should not be used      #
+# without independent verification. Recorded Future makes no representations or warranties,  #
+# express, implied, statutory, or otherwise, regarding any aspect of this code or of the     #
+# information it may retrieve, and provides it both strictly “as-is” and without assuming    #
+# responsibility for any information it may retrieve. Recorded Future shall not be liable    #
+# for, and you assume all risk of using, the foregoing. By using this code, Customer         #
+# represents that it is solely responsible for having all necessary licenses, permissions,   #
+# rights, and/or consents to connect to third party APIs, and that it is solely responsible  #
+# for having all necessary licenses, permissions, rights, and/or consents to any data        #
+# accessed from any third party API.                                                         #
+##############################################################################################
+
+from ..errors import RecordedFutureError
+
+
+class RiskRuleError(RecordedFutureError):
+    """Base error for the risk_rules module."""
+
+
+class RiskRuleFetchError(RecordedFutureError):
+    """Raised when the risk rules for an entity type cannot be fetched."""

psengine-2.11.0/psengine/risk_rules/models.py

@@ -0,0 +1,33 @@
+##################################### 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 enum import Enum
+
+from ..common_models import RFBaseModel
+
+
+class RiskRuleEntityType(str, Enum):
+    """Enum of IOC entity types supported by the `/v2/{entity_type}/riskrules` endpoint."""
+
+    IP = 'ip'
+    DOMAIN = 'domain'
+    HASH = 'hash'
+    VULNERABILITY = 'vulnerability'
+    URL = 'url'
+
+
+class RiskRuleCategory(RFBaseModel):
+    """A framework category attached to a risk rule (e.g. MITRE tactic or technique)."""
+
+    name: str
+    framework: str

psengine-2.11.0/psengine/risk_rules/risk_rule.py

@@ -0,0 +1,78 @@
+##################################### 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 functools import total_ordering
+from typing import Any
+
+from pydantic import Field
+
+from ..common_models import RFBaseModel
+from .models import RiskRuleCategory
+
+
+@total_ordering
+class RiskRule(RFBaseModel):
+    """Validate data received from the `/v2/{entity_type}/riskrules` endpoint.
+
+    A Recorded Future risk rule is a scoring rule that contributes to the overall risk score of an
+    entity of a given IOC type (ip, domain, hash, url, vulnerability). Each rule has a criticality
+    level (1-3), a human readable label, a description of what it detects, and a count of entities
+    currently matching the rule.
+
+    This class supports hashing, equality comparison, string representation, and total ordering
+    of `RiskRule` instances.
+
+    Hashing:
+        Returns a hash value based on the tuple `(name, criticality)`.
+
+    Equality:
+        Two `RiskRule` instances are equal if they share the same `name` and `criticality`.
+
+    Greater-than Comparison:
+        A rule is "greater" than another if its `criticality` is higher. When two rules share the
+        same criticality, the one whose `name` sorts later alphabetically is considered greater.
+        Combined with `@total_ordering`, this yields most-critical-first when using `sorted()` in
+        reverse (or `sorted(rules, reverse=True)`).
+
+    String Representation:
+        Returns a compact one-line summary of the rule.
+
+        ```python
+        >>> print(risk_rule)
+        Risk Rule: bogusBgp, Criticality: 1 (Unusual), Count: 24590
+        ```
+    """
+
+    name: str
+    description: str
+    criticality: int
+    criticality_label: str = Field(alias='criticalityLabel')
+    count: int
+    categories: list[RiskRuleCategory] = []
+    related_entities: list[Any] = Field(alias='relatedEntities', default=[])
+
+    def __hash__(self):
+        return hash((self.name, self.criticality))
+
+    def __eq__(self, other: 'RiskRule'):
+        return (self.name, self.criticality) == (other.name, other.criticality)
+
+    def __gt__(self, other: 'RiskRule'):
+        return (self.criticality, self.name) > (other.criticality, other.name)
+
+    def __str__(self):
+        return (
+            f'Risk Rule: {self.name}, '
+            f'Criticality: {self.criticality} ({self.criticality_label}), '
+            f'Count: {self.count}'
+        )

psengine-2.11.0/psengine/risk_rules/risk_rule_mgr.py

@@ -0,0 +1,63 @@
+##################################### 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 validate_call
+from typing_extensions import Doc
+
+from ..endpoints import EP_RISK_RULES
+from ..helpers import debug_call
+from ..helpers.helpers import connection_exceptions
+from ..rf_client import RFClient
+from .errors import RiskRuleFetchError
+from .models import RiskRuleEntityType
+from .risk_rule import RiskRule
+
+
+class RiskRuleMgr:
+    """Manages requests for Recorded Future risk rules."""
+
+    def __init__(
+        self,
+        rf_token: Annotated[str | None, Doc('Recorded Future API token.')] = None,
+    ):
+        """Initializes the `RiskRuleMgr` 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=RiskRuleFetchError)
+    def fetch(
+        self,
+        entity_type: Annotated[
+            RiskRuleEntityType,
+            Doc('The IOC type to fetch risk rules for: ip, domain, hash, vulnerability, or url.'),
+        ],
+    ) -> Annotated[list[RiskRule], Doc('The list of risk rules for the given IOC type.')]:
+        """Fetch every risk rule defined for the given IOC type.
+
+        Endpoint:
+            `/v2/{entity_type}/riskrules`
+
+        Raises:
+            ValidationError: If `entity_type` is not one of the supported IOC types.
+            RiskRuleFetchError: If an API error occurs while fetching risk rules.
+        """
+        url = EP_RISK_RULES.format(entity_type.value)
+        self.log.info(f'Fetching risk rules for entity type: {entity_type.value}')
+        response = self.rf_client.request('get', url).json()
+        results = response['data']['results']
+        return [RiskRule.model_validate(r) for r in results]

{psengine-2.10.0 → psengine-2.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "psengine"
-version = "2.10.0"
+version = "2.11.0"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10, <3.15"
@@ -33,7 +33,7 @@ dependencies = [
     "python-dateutil>=2.7.0",
     "more-itertools>=9.0.0, <=11.1.0",
     "pydantic>=2.7, <3.0.0",
-    "pydantic-settings[toml]>=2.14.2,<2.15.0",
+    "pydantic-settings[toml]>=2.14.2,<2.16.0",
 ]
 
 [[project.authors]]
@@ -59,8 +59,8 @@ dev = [
     "pytest-mock==3.15.1",
     "pytest-md==0.2.0",
     "pytest-random-order==1.2.0",
-    "pytest-httpdbg==0.10.2",
-    "ruff~=0.15.8",
+    "pytest-httpdbg==0.10.3",
+    "ruff>=0.16.1,<0.17.0",
     "mimesis>=19.1.0",
     "freezegun>=1.5.5",
 ]

{psengine-2.10.0 → psengine-2.11.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "psengine"
-version = "2.10.0"
+version = "2.11.0"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10, <3.15"
@@ -36,7 +36,7 @@ dependencies = [
     "python-dateutil>=2.7.0",
     "more-itertools>=9.0.0, <=11.1.0",
     "pydantic>=2.7, <3.0.0",
-    "pydantic-settings[toml]>=2.14.2,<2.15.0",
+    "pydantic-settings[toml]>=2.14.2,<2.16.0",
 ]
 
 
@@ -52,8 +52,8 @@ dev = [
     "pytest-mock==3.15.1",
     "pytest-md==0.2.0",
     "pytest-random-order==1.2.0",
-    "pytest-httpdbg==0.10.2",
-    "ruff~=0.15.8",
+    "pytest-httpdbg==0.10.3",
+    "ruff>=0.16.1,<0.17.0",
     "mimesis>=19.1.0",
     "freezegun>=1.5.5",
 ]