psengine 2.1.0__tar.gz → 2.2.0__tar.gz

psengine-2.2.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: psengine
+Version: 2.2.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
+Project-URL: Homepage, https://github.com/RecordedFuture-ProfessionalServices/psengine
+Project-URL: Changelog, https://recordedfuture-professionalservices.github.io/psengine/CHANGELOG/
+Keywords: API,Recorded Future,Cyber Security Engineering,Threat Intelligence
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.27.1
+Requires-Dist: jsonpath_ng<=1.6.1,>=1.5.3
+Requires-Dist: stix2~=3.0.1
+Requires-Dist: python-dateutil>=2.7.0
+Requires-Dist: more-itertools<=10.2.0,>=9.0.0
+Requires-Dist: pydantic<3.0.0,>=2.7
+Requires-Dist: pydantic-settings[toml]<2.11.0,>=2.5.2
+Requires-Dist: markdown-strings==3.4.0
+Provides-Extra: dev
+Requires-Dist: pytest==8.3.4; extra == "dev"
+Requires-Dist: pytest-cov==6.0.0; extra == "dev"
+Requires-Dist: pytest-mock==3.14.0; extra == "dev"
+Requires-Dist: pytest-md==0.2.0; extra == "dev"
+Requires-Dist: pytest-random-order==1.1.1; extra == "dev"
+Requires-Dist: pytest-httpdbg==0.9.0; extra == "dev"
+Requires-Dist: ruff~=0.11.0; extra == "dev"
+Requires-Dist: mimesis>=12.1.0; extra == "dev"
+Requires-Dist: build==1.3.0; extra == "dev"
+Requires-Dist: wheel==0.45.1; extra == "dev"
+Requires-Dist: setuptools==80.9.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: ruff~=0.11.0; extra == "docs"
+Requires-Dist: mike~=2.1.3; extra == "docs"
+Requires-Dist: mkdocs~=1.6.1; extra == "docs"
+Requires-Dist: mkdocs-material~=9.6.18; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.18; extra == "docs"
+Requires-Dist: griffe-typingdoc~=0.2.8; extra == "docs"
+Requires-Dist: mkdocs-codeinclude-plugin~=0.2.1; extra == "docs"
+Requires-Dist: markdown-include~=0.8.1; extra == "docs"
+Requires-Dist: mkdocs-exclude~=1.0.2; extra == "docs"
+Dynamic: license-file
+
+**Documentation**: <https://recordedfuture-professionalservices.github.io/psengine/>
+
+**Github**: <https://github.com/RecordedFuture-ProfessionalServices/psengine>
+
+**PyPi**: <https://pypi.org/project/psengine/>
+
+---
+
+PSEngine is a simple, yet elegant, library for rapid development of integrations with Recorded Future.
+
+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 Cyber Security Engineering team powering a number of high profile integrations, such as: Elasticsearch, QRadar, Anomali, Jira, TheHive, etc.
+
+## Installation
+
+PSEngine is a Python package that can be installed using `pip`. To install PSengine, run the following command:
+
+```bash
+pip install psengine
+```
+
+PSEngine officially supports Python >= 3.9, < 3.14.
+
+
+## Supported Features & Best Practices
+
+PSEngine is ready for the demands of building robust and reliable integrations.
+
+It can easily interact with the following Recorded Future datasets:
+
+* Analyst Notes
+* Collective Insights
+* Classic & Playbook Alerts
+* Detection Rules
+- Identity Exposures management
+* List management
+* On demand IOC enrichment
+* Risklists
+- STIX conversion
+
+
+And facilitate the development with features like:
+
+* Built-in logging
+* Easy configuration management
+- Markdown creation from certain data types
+* Proxy support
+

psengine-2.2.0/README.md

@@ -0,0 +1,49 @@
+**Documentation**: <https://recordedfuture-professionalservices.github.io/psengine/>
+
+**Github**: <https://github.com/RecordedFuture-ProfessionalServices/psengine>
+
+**PyPi**: <https://pypi.org/project/psengine/>
+
+---
+
+PSEngine is a simple, yet elegant, library for rapid development of integrations with Recorded Future.
+
+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 Cyber Security Engineering team powering a number of high profile integrations, such as: Elasticsearch, QRadar, Anomali, Jira, TheHive, etc.
+
+## Installation
+
+PSEngine is a Python package that can be installed using `pip`. To install PSengine, run the following command:
+
+```bash
+pip install psengine
+```
+
+PSEngine officially supports Python >= 3.9, < 3.14.
+
+
+## Supported Features & Best Practices
+
+PSEngine is ready for the demands of building robust and reliable integrations.
+
+It can easily interact with the following Recorded Future datasets:
+
+* Analyst Notes
+* Collective Insights
+* Classic & Playbook Alerts
+* Detection Rules
+- Identity Exposures management
+* List management
+* On demand IOC enrichment
+* Risklists
+- STIX conversion
+
+
+And facilitate the development with features like:
+
+* Built-in logging
+* Easy configuration management
+- Markdown creation from certain data types
+* Proxy support
+

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

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

{psengine-2.1.0 → psengine-2.2.0}/psengine/analyst_notes/helpers.py

@@ -14,9 +14,10 @@
 import json
 import logging
 from pathlib import Path
-from typing import Union
+from typing import Annotated, Union
 
 from pydantic import validate_call
+from typing_extensions import Doc
 
 from ..errors import WriteFileError
 from ..helpers import OSHelpers, debug_call
@@ -28,16 +29,14 @@ LOG = logging.getLogger('psengine.analyst_notes.helpers')
 @debug_call
 @validate_call
 def save_attachment(
-    note_id: str, data: Union[bytes, str], ext: str, output_directory: Union[str, Path]
+    note_id: Annotated[str, Doc('The ID of the AnalystNote.')],
+    data: Annotated[Union[bytes, str], Doc('The data returned from `fetch_attachment`.')],
+    ext: Annotated[str, Doc('The extension of the attachment, returned by `fetch_attachment`.')],
+    output_directory: Annotated[Union[str, Path], Doc('The directory to save the file into.')],
 ) -> None:
-    """Save yara, sigma, snort or pdf to file. The file will use the extension provided and the
-    ``note_id`` to create the filename.
+    """Save a YARA, Sigma, Snort, or PDF attachment to a file.
 
-    Args:
-        note_id (str): ``AnalystNote`` id
-        data (Union[bytes, str]): data, returned from ``fetch_attachment``
-        ext (str): extension of the attachment, returned by ``fetch_attachment``
-        output_directory (str, Path): the directory to save the file into
+    The file will use the provided extension and the `note_id` to create the filename.
     """
     output_directory = (
         output_directory if isinstance(output_directory, str) else output_directory.as_posix()
@@ -47,13 +46,11 @@ def save_attachment(
 
 @debug_call
 @validate_call
-def save_note(note: AnalystNote, output_directory: Union[str, Path]) -> None:
-    """Save AnalystNote object on file. The file will have the name of the note id.
-
-    Args:
-        note (AnalystNote): note to save.
-        output_directory (str, Path): the directory to save the file into
-    """
+def save_note(
+    note: Annotated[AnalystNote, Doc('The note to save.')],
+    output_directory: Annotated[Union[str, Path], Doc('The directory to save the file into.')],
+) -> None:
+    """Save an `AnalystNote` object to a file named with the note ID."""
     output_directory = (
         output_directory if isinstance(output_directory, str) else output_directory.as_posix()
     )
@@ -70,12 +67,6 @@ def _save_attachment(
 ) -> None:
     """Save attachment from bytes or note itself from json.
 
-    Args:
-        note_id (str): id of the note, will be the filename
-        data (bytes | str): content to save
-        ext (str): extension of the file.
-        output_directory (str): the directory to save the file into
-
     Raises:
         WriteFileError: if saving to file fails
     """

{psengine-2.1.0 → psengine-2.2.0}/psengine/analyst_notes/models.py

@@ -13,11 +13,12 @@
 
 import logging
 from datetime import datetime
-from typing import Any, Optional, Union
+from typing import Annotated, Any, Optional, Union
 
-from pydantic import Field, ValidationError, field_validator, model_validator
+from pydantic import BeforeValidator, Field, ValidationError, field_validator, model_validator
 
 from ..common_models import IdNameType, IdNameTypeDescription, RFBaseModel
+from ..helpers import Validators
 
 
 class DiamondModel(RFBaseModel):
@@ -189,7 +190,7 @@ class Attributes(RFBaseModel):
     @field_validator('events', mode='after')
     @classmethod
     def remove_empty_events(cls, values):
-        """Remove empty events when ``NoteEvent`` skip the validation."""
+        """Remove empty events when `NoteEvent` skip the validation."""
         return [v for v in values if v.type_ and v.attributes]
 
 
@@ -198,7 +199,10 @@ class PreviewAttributesIn(RFBaseModel):
     text: str
     note_entities: Optional[list[str]] = []
     context_entities: Optional[list[str]] = []
-    topic: Union[list[str], str, None] = []
+    topic: Annotated[
+        Union[list[str], str, None],
+        BeforeValidator(Validators.convert_str_to_list),
+    ] = []
     labels: Optional[list[str]] = []
     validation_urls: Optional[list[str]] = []
 

{psengine-2.1.0 → psengine-2.2.0}/psengine/analyst_notes/note.py

@@ -12,9 +12,10 @@
 ##############################################################################################
 
 from functools import total_ordering
-from typing import Optional, Union
+from typing import Annotated, Optional, Union
 
 from pydantic import Field
+from typing_extensions import Doc
 
 from ..common_models import IdNameTypeDescription, RFBaseModel
 from ..constants import TIMESTAMP_STR
@@ -26,32 +27,34 @@ from .models import Attributes, PreviewAttributesIn, PreviewAttributesOut, Reque
 # AnalystNote also used by BaseEnrichedEntity
 @total_ordering
 class AnalystNote(RFBaseModel):
-    """Validate data received from ``/search``, ``/analystnote/{note}`` endpoints.
+    """Validate data received from the `/search` and `/analystnote/{note}` endpoints.
 
-    Methods:
-        __hash__:
-            Returns a hash value based on note ``id_``.
+    This class supports hashing, equality comparison, string representation, and total ordering
+    of `AnalystNote` instances.
 
-        __eq__:
-            Checks equality between two AnalystNote instances based on ``id_`` and published time.
+    Hashing:
+        Returns a hash value based on the note `id_`.
 
-        __gt__:
-            Defines a greater-than comparison between two AnalystNote instances based published time
-            and the ``id_``
+    Equality:
+        Checks equality between two `AnalystNote` instances based on the `id_` and published time.
 
-        __str__:
-            Returns a string representation of the AnalystNote instance with:
-            ``id_``, ``title``, and published timestamp.
+    Greater-than Comparison:
+        Defines a greater-than comparison between two `AnalystNote` instances based on the published
+        time and the `id_`.
 
-            .. code-block:: python
+    String Representation:
+        Returns a string representation of the `AnalystNote` instance including the `id_`, `title`,
+        and published timestamp.
 
-                >>> print(analyst_note)
-                Analyst Note ID: 12345, Title: Cyber Vuln, Published: 2024-05-21 10:42:30AM
+        ```python
+        >>> print(analyst_note)
+        Analyst Note ID: 12345, Title: Cyber Vuln, Published: 2024-05-21 10:42:30AM
+        ```
 
-    Total Ordering:
-        The ordering of AnalystNote instances is determined primarily by the published timestamp in
-        the attributes. If two instances have the same published timestamp, the note id is used as
-        a secondary criterion for ordering.
+    Ordering:
+        The ordering of `AnalystNote` instances is determined primarily by the published timestamp.
+        If two instances have the same published timestamp, the note `id_` is used as a secondary
+        criterion.
     """
 
     external_id: Optional[str] = None
@@ -77,7 +80,7 @@ class AnalystNote(RFBaseModel):
     @property
     def detection_rule_type(self) -> Optional[str]:
         """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`, and `snort rule` in the topics of the note.
         """
         topics_type = ('sigma rule', 'yara rule', 'snort rule')
 
@@ -101,26 +104,20 @@ class AnalystNote(RFBaseModel):
 
     def markdown(
         self,
-        extract_entities: bool = True,
-        diamond_model: bool = True,
-        html_tags: bool = False,
-        defang_malicious_infrastructure: bool = False,
-        character_limit: int = None,
-    ) -> str:
-        """Return the markdown representation of the Note.
-
-        Args:
-            extract_entities (bool): Extract and include entities in the markdown. Defaults to True.
-            diamond_model (bool): Include a diamond model visualization. Defaults to True.
-            html_tags (bool): Include HTML tags in the output. Defaults to False.
-            defang_malicious_infrastructure (bool): Defang URLs or other malicious indicators.
-                Defaults to False.
-            character_limit (int, optional): Limit the output to a specified number of characters.
-                Defaults to None.
-
-        Returns:
-            str: The generated markdown string.
-        """
+        extract_entities: Annotated[
+            bool, Doc('Extract and include entities in the markdown.')
+        ] = True,
+        diamond_model: Annotated[bool, Doc('Include a diamond model visualization.')] = True,
+        html_tags: Annotated[bool, Doc('Include HTML tags in the output.')] = False,
+        defang_malicious_infrastructure: Annotated[
+            bool, Doc('Defang URLs or other malicious indicators.')
+        ] = False,
+        character_limit: Annotated[
+            Optional[int],
+            Doc('Limit the output to a specified number of characters.'),
+        ] = None,
+    ) -> Annotated[str, Doc('The generated markdown string.')]:
+        """Return the markdown representation of the note."""
         return _markdown(
             self,
             extract_entities=extract_entities,
@@ -132,7 +129,7 @@ class AnalystNote(RFBaseModel):
 
 
 class AnalystNotePreviewIn(RFBaseModel):
-    """Validate data sent to ``/preview`` endpoint."""
+    """Validate data sent to `/preview` endpoint."""
 
     attributes: PreviewAttributesIn
     source: Optional[str]
@@ -141,14 +138,14 @@ class AnalystNotePreviewIn(RFBaseModel):
 
 
 class AnalystNotePreviewOut(RFBaseModel):
-    """Validate data received from ``/preview`` endpoint."""
+    """Validate data received from `/preview` endpoint."""
 
     attributes: PreviewAttributesOut
     source: IdNameTypeDescription
 
 
 class AnalystNotePublishIn(AnalystNotePreviewIn):
-    """Validate data sent to ``/publish`` endpoint."""
+    """Validate data sent to `/publish` endpoint."""
 
     attributes: PreviewAttributesIn
     source: Optional[str] = None
@@ -160,13 +157,13 @@ class AnalystNotePublishIn(AnalystNotePreviewIn):
 
 
 class AnalystNotePublishOut(RFBaseModel):
-    """Validate data received from ``/publish`` endpoint."""
+    """Validate data received from `/publish` endpoint."""
 
     note_id: str
 
 
 class AnalystNoteSearchIn(RFBaseModel):
-    """Validate data sent to ``/search`` endpoint."""
+    """Validate data sent to `/search` endpoint."""
 
     published: Optional[str] = None
     entity: Optional[str] = None