new: [galaxies] create galaxy with search

doc/README.md

@@ -41,7 +41,7 @@ Example:
 
 ## Transform from MISP Event ID
 While MISP already has a graphing capability we would like to use the power of Maltego to look at the data and expand the work.
-* create a *MISP Event* and give it an `event id`, or `UUID`
+* Create a *MISP Event* and give it an `event id`, or `UUID`
 * One **manual** way is to right click and choose *Local Transforms* > *MISP_maltego* > *Event To Attributes* 
   * Notice the event is transformed to *Attributes*, *Objects*, *Tags*, *Galaxies* and related *MISP Events*
   * You can now further transform on an *Object* > *Object To Attributes* and see the content of the object
@@ -60,6 +60,18 @@ To permit this MISP-Maltego will always add a green bookmark to all the data tha
 
 
 ## Transform from Galaxy
-TODO
+Galaxies are actually tags with much more contextual data. Examples are threat actors, malware families, but also the whole MITRE ATT&CK data is available as Galaxy. All this data comes from the [MISP Galaxy](https://github.com/MISP/misp-galaxy) repository. Today the integration is not done using a MISP server because of limitations in MISP.
+You might encounter Galaxies when transforming from MISP Events or Attributes. An alternative use-case is by starting immediately from a Galaxy.
+There are 3 ways to manually create a good Galaxy Entity.
+1. Using a find capability (see below)
+2. Create the Galaxy and set the UUID. You can find the UUIDs in the [MISP Galaxy](https://github.com/MISP/misp-galaxy) repository.
+3. Create the Galaxy with the right tag name; for example: `misp-galaxy:`
+
+To use the magical search feature:
+* Create a *MISP Galaxy* and type the keyword as value.
+* Run the *Galaxy To Relation* transform, notice the search results will appear as connected entities
+* Remove the non-relevant entities, including the your search-keyword
+![animated galaxy search](https://raw.githubusercontent.com/MISP/MISP-maltego/master/doc/img/usecase4-galaxy-search.gif)
+
 ## Visualise MITRE ATT&CK
-TODO
+TODO

src/MISP_maltego/transforms/common/util.py

@@ -1,6 +1,6 @@
-from canari.maltego.entities import Hash, Domain, IPv4Address, URL, DNSName, AS, Website, NSRecord, PhoneNumber, EmailAddress, File, Person, Hashtag, Location, Company, Alias, Port, Twitter, Unknown
+from canari.maltego.entities import Hash, Domain, IPv4Address, URL, DNSName, AS, Website, NSRecord, PhoneNumber, EmailAddress, File, Person, Hashtag, Location, Company, Alias, Port, Twitter
 from MISP_maltego.transforms.common.entities import MISPEvent, MISPObject, MISPGalaxy
-from canari.maltego.message import UIMessageType, UIMessage, Label, LinkStyle, MaltegoException, Bookmark
+from canari.maltego.message import Label, LinkStyle, MaltegoException, Bookmark
 from pymisp import PyMISP
 import json
 import os
@@ -8,6 +8,7 @@ import os.path
 import tempfile
 import time
 
+# FIXME from galaxy to MISP Event is confusing
 
 # mapping_maltego_to_misp = {
 #     'maltego.Hash': ['md5', 'sha1', 'sha256', 'sha224', 'sha384', 'sha512', 'sha512/224', 'sha512/256'],
@@ -499,6 +500,21 @@ def get_galaxy_cluster(uuid=None, tag=None):
                 return item
 
 
+def search_galaxy_cluster(keyword):
+    keyword = keyword.lower()
+    global galaxy_cluster_uuids
+    if not galaxy_cluster_uuids:
+        galaxy_cluster_uuids = galaxy_load_cluster_mapping()
+    for item in galaxy_cluster_uuids.values():
+        if keyword in item['tag_name'].lower():
+            yield item
+        else:
+            if 'meta' in item and 'synonyms' in item['meta']:
+                for synonym in item['meta']['synonyms']:
+                    if keyword in synonym.lower():
+                        yield item
+
+
 def get_galaxies_relating(uuid):
     global galaxy_cluster_uuids
     if not galaxy_cluster_uuids:

src/MISP_maltego/transforms/galaxytoevent.py

@@ -1,7 +1,7 @@
 from canari.maltego.transform import Transform
 # from canari.framework import EnableDebugWindow
 from MISP_maltego.transforms.common.entities import MISPEvent, MISPGalaxy
-from MISP_maltego.transforms.common.util import get_misp_connection, galaxycluster_to_entity, get_galaxy_cluster, get_galaxies_relating, mapping_galaxy_icon
+from MISP_maltego.transforms.common.util import get_misp_connection, galaxycluster_to_entity, get_galaxy_cluster, get_galaxies_relating, search_galaxy_cluster, mapping_galaxy_icon
 from canari.maltego.message import UIMessageType, UIMessage
 
 
@@ -56,6 +56,18 @@ class GalaxyToRelations(Transform):
         elif maltego_misp_galaxy.name:
             current_cluster = get_galaxy_cluster(tag=maltego_misp_galaxy.name)
 
+        if not current_cluster:
+            # maybe the user is searching for a cluster based on a substring.
+            # Search in the list for those that match and return galaxy entities
+            potential_clusters = search_galaxy_cluster(maltego_misp_galaxy.name)
+            # TODO check if duplicates are possible
+            if potential_clusters:
+                for potential_cluster in potential_clusters:
+                    response += galaxycluster_to_entity(potential_cluster, link_label='Search result')
+                return response
+
+        # import json
+        # print(json.dumps(current_cluster))
         if not current_cluster:
             response += UIMessage("Galaxy Cluster UUID not in local mapping. Please update local cache; non-public UUID are not supported yet.", type=UIMessageType.Inform)
             return response