psengine 2.0.7__tar.gz → 2.1.1__tar.gz

{psengine-2.0.7 → psengine-2.1.1}/PKG-INFO

@@ -1,12 +1,22 @@
 Metadata-Version: 2.4
 Name: psengine
-Version: 2.0.7
+Version: 2.1.1
 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://github.com/RecordedFuture-ProfessionalServices/psengine/blob/main/CHANGELOG.rst
+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/x-rst
 License-File: LICENSE
@@ -16,29 +26,26 @@ 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.5.2
+Requires-Dist: pydantic-settings[toml]<2.11.0,>=2.5.2
 Requires-Dist: markdown-strings==3.4.0
 Provides-Extra: dev
-Requires-Dist: tox==4.12.1; extra == "dev"
-Requires-Dist: build==1.0.3; 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-vcr==1.0.2; extra == "dev"
-Requires-Dist: pytest-watch==4.2.0; extra == "dev"
-Requires-Dist: requests==2.29.0; extra == "dev"
+Requires-Dist: pytest-httpdbg==0.9.0; extra == "dev"
 Requires-Dist: ruff~=0.11.0; extra == "dev"
-Requires-Dist: wheel==0.37.1; extra == "dev"
-Requires-Dist: setuptools==61.0.0; extra == "dev"
-Requires-Dist: Sphinx==7.1.2; extra == "dev"
-Requires-Dist: sphinxcontrib-confluencebuilder==2.3.0; extra == "dev"
-Requires-Dist: atlassian-python-api==3.41.4; extra == "dev"
-Requires-Dist: sphinx_autodoc_typehints==1.25.2; extra == "dev"
-Requires-Dist: sphinxcontrib-napoleon; extra == "dev"
-Requires-Dist: typer==0.12.5; extra == "dev"
-Requires-Dist: cookiecutter==2.6.0; extra == "dev"
-Requires-Dist: tomlkit>=0.13.2; 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: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+Requires-Dist: griffe-typingdoc; extra == "docs"
 Dynamic: license-file
 
 ==================================================

{psengine-2.0.7 → psengine-2.1.1}/psengine/_version.py

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

{psengine-2.0.7 → psengine-2.1.1}/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.0.7 → psengine-2.1.1}/psengine/analyst_notes/models.py

@@ -189,7 +189,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]
 
 

{psengine-2.0.7 → psengine-2.1.1}/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