ps-banshee 1.1.0__py3-none-any.whl

banshee/__init__.py

@@ -0,0 +1,16 @@
+##################################### 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.                                                         #
+##############################################################################################
+
+"""Base package for PS Banshee."""
+
+from ._version import __version__ as version

banshee/_version.py

@@ -0,0 +1,15 @@
+#################################### 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 importlib.metadata import version
+
+__version__ = version('ps-banshee')

banshee/app_config.py

@@ -0,0 +1,40 @@
+#################################### 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 psengine.config import Config
+from pydantic import ValidationError
+
+from ._version import __version__
+from .commands.errors import InitConfigError
+
+
+def config_init(cmd: str, rf_token: str = None, no_ssl_verify: bool = False) -> Config:
+    """Global configuration for the CLI.
+
+    Args:
+        cmd (str): The command name + sub command, used to generate the app_id,
+            typically will be the name one of the banshee commands,
+            confor example: 'ca-search', or 'entity-lookup'.
+        rf_token (str, optional): The Recorded Future API token.
+        no_ssl_verify (bool, optional): Disable SSL verification.
+    """
+    # invert no_ssl_verify
+    ssl_verify = not no_ssl_verify
+    app_id = f'banshee_{cmd}/{__version__}'
+    try:
+        Config.init(rf_token=rf_token, app_id=app_id, client_ssl_verify=ssl_verify)
+    except ValidationError as e:
+        if 'rf_token' in e.errors()[0]['loc']:
+            raise InitConfigError('Invalid Recorded Future API key')  # noqa: B904
+        raise InitConfigError(e.errors()[0]['msg'])  # noqa: B904

banshee/branding.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 typer import Typer
+
+BRANDING = ':rocket: \033[93mBrought to you by the Cyber Security Engineers at Recorded Future\033[0m :rocket:'  # noqa: E501
+
+
+def banshee_cmd(app: Typer, help_: str, epilog: str, *args, **kwargs):
+    """Main decorator create banshee commands.
+    Under the hood, it adds branding to the help text of the command.
+
+
+    Args:
+        app (Typer): The Typer app instance
+        help_ (str): The help text for the command
+        epilog (str): The epilog text for the command
+        *args: Additional arguments to pass to the command
+        **kwargs: Additional keyword arguments to pass to the command
+
+    Returns:
+        Typer: The updated Typer app instance
+    """
+    help_ += f'\n\n{BRANDING}'
+    return app.command(help=help_, epilog=epilog, *args, **kwargs)  # noqa: B026

banshee/commands/__init__.py

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

banshee/commands/args.py

@@ -0,0 +1,44 @@
+##################################### 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 Annotated, Optional
+
+from typer import Option
+
+################################
+# Global options / arguments
+################################
+
+# How to use: api_key: RF_API_KEY = None
+OPT_RF_API_KEY = Annotated[
+    Optional[str],
+    Option(
+        '--api-key', '-k', help='Recorded Future API Key', envvar='RF_TOKEN', show_default=False
+    ),
+]
+
+# How to use: pretty: PRETTY_PRINT = False
+OPT_PRETTY_PRINT = Annotated[
+    bool, Option('--pretty', '-p', help='Pretty print the results in a human readable format')
+]
+
+
+OPT_NO_SSL_VERIFY = Annotated[
+    Optional[bool],
+    Option(
+        '--no-ssl-verify',
+        '-s',
+        help="""Disable SSL Verification. Useful when using proxies. To
+            utilize a proxy set the environment variable HTTP_PROXY or HTTPS_PROXY.""",
+    ),
+]

banshee/commands/cmd_classic_alerts.py

@@ -0,0 +1,175 @@
+##################################### 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 re
+import sys
+from typing import Annotated
+
+from typer import Argument, BadParameter, Option, Typer
+
+from ..branding import banshee_cmd
+from ..legacy_alerts.alert_lookup import lookup_alert
+from ..legacy_alerts.alert_search import search_alerts
+from ..legacy_alerts.alert_update import update_alerts
+from ..legacy_alerts.constants import AlertStatus
+from ..legacy_alerts.rules_search import search_alert_rules
+from .args import OPT_PRETTY_PRINT
+from .epilogs import (
+    EPILOG_ALERT_LOOKUP,
+    EPILOG_ALERT_RULES_SEARCH,
+    EPILOG_ALERT_SEARCH,
+    EPILOG_ALERT_UPDATE,
+)
+
+CMD_NAME = 'ca'
+CMD_HELP = 'Search and lookup Classic Alerts'
+CMD_RICH_HELP = 'Recorded Future Classic Alerts'
+
+app = Typer(no_args_is_help=True)
+
+ALERT_ID_INVALID_MSG = "Alert ID '{}' is not valid. Alert ID should be at least 6 characters long."  # noqa: E501
+
+###################################
+# Callbacks
+###################################
+
+
+def validate_alert_id(alert_id: str):
+    # if value is less than 6 char long
+    if len(alert_id) < 6:
+        raise BadParameter(ALERT_ID_INVALID_MSG.format(alert_id))
+
+    return alert_id
+
+
+def parse_alert_ids_input(value: list[str]):
+    if not value:
+        raise BadParameter('No Alert IDs supplied')
+
+    alert_ids = value
+    if isinstance(value, str):
+        alert_ids = [x for x in re.split(r'[\s]+', value) if x]
+
+        if not len(alert_ids):
+            raise BadParameter('No Alert IDs provided')
+
+    # Now check that each ID is valid
+    for alert_id in alert_ids:
+        validate_alert_id(alert_id)
+
+    return alert_ids
+
+
+def parse_triggered(value: str):
+    if not value.startswith('[') and not value.startswith('('):
+        value = f'-{value.strip()}'
+
+    return value
+
+
+###################################
+# Commands
+###################################
+
+
+@banshee_cmd(app=app, help_='Lookup a single Classic Alert', epilog=EPILOG_ALERT_LOOKUP)
+def lookup(
+    alert_id: Annotated[
+        str, Argument(help='Alert ID to lookup', callback=validate_alert_id, show_default=False)
+    ],
+    pretty: OPT_PRETTY_PRINT = False,
+):
+    lookup_alert(id_=alert_id, pretty=pretty)
+
+
+@banshee_cmd(app=app, help_='Search for Classic Alerts', epilog=EPILOG_ALERT_SEARCH)
+def search(
+    triggered: Annotated[
+        str,
+        Option(
+            '--triggered',
+            '-t',
+            callback=parse_triggered,
+            help='Filter on triggered time, e.g. 1d; 12h; [2024-08-01, 2024-08-14]; [2024-09-23 12:03:58.000, 2024-09-23 12:03:58.567)',  # noqa: E501
+            show_default=True,
+        ),
+    ] = '1d',
+    alert_rules: Annotated[
+        list[str],
+        Option('--rule', '-r', help='Filter by an alert rule name (freetext)', show_default=False),
+    ] = None,
+    status: Annotated[
+        AlertStatus, Option('-s', '--status', help='Filter by alert status', show_default=False)
+    ] = None,
+    pretty: OPT_PRETTY_PRINT = False,
+):
+    search_alerts(
+        triggered=triggered,
+        alert_rules=alert_rules,
+        status=status,
+        pretty=pretty,
+    )
+
+
+@banshee_cmd(app=app, help_='Search Classic Alert rules', epilog=EPILOG_ALERT_RULES_SEARCH)
+def rules(
+    freetext: Annotated[str, Argument(help='Freetext to search in alert rules')] = None,
+    pretty: OPT_PRETTY_PRINT = False,
+):
+    search_alert_rules(pretty=pretty, freetext=freetext)
+
+
+@banshee_cmd(app=app, help_='Update a classic alert', epilog=EPILOG_ALERT_UPDATE)
+def update(
+    alert_ids: list[str] = Argument(  # noqa: B008
+        ... if sys.stdin.isatty() else None,  # noqa: B008
+        show_default=False,
+        help='One or more whitespace separated Alert ID',
+    ),
+    status: Annotated[
+        AlertStatus, Option('-s', '--status', help='New alert status', show_default=False)
+    ] = None,
+    note: Annotated[str, Option('-n', '--note', help='Add a text note', show_default=False)] = None,
+    note_append: Annotated[
+        bool,
+        Option(
+            '-A',
+            '--append',
+            help='Append to the existing text note, instead of overwriting it.',
+            show_default=True,
+        ),
+    ] = False,
+    assignee: Annotated[
+        str,
+        Option(
+            '--assignee',
+            '-a',
+            help='New user to assign the alert(s) to. Accepts uhash or email address of the user, for example: uhash:3aXZxdkM12; analyst@acme.com',  # noqa: E501
+            show_default=False,
+        ),
+    ] = None,
+):
+    if alert_ids is None:
+        alert_ids = sys.stdin.read()
+
+    parsed_ids = parse_alert_ids_input(alert_ids)
+
+    if status is None and note is None and assignee is None:
+        raise BadParameter('At least one of --status, --note or --assignee must be privded.')
+
+    if note_append and note is None:
+        raise BadParameter('note argument must be provided when append option is set')
+
+    update_alerts(
+        alert_ids=parsed_ids, status=status, note=note, note_append=note_append, assignee=assignee
+    )

banshee/commands/cmd_entity.py

@@ -0,0 +1,54 @@
+##################################### 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 Annotated
+
+from typer import Argument, Option, Typer
+
+from ..branding import banshee_cmd
+from ..entity_match import EntityType, entity_lookup, entity_search
+from .args import OPT_PRETTY_PRINT
+from .epilogs import EPILOG_ENTITY_LOOKUP, EPILOG_ENTITY_SEARCH
+
+CMD_NAME = 'entity'
+CMD_HELP = 'Search and lookup entities'
+CMD_RICH_HELP = 'Entity Match'
+
+app = Typer(no_args_is_help=True)
+
+
+@banshee_cmd(app=app, help_='Lookup an entity by its ID', epilog=EPILOG_ENTITY_LOOKUP)
+def lookup(
+    entity_id: str = Argument(show_default=False, help='ID of the entity to lookup'),
+    pretty: OPT_PRETTY_PRINT = False,
+):
+    entity_lookup(entity_id=entity_id, pretty=pretty)
+
+
+@banshee_cmd(
+    app=app, help_='Search entities by name and optically by type', epilog=EPILOG_ENTITY_SEARCH
+)
+def search(
+    name: str = Argument(show_default=False, help='Name of the entity to search for'),
+    type_: Annotated[
+        list[EntityType],
+        Option(
+            '-t', '--type', help='One or more type of the entity to search for', show_default=False
+        ),
+    ] = None,
+    limit: Annotated[
+        int, Option('-l', '--limit', help='Limit number of results', min=1, max=100)
+    ] = 100,
+    pretty: OPT_PRETTY_PRINT = False,
+):
+    entity_search(name=name, type_=type_, limit=limit, pretty=pretty)

banshee/commands/cmd_ioc.py

@@ -0,0 +1,236 @@
+##################################### 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 re
+import sys
+from typing import Annotated, Optional
+
+from typer import Argument, BadParameter, Option, Typer
+
+from ..branding import banshee_cmd
+from ..indicators import IOCType, lookup_ioc, search_ioc, search_ioc_rules, soar_enrich
+from .args import OPT_PRETTY_PRINT
+from .epilogs import EPILOG_IOC_BULK_LOOKUP, EPILOG_IOC_LOOKUP, EPILOG_IOC_RULES, EPILOG_IOC_SEARCH
+
+CMD_NAME = 'ioc'
+CMD_HELP = 'Search and lookup IOCs'
+CMD_RICH_HELP = 'Indicators of Compromise'
+
+app = Typer(no_args_is_help=True)
+
+
+def parse_ioc_input(value: list[str]):
+    if not value:
+        raise BadParameter('No IOCs supplied')
+
+    iocs = value
+    if isinstance(value, str):
+        iocs = [x for x in re.split(r'[\s]+', value) if x]
+
+        if not len(iocs):
+            raise BadParameter('No IOCs provided')
+
+    return iocs
+
+
+@banshee_cmd(
+    app=app,
+    help_=(
+        'Detailed enrichment for one or more IOCs — one API call per indicator. '
+        'Use `--verbosity` to control how many fields are returned, from basic risk score up to '
+        'full intel including links, analyst notes, etc. '
+        'Use this when you need rich context.'
+    ),
+    epilog=EPILOG_IOC_LOOKUP,
+    rich_help_panel='IOC Enrichment',
+)
+def lookup(
+    entity_type: Annotated[IOCType, Argument(show_default=False, help='Type of IOC')],
+    ioc: list[str] = Argument(  # noqa: B008
+        ... if sys.stdin.isatty() else None,  # noqa: B008
+        show_default=False,
+        help='One or more whitespace separated IOC',
+    ),
+    ai_insights: Annotated[
+        bool,
+        Option(
+            '--ai-insights',
+            '-a',
+            help=(
+                'Enable AI-generated insights from Recorded Future that summarize relevant '
+                'risk rules and key references. Response times may be slightly longer due '
+                'to AI processing.'
+            ),
+        ),
+    ] = False,
+    verbosity: Annotated[
+        int,
+        Option(
+            '--verbosity',
+            '-v',
+            min=1,
+            max=5,
+            help=(
+                'Controls the amount of data returned in the response. '
+                'Higher verbosity levels include additional fields and details '
+                'in the JSON output. Higher verbosity levels may result in slower '
+                'response times due to increased data retrieval. '
+            ),
+        ),
+    ] = 1,
+    pretty: OPT_PRETTY_PRINT = False,
+):
+    if ioc is None:
+        ioc = sys.stdin.read()
+
+    ioc = parse_ioc_input(ioc)
+
+    lookup_ioc(
+        indicators=ioc,
+        entity_type=entity_type,
+        verbose_level=verbosity,
+        pretty=pretty,
+        ai_insights=ai_insights,
+    )
+
+
+@banshee_cmd(
+    app=app,
+    help_=(
+        'Fast bulk enrichment that batches up to 1000 IOCs per API call — '
+        'submit any number of indicators and the command handles the batching automatically. '
+        'Returns a fixed set of fields — risk score and triggered risk rules. '
+        'Use this for high-volume triage. '
+    ),
+    epilog=EPILOG_IOC_BULK_LOOKUP,
+    rich_help_panel='IOC Enrichment',
+)
+def bulk_lookup(
+    entity_type: Annotated[IOCType, Argument(show_default=False, help='Type of IOC')],
+    ioc: list[str] = Argument(  # noqa: B008
+        ... if sys.stdin.isatty() else None,  # noqa: B008
+        show_default=False,
+        help='One or more whitespace separated IOC',
+    ),
+    pretty: OPT_PRETTY_PRINT = False,
+):
+    if ioc is None:
+        ioc = sys.stdin.read()
+
+    ioc = parse_ioc_input(ioc)
+
+    soar_enrich(indicators=ioc, entity_type=entity_type.value, pretty=pretty)
+
+
+def parse_risk_score_input(value: str):
+    if not value:
+        return value
+
+    if not re.match(r'^[\[\(](\d+|),(\d+|)[\]\)]$', value.strip()):
+        raise BadParameter('Invalid risk score format')
+
+    return value.strip()
+
+
+@banshee_cmd(
+    app=app, help_='Search for IOCs', epilog=EPILOG_IOC_SEARCH, rich_help_panel='IOC Search'
+)
+def search(
+    entity_type: Annotated[IOCType, Argument()],
+    limit: Annotated[
+        Optional[int],
+        Option('--limit', '-l', help='Maximum number of IOCs to return', min=1, max=1000),
+    ] = 5,
+    risk_score: Annotated[
+        Optional[str],
+        Option(
+            '--risk-score',
+            '-r',
+            help='Filter by risk score range',
+            callback=parse_risk_score_input,
+            show_default=False,
+        ),
+    ] = None,
+    risk_rule: Annotated[
+        Optional[str], Option('--risk-rule', '-R', help='Filter by risk rule', show_default=False)
+    ] = None,
+    verbosity: Annotated[
+        int,
+        Option(
+            '--verbosity',
+            '-v',
+            min=1,
+            max=5,
+            help=(
+                'Controls the amount of data returned in the response. '
+                'Higher verbosity levels include additional fields and details '
+                'in the JSON output. Higher verbosity levels may result in slower '
+                'response times due to increased data retrieval. '
+            ),
+        ),
+    ] = 1,
+    pretty: OPT_PRETTY_PRINT = False,
+):
+    search_ioc(
+        entity_type=entity_type.value,
+        limit=limit,
+        risk_score=risk_score,
+        risk_rule=risk_rule,
+        verbose_level=verbosity,
+        pretty=pretty,
+    )
+
+
+@banshee_cmd(
+    app=app, help_='Search for IOC Rules', epilog=EPILOG_IOC_RULES, rich_help_panel='IOC Rules'
+)
+def rules(
+    entity_type: Annotated[IOCType, Argument(show_default=False, help='Type of IOC')],
+    freetext: Annotated[
+        str,
+        Option(
+            '-F',
+            '--freetext',
+            show_default=False,
+            help='Free text search to filter rules by name/description',
+        ),
+    ] = None,
+    mitre_code: Annotated[
+        str,
+        Option(
+            '-M',
+            '--mitre-code',
+            show_default=False,
+            help='Filter by MITRE ATT&CK code',
+        ),
+    ] = None,
+    criticality: Annotated[
+        int,
+        Option(
+            '-C',
+            '--criticality',
+            show_default=False,
+            min=0,
+            max=5,
+            help='Filter by criticality. Higher the value, higher the criticality',
+        ),
+    ] = None,
+    pretty: OPT_PRETTY_PRINT = False,
+):
+    search_ioc_rules(
+        entity_type=entity_type.value,
+        freetext=freetext,
+        mitre_code=mitre_code,
+        criticality=criticality,
+        pretty=pretty,
+    )