diff --git a/galaxy/README.md b/galaxy/README.md index 6133caa..41a9ac6 100644 --- a/galaxy/README.md +++ b/galaxy/README.md @@ -55,6 +55,144 @@ Once this is done double check if you can still see the Galaxies in the Web UI. ### Adding a new Galaxy (WiP - notFuctional) +#### Context + +A galaxy is designed to provide more info than a tag. It comes in two formats: regular or matrix-shape. In a tag, you can only display one label and one color. In a galaxy, you can display: +- name +- synonymous +- description +- categories (for matrix-galaxies) + +#### Directory structure + +Galaxies are represented by two json files stored in: +```bash +/var/www/MISP/app/files/misp-galaxy/galaxies/mygalaxy.json +/var/www/MISP/app/files/misp-galaxy/clusters/mygalaxy.json +``` +The __/galaxies__ file contains metatdatas and galaxy structure. +The __/clusters__ file contains actual data. + +__WARNING__: files names are very important: they will be used to chain the files together. +The cluster file is linked to the galaxy file through a json property (__type__) which MUST equal the cluster file name (more later). + +#### The galaxy file +The galaxy file provides the framework for the data stored in the cluster file. +For example: +```bash +{ + "description": "attck4fraud - Principles of MITRE ATT&CK in the fraud domain", + "icon": "map", + "kill_chain_order": { + "fraud-tactics": [ + "Initiation", + "Target Compromise", + "Perform Fraud", + "Obtain Fraudulent Assets", + "Assets Transfer", + "Monetisation" + ] + }, + "name": "attck4fraud", + "namespace": "misp", + "type": "financial-fraud", + "uuid": "cc0c8ae9-aec2-42c6-9939-f4f82b051836", + "version": 1 +} +``` +* __description__: generalities about the galaxy (1) +* __icon__: the icon used in the MISP interface (2) +* __name__: the name of the galaxy (3) +* __namespace__: the namespace where is stored the galaxy. Namespace are used to regroup similar galaxies (4) +* __type__: __IMPORTANT field__, it MUST match the cluster file name to actually chain both files together (5) +* __uuid__: as any MISP object, it has a uuid. __IMPORTANT__, it MUST be repeated in the uuid property of the cluster file (6) +* __version__: as usual in MISP, versioning, especially to force update (7) +* __kill_chain_order__: a special and optionnal field: it will be used if you want to create a matrix-galaxy. In this field, you insert a named table (_fraud-tactics_ in the example above) containing the categories labels of you data. They will be used then in the cluster file (8) + +More detail on galaxy fields here: https://tools.ietf.org/html/draft-dulaunoy-misp-galaxy-format-06#page-9 + +#### The cluster file + +The cluster file provides the actual data of the galaxy. +For example (Attck4fraud): +```bash +{ + "authors": [ + "Francesco Bigarella" + ], + "category": "guidelines", + "description": "attck4fraud - Principles of MITRE ATT&CK in the fraud domain", + "name": "attck4fraud", + "source": "Open Sources", + __"type": "financial-fraud",__ + __"uuid": "cc0c8ae9-aec2-42c6-9939-f4f82b051836"__, + "values": [ + { + "description": "In the context of ATT&CK for Fraud, phishing is described as the sending of fraudulent emails to a large audience in order to obtain sensitive information (PII, credentials, payment information). Phishing is never targeted to a specific individual or organisation. Phishing tries to create a sense of urgency or curiosity in order to capture the victim.", + "meta": { + "detection": "Email sender is spoofed; Email sender belongs to a domain recently created; Presence of typos or poor grammar in the email text; The request in the mail is unsolicited and creates urgency; No recollection of the subject or the sender of the phishing email; Request for credentials; Presence of a suspicious URL or attachment.", + "examples": [ + "Phishing messages were sent to Amazon users posing as the Amazon customer support", + "Fake Apple invoices were sent to Apple App Store customers in order to obtain their Apple ID credentials" + ], + "external_id": "FT1001", + "kill_chain": [ + "fraud-tactics:Initiation" + ], + "mitigation": "Implementation of DKIM and SPF authentication to detected spoofed email senders; anti-phishing solutions.", + "refs": [ + "https://blog.malwarebytes.com/cybercrime/2015/02/amazon-notice-ticket-number-phish-seeks-card-details/", + "https://www.bleepingcomputer.com/news/security/widespread-apple-id-phishing-attack-pretends-to-be-app-store-receipts/" + ], + ... + ], + "version": 3 +} +``` +* __authors__: descriptive field +* __category__: descriptive field +* __description__: descriptive field +* __name__: same as in /galaxy file, used in the Matrix display +* __source__: descriptive field +* __type__: IMPORTANT, this field MUST match the /galaxy and /cluster files names AND the type field in the /galaxy file name -5 in above paragraph- +* __uuid__: IMPORTANT, this field MUST match the /galaxy uuid field -6 in above paragraph- +* __values__: a table containing the actual values +* __data fileds__: fields used to describe single data are detailed here: https://tools.ietf.org/html/draft-dulaunoy-misp-galaxy-format-06#page-9 +* __kill_chain__: IMPORTANT, provide the column of the Matrix where the data will be displayed: + __arg1__: MUST match /galaxy file's kill_chain arg (_fraud-tactics_ in the example) + __arg2__: name of the column of the data (_Initiation_ in the example) + +More details on /cluster fields can be found here: https://tools.ietf.org/html/draft-dulaunoy-misp-galaxy-format-06#page-9 + +#### Implementation +* Once your files are ready, ALWAYS submit them in a json validator such as: +https://jsonformatter.curiousconcept.com/ + +Do it before putting them into your instance, it will save your sanity. + +* Copy/paste your files in both folders (/galaxies and /clusters) + +* Go to Galaxies/List galaxies and clic on Update galaxies + +* Your new galaxy should be displayed on the screen with the others + +* Your galaxy is available in the events for selecting in the right namespace + +#### Troubleshooting + +* __The galaxy does not udpate, galaxy is empty__ + * Check json validation + * Update version of files + * Check files names + +* __Matrix is not displayed__ + * Check the kill_chain_order array in the /galaxies json + * Check the chaining + + + + + #### Dependencies To create your own Galaxies the following tools are needed to run the validation scripts. diff --git a/galaxy/figures/ClusterJson.png b/galaxy/figures/ClusterJson.png new file mode 100644 index 0000000..804173d Binary files /dev/null and b/galaxy/figures/ClusterJson.png differ diff --git a/galaxy/figures/GalaxyJson.png b/galaxy/figures/GalaxyJson.png new file mode 100644 index 0000000..966fc45 Binary files /dev/null and b/galaxy/figures/GalaxyJson.png differ diff --git a/galaxy/figures/GalaxyManagmentGui.png b/galaxy/figures/GalaxyManagmentGui.png new file mode 100644 index 0000000..381ca27 Binary files /dev/null and b/galaxy/figures/GalaxyManagmentGui.png differ diff --git a/galaxy/figures/JsonChaining.png b/galaxy/figures/JsonChaining.png new file mode 100644 index 0000000..5137a26 Binary files /dev/null and b/galaxy/figures/JsonChaining.png differ diff --git a/galaxy/figures/Matrix.png b/galaxy/figures/Matrix.png new file mode 100644 index 0000000..58d3f3f Binary files /dev/null and b/galaxy/figures/Matrix.png differ