misp / misp-book

User guide of MISP

description
Introduction to MISP - Open Source Threat Intelligence Sharing Platform

Introduction

User guide for MISP - The Open Source Threat Intelligence Sharing Platform. This user guide is intended for ICT professionals such as security analysts, security incident handlers, or malware reverse engineers who share threat intelligence using MISP or integrate MISP into other security monitoring tools. The user guide includes day-to-day usage of the MISP's graphical user interface along with its automated interfaces (API), in order to integrate MISP within a security environment and operate one or more MISP instances.

Acknowledgement

The MISP user guide is a collaborative effort between all the contributors to MISP including:

• Belgian Ministry of Defence (CERT)
• CIRCL Computer Incident Response Center Luxembourg
• Iklody IT Solutions
• NATO NCIRC
• Cthulhu Solutions
• CERT-EU

and many other contributors especially the ones during the MISP hackathons.

Contributing

We welcome contributions to the MISP book. If you want to contribute, see our contributing guide

Format

MISP book is available in HTML, PDF, ePub and Kindle mobi format.

License

The MISP user guide is dual-licensed under GNU Affero General Public License version 3 and CC-BY-SA 4.0 international.

• Copyright (C) 2012 Christophe Vandeplas
• Copyright (C) 2012 Belgian Defence
• Copyright (C) 2012 NATO / NCIRC
• Copyright (C) 2013-2021 Andras Iklody
• Copyright (C) 2015-2022 Alexandre Dulaunoy
• Copyright (C) 2014-2022 CIRCL - Computer Incident Response Center Luxembourg
• Copyright (C) 2018 Camille Schneider
• Copyright (C) 2018-2022 Steve Clement
• Copyright (C) 2021 Jeroen Pinoy

misp-book's Issues

use-case chapter - how to deal with false-positive

use-case chapter - how to deal with false-positive

new strict JSON schema to add

new strict JSON schema to add https://github.com/MISP/PyMISP/blob/master/pymisp/data/schema.json

Clarification on use of "thumbs-up" and "thumbs-down" sightings buttons

Some of our users have pointed out that the thumbs-up/down interface for sightings may be confusing. They understood that the "thumbs-up" button was to be used to signal any kind of sighting (true or false positive), and then the thumbs-down was to be click additionally in case of false positive.

Even though that was not my understanding, by reading the documentation, together with the icon tooltips, I think the wording may be a bit ambiguous.

I open this issue to get confirmation from the developers/designers that the "canonical use" is:

• Thumbs-up for signalling only a true positive.
• Thumbs-down for signalling a false positive.

If confirmed, I can propose a pull-request to clarify this point in the documentation.

Also, a change in the icon tooltips could be considered to clarify this use. I will do a PR for that in the corresponding repo.

Document enrichment plugin & enrichment module format

Documenting and explaining threat id

As requested in MISP/MISP#729 , we should better document the threat id.

1 = high
2 = medium
3 = low
4 = undefined

The practical examples of the tool-tip could be used to show the potential interpretation of the threat id.

Chapters which needs improvements

Might be incomplete or having outdated screens

• Administration
• Misp Objects
• Quick Start
• General layout
• Managing feeds
• Sightings
• Taxonomies (lists)
• Galaxy (lists)
• Using the system

(Non exaustive list)

Include the default example of lifetime of an event

Include the default example of lifetime of an event (based on the current xmind)

PyMISP documentation in misp-book

PyMISP documentation in misp-book

Usage instructions quite limited

I tried getting the MISP Book running locally but failed to do so only relying on the notes in the USAGE file.
I'm on Ubuntu (15.10 in this case) and finally got it working after doing these steps on a clean installation:

Install node and npm

sudo apt-get install nodejs nodejs-legacy npm 

Install further requirements

sudo apt-get install libcairo2-dev libjpeg-dev
sudo apt-get install calibre  # for generating PDFs

Might save other people a few minutes if you could include these instructions, what do you think?

Documentation about "Hover" and "Expansion"

There is no documentation about "hover" and "expansion" that is supposed to come with the misp-modules.

Distribution model

Following this discussion MISP/MISP#1015 we should update the documentation about the distribution and what is pulled or not following the distribution level.

Add best-practices for tagging (especially when to tag at event or attribute level)

Add best-practices for tagging (especially when to tag at event or attribute level)

Describe setup/requirement recommendations on misp-project

It's a recurring question, the idea isn't to set some hard minimums, but rather to describe usual / recommended requirements and guidance.

Remote Server description

As far as I can see, there is no part that covers how to deal with servers / sharing etc.

Shall I write it?

add visual for explaining the distribution levels including misp-training slides (usage)

add visual for explaining the distribution levels including misp-training slides (usage)

Events, Attributes, Indicators, Observable

Events, Attributes, Indicators, Observable definition and description how this is used in MISP 2.4

Requirements section

We got a lot of questions regarding the MISP hardware requirements. Maybe we should add a specific section about this.

Confusing snippet in Taxonomy section

https://github.com/MISP/misp-book/blame/master/taxonomy/README.md#L86

It's not clear to me what "Her, we classified Tags." is supposed to mean.

Broken images links

There are some broken links for images into the quick start (the last one, "") and in the General Layout (in event actions, "").

Write documentation about the MISP sync protocol

Write a simple documentation about the MISP protocol use for synchronisation along with the distribution of events within the MISP instances. (2.4 protocol)

Document usage of data filtering strategy

Quote from a mail, this but better explained:

"our mantra is, keep your data for correlation and exclude it from the exports. What I'd suggest:

a. Set an automatic tag for your feed (such as "expireMeInAMonth") - these tags will be automatically applied to all events coming from the feed hereafter
b. When exporting data from MISP, for example for your SIEM/NIDS/etc use the following rules:

• 1x full data set, but exclude everything tagged "expireMeInAMonth"
• 1x the data set carrying the "expireMeInAMonth" tag, but with the "last":"30d" parameter set
  c. Feed both data sets to your tools

This will get you all your regular data + the past 30 day's worth of data from the feed."

Use GPG consistently

Okay, this is super-nitpicky... :-)

The book uses "GPG", "Gpg", "GnuPG", and "PGP". Suggest to use only one term to simplify searching...

Document base-URL

Depending on your configuration,you might need to change the base URL in MISP server settings.
This could be documented on the VM part

Lifecycle documentation of event workflow, inter-analyst workflows etc..

During Hackathon & Training days in Luxembourg in March 2018, we discussed with Andras and Alexandre Dulaunoy about having Sequence Diagrams or other visualization to explain how people work and interact with MISP.

A suggestion is to use Web Sequence Diagrams like markup text to graph / svg / png:

Title: Adding new MISP events

Alice (Org A) -> MISP unpublished: Add event

Note: 
**Any edit/modification on exiting event** puts back the Event in _unpublished mode_.

Alice (Org A) -->> Bob (Org A, Publisher): _Out of band Notification (voice, sms, ...): Please verrify and publish my Event_

MISP unpublished -> Bob (Org A, Publisher): Publish

Bob (Org A, Publisher) -> MISP published: Publish

Note: See **[MISP guide](https://github.com/MISP/MISP/)** for more details

Many tools:
Commercial: https://swimlanes.io/#dVBNa4NAEL3vr3hHI0bvOQgWeughTSC9lSLqjjpUd4M72ubfd42Shn7Asiwz72vfC0tHO2Ras2lg6AP7p9MRNJERp1TWcUUIDkODbINtumxHcx7Ljl1L+kpd4Eo9W/FaKgwzcwFplqS3mmuuCmFr4A99ssxGV0IY4jyKQ1lU75CW8DhPwQb5nQO8BuXxryzbNMWDLddBhONKGDY75IdRYGuvbDR8qu8MwWS9SgTXuwhxHHvwsaPCESYaBq4vmCmrOfrLkilX6ufH5zL+s1/fSv0NuPV41+KNsnR4IkIYvl5Rzcia3oJW5Ox2SdKwtGMZV7ZP5vVybXyXtR18VwNBkxTcOfUF

or Free: https://bramp.github.io/js-sequence-diagrams/

OSINT feed creation and usage to add (based on Koen blog post)

OSINT feed creation and usage to add (based on Koen blog post)

https://www.vanimpe.eu/2016/03/23/using-open-source-intelligence-osint-with-misp/

Document import/export plugin & import/export modules format

example - convention with example organisations

example - convention with example organisations

Document ZeroMQ plugin

Error 500 after fresh Centos7 Install

I followed the install guide according, and when I start the process everything appears to start but I am not able to access http://misp/user/login url. I am getting an error 500.
sudo su -s /bin/bash apache -c 'scl enable rh-php56 /var/www/MISP/app/Console/worker/start.sh'
[sudo] password for sjohn345:
Stopping workers
Stopping 12950 ... Done
Stopping the Scheduler Worker ... Done
Stopping 12968 ... Done
Stopping 12986 ... Done
Stopping 13004 ... Done

Creating workers
Starting worker ... Done

Creating workers
Starting worker ... Done

Creating workers
Starting worker ... Done

Creating workers
Starting worker ... Done

Creating the scheduler workers
Starting scheduler worker ... Done
! more misp.local_error.log
[Wed Jul 05 21:28:56.478562 2017] [:error] [pid 11684] [client ::1:51188] PHP Fatal error: Can't use function return value in write context in /var/www/MISP/app/Controller/UsersController.php on line 97
[Wed Jul 05 21:28:56.479803 2017] [:error] [pid 11684] [client ::1:51188] PHP Fatal error: Can't use function return value in write context in /var/www/MISP/app/Controller/AppController.php on line 305
[Wed Jul 05 21:29:02.058256 2017] [:error] [pid 2369] [client ::1:51190] PHP Fatal error: Can't use function return value in write context in /var/www/MISP/app/Controller/AppController.php on line 305

Misp-book: general-layout =>drop-down menus explanations

I up to date misp-book/general-layout/

In the menu bar "layout Filter", it seems to be a new tab "Warning List", who is not documented. What is it and for what can I use that? (Yeah, I know that it will shows a list of warnings, but I don't know why it is usefull).

Using MISP with other Threat sharing solutions

Is MISP compatible with other Threat sharing solutions such as CIFS?

Sharing groups explanation and usage to add

Sharing groups explanation and usage to add

Feed section needs to be updated following the new separation in MISP (caching/import)

Feed section needs to be updated following the new separation (caching versus import)

Visualise data-flow of data within MISP (from whitelist to warning lists)

MISP/MISP#2734

Document export plugin & export modules format

Pymisp issue

Good morning ,

I have an issue with Pymisp.

When I try to change/add/delete the tag of any event via web, the event
goes to unpublished status. But,changing/adding/removing the tag via API
(pymisp) does not change the publishing status of that event.

Is that an error?
What would be the method to make these massive label changes through
Pymisp and change the publication status of each event?

Thank you very much in advance.

I look forward to hearing from you.

Greetings.

Feed field explanations are missing

Explain fields such as delta merge

Back-up of MISP to be documented

Back-up of MISP to be documented

Broken anchor (interface from scheduled task)

Broken anchor (interface from scheduled task)

via @adulau

Defanging and un-defanging rules in MISP

We should document all the rules in MISP to un-defang URLs and other artifacts.

MISP provisioning descriptions

1. Create a use-case based description of how to deploy MISP in the sense of requirements, topologies, etc
2. Write a tool that calculates optimal provisioning based on desired data/community sizes.

How to contribute to MISP development - new chapter

Some topics to add

• Addition of new attributes not currently supported in MISP (like MISP/MISP#800)
• Proposing tools using PyMISP
• Updating documentation

RESTful API - Specify dates

I am using the api endpoint:

https://<server-name>/events/

and trying to get all the events. The issue I'm having is that this endpoint returns too many events at once. Is there a way to specify start / end in the RESTful api? I saw you could with the /events/xml/download endpoint, but I just want to get the json response rather than a file.

I've tried:

https://<server-name>/events?from=2016-01-01
https://<server-name>/events/null/null/null/2016-01-01

Publish event to ZMQ does not include Objects information

Dears,

Since MISP 2.4.80, we have the possibility to define objects. If you download a sample, the object is automatically created with subsequent attributes (filename, md5, sha1, sha256 and filesize).
However, it seems that this information is not included when publishing the event to ZMQ.

Am I missing something or is it not supported? I am running 2.4.80 on Ubuntu.

Thanks a lot in advance for your help!

BR's
Irving

New API call to get the JSON with all attributes and categories

https://misppriv.circl.lu/attributes/describeTypes.json

to add in the doc

A note about the PHP session and the recommended Redis session

A note about the PHP session and the recommended Redis session and the config
aspect too:

https://www.digitalocean.com/community/tutorials/how-to-set-up-a-redis-server-as-a-session-handler-for-php-on-ubuntu-14-04

Describe role of each worker

Describe role of each worker and their respective interdependencies.

Mentioning double-click to edit an event

Mentioning double-click to edit an event

License of MISP-Book

Hi

Since misp-book has been exported from main MISP archive, license of miss-book should be GNU Affero GPL v3.
However, since it is a documentation, and I would believe that it is in the interest of the MISP project for such documentation to be licensed under a more "academic" framework, I would suggest the following:

a - IF you can get the formal agreement of all authors (i.e., contributors to the documentation and - if applicable and required, so check with contributors - their employers), relicense the content under a simpler Creative common CC-BY 4.0 license (which in version 4 is compatible with the GNU Affero GPL v3 License). Other option is dual license of documentation (again, if agreement is granted by all contributors or reap. right holders), CC BY 4.0 AND Affero GNU GPL v3.
Attribution-only licenses will allow third parties to use the content of documentation as they please (as long as authors are acknowledged), which shouldn't be an issue since this is a supportive content to the benefit of MISP.
b - IF NOT, license for documentation is solely GNU Affero GPL v3.

Matthieu

Rework API Documentation

This is to document the open points in the API documentation:

• Describe Error Codes

• make CURL examples for every Endpoint

• document searchtimestamp (see #32)

• POST /events more fields explanation

• remove API keys from sample data