psengine 2.0.4__py3-none-any.whl

psengine/playbook_alerts/markdown/markdown_domain_abuse.py

@@ -0,0 +1,118 @@
+##################################### 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 base64
+
+from markdown_strings import bold
+
+from ...constants import TIMESTAMP_STR
+from ...helpers import FormattingHelpers
+from ...markdown import MarkdownMaker
+from ...markdown.markdown import divider, table_from_rows
+from ..models.pba_domain_abuse import ValueServer
+
+
+def _add_screenshots(pba, md_maker: MarkdownMaker):
+    screenshots = [f'{bold("Screenshot Count:")} {len(pba.panel_evidence_summary.screenshots)}']
+    for screenshot in pba.panel_evidence_summary.screenshots:
+        screenshots.append(f'{bold("Created:")} {screenshot.created.strftime(TIMESTAMP_STR)}')
+
+        image = base64.b64encode(pba.images[screenshot.image_id]['image_bytes']).decode('utf-8')
+
+        for mentions in pba.panel_evidence_summary.screenshot_mentions:
+            if mentions.screenshot == screenshot.image_id and mentions.url:
+                url = FormattingHelpers.cleanup_rf_id(mentions.url)
+                md_maker.iocs_to_defang.append(url)
+                screenshots.append(f'{bold("Screenshot URL:")} {"".join(url)}')
+
+        screenshots.append(f'![img](data:image/png;base64,{image})')
+        screenshots.append(divider())
+
+    md_maker.add_section('Screenshots', screenshots)
+
+
+def _add_whois(pba, md_maker: MarkdownMaker):
+    whois_body = [
+        body for body in pba.panel_evidence_whois.body if isinstance(body.value, ValueServer)
+    ]
+
+    whois_data = []
+    for whois in whois_body:
+        entity = FormattingHelpers.cleanup_rf_id(whois.entity)
+        md_maker.iocs_to_defang.append(entity)
+        whois_entity = f"{bold('Entity:')} {entity}"
+
+        if (v := whois.value) and v.name_servers:
+            created_dt, updated_dt, expires_dt = '', '', ''
+            name_servers = [FormattingHelpers.cleanup_rf_id(s) for s in v.name_servers]
+            servers = f"{bold('Name servers:')} {', '.join(name_servers)}"
+            md_maker.iocs_to_defang.extend(name_servers)
+
+            if v.created_date:
+                created_dt = f'{bold("Creation Date:")} {v.created_date.strftime(TIMESTAMP_STR)}'
+
+            if v.updated_date:
+                updated_dt = f'{bold("Update Date:")} {v.updated_date.strftime(TIMESTAMP_STR)}'
+
+            if v.expires_date:
+                expires_dt = f'{bold("Expiration Date:")} {v.expires_date.strftime(TIMESTAMP_STR)}'
+
+            registrar = f'{bold("Registrar:")} {v.registrar_name}' if v.registrar_name else ''
+
+            whois_data.extend(
+                [whois_entity, servers, created_dt, updated_dt, expires_dt, registrar]
+            )
+
+    if whois_data:
+        md_maker.add_section('WHOIS Details', whois_data)
+
+
+def _add_dns_records(pba, md_maker: MarkdownMaker):
+    records = [
+        [
+            FormattingHelpers.cleanup_rf_id(record.entity),
+            record.risk_score,
+            record.criticality,
+            record.record_type,
+            ', '.join(c.context for c in record.context_list if c),
+        ]
+        for record in pba.panel_evidence_summary.resolved_record_list
+    ]
+    md_maker.iocs_to_defang.extend(list(zip(*records))[0])
+
+    records.sort(key=lambda x: x[1], reverse=True)
+    records.insert(0, ['Entity', 'Risk Score', 'Criticality', 'Record Type', 'Context'])
+    evidence_summary = [
+        f'{bold("Reason:")} {pba.panel_evidence_summary.explanation}\n',
+        f'{table_from_rows(records)}',
+    ]
+
+    md_maker.add_section('DNS Records', evidence_summary)
+
+
+def _domain_abuse_markdown(pba, md_maker: MarkdownMaker, *args) -> str:  # noqa: ARG001
+    if targets := pba.panel_status.targets:
+        targets = [FormattingHelpers.cleanup_rf_id(t) for t in targets]
+        md_maker.iocs_to_defang.extend(targets)
+        md_maker.add_section('Targets', targets)
+
+    if pba.panel_evidence_summary.resolved_record_list:
+        _add_dns_records(pba, md_maker)
+
+    if pba.panel_evidence_whois:
+        _add_whois(pba, md_maker)
+
+    if pba.images and not md_maker.character_limit:
+        _add_screenshots(pba, md_maker)
+
+    return md_maker.format_output()

psengine/playbook_alerts/markdown/markdown_identity_exposure.py

@@ -0,0 +1,158 @@
+##################################### 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 markdown_strings import bold, unordered_list
+
+from ...constants import TIMESTAMP_STR
+from ...markdown import MarkdownMaker
+from ...markdown.markdown import divider
+
+DOMAIN_CONFIG_URL = 'https://app.recordedfuture.com/portal/identity/domain-configuration'
+PORTAL_URL = 'https://app.recordedfuture.com/portal/playbook-alerts/{}'
+
+
+def _get_compromised_host(pba) -> str:
+    host_data = []
+    summ = pba.panel_evidence_summary
+
+    if not (
+        summ.compromised_host
+        and summ.compromised_host.os_username
+        and summ.compromised_host.computer_name
+    ):
+        return ''
+
+    comprom = summ.compromised_host
+    os = _format_field('Operating System', comprom.os)
+    username = _format_field('OS Username', comprom.os_username)
+    file_path = _format_field('File Path', comprom.malware_file)
+    timezone = _format_field('Time Zone', comprom.timezone)
+    uac = _format_field('User Account Control Setting', comprom.uac)
+    av = _format_field('Antivirus', comprom.antivirus)
+    machine = _format_field('Machine Name', comprom.computer_name)
+
+    host_data = [x for x in [os, username, file_path, timezone, machine, uac, av] if x]
+
+    return f"\n{bold('Compromised Host:')}\n\n{unordered_list(host_data, esc=False)}"
+
+
+def _get_technology(pba) -> str:
+    items = []
+    for tech in pba.panel_evidence_summary.technologies:
+        label = 'Category:' if tech.category else 'Technology:'
+        items.append(f'{bold(label)} {tech.name}')
+
+    if not items:
+        return ''
+
+    return f"\n{bold('Technology:')}\n\n{unordered_list(items, esc=False)}"
+
+
+def _add_exposure(pba, md_maker: MarkdownMaker):
+    summ = pba.panel_evidence_summary
+    result = []
+
+    result.append(_format_field('Identity', pba.panel_status.entity_name))
+    result.append(_format_password(summ.exposed_secret.details))
+    result.append(_format_assessments(summ.assessments))
+    if summ.compromised_host.exfiltration_date:
+        result.append(
+            _format_field(
+                'Exfiltration Date', summ.compromised_host.exfiltration_date.strftime(TIMESTAMP_STR)
+            )
+        )
+
+    result.append(_format_field('Authorization URL', summ.authorization_url))
+    result.append(_format_field('IP Address', summ.infrastructure.ip))
+    result.append(_format_field('Properties', summ.exposed_secret.details.properties))
+
+    result.append(_format_hashes(summ.exposed_secret.hashes))
+    result.append(_format_source(summ.dump))
+    result.append(_get_compromised_host(pba))
+
+    result.append('\n' + _format_field('Malware Family', summ.malware_family.name))
+
+    result.append(_get_technology(pba))
+    result.append(divider())
+
+    md_maker.add_section('Exposure', result)
+
+
+def _format_field(label, value) -> str:
+    """Generic helper for fields that can be single strings or lists.
+    Returns an empty string if there's no value.
+    """
+    if not value:
+        return ''
+    if isinstance(value, list):
+        value = ', '.join(value)
+    return f'{bold(label + ":")} {value}'
+
+
+def _format_password(secret_details):
+    password = ''
+    if secret_details.clear_text_hint:
+        # Hides all but the password hint
+        password = (
+            f"{bold('Password:')} {secret_details.clear_text_hint:•<8} [ⓘ] ({DOMAIN_CONFIG_URL})"
+        )
+    if secret_details.clear_text_value:
+        # If support has enabled clear text, it takes precedence
+        password = f"{bold('Password:')} {secret_details.clear_text_value}"
+    return password
+
+
+def _format_assessments(assessments) -> str:
+    if assessments:
+        names = ', '.join(ass.name for ass in assessments)
+        return f"{bold('Assessment:')} {names}"
+    return ''
+
+
+def _format_hashes(hashes) -> str:
+    hash_values = [f'{bold(h.algorithm)} {h.hash_}' for h in hashes if h.hash_]
+    if hash_values:
+        formatted_hashes = '\n\n' + unordered_list(hash_values, esc=False)
+        return f"\n{bold('Hashes:')} {formatted_hashes}\n"
+    return ''
+
+
+def _format_source(dump) -> str:
+    source_data = []
+    if dump.name:
+        source_data.append(f"{bold('Name:')} {dump.name}")
+    if dump.description:
+        source_data.append(f"{bold('Description:')} {dump.description}")
+    if source_data:
+        return f"\n{bold('Source:')}\n\n{unordered_list(source_data, esc=False)}"
+    return ''
+
+
+def _add_actions_to_consider(pba, md_maker: MarkdownMaker):
+    actions = []
+    actions.append(f'-  [Check Incident Report] ({PORTAL_URL.format(pba.playbook_alert_id)})')
+    actions.append('-  Enforce Password Reset')
+    actions.append('-  Initiate MFA Challenge')
+    actions.append('-  Request Compromised Host Incident Response')
+    actions.append('-  Review Malware Hunting Packages')
+
+    md_maker.add_section('Actions to Consider', actions)
+
+
+def _identity_exposure_markdown(pba, md_maker: MarkdownMaker, *args) -> str:  # noqa: ARG001
+    if pba.panel_evidence_summary:
+        _add_exposure(pba, md_maker)
+
+    _add_actions_to_consider(pba, md_maker)
+
+    return md_maker.format_output()

psengine/playbook_alerts/models/__init__.py

@@ -0,0 +1,36 @@
+##################################### 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 .common_models import ResolvedEntity
+from .panel_log import PanelLogV2
+from .panel_status import PanelAction
+from .pba_code_repo_leak import (
+    CodeRepoEvidencePanel,
+    CodeRepoPanelStatus,
+)
+from .pba_cyber_vulnerability import (
+    CyberVulnerabilityEvidencePanel,
+    CyberVulnerabilityPanelStatus,
+)
+from .pba_domain_abuse import (
+    DomainAbuseEvidenceDns,
+    DomainAbuseEvidenceSummary,
+    DomainAbuseEvidenceWhois,
+    DomainAbusePanelStatus,
+)
+from .pba_identity_exposures import (
+    IdentityEvidencePanel,
+    IdentityPanelStatus,
+)
+from .pba_third_party_risk import TPREvidencePanel, TPRPanelStatus
+from .search_endpoint import DatetimeRange, SearchCounts, SearchData, SearchResponse, SearchStatus

psengine/playbook_alerts/models/common_models.py

@@ -0,0 +1,18 @@
+##################################### 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 ...common_models import RFBaseModel
+
+
+class ResolvedEntity(RFBaseModel):
+    name: str

psengine/playbook_alerts/models/panel_log.py

@@ -0,0 +1,329 @@
+##################################### 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 datetime import datetime
+from typing import Optional
+
+from pydantic import Field, HttpUrl, model_validator
+
+from ...common_models import IdOptionalNameType, RFBaseModel
+
+
+class ChangeType(RFBaseModel):
+    type_: str = Field(alias='type')
+
+
+class PriorityChange(ChangeType):
+    old: str
+    new: str
+
+
+class StatusChange(ChangeType):
+    old: str
+    new: str
+    actions_taken: list
+
+
+class OldNewOptionalType(ChangeType):
+    """This is valid for the following Panel Log types.
+
+    - ``ExternalIdChange``,
+    - ``DescriptionChange``,
+    - ``TitleChange``,
+    - ``ReopenStrategyChange``
+
+    """
+
+    old: Optional[str] = None
+    new: Optional[str] = None
+
+
+class AddedRemovedTypeEntities(ChangeType):
+    """This is valid for the following Panel Log types.
+
+    - ``EntityChangeV2``,
+    - ``RelatedEntityChangeV2``
+    """
+
+    removed: Optional[list[IdOptionalNameType]] = []
+    added: Optional[list[IdOptionalNameType]] = []
+
+
+class AddedRemovedList(ChangeType):
+    removed: Optional[list[str]] = []
+    added: Optional[list[str]] = []
+
+
+class CommentChange(ChangeType):
+    comment: str
+
+
+class Assignee(RFBaseModel):
+    id_: str = Field(alias='id')
+    name: str
+
+
+class AssigneeChange(ChangeType):
+    old: Optional[Assignee] = None
+    new: Optional[Assignee] = None
+
+
+class DnsRecord(RFBaseModel):
+    type_: Optional[str] = Field(alias='type', default=None)
+    entity: Optional[IdOptionalNameType] = None
+
+
+class DomainAbuseDnsChange(ChangeType):
+    domain: str
+    removed: list[DnsRecord]
+    added: list[DnsRecord]
+
+
+class WhoisRecord(RFBaseModel):
+    status: Optional[str] = None
+    registrar_name: Optional[str] = None
+    private_registration: Optional[bool] = None
+    name_servers: Optional[list[str]] = []
+    contact_email: Optional[str] = None
+    created: Optional[datetime] = None
+
+
+class WhoisContactRecord(ChangeType):
+    telephone: Optional[str] = None
+    street1: Optional[str] = None
+    state: Optional[str] = None
+    postal_code: Optional[str] = None
+    organization: Optional[str] = None
+    name: Optional[str] = None
+    fax: Optional[str] = None
+    email: Optional[str] = None
+    country_code: Optional[str] = None
+    country: Optional[str] = None
+    city: Optional[str] = None
+    created: Optional[datetime] = None
+
+
+class DomainAbuseWhoisChange(ChangeType):
+    domain: str
+    old_record: Optional[WhoisRecord] = None
+    new_record: Optional[WhoisRecord] = None
+    removed_contacts: list[WhoisContactRecord]
+    added_contacts: list[WhoisContactRecord]
+
+
+class LogotypeInScreenshot(RFBaseModel):
+    logotype_id: Optional[str] = None
+    screenshot_id: Optional[str] = None
+    url: HttpUrl
+
+
+class DomainAbuseLogoTypeChange(ChangeType):
+    domain: str
+    removed: Optional[list[LogotypeInScreenshot]] = []
+    added: Optional[list[LogotypeInScreenshot]] = []
+
+
+class MaliciousAssessment(RFBaseModel):
+    id_: str = Field(alias='id')
+    level: int
+    title: Optional[str] = None
+
+
+class MaliciousDnsRecord(RFBaseModel):
+    id_: Optional[str] = Field(alias='id', default=None)
+    assessments: list[MaliciousAssessment]
+
+
+class DomainAbuseMaliciousDnsChange(ChangeType):
+    domain: str
+    removed: Optional[list[MaliciousDnsRecord]] = []
+    added: Optional[list[MaliciousDnsRecord]] = []
+
+
+class ReregistrationRecord(RFBaseModel):
+    registrar: Optional[str] = None
+    registrar_name: Optional[str] = None
+    iana_id: Optional[int] = None
+    expiration: Optional[datetime] = None
+
+
+class DomainAbuseReregistrationRecordChange(ChangeType):
+    domain: str
+    removed: Optional[ReregistrationRecord] = None
+    added: Optional[ReregistrationRecord] = None
+
+
+class Source(RFBaseModel):
+    id_: str = Field(alias='id')
+    name: str
+
+
+class UrlAssessment(MaliciousAssessment):
+    source: Source
+
+
+class MaliciousUrlRecord(RFBaseModel):
+    url: Optional[HttpUrl] = None
+    assessments: list[UrlAssessment]
+
+
+class DomainAbuseMaliciousUrlChange(ChangeType):
+    domain: str
+    removed: Optional[list[MaliciousUrlRecord]] = []
+    added: Optional[list[MaliciousUrlRecord]] = []
+
+
+class MentionedEntity(RFBaseModel):
+    entity: IdOptionalNameType
+    reference: Optional[str] = None
+    fragment: Optional[str] = None
+
+
+class ScreenshotMention(RFBaseModel):
+    url: HttpUrl
+    screenshot_id: str
+    document: str
+    analyzed: datetime
+    mentioned_entities: list[MentionedEntity]
+
+
+class DomainAbuseScreenshotMentions(ChangeType):
+    domain: str
+    added: list[ScreenshotMention]
+
+
+class VulnerabilityAssessment(RFBaseModel):
+    id_: str = Field(alias='id')
+    level: int
+    title: Optional[str] = None
+
+
+class TriggeredRiskRule(RFBaseModel):
+    id_: str = Field(alias='id')
+    name: Optional[str] = None
+    description: Optional[str] = None
+    evidence_string: Optional[str] = None
+    machine_name: Optional[str] = None
+    timestamp: Optional[datetime] = None
+
+
+class VulnerabilityLifecycleChange(ChangeType):
+    added: Optional[VulnerabilityAssessment] = None
+    removed: Optional[VulnerabilityAssessment] = None
+    triggered_by_risk_rule: Optional[TriggeredRiskRule] = None
+
+
+class Document(RFBaseModel):
+    id_: str = Field(alias='id')
+    content: str
+    owner_id: str
+    owner_name: Optional[str] = None
+    published: datetime
+
+
+class WatchList(RFBaseModel):
+    id_: str = Field(alias='id')
+    name: Optional[str] = None
+
+
+class RepoAssessment(RFBaseModel):
+    id_: str = Field(alias='id')
+    level: int
+    title: Optional[str] = None
+    text_indicator: Optional[str] = None
+    entity: Optional[IdOptionalNameType] = None
+
+
+class CodeRepoLeakageEvidence(RFBaseModel):
+    assessments: list[RepoAssessment]
+    document: Document
+    target_entities: list[IdOptionalNameType]
+    watch_lists: list[WatchList]
+
+
+class CodeRepoLeakageEvidenceChange(ChangeType):
+    added: list[CodeRepoLeakageEvidence]
+
+
+class TPRRiskEvidence(RFBaseModel):
+    level: int
+    evidence_string: Optional[str] = None
+    timestamp: Optional[datetime] = None
+
+
+class ThirdPartyAssessmentChange(ChangeType):
+    risk_attribute: str
+    added: Optional[TPRRiskEvidence] = None
+    removed: Optional[TPRRiskEvidence] = None
+
+
+class Assessment(RFBaseModel):
+    level: int
+    evidence_string: str
+    timestamp: datetime
+
+
+class AssessmentChange(ChangeType):
+    risk_attribute: str
+    removed: Optional[Assessment] = None
+    added: Optional[Assessment] = None
+
+
+TYPE_MAPPING = {
+    'assignee_change': AssigneeChange,
+    'status_change': StatusChange,
+    'priority_change': PriorityChange,
+    'reopen_strategy_change': OldNewOptionalType,
+    'title_change': OldNewOptionalType,
+    'entities_change': AddedRemovedTypeEntities,
+    'related_entities_change': AddedRemovedTypeEntities,
+    'description_change': OldNewOptionalType,
+    'external_id_change': OldNewOptionalType,
+    'comment_change': CommentChange,
+    'action_change': AddedRemovedList,
+    'assessment_ids_change': AddedRemovedList,
+    'dns_change': DomainAbuseDnsChange,
+    'whois_change': DomainAbuseWhoisChange,
+    'logotype_in_screenshot_change': DomainAbuseLogoTypeChange,
+    'malicious_dns_change': DomainAbuseMaliciousDnsChange,
+    'reregistration_change': DomainAbuseReregistrationRecordChange,
+    'malicious_url_change': DomainAbuseMaliciousUrlChange,
+    'screenshot_mentions_change': DomainAbuseScreenshotMentions,
+    'lifecycle_in_cve_change': VulnerabilityLifecycleChange,
+    'evidence_change': CodeRepoLeakageEvidenceChange,
+    'tpr_assessment_change': ThirdPartyAssessmentChange,
+    'assessment_change': AssessmentChange,
+}
+
+
+class PanelLogV2(RFBaseModel):
+    id_: str = Field(alias='id')
+    author_id: Optional[str] = None
+    author_name: Optional[str] = None
+    created: datetime
+    changes: list
+
+    @model_validator(mode='before')
+    @classmethod
+    def validate_changes(cls, data):
+        """Validate each panel_log_v2 changes based on the supported changes.
+
+        The list of changes is in ``TYPE_MAPPING``. Skip unsupported changes.
+        """
+        new_changes = [
+            model_type.model_validate(change)
+            for change in data.get('changes', [])
+            if (change_type := change.get('type')) and (model_type := TYPE_MAPPING.get(change_type))
+        ]
+        data['changes'] = new_changes
+        return data