diff --git a/REQUIREMENTS b/REQUIREMENTS index e749db9..73b002a 100644 --- a/REQUIREMENTS +++ b/REQUIREMENTS @@ -95,6 +95,7 @@ sparqlwrapper==1.8.5 stix2-patterns==1.3.0 tabulate==0.8.7 tornado==6.0.4 +trustar==0.3.28 url-normalize==1.4.1 urlarchiver==0.2 urllib3==1.25.8 diff --git a/doc/README.md b/doc/README.md index 15721f1..e173ad4 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1184,6 +1184,35 @@ Module to get information from ThreatMiner. ----- +#### [trustar_enrich](https://github.com/MISP/misp-modules/tree/master/misp_modules/modules/expansion/trustar_enrich.py) + + + +Module to get enrich indicators with TruSTAR. +- **features**: +>This module enriches MISP attributes with scoring and metadata from TruSTAR. +> +>The TruSTAR indicator summary is appended to the attributes along with links to any associated reports. +- **input**: +>Any of the following MISP attributes: +>- btc +>- domain +>- email-src +>- filename +>- hostname +>- ip-src +>- ip-dst +>- md5 +>- sha1 +>- sha256 +>- url +- **output**: +>MISP attributes enriched with indicator summary data from the TruSTAR API. Data includes a severity level score and additional source and scoring info. +- **references**: +>https://docs.trustar.co/api/v13/indicators/get_indicator_summaries.html + +----- + #### [urlhaus](https://github.com/MISP/misp-modules/tree/master/misp_modules/modules/expansion/urlhaus.py) diff --git a/doc/expansion/trustar_enrich.json b/doc/expansion/trustar_enrich.json new file mode 100644 index 0000000..294419d --- /dev/null +++ b/doc/expansion/trustar_enrich.json @@ -0,0 +1,8 @@ +{ + "description": "Module to get enrich indicators with TruSTAR.", + "logo": "logos/trustar.png", + "input": "Any of the following MISP attributes:\n- btc\n- domain\n- email-src\n- filename\n- hostname\n- ip-src\n- ip-dst\n- md5\n- sha1\n- sha256\n- url", + "output": "MISP attributes enriched with indicator summary data from the TruSTAR API. Data includes a severity level score and additional source and scoring info.", + "references": ["https://docs.trustar.co/api/v13/indicators/get_indicator_summaries.html"], + "features": "This module enriches MISP attributes with scoring and metadata from TruSTAR.\n\nThe TruSTAR indicator summary is appended to the attributes along with links to any associated reports." +} diff --git a/doc/logos/trustar.png b/doc/logos/trustar.png new file mode 100644 index 0000000..d4ac521 Binary files /dev/null and b/doc/logos/trustar.png differ diff --git a/misp_modules/modules/expansion/__init__.py b/misp_modules/modules/expansion/__init__.py index 3f3dfca..dbd3473 100644 --- a/misp_modules/modules/expansion/__init__.py +++ b/misp_modules/modules/expansion/__init__.py @@ -1,6 +1,7 @@ from . import _vmray # noqa import os import sys + sys.path.append('{}/lib'.format('/'.join((os.path.realpath(__file__)).split('/')[:-3]))) __all__ = ['cuckoo_submit', 'vmray_submit', 'bgpranking', 'circl_passivedns', 'circl_passivessl', @@ -16,4 +17,5 @@ __all__ = ['cuckoo_submit', 'vmray_submit', 'bgpranking', 'circl_passivedns', 'c 'ods_enrich', 'odt_enrich', 'joesandbox_submit', 'joesandbox_query', 'urlhaus', 'virustotal_public', 'apiosintds', 'urlscan', 'securitytrails', 'apivoid', 'assemblyline_submit', 'assemblyline_query', 'ransomcoindb', 'malwarebazaar', - 'lastline_query', 'lastline_submit', 'sophoslabs_intelix', 'cytomic_orion', 'censys_enrich'] + 'lastline_query', 'lastline_submit', 'sophoslabs_intelix', 'cytomic_orion', 'censys_enrich', + 'trustar_enrich'] diff --git a/misp_modules/modules/expansion/trustar_enrich.py b/misp_modules/modules/expansion/trustar_enrich.py new file mode 100644 index 0000000..efe7c53 --- /dev/null +++ b/misp_modules/modules/expansion/trustar_enrich.py @@ -0,0 +1,133 @@ +import json +import pymisp +from pymisp import MISPAttribute, MISPEvent, MISPObject +from trustar import TruStar + +misperrors = {'error': "Error"} +mispattributes = { + 'input': ["btc", "domain", "email-src", "filename", "hostname", "ip-src", "ip-dst", "malware-type", "md5", "sha1", + "sha256", "url"], 'format': 'misp_standard'} + +moduleinfo = {'version': "0.1", 'author': "Jesse Hedden", + 'description': "Enrich data with TruSTAR", + 'module-type': ["hover", "expansion"]} + +moduleconfig = ["user_api_key", "user_api_secret", "enclave_ids"] + +MAX_PAGE_SIZE = 100 # Max allowable page size returned from /1.3/indicators/summaries endpoint + + +class TruSTARParser: + ENTITY_TYPE_MAPPINGS = { + 'BITCOIN_ADDRESS': "btc", + 'CIDR_BLOCK': "ip-src", + 'CVE': "vulnerability", + 'URL': "url", + 'EMAIL_ADDRESS': "email-src", + 'SOFTWARE': "filename", + 'IP': "ip-src", + 'MALWARE': "malware-type", + 'MD5': "md5", + 'REGISTRY_KEY': "regkey", + 'SHA1': "sha1", + 'SHA256': "sha256" + } + + REPORT_BASE_URL = "https://station.trustar.co/constellation/reports/{}" + + CLIENT_METATAG = "MISP-{}".format(pymisp.__version__) + + def __init__(self, attribute, config): + config['enclave_ids'] = config.get('enclave_ids', "").strip().split(',') + config['client_metatag'] = self.CLIENT_METATAG + self.ts_client = TruStar(config=config) + + self.misp_event = MISPEvent() + self.misp_attribute = MISPAttribute() + self.misp_attribute.from_dict(**attribute) + self.misp_event.add_attribute(**self.misp_attribute) + + def get_results(self): + """ + Returns the MISP Event enriched with TruSTAR indicator summary data. + """ + event = json.loads(self.misp_event.to_json()) + results = {key: event[key] for key in ('Attribute', 'Object') if (key in event and event[key])} + return {'results': results} + + def generate_trustar_links(self, entity_value): + """ + Generates links to TruSTAR reports if they exist. + + :param entity_value: Value of entity. + """ + report_links = list() + trustar_reports = self.ts_client.search_reports(entity_value) + for report in trustar_reports: + report_links.append(self.REPORT_BASE_URL.format(report.id)) + + return report_links + + def parse_indicator_summary(self, summaries): + """ + Converts a response from the TruSTAR /1.3/indicators/summaries endpoint + a MISP trustar_report object and adds the summary data and links as attributes. + + :param summaries: A TruSTAR Python SDK Page.generator object for generating + indicator summaries pages. + """ + + for summary in summaries: + trustar_obj = MISPObject('trustar_report') + indicator_type = summary.indicator_type + indicator_value = summary.value + if indicator_type in self.ENTITY_TYPE_MAPPINGS: + trustar_obj.add_attribute(indicator_type, attribute_type=self.ENTITY_TYPE_MAPPINGS[indicator_type], + value=indicator_value) + trustar_obj.add_attribute("INDICATOR_SUMMARY", attribute_type="text", + value=json.dumps(summary.to_dict(), sort_keys=True, indent=4)) + report_links = self.generate_trustar_links(indicator_value) + for link in report_links: + trustar_obj.add_attribute("REPORT_LINK", attribute_type="link", value=link) + self.misp_event.add_object(**trustar_obj) + + +def handler(q=False): + """ + MISP handler function. A user's API key and secret will be retrieved from the MISP + request and used to create a TruSTAR API client. If enclave IDs are provided, only + those enclaves will be queried for data. Otherwise, all of the enclaves a user has + access to will be queried. + """ + + if q is False: + return False + + request = json.loads(q) + + config = request.get('config', {}) + if not config.get('user_api_key') or not config.get('user_api_secret'): + misperrors['error'] = "Your TruSTAR API key and secret are required for indicator enrichment." + return misperrors + + attribute = request['attribute'] + trustar_parser = TruSTARParser(attribute, config) + + try: + summaries = list( + trustar_parser.ts_client.get_indicator_summaries([attribute['value']], page_size=MAX_PAGE_SIZE)) + except Exception as e: + misperrors['error'] = "Unable to retrieve TruSTAR summary data: {}".format(e) + return misperrors + + trustar_parser.parse_indicator_summary(summaries) + return trustar_parser.get_results() + + +def introspection(): + return mispattributes + + +def version(): + moduleinfo['config'] = moduleconfig + return moduleinfo diff --git a/misp_modules/modules/import_mod/__init__.py b/misp_modules/modules/import_mod/__init__.py index fbad911..45e3359 100644 --- a/misp_modules/modules/import_mod/__init__.py +++ b/misp_modules/modules/import_mod/__init__.py @@ -15,4 +15,5 @@ __all__ = [ 'threatanalyzer_import', 'csvimport', 'joe_import', + 'trustar_import', ]