Merge pull request #274 from 9b/master

Backscatter.io expansion module

README.md

@@ -17,6 +17,7 @@ For more information: [Extending MISP with Python modules](https://www.circl.lu/
 
 ### Expansion modules
 
+* [Backscatter.io](misp_modules/modules/expansion/backscatter_io) - a hover and expansion module to expand an IP address with mass-scanning observations.
 * [BGP Ranking](misp_modules/modules/expansion/bgpranking.py) - a hover and expansion module to expand an AS number with the ASN description, its history, and position in BGP Ranking.
 * [BTC transactions](misp_modules/modules/expansion/btc_steroids.py) - An expansion hover module to get a blockchain balance and the transactions from a BTC address in MISP.
 * [CIRCL Passive DNS](misp_modules/modules/expansion/circl_passivedns.py) - a hover and expansion module to expand hostname and IP addresses with passive DNS information.

REQUIREMENTS

@@ -11,6 +11,7 @@ aiohttp==3.4.4
 antlr4-python3-runtime==4.7.2 ; python_version >= '3'
 async-timeout==3.0.1
 attrs==18.2.0
+backscatter==0.2.3
 beautifulsoup4==4.7.1
 blockchain==1.4.4
 certifi==2018.11.29

misp_modules/modules/expansion/__init__.py

@@ -8,4 +8,4 @@ __all__ = ['vmray_submit', 'bgpranking', 'circl_passivedns', 'circl_passivessl',
            'yara_syntax_validator', 'hashdd', 'onyphe', 'onyphe_full', 'rbl',
            'xforceexchange', 'sigma_syntax_validator', 'stix2_pattern_syntax_validator',
            'sigma_queries', 'dbl_spamhaus', 'vulners', 'yara_query', 'macaddress_io',
-           'intel471']
+           'intel471', 'backscatter_io']

misp_modules/modules/expansion/backscatter_io.py

@@ -0,0 +1,75 @@
+# -*- coding: utf-8 -*-
+"""Backscatter.io Module."""
+import json
+try:
+    from backscatter import Backscatter
+except ImportError:
+    print("Backscatter.io library not installed.")
+
+misperrors = {'error': 'Error'}
+mispattributes = {'input': ['ip-src', 'ip-dst'], 'output': ['freetext']}
+moduleinfo = {'version': '1', 'author': 'brandon@backscatter.io',
+              'description': 'Backscatter.io module to bring mass-scanning observations into MISP.',
+              'module-type': ['expansion', 'hover']}
+moduleconfig = ['api_key']
+query_playbook = [
+    {'inputs': ['ip-src', 'ip-dst'],
+     'services': ['observations', 'enrichment'],
+     'name': 'generic'}
+]
+
+
+def check_query(request):
+    """Check the incoming request for a valid configuration."""
+    output = {'success': False}
+    config = request.get('config', None)
+    if not config:
+        misperrors['error'] = "Configuration is missing from the request."
+        return output
+    for item in moduleconfig:
+        if config.get(item, None):
+            continue
+        misperrors['error'] = "Backscatter.io authentication is missing."
+        return output
+    if not request.get('ip-src') and request.get('ip-dst'):
+        misperrors['error'] = "Unsupported attributes type."
+        return output
+    profile = {'success': True, 'config': config, 'playbook': 'generic'}
+    if 'ip-src' in request:
+        profile.update({'value': request.get('ip-src')})
+    else:
+        profile.update({'value': request.get('ip-dst')})
+    return profile
+
+
+def handler(q=False):
+    """Handle gathering data."""
+    if not q:
+        return q
+    request = json.loads(q)
+    checks = check_query(request)
+    if not checks['success']:
+        return misperrors
+
+    try:
+        bs = Backscatter(checks['config']['api_key'])
+        response = bs.get_observations(query=output['value'], query_type='ip')
+        if not response['success']:
+            misperrors['error'] = '%s: %s' % (response['error'], response['message'])
+            return misperrors
+        output = {'results': [{'types': mispattributes['output'], 'values': [str(response)]}]}
+    except Exception, e:
+        misperrors['error'] = str(e)
+        return misperrors
+
+    return output
+
+
+def introspection():
+    return mispattributes
+
+
+def version():
+    moduleinfo['config'] = moduleconfig
+    return moduleinfo
+