psengine 2.8.5__tar.gz → 2.10.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: psengine
-Version: 2.8.5
+Version: 2.10.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
@@ -76,6 +76,7 @@ It can easily interact with the following Recorded Future datasets:
 - On demand IOC enrichment
 - Risklists
 - Risk History
+- Sandbox Detonation of files and URLs
 - STIX conversion
 
 

{psengine-2.8.5 → psengine-2.10.0}/README.md

@@ -43,6 +43,7 @@ It can easily interact with the following Recorded Future datasets:
 - On demand IOC enrichment
 - Risklists
 - Risk History
+- Sandbox Detonation of files and URLs
 - STIX conversion
 
 

{psengine-2.8.5 → psengine-2.10.0}/psengine/analyst_notes/note_mgr.py

@@ -92,6 +92,11 @@ class AnalystNoteMgr:
 
         `max_results` is the maximum number of references, not notes.
 
+        Note:
+            Search returns a reduced `AnalystNote` projection. Fields such as
+            `diamond_model`, `events`, and `labels` are not populated and must be
+            retrieved per note via `lookup()`.
+
         Endpoint:
             `/analystnote/search`
 

{psengine-2.8.5 → psengine-2.10.0}/psengine/classic_alerts/classic_alert.py

@@ -208,6 +208,7 @@ class ClassicAlert(RFBaseModel):
         html_tags: Annotated[bool, Doc('Include HTML tags in the markdown.')] = False,
         character_limit: Annotated[int | None, Doc('Character limit for the markdown.')] = None,
         defang_iocs: Annotated[bool, Doc('Defang IOCs in hits.')] = False,
+        comment: Annotated[bool, Doc('Include reviewer note in the markdown.')] = False,
     ) -> Annotated[str, Doc('Markdown representation of the alert.')]:
         """Return a markdown string representation of the `ClassicAlert` instance.
 
@@ -229,6 +230,7 @@ class ClassicAlert(RFBaseModel):
             html_tags=html_tags,
             character_limit=character_limit,
             defang_iocs=defang_iocs,
+            comment=comment,
         )
 
     @property

{psengine-2.8.5 → psengine-2.10.0}/psengine/classic_alerts/markdown/markdown.py

@@ -306,6 +306,13 @@ def _add_hits_section_if_no_enriched_entities(
         )
 
 
+def _add_comment_section(
+    md_maker: MarkdownMaker, classic_alert: 'ClassicAlert', comment: bool
+) -> None:
+    if comment and classic_alert.review.note:
+        md_maker.add_section('Reviewer Note', classic_alert.review.note)
+
+
 def _markdown_alert(
     classic_alert: 'ClassicAlert',
     owner_org: bool = False,
@@ -315,6 +322,7 @@ def _markdown_alert(
     html_tags: bool = False,
     character_limit: int = None,
     defang_iocs: bool = False,
+    comment: bool = False,
 ) -> str:
     """Returns a markdown string representation of the `ClassicAlert` instance.
 
@@ -331,6 +339,7 @@ def _markdown_alert(
         html_tags (bool, optional): Include HTML tags in the markdown. Defaults to False.
         character_limit (int, optional): Character limit for the markdown. Defaults to None.
         defang_iocs (bool, optional): Defang IOCs in hits. Defaults to False.
+        comment (bool, optional): Include reviewer note in the markdown. Defaults to False.
 
     Raises:
         AlertMarkdownError: If fields are not available.
@@ -351,6 +360,7 @@ def _markdown_alert(
         _add_summary_section(md_maker, classic_alert)
         _add_owner_org_section(md_maker, classic_alert, owner_org)
         _add_ai_insights_section(md_maker, classic_alert, ai_insights)
+        _add_comment_section(md_maker, classic_alert, comment)
 
         if classic_alert.enriched_entities:
             _add_enriched_entities_sections(md_maker, classic_alert, triggered_by, html_tags)

{psengine-2.8.5 → psengine-2.10.0}/psengine/config/config.py

@@ -18,7 +18,7 @@ from copy import deepcopy
 from pathlib import Path
 from typing import Annotated
 
-from pydantic import Field, Secret, field_validator, validate_call
+from pydantic import Field, Secret, ValidationInfo, field_validator, validate_call
 from pydantic_settings import (
     BaseSettings,
     DotEnvSettingsSource,
@@ -32,6 +32,7 @@ from typing_extensions import Doc
 
 from ..constants import (
     ASI_TOKEN_ENV_VAR,
+    ASI_TOKEN_VALIDATION_REGEX,
     BACKOFF_FACTOR,
     POOL_MAX_SIZE,
     REQUEST_TIMEOUT,
@@ -39,6 +40,8 @@ from ..constants import (
     RF_TOKEN_ENV_VAR,
     RF_TOKEN_VALIDATION_REGEX,
     ROOT_DIR,
+    SANDBOX_TOKEN_ENV_VAR,
+    SANDBOX_TOKEN_VALIDATION_REGEX,
     SSL_VERIFY,
     STATUS_FORCELIST,
 )
@@ -48,6 +51,20 @@ from .errors import ConfigFileError
 PLAT_REGEX = r'^([A-Z]|[a-z])+(\/\d+)?((\.\d+)*?)$'
 APP_ID_REGEX = r'^\S+\/\d+((\.\d+)*?)$'
 
+TOKEN_CONFIG = {
+    'rf_token': (RF_TOKEN_ENV_VAR, RF_TOKEN_VALIDATION_REGEX, 'Recorded Future'),
+    'asi_token': (
+        ASI_TOKEN_ENV_VAR,
+        ASI_TOKEN_VALIDATION_REGEX,
+        'Recorded Future Attack Surface Intelligence',
+    ),
+    'sandbox_token': (
+        SANDBOX_TOKEN_ENV_VAR,
+        SANDBOX_TOKEN_VALIDATION_REGEX,
+        'Recorded Future Sandbox',
+    ),
+}
+
 
 class RFToken(Secret[str]):
     """Recorded Future token mask."""
@@ -93,6 +110,7 @@ class ConfigModel(BaseSettings):
     app_id: str | None = Field(default=None, pattern=APP_ID_REGEX, examples=['get-alerts/1.0.0'])
     rf_token: RFToken | None = Field(default=os.environ.get(RF_TOKEN_ENV_VAR, ''))
     asi_token: RFToken | None = Field(default=os.environ.get(ASI_TOKEN_ENV_VAR, ''))
+    sandbox_token: RFToken | None = Field(default=os.environ.get(SANDBOX_TOKEN_ENV_VAR, ''))
     http_proxy: str | None = None
     https_proxy: str | None = None
     client_ssl_verify: bool | None = SSL_VERIFY
@@ -159,28 +177,28 @@ class ConfigModel(BaseSettings):
                 raise ValueError('The config file extension must be .toml or .json or .env')
         return tuple(sources)
 
-    @field_validator('rf_token', mode='before')
+    @field_validator('rf_token', 'asi_token', 'sandbox_token', mode='before')
     @classmethod
     def validate_token(
         cls,
-        rf_token: Annotated[str, Doc('Recorded Future token.')],
+        token: Annotated[str, Doc('API token value.')],
+        info: ValidationInfo,
     ) -> Annotated[str, Doc('Validated token.')]:
-        """Validate a Recorded Future token.
+        """Validate a Recorded Future API token (`rf_token`, `asi_token`, or `sandbox_token`).
 
         Raises:
-            ValueError: When the token is not 32 alphanumeric characters in the `[a-f][0-9]` range.
+            ValueError: When the token does not match the expected format for its field.
         """
-        rf_token = rf_token or os.environ.get(RF_TOKEN_ENV_VAR)
-        if not rf_token:
+        env_var, regex, label = TOKEN_CONFIG[info.field_name]
+        token = token or os.environ.get(env_var)
+        if not token:
             # Edge case: when RF_RF_TOKEN env var is set, it is used and RF_TOKEN is ignored
             # So we check if RF_TOKEN is set and validate it
             return ''
-        if not re.match(RF_TOKEN_VALIDATION_REGEX, rf_token):
-            raise ValueError(
-                f'Invalid Recorded Future API token.must match regex {RF_TOKEN_VALIDATION_REGEX}'
-            )
+        if not re.fullmatch(regex, token):
+            raise ValueError(f'Invalid {label} API token. Must match regex {regex}')
 
-        return rf_token
+        return token
 
     @validate_call
     def save_config(
@@ -198,7 +216,7 @@ class ConfigModel(BaseSettings):
         """
         directory = Path(directory)
         log = logging.getLogger(__name__)
-        data = self.model_dump_json(exclude=['rf_token', 'asi_token'], indent=4)
+        data = self.model_dump_json(exclude=['rf_token', 'asi_token', 'sandbox_token'], indent=4)
         OSHelpers.mkdir(directory)
         config_path = directory / file
         log.info(f'Saving config in {config_path.as_posix()}')
@@ -245,6 +263,8 @@ class Config:
             platform_id (str): Name & version of the tool this integrates with, example: ES/8.0.0.
             app_id (str): Name & version of the integration itself, example: get-alerts/1.0.0.
             rf_token (str): Recorded Future API token.
+            asi_token (str): Recorded Future Attack Surface Intelligence API token.
+            sandbox_token (str): Recorded Future Sandbox API token.
             http_proxy (str): HTTP proxy.
             https_proxy (str): HTTPS proxy.
             client_ssl_verify (bool): SSL verification. Default is True.

{psengine-2.8.5 → psengine-2.10.0}/psengine/constants.py

@@ -26,6 +26,8 @@ RF_TOKEN_ENV_VAR = 'RF_TOKEN'  # noqa: S105
 RF_TOKEN_VALIDATION_REGEX = r'^[a-z0-9]{32}$'  # noqa: S105
 ASI_TOKEN_ENV_VAR = 'RF_ASI_TOKEN'  # noqa: S105
 ASI_TOKEN_VALIDATION_REGEX = r'^[a-zA-Z0-9-_]{32}$'  # noqa: S105
+SANDBOX_TOKEN_ENV_VAR = 'RF_SANDBOX_TOKEN'  # noqa: S105
+SANDBOX_TOKEN_VALIDATION_REGEX = r'^[a-f0-9]{40}$'  # noqa: S105
 
 
 #####################

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

@@ -53,10 +53,13 @@ EP_PLAYBOOK_ALERT = BASE_URL + '/playbook-alert'
 EP_PLAYBOOK_ALERT_SEARCH = EP_PLAYBOOK_ALERT + '/search'
 EP_PLAYBOOK_ALERT_COMMON = EP_PLAYBOOK_ALERT + '/common'
 EP_PLAYBOOK_ALERT_CODE_REPO_LEAKAGE = EP_PLAYBOOK_ALERT + '/code_repo_leakage'
+EP_PLAYBOOK_ALERT_COMPROMISED_BANK_CHECKS = EP_PLAYBOOK_ALERT + '/compromised_bank_checks'
 EP_PLAYBOOK_ALERT_CYBER_VULNERABILITY = EP_PLAYBOOK_ALERT + '/vulnerability'
 EP_PLAYBOOK_ALERT_DOMAIN_ABUSE = EP_PLAYBOOK_ALERT + '/domain_abuse'
 EP_PLAYBOOK_ALERT_GEOPOLITICS_FACILITY = EP_PLAYBOOK_ALERT + '/geopolitics_facility'
 EP_PLAYBOOK_ALERT_IDENTITY_NOVEL_EXPOSURES = EP_PLAYBOOK_ALERT + '/identity_novel_exposures'
+EP_PLAYBOOK_ALERT_MALICIOUS_SITES = EP_PLAYBOOK_ALERT + '/malicious_sites'
+EP_PLAYBOOK_ALERT_MALICIOUS_SITES_CREATE = EP_PLAYBOOK_ALERT_MALICIOUS_SITES + '/create'
 EP_PLAYBOOK_ALERT_THIRD_PARTY_RISK = EP_PLAYBOOK_ALERT + '/third_party_risk'
 EP_PLAYBOOK_ALERT_MALWARE_REPORT = EP_PLAYBOOK_ALERT + '/malware_report'
 
@@ -72,6 +75,8 @@ EP_ENTITY_LOOKUP = BASE_URL + '/entity-match/entity/{}'
 EP_LIST = BASE_URL + '/list'
 EP_CREATE_LIST = EP_LIST + '/create'
 EP_SEARCH_LIST = EP_LIST + '/search'
+EP_LIST_ENTITIES_WITH_TAGS = EP_LIST + '/{}/entitiesWithTags'
+EP_LIST_ENTITY_TAGS = EP_LIST + '/{}/entity/tags'
 
 ###############################################################################
 # SOAR Endpoints
@@ -158,6 +163,33 @@ 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}/{{}}'
 
+###############################################################################
+# Recorded Future Sandbox API Base URLs and Endpoints
+###############################################################################
+SANDBOX_API_VERSION = 'v0'
+
+# Sandbox base URLs by region
+SANDBOX_BASE_URLS = {
+    'eu': 'https://sandbox.recordedfuture.com/api/' + SANDBOX_API_VERSION,
+    'usa': 'https://us-sandbox.recordedfuture.com/api/' + SANDBOX_API_VERSION,
+    'apj': 'https://apj-sandbox.recordedfuture.com/api/' + SANDBOX_API_VERSION,
+    'public': 'https://tria.ge/api/' + SANDBOX_API_VERSION,
+    'private': 'https://private.tria.ge/api/' + SANDBOX_API_VERSION,
+}
+
+# Sandbox Sample Endpoints (using {base_url} as placeholder)
+EP_SANDBOX_SAMPLES = '{base_url}/samples'
+EP_SANDBOX_SAMPLES_ID = '{base_url}/samples/{sample_id}'
+EP_SANDBOX_SAMPLES_DOWNLOAD = '{base_url}/samples/{sample_id}/sample'
+EP_SANDBOX_SAMPLES_SUMMARY = '{base_url}/samples/{sample_id}/summary'
+EP_SANDBOX_SAMPLES_STATIC_REPORT = '{base_url}/samples/{sample_id}/reports/static'
+EP_SANDBOX_SAMPLES_OVERVIEW = '{base_url}/samples/{sample_id}/overview.json'
+EP_SANDBOX_SAMPLES_BEHAVIORAL = '{base_url}/samples/{sample_id}/{task_id}/report_triage.json'
+EP_SANDBOX_SAMPLES_PROFILE = '{base_url}/samples/{sample_id}/profile'
+EP_SANDBOX_SEARCH = '{base_url}/search'
+EP_SANDBOX_PROFILES = '{base_url}/profiles'
+EP_SANDBOX_PROFILES_ID = '{base_url}/profiles/{profile_id}'
+
 ################################################################################
 # Threat Map API Endpoints
 ################################################################################

{psengine-2.8.5 → psengine-2.10.0}/psengine/enrich/models/soar.py

@@ -38,7 +38,6 @@ class Evidence(RFBaseModel):
     timestamp: datetime
     description: str
     rule: str
-    # TODO - temp fix until API team fixes/confirms behaviour of sightings
     sightings: int = 0
     mitigation: str
     level: int

{psengine-2.8.5 → psengine-2.10.0}/psengine/entity_lists/__init__.py

@@ -11,6 +11,20 @@
 # accessed from any third party API.                                                         #
 ##############################################################################################
 
-from .entity_list import EntityList, ListEntity, ListInfoOut, ListStatusOut
+from .constants import ListTagName
+from .entity_list import (
+    EntityList,
+    ListEntity,
+    ListEntityWithTags,
+    ListInfoOut,
+    ListStatusOut,
+)
 from .entity_list_mgr import EntityListMgr
 from .errors import ListApiError, ListResolutionError, ListStateError
+from .models import (
+    EntityNotResolvedOperation,
+    ListEntityTag,
+    ReplaceEntityTagsOut,
+    TagsUnchangedOperation,
+    TagsUpdatedOperation,
+)

psengine-2.10.0/psengine/entity_lists/constants.py

@@ -0,0 +1,90 @@
+##################################### 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
+
+IS_READY_INCREMENT = 5
+
+ADD_OP = 'add'
+REMOVE_OP = 'remove'
+UNCHANGED_NAME = 'unchanged'
+ERROR_NAME = 'error'
+
+
+class ListTagName(str, Enum):
+    """The 57 predefined tag values accepted by `list/{id}/entity/tags`.
+
+    Provided for discoverability only - `update_entity_tags` accepts plain strings too,
+    and the API is the authority on which values are valid. `name` values here are the
+    API values (`tier1`), not display names (`Tier 1`).
+
+    See https://docs.recordedfuture.com/reference/lists-available-tags.
+    """
+
+    THIRD_PARTY = '3rd_party'
+    FOURTH_PARTY = '4th_party'
+    AVAILABILITY = 'availability'
+    BUSINESS_CONTINUITY = 'business_continuity'
+    C_SUITE = 'c_suite'
+    CEO = 'ceo'
+    CFO = 'cfo'
+    CLOUD = 'cloud'
+    CONFIDENTIAL_DATA = 'confidential_data'
+    CONFIDENTIALITY = 'confidentiality'
+    CONFIRMED = 'confirmed'
+    COO = 'coo'
+    CRITICAL = 'critical'
+    CRITICAL_INFRASTRUCTURE = 'critical_infrastructure'
+    CUSTOMER_DATA = 'customer_data'
+    CYBER_VENDOR = 'cyber_vendor'
+    DEVELOPMENT = 'development'
+    DMZ = 'dmz'
+    DORA = 'dora'
+    ECOMMERCE = 'ecommerce'
+    EOL = 'eol'
+    EOS = 'eos'
+    FALSE_NEGATIVE = 'false_negative'
+    FALSE_POSITIVE = 'false_positive'
+    FINANCIAL = 'financial'
+    FINISHED_GOODS = 'finished_goods'
+    GDPR = 'gdpr'
+    HIGH = 'high'
+    HIPAA = 'hipaa'
+    INFORMATION_AND_COMMUNICATION_TECHNOLOGY = 'information_and_communication_technology'
+    INTEGRITY = 'integrity'
+    INTERNAL = 'internal'
+    INTERNET_FACING = 'internet_facing'
+    ISO_27001 = 'iso_27001'
+    LOW = 'low'
+    M_AND_A = 'm_and_a'
+    MEDIUM = 'medium'
+    MONITORING = 'monitoring'
+    MOST_CRITICAL_SUPPLIER = 'most_critical_supplier'
+    NETWORK_CONNECTIVITY = 'network_connectivity'
+    NO_PATCH_AVAILABLE = 'no_patch_available'
+    PCI_DSS = 'pci_dss'
+    PII = 'pii'
+    POTENTIAL = 'potential'
+    PRODUCTION = 'production'
+    PROTECTED_HEALTH_INFORMATION = 'protected_health_information'
+    RAW_MATERIALS = 'raw_materials'
+    SOX = 'sox'
+    SUBSIDIARY = 'subsidiary'
+    TEMP_INCIDENT = 'temp_incident'
+    TIER0 = 'tier0'
+    TIER1 = 'tier1'
+    TIER2 = 'tier2'
+    TIER3 = 'tier3'
+    TRUE_NEGATIVE = 'true_negative'
+    TRUE_POSITIVE = 'true_positive'
+    UNPATCHED = 'unpatched'

{psengine-2.8.5 → psengine-2.10.0}/psengine/entity_lists/entity_list.py

@@ -22,7 +22,7 @@ from typing_extensions import Doc
 
 from ..common_models import IdNameType, RFBaseModel
 from ..constants import TIMESTAMP_STR
-from ..endpoints import EP_LIST
+from ..endpoints import EP_LIST, EP_LIST_ENTITIES_WITH_TAGS, EP_LIST_ENTITY_TAGS
 from ..entity_match import EntityMatchMgr, MatchApiError
 from ..helpers import debug_call
 from ..helpers.helpers import connection_exceptions
@@ -31,9 +31,13 @@ from .constants import ADD_OP, ERROR_NAME, IS_READY_INCREMENT, REMOVE_OP, UNCHAN
 from .errors import ListApiError
 from .models import (
     AddEntityRequestModel,
+    EntityNotResolvedOperation,
     ListEntityOperationResponse,
+    ListEntityTag,
     OwnerOrganisationDetails,
     RemoveEntityRequestModel,
+    ReplaceEntityTagsIn,
+    ReplaceEntityTagsOut,
 )
 
 
@@ -85,6 +89,17 @@ class ListEntity(RFBaseModel):
         )
 
 
+class ListEntityWithTags(ListEntity):
+    """Validate data received from `/{listId}/entitiesWithTags` endpoint.
+
+    Identical to `ListEntity`, with the addition of the list-specific `tags` assigned to the
+    entity. Tags are predefined and only populated for lists whose type has tagging enabled -
+    see `ListEntityTag`.
+    """
+
+    tags: list[ListEntityTag] = []
+
+
 class EntityList(ListInfoOut):
     """Validate data received from `/create` endpoint."""
 
@@ -273,6 +288,99 @@ class EntityList(ListInfoOut):
         response = self.rf_client.request('get', url)
         return [ListEntity.model_validate(entity) for entity in response.json()]
 
+    @debug_call
+    @connection_exceptions(ignore_status_code=[], exception_to_raise=ListApiError)
+    def entities_with_tags(
+        self,
+    ) -> Annotated[
+        list[ListEntityWithTags],
+        Doc('Response from the `list/{id}/entitiesWithTags` endpoint.'),
+    ]:
+        """Get entities for a list, together with their list-specific tags.
+
+        Tags are **not** free-text. They are a fixed set of 57 predefined values, so arbitrary
+        tag strings cannot be expected. See
+        https://docs.recordedfuture.com/reference/lists-available-tags for the full list of valid
+        tags, their display names, and their API values.
+
+        `tags` is only populated for lists whose type has tagging enabled server-side (currently
+        Third-Parties Watch Lists). A list of any other type returns its entities with an empty
+        `tags` list rather than an error, so an empty `tags` does not indicate a failure. A list
+        whose type supports tagging but which has not yet been migrated server-side responds 400
+        instead.
+
+        Endpoint:
+            `list/{id}/entitiesWithTags`
+
+        Raises:
+            ListApiError: If connection error occurs. The API responds 400 if the list's type
+                supports tagging but the list has not been migrated to support tags, and 404 if
+                the list does not exist.
+        """
+        url = EP_LIST_ENTITIES_WITH_TAGS.format(self.id_)
+        response = self.rf_client.request('get', url)
+        return [ListEntityWithTags.model_validate(entity) for entity in response.json()]
+
+    @debug_call
+    @validate_call
+    @connection_exceptions(ignore_status_code=[], exception_to_raise=ListApiError)
+    def update_entity_tags(
+        self,
+        entity: Annotated[
+            str | tuple[str, str], Doc('ID or (name, type) tuple of the entity to tag.')
+        ],
+        tags: Annotated[
+            list[str],
+            Doc('Complete set of tags to apply. Replaces every tag already on the entity.'),
+        ],
+    ) -> Annotated[
+        ReplaceEntityTagsOut, Doc('Response from the `list/{id}/entity/tags` endpoint.')
+    ]:
+        """Replace all tags on an entity in a list.
+
+        This **replaces** rather than appends: `tags` becomes the entity's complete tag set,
+        and passing an empty list clears every tag from it.
+
+        Tags are **not** free-text. They are a fixed set of 57 predefined values - pass them as
+        plain strings or as `ListTagName` members. Invalid names are rejected by the API with a
+        400. See https://docs.recordedfuture.com/reference/lists-available-tags for the full
+        list.
+
+        Tagging is only enabled for lists whose type supports it (currently Third-Parties Watch
+        Lists); other list types respond 403.
+
+        If `entity` is a `(name, type)` tuple that cannot be resolved, the returned
+        `operation` is an `EntityNotResolvedOperation` rather than an exception, matching
+        `add` and `remove`.
+
+        Endpoint:
+            `list/{id}/entity/tags`
+
+        Raises:
+            ValidationError: if any supplied parameter is of incorrect type.
+            ListApiError: If connection error occurs. The API responds 400 for an invalid tag
+                name, entity, or list, 403 if tag updates are not enabled for the list type,
+                and 404 if the entity is not on the list.
+        """
+        if isinstance(entity, str):
+            resolved_entity_id = entity
+        else:
+            resolved_entity = self.match_mgr.resolve_entity_id(entity[0], entity_type=entity[1])
+            if not resolved_entity.is_found:
+                return ReplaceEntityTagsOut(
+                    operation=EntityNotResolvedOperation(
+                        status='entity_not_resolved', message=str(resolved_entity.content)
+                    )
+                )
+            resolved_entity_id = resolved_entity.content.id_
+
+        request_body = {'entity': {'id': resolved_entity_id}, 'tags': tags}
+        ReplaceEntityTagsIn.model_validate(request_body)
+
+        url = EP_LIST_ENTITY_TAGS.format(self.id_)
+        response = self.rf_client.request('post', url, data=request_body)
+        return ReplaceEntityTagsOut.model_validate(response.json())
+
     @debug_call
     @connection_exceptions(ignore_status_code=[], exception_to_raise=ListApiError)
     def text_entries(

{psengine-2.8.5 → psengine-2.10.0}/psengine/entity_lists/models.py

@@ -12,15 +12,33 @@
 ##############################################################################################
 
 
+from datetime import datetime
+from typing import Literal
+
 from pydantic import Field
 
-from ..common_models import RFBaseModel
+from ..common_models import IdName, RFBaseModel
 
 
 class EntityID(RFBaseModel):
     id_: str = Field(alias='id')
 
 
+class ListEntityTag(IdName):
+    """Validate a single tag received from `/{listId}/entitiesWithTags` endpoint.
+
+    Tags are **not** free-text. They are a fixed set of 57 predefined values, populated only for
+    lists whose type has tagging enabled (currently Third-Parties Watch Lists), so arbitrary tag
+    strings cannot be supplied or expected. `id` always has the form
+    `enum:EntityListTag:<name>`, for example `enum:EntityListTag:tier1`.
+
+    `name` is the tag's API value (`tier1`), not its display name (`Tier 1`).
+
+    See https://docs.recordedfuture.com/reference/lists-available-tags for the full list of
+    valid tags.
+    """
+
+
 class Organisation(RFBaseModel):
     organisation_id: str
     organisation_name: str
@@ -84,3 +102,67 @@ class ListEntityOperationResponse(RFBaseModel):
     """Validate data received from `/{listId}/entity/remove` endpoint."""
 
     result: str
+
+
+class TagsUpdatedOperation(RFBaseModel):
+    """Tags on the entity were changed."""
+
+    status: Literal['tags_updated']
+    tags_before: list[str]
+    tags_after: list[str]
+    tags_added: list[str]
+    tags_removed: list[str]
+    updated: datetime
+
+
+class TagsUnchangedOperation(RFBaseModel):
+    """Requested tags already matched the entity's tags, so nothing changed."""
+
+    status: Literal['tags_unchanged']
+    current_tags: list[str]
+    message: str
+
+
+class EntityNotResolvedOperation(RFBaseModel):
+    """A `(name, type)` tuple could not be resolved to an entity ID.
+
+    Produced by psengine, never returned by the API. Mirrors how `add` and `remove`
+    surface a failed lookup in their result rather than raising.
+    """
+
+    status: Literal['entity_not_resolved']
+    message: str
+
+
+class ReplaceEntityTagsIn(RFBaseModel):
+    """Validate data sent to `/{listId}/entity/tags` endpoint."""
+
+    entity: EntityID
+    tags: list[str]
+
+
+class ReplaceEntityTagsOut(RFBaseModel):
+    """Validate data received from `/{listId}/entity/tags` endpoint.
+
+    `operation` is discriminated on `status`, so each variant only exposes the fields the
+    API actually returns for it.
+    """
+
+    entity_id: str | None = None
+    operation: TagsUpdatedOperation | TagsUnchangedOperation | EntityNotResolvedOperation = Field(
+        discriminator='status'
+    )
+
+    @property
+    def changed(self) -> bool:
+        """Whether the call actually changed the entity's tags."""
+        return self.operation.status == 'tags_updated'
+
+    @property
+    def current_tags(self) -> list[str] | None:
+        """The entity's tags after the call, or None if the entity was not resolved."""
+        if isinstance(self.operation, TagsUpdatedOperation):
+            return self.operation.tags_after
+        if isinstance(self.operation, TagsUnchangedOperation):
+            return self.operation.current_tags
+        return None