psengine 2.0.4__py3-none-any.whl

psengine/enrich/lookup.py

@@ -0,0 +1,299 @@
+##################################### 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 Optional, Union
+
+from pydantic import Field
+
+from ..common_models import IdNameType, IdNameTypeDescription, RFBaseModel
+from ..constants import TIMESTAMP_STR
+from .models.base_enriched_entity import BaseEnrichedEntity
+from .models.lookup import (
+    CVSS,
+    CVSSV3,
+    CVSSRating,
+    DnsPortCert,
+    EnterpriseList,
+    EntityRisk,
+    IPLocation,
+    LinkedMalware,
+    Links,
+    NvdReference,
+    RawRisk,
+    RiskMapping,
+    RiskyCIDRPIP,
+)
+
+
+class EnrichedIP(BaseEnrichedEntity):
+    """IP Enriched by ``/v2/ip/{ip}`` endpoint. Inherit behaviours from ``BaseEnrichedEntity``."""
+
+    risk: Optional[EntityRisk] = None
+    links: Optional[Links] = None
+    enterprise_lists: Optional[list[EnterpriseList]] = Field(alias='enterpriseLists', default=None)
+    threat_list: Optional[list[IdNameTypeDescription]] = Field(alias='threatLists', default=None)
+    risk_mapping: Optional[list[RiskMapping]] = Field(alias='riskMapping', default=None)
+    dns_port_cert: Optional[DnsPortCert] = Field(alias='dnsPortCert', default=None)
+    location: Optional[IPLocation] = None
+    risky_cidr_ips: Optional[list[RiskyCIDRPIP]] = Field(alias='riskyCIDRIPs', default=None)
+
+
+class EnrichedDomain(BaseEnrichedEntity):
+    """Domain Enriched by ``/v2/domain/{domain}`` endpoint.
+    Inherit behaviours from ``BaseEnrichedEntity``.
+    """
+
+    risk: Optional[EntityRisk] = None
+    links: Optional[Links] = None
+    enterprise_lists: Optional[list[EnterpriseList]] = Field(alias='enterpriseLists', default=None)
+    threat_lists: Optional[list[IdNameTypeDescription]] = Field(alias='threatLists', default=None)
+    risk_mapping: Optional[list[RiskMapping]] = Field(alias='riskMapping', default=None)
+
+
+class EnrichedURL(BaseEnrichedEntity):
+    """URL Enriched by ``/v2/url/{url}`` endpoint.
+    Inherit behaviours from ``BaseEnrichedEntity``.
+    """
+
+    risk: Optional[EntityRisk] = None
+    links: Optional[Links] = None
+    enterprise_lists: Optional[list[EnterpriseList]] = Field(alias='enterpriseLists', default=None)
+    risk_mapping: Optional[list[RiskMapping]] = Field(alias='riskMapping', default=None)
+
+
+class EnrichedHash(BaseEnrichedEntity):
+    """Hash Enriched by ``/v2/hash/{hash}`` endpoint.
+    Inherit behaviours from ``BaseEnrichedEntity``.
+    """
+
+    risk: Optional[EntityRisk] = None
+    links: Optional[Links] = None
+    enterprise_lists: Optional[list[EnterpriseList]] = Field(alias='enterpriseLists', default=None)
+    threat_list: Optional[list[IdNameTypeDescription]] = Field(alias='threatLists', default=None)
+    risk_mapping: Optional[list[RiskMapping]] = Field(alias='riskMapping', default=None)
+    hash_algorithm: Optional[str] = Field(alias='hashAlgorithm', default=None)
+    file_hashes: Optional[list[str]] = Field(alias='fileHashes', default=None)
+
+
+class EnrichedVulnerability(BaseEnrichedEntity):
+    """Vulnerability Enriched by ``/v2/vulnerability/{cve}`` endpoint.
+    Inherit behaviours from ``BaseEnrichedEntity``.
+    """
+
+    risk: Optional[EntityRisk] = None
+    links: Optional[Links] = None
+    enterprise_lists: Optional[list[EnterpriseList]] = Field(alias='enterpriseLists', default=None)
+    threat_list: Optional[list[IdNameTypeDescription]] = Field(alias='threatLists', default=None)
+    risk_mapping: Optional[list[RiskMapping]] = Field(alias='riskMapping', default=None)
+    common_names: Optional[list[str]] = Field(alias='commonNames', default=None)
+    lifecycle_stage: Optional[str] = Field(alias='lifecycleStage', default=None)
+    linked_malware: Optional[LinkedMalware] = Field(alias='linkedMalware', default=None)
+    cpe: Optional[list[str]] = None
+    cpe_22_uri: Optional[list[str]] = Field(alias='cpe22uri', default=None)
+    cvss: Optional[CVSS] = None
+    cvss_ratings: list[CVSSRating] = Field(alias='cvssRatings', default=None)
+    cvssv3: Optional[CVSSV3] = None
+    nvd_description: Optional[str] = Field(alias='nvdDescription', default=None)
+    nvd_references: Optional[list[NvdReference]] = Field(alias='nvdReferences', default=None)
+    raw_risk: Optional[list[RawRisk]] = Field(alias='rawrisk', default=None)
+    related_links: Optional[list[str]] = Field(alias='relatedLinks', default=None)
+
+
+class EnrichedMalware(BaseEnrichedEntity):
+    """Malware Enriched by ``/v2/malware/{id}`` endpoint.
+    Inherit behaviours from ``BaseEnrichedEntity``.
+    """
+
+    links: Optional[Links] = None
+    categories: Optional[list[IdNameType]] = None
+
+
+class EnrichedCompany(BaseEnrichedEntity):
+    """Company Enriched by ``/v2/company/{id}`` and ``/v2/company/by_domain/{domain}`` endpoint.
+    Inherit behaviours from ``BaseEnrichedEntity``.
+    """
+
+    risk: Optional[EntityRisk] = None
+    curated: Optional[bool] = None
+    threat_list: Optional[list[IdNameTypeDescription]] = Field(alias='threatLists', default=None)
+    risk_mapping: Optional[list[RiskMapping]] = Field(alias='riskMapping', default=None)
+
+
+_EnrichmentObjectType = Union[
+    EnrichedCompany,
+    EnrichedDomain,
+    EnrichedIP,
+    EnrichedHash,
+    EnrichedMalware,
+    EnrichedURL,
+    EnrichedVulnerability,
+]
+
+
+@total_ordering
+class EnrichmentData(RFBaseModel):
+    """Model for the custom return of lookup of IOCs.
+
+    Methods:
+        __hash__:
+            Returns a hash value based on the content's attributes.
+
+            - If ``content`` is an instance of ``EnrichedMalware``:
+                The hash is calculated using the entity ``id_`` and the last seen timestamp.
+            - Else:
+                The hash includes the entity ``id_``, risk score, and the last seen timestamp.
+
+        __eq__:
+            Checks equality between two ``EnrichmentData`` instances based on their ``content``.
+
+            - If ``content`` is an instance of ``EnrichedMalware``:
+                Equality is determined by comparing the entity name and the last seen timestamp.
+            - Else:
+                Equality is determined by comparing the entity name, last seen timestamp and
+                risk score.
+
+        __gt__:
+            Defines a greater-than comparison between ``EnrichmentData`` instances based on their
+            ``content``.
+
+            - If ``content`` is an instance of ``EnrichedMalware``:
+                Comparison is based on the last seen timestamp and entity name.
+            - Else:
+                Comparison is based on the last seen timestamp, entity name, and risk score.
+
+        __str__ and __repr__:
+            Returns a string representation of the ``EnrichmentData`` instance.
+            __repr__ is used for printing elements properly within a list.
+
+            - If ``content`` is an instance of ``EnrichedMalware``:
+                Includes class name, entity name, and last seen timestamp.
+
+                .. code-block:: python
+
+                    >>> print(enrichment_data)
+                    EnrichedMalware: exampleMalware, Last Seen: 2024-05-21 01:30:00PM
+
+            - Else:
+                Includes class name, entity name, risk score, and last seen timestamp.
+
+                .. code-block:: python
+
+                    >>> print(enrichment_data)
+                    EnrichedIP: 1.1.1.1, Risk Score: 85, Last Seen: 2024-05-21 01:30:00PM
+
+    Total Ordering:
+        The ordering of ``EnrichmentData`` instances is determined by the ``content``'s last
+        seen timestamp.
+
+        - If ``content`` is an instance of ``EnrichedMalware``:
+            If two instances have the same last seen timestamp, their entity name is used as a
+            secondary criterion.
+
+        - Else:
+            If two instances have the same last seen timestamp, their entity name and risk score are
+            used as secondary criteria.
+    """
+
+    entity: str
+    entity_type: Optional[str]
+    is_enriched: bool
+    content: Union[str, _EnrichmentObjectType]
+
+    def __hash__(self):
+        if isinstance(self.content, EnrichedMalware):
+            return hash(
+                (
+                    self.content.entity.id_,
+                    self.content.timestamps.last_seen,
+                )
+            )
+        elif isinstance(self.content, str):
+            return hash(self.entity)
+
+        return hash(
+            (
+                self.content.entity.id_,
+                self.content.risk.score,
+                self.content.timestamps.last_seen,
+            )
+        )
+
+    def __eq__(self, other: 'EnrichmentData'):
+        if isinstance(self.content, EnrichedMalware):
+            return (
+                self.content.entity.name,
+                self.content.timestamps.last_seen,
+            ) == (
+                other.content.entity.name,
+                other.content.timestamps.last_seen,
+            )
+        elif isinstance(self.content, str):
+            return self.entity == other.entity
+        return (
+            self.content.risk.score,
+            self.content.entity.name,
+            self.content.timestamps.last_seen,
+        ) == (
+            other.content.risk.score,
+            other.content.entity.name,
+            other.content.timestamps.last_seen,
+        )
+
+    def __gt__(self, other: 'EnrichmentData'):
+        if isinstance(self.content, EnrichedMalware):
+            return (
+                self.content.timestamps.last_seen,
+                self.content.entity.name,
+            ) > (
+                other.content.timestamps.last_seen,
+                other.content.entity.name,
+            )
+        elif isinstance(self.content, str):
+            return self.entity > other.entity
+        return (
+            self.content.risk.score,
+            self.content.timestamps.last_seen,
+            self.content.entity.name,
+        ) > (
+            other.content.risk.score,
+            other.content.timestamps.last_seen,
+            other.content.entity.name,
+        )
+
+    def __str__(self):
+        if isinstance(self.content, EnrichedMalware):
+            return (
+                f'{self.content.__class__.__name__}: {self.content.entity.name}, '
+                f'Last Seen: {self.content.timestamps.last_seen.strftime(TIMESTAMP_STR)}'
+            )
+        elif isinstance(self.content, str):
+            return f'{self.entity}: {self.content}'
+        return (
+            f'{self.content.__class__.__name__}: {self.content.entity.name}, '
+            f'Risk Score: {self.content.risk.score}, '
+            f'Last Seen: {self.content.timestamps.last_seen.strftime(TIMESTAMP_STR)}'
+        )
+
+    def __repr__(self):
+        if isinstance(self.content, EnrichedMalware):
+            return (
+                f'{self.content.__class__.__name__}: {self.content.entity.name}, '
+                f'Last Seen: {self.content.timestamps.last_seen.strftime(TIMESTAMP_STR)}'
+            )
+        elif isinstance(self.content, str):
+            return f'{self.entity}: {self.content}'
+        return (
+            f'{self.content.__class__.__name__}: {self.content.entity.name}, '
+            f'Risk Score: {self.content.risk.score}, '
+            f'Last Seen: {self.content.timestamps.last_seen.strftime(TIMESTAMP_STR)}'
+        )

psengine/enrich/lookup_mgr.py

@@ -0,0 +1,341 @@
+##################################### 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 Optional
+from urllib.parse import quote
+
+from pydantic import validate_call
+
+from ..endpoints import CONNECT_API_BASE_URL
+from ..helpers import MultiThreadingHelper, connection_exceptions, debug_call
+from ..rf_client import RFClient
+from .constants import (
+    ALLOWED_ENTITIES,
+    ENTITY_FIELDS,
+    IOC_TO_MODEL,
+    MALWARE_FIELDS,
+    MESSAGE_404,
+    TYPE_MAPPING,
+)
+from .errors import EnrichmentLookupError
+from .lookup import EnrichmentData
+
+
+class LookupMgr:
+    """Enrichment of a single or a group of Entities."""
+
+    def __init__(self, rf_token: str = None):
+        """Initializes the LookupMgr object.
+
+        Args:
+            rf_token (str, optional): Recorded Future API token. Defaults to None
+        """
+        self.log = logging.getLogger(__name__)
+        self.rf_client = RFClient(api_token=rf_token) if rf_token else RFClient()
+
+    @validate_call
+    @debug_call
+    def lookup(
+        self,
+        entity: str,
+        entity_type: ALLOWED_ENTITIES,
+        fields: Optional[list[str]] = None,
+    ) -> EnrichmentData:
+        """Perform lookup of an entity based on its id or name.
+        ``entity`` can contain both a Recorded Future ID or a entity name. See example below.
+
+        The entity_type must always be specified.
+        The allowed values are:
+
+            - ``company``,
+            - ``Company``,
+            - ``company_by_domain``,
+            - ``CyberVulnerability``,
+            - ``domain``,
+            - ``hash``,
+            - ``Hash``,
+            - ``InternetDomainName``,
+            - ``ip``,
+            - ``IpAddress``,
+            - ``malware``,
+            - ``Malware``,
+            - ``Organization``,
+            - ``url``,
+            - ``URL``,
+            - ``vulnerability``,
+
+        If ``fields`` parameter is specified, it will be added to the mandatory fields, which
+        are:
+
+            - for every entity except malware: ``['entity', 'risk', 'timestamps']``
+            - for malware: ``['entity', 'timestamps']``
+
+
+        Examples:
+            Performing a lookup using different ``entity`` type:
+
+                .. code-block:: python
+                    :linenos:
+
+                    mgr.lookup('idn:google.com', 'domain')
+                    mgr.lookup('google.com', 'domain')
+                    mgr.lookup('A_BCDE', 'company')
+
+
+            Performing a lookup of a ``company_by_domain`` specifying additional fields:
+
+                .. code-block:: python
+                    :linenos:
+
+                    mgr.lookup(
+                        'recordedfuture.com',
+                        entity_type='company_by_domain',
+                        fields=['curated']
+                    )
+
+        The output is always ``EnrichmentData`` object with a format like below:
+        If a 404 is received:
+
+            .. code-block:: python
+
+                {
+                    'entity': entity,
+                    'entity_type': entity_type,
+                    'is_enriched': False,
+                    'content': '404 received. Nothing known on this entity',
+                }
+
+        If a 200 is received:
+
+            .. code-block:: python
+
+                {
+                    'entity': entity,
+                    'entity_type': entity_type,
+                    'is_enriched': True,
+                    'content': the enriched data model
+                }
+
+        To write an enriched object to file:
+
+            .. code-block:: python
+                :linenos:
+
+                from pathlib import Path
+                from json import dump
+                from psengine.enrich import LookupMgr
+
+                mgr = LookupMgr()
+                OUTPUT_DIR = Path('your' / 'path')
+                OUTPUT_DIR.mkdir(exists_ok=True)
+                ip = mgr.lookup('1.1.1.1', 'ip')
+                (OUTPUT_DIR / f'{ip.entity}.json').write_text(dumps(ip.json(), indent=2))
+
+
+        Endpoint:
+            ``v2/{entity_type}/{entity}``
+
+        Args:
+            entity (str): Name or RFID of the entity.
+            entity_type (str): Type of the entity.
+            fields (List[str], optional): Fields for the entity to enrich.
+            EnrichmentData: An object containing the entity details.
+
+        Raises:
+            ValidationError If a field does not match the type hint.
+            EnrichmentLookupError: if a lookup terminates with a non 200 or 404 return code.
+        """
+        default_fields = MALWARE_FIELDS if entity_type.lower() == 'malware' else ENTITY_FIELDS
+        fields = fields if fields else default_fields
+        fields = self._merge_fields(fields, default_fields)
+
+        return self._lookup(entity, entity_type, fields)
+
+    @validate_call
+    @debug_call
+    def lookup_bulk(
+        self,
+        entity: list[str],
+        entity_type: ALLOWED_ENTITIES,
+        fields: list[str] = ENTITY_FIELDS,
+        max_workers: Optional[int] = 0,
+    ) -> list[EnrichmentData]:
+        """Perform lookup of multiple entities based on ids or name.
+        ``entity`` can contain both a Recorded Future ID or a entity name.
+        The entities must be of the same ``entity_type``. See example below.
+
+        The ``entity_type`` must always be specified.
+        The allowed values are:
+
+             - ``company``,
+             - ``Company``,
+             - ``company_by_domain``,
+             - ``CyberVulnerability``,
+             - ``domain``,
+             - ``hash``,
+             - ``Hash``,
+             - ``InternetDomainName``,
+             - ``ip``,
+             - ``IpAddress``,
+             - ``malware``,
+             - ``Malware``,
+             - ``Organization``,
+             - ``url``,
+             - ``URL``,
+             - ``vulnerability``,
+
+        If ``fields`` parameter is specified, it will be added to the mandatory fields, which
+        are:
+
+            - for every entity except malware: ``['entity', 'risk', 'timestamps']``
+            - for malware: ``['entity', 'timestamps']``
+
+        Examples:
+            Multiple IOC types enrichment:
+
+                .. code-block:: python
+                     :linenos:
+
+                     data = {
+                         'IpAddress': ['1.1.1.1', '2.2.2.2'],
+                         'InternetDomainName': [ 'google.com', 'facebook.com']
+                     }
+                     results = []
+                     for entity_type, entities in data.items():
+                         results.extend(mgr.lookup_bulk(entities, entity_type)
+
+            To write an enriched object to file:
+
+                .. code-block:: python
+                    :linenos:
+
+                    from pathlib import Path
+                    from json import dump
+                    from psengine.enrich import LookupMgr
+
+                    mgr = LookupMgr()
+                    OUTPUT_DIR = Path('your' / 'path')
+                    OUTPUT_DIR.mkdir(exists_ok=True)
+                    data = mgr.lookup_bulk(['1.1.1.1', '8.8.8.8'], 'ip')
+                    for ip in data:
+                        (OUTPUT_DIR / f'{ip.entity}.json').write_text(dumps(ip.json(), indent=2))
+
+
+            The output is always a list of ``EnrichmentData`` object with a format like below:
+            If a 404 is received:
+
+                .. code-block:: python
+
+                    {
+                        'entity': entity,
+                        'entity_type': entity_type,
+                        'is_enriched': False,
+                        'content': '404 received. Nothing known on this entity',
+                    }
+
+            If a 200 is received:
+
+                .. code-block:: python
+
+                    {
+                        'entity': entity,
+                        'entity_type': entity_type,
+                        'is_enriched': True,
+                        'content': the enriched data model
+                    }
+
+            Multithreaded examples:
+
+                .. code-block:: python
+
+                    mgr.lookup_bulk(['google.com', 'facebook.com'], 'domain', max_workers=10)
+
+        Endpoint:
+             ``v2/{entity_type}/{entity}``
+
+
+        Args:
+             entity (List[str]): list of names or RFIDs.
+             entity_type (List[str]): Type of the entities.
+             fields (List[str], optional): Fields for the entities to enrich.
+             max_workers (int, optional): number of workers to multithread requests.
+
+        Returns:
+             List[EnrichmentData]: A list of object containing the entity details.
+
+        Raises:
+             ValidationError If a field does not match the type hint.
+             EnrichmentLookupError: if a lookup terminates with a non 200 or 404 return code.
+        """
+        default_fields = MALWARE_FIELDS if entity_type.lower() == 'malware' else ENTITY_FIELDS
+        fields = fields if fields else default_fields
+        fields = self._merge_fields(fields, default_fields)
+        if max_workers:
+            res = MultiThreadingHelper.multithread_it(
+                max_workers,
+                self._lookup,
+                iterator=entity,
+                entity_type=entity_type,
+                fields=fields,
+            )
+        else:
+            res = [self._lookup(entity, entity_type, fields) for entity in entity]
+
+        return res
+
+    def _lookup(
+        self,
+        entity: str,
+        entity_type: str,
+        fields: list,
+    ):
+        entity_type = TYPE_MAPPING.get(entity_type, entity_type)
+
+        enriched = self._fetch_data(
+            entity=entity,
+            entity_type=entity_type,
+            fields=fields,
+        )
+        if not enriched:
+            enriched = EnrichmentData(
+                entity=entity,
+                entity_type=entity_type,
+                is_enriched=False,
+                content=MESSAGE_404,
+            )
+
+        return enriched
+
+    @connection_exceptions(ignore_status_code=[404], exception_to_raise=EnrichmentLookupError)
+    @debug_call
+    def _fetch_data(self, entity: str, entity_type: str, fields: list) -> EnrichmentData:
+        """Perform the actual lookup. If a 404 is returned, return None."""
+        encoded_entity = quote(entity, safe='.')
+        entity_type = 'company/by_domain' if entity_type == 'company_by_domain' else entity_type
+
+        url = f'{CONNECT_API_BASE_URL}/{entity_type}/{encoded_entity}'
+
+        params = {}
+        params['fields'] = ','.join(fields)
+
+        response = self.rf_client.request('get', url, params=params).json()
+        return EnrichmentData(
+            entity=entity,
+            entity_type=entity_type,
+            is_enriched=True,
+            content=IOC_TO_MODEL[entity_type].model_validate(response['data']),
+        )
+
+    def _merge_fields(self, fields: list[str], default_fields: list[str]) -> list[str]:
+        return list(set(fields).union(set(default_fields)))

psengine/enrich/models/__init__.py

@@ -0,0 +1,13 @@
+##################################### 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.                                                         #
+##############################################################################################
+

psengine/enrich/models/base_enriched_entity.py

@@ -0,0 +1,43 @@
+##################################### 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 typing import Optional
+
+from pydantic import Field
+
+from ...analyst_notes.note import AnalystNote
+from ...common_models import IdNameTypeDescription, RFBaseModel
+from ..models.lookup import (
+    AIInsights,
+    Metric,
+    ReferenceCount,
+    RelatedEntities,
+    Sighting,
+    Timestamps,
+)
+
+
+class BaseEnrichedEntity(RFBaseModel):
+    """Base Model for Enrichment.
+    This model is intended to be inherited and should not be used on its own.
+    """
+
+    ai_insights: Optional[AIInsights] = Field(alias='aiInsights', default=None)
+    analyst_notes: Optional[list[AnalystNote]] = Field(alias='analystNotes', default=[])
+    counts: Optional[list[ReferenceCount]] = []
+    entity: Optional[IdNameTypeDescription] = None
+    intel_card: Optional[str] = Field(alias='intelCard', default=None)
+    metrics: Optional[list[Metric]] = []
+    related_entities: Optional[list[RelatedEntities]] = Field(alias='relatedEntities', default=[])
+    sightings: Optional[list[Sighting]] = []
+    timestamps: Optional[Timestamps] = None