diff --git a/.gitignore b/.gitignore index 7395121..ff786c9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,13 @@ +# Temp md files *.md~ + +# Compiled assets book.pdf +book.epub +book.mobi + +# Compiled book +_book + +# node foo +node_modules diff --git a/README.md b/README.md index 0ef3836..9f45916 100644 --- a/README.md +++ b/README.md @@ -40,11 +40,9 @@ The MISP user guide is dual-licensed under [GNU Affero General Public License ve * Copyright \(C\) 2012 Christophe Vandeplas * Copyright \(C\) 2012 Belgian Defence * Copyright \(C\) 2012 NATO / NCIRC -* Copyright \(C\) 2013-2018 Andras Iklody -* Copyright \(C\) 2015-2018 Alexandre Dulaunoy -* Copyright \(C\) 2014-2018 CIRCL - Computer Incident Response Center Luxembourg +* Copyright \(C\) 2013-2020 Andras Iklody +* Copyright \(C\) 2015-2020 Alexandre Dulaunoy +* Copyright \(C\) 2014-2020 CIRCL - Computer Incident Response Center Luxembourg * Copyright \(C\) 2018 Camille Schneider -* Copyright \(C\) 2018 Steve Clement - - +* Copyright \(C\) 2018-2020 Steve Clement diff --git a/SUMMARY.md b/SUMMARY.md index a8dd090..910de76 100755 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -12,6 +12,7 @@ * [Extending Events](extended-events/README.md) - in progress * [Administration](administration/README.md) * [Managing Feeds](managing-feeds/README.md) +* [Updating Python dependencies](updating-python/README.md) * [Automation and MISP API](automation/README.md) * [PyMISP - Python Library to Access MISP](pymisp/README.md) * [Create an Event Based on a Report](create-event-report/README.md) diff --git a/administration/README.md b/administration/README.md index 9a2f5e9..b15dd1e 100644 --- a/administration/README.md +++ b/administration/README.md @@ -86,9 +86,9 @@ Site admins can use the "Contact users" feature to send all or individual user a * **Action:** This defines the e-mail type, which can be a custom message or a password reset. Password resets automatically include a new temporary password at the bottom of the message and will automatically change the user's password accordingly. * **Subject:** In the case of a custom e-mail, you can enter a subject line here. * **Recipient:** The recipient toggle lets you contact all your users, a single user (which creates a second drop-down list with all the e-mail addresses of the users) and potential future users (which opens up a text field for the e-mail address and a text area field for a GnuPG public key). -* **Custom message checkbox:** This is available for password resets or for welcome message, you can either write your own message (which will be appended with a temporary key and the signature), or let the system generate one automatically. +* **Custom message checkbox:** This is available for password resets and for welcome messages. You can either write your own message (which will be appended with a temporary key and the signature), or let the system generate one automatically. -Keep in mind that all e-mails sent through this system, in addition to your own message, will be signed in the name of the instance's host organisation's support team, the e-ail will also include the e-mail address of the instance's support (if the contact field is set in the bootstrap file), and will include the instance's GnuPG signature for users that have a GnuPG key set (and thus are eligible for an encrypted e-mail). +Keep in mind that all e-mails sent through this system, in addition to your own message, will be signed in the name of the instance's host organisation's support team, the e-mail will also include the e-mail address of the instance's support (if the contact field is set in the bootstrap file), and will include the instance's GnuPG signature for users that have a GnuPG key set (and thus are eligible for an encrypted e-mail). :warning: GnuPG instance key is the GnuPG key used by the MISP instance and which is only used to sign notification. The GnuPG key used in the MISP instance must not be used anywhere else and should not be valuable. @@ -113,9 +113,9 @@ To add a new organisation, click on the "Add Organisation" button in the adminis * **Type of organisation:** Define the type of the organisation. * **Contacts:** You can add some contact details for the organisation. -#### Listing all organisation +#### Listing all organisations -To list all current organisation of the system, just click on List Organisations under the administration menu to the left. There are 3 tabs in this view to filter local organisations, remote organisations or both. The default view displays local organisations. For all views the following columns of information are available: +To list all current organisations of the system, just click on List Organisations under the administration menu to the left. There are 3 tabs in this view to filter local organisations, remote organisations or both. The default view displays local organisations. For all views the following columns of information are available: ![List of organisations.](figures/list_org.png) @@ -130,6 +130,7 @@ To list all current organisation of the system, just click on List Organisations * **Contacts:** Contacts of organisation. * **Added by:** Login of the user who added the organisation * **Local:** Flag defined if the organisation is local or remote. +* **Users:** The amount of users on this instance belonging to the organisation. * **Actions:** There are 3 options available: edit, delete or display an organisation's information. These options are also available on the left menu when you are on the display view. * **Edit Organisation:** Same options of create organisation's view. ![Edit organisation.](figures/edit_org.png) @@ -139,7 +140,7 @@ To list all current organisation of the system, just click on List Organisations ![View organisation.](figures/view_org.png) #### Merge organisations -Merge Organisation menu is available only in the organisation view, under the left menu. Merge one organisation to another will transfer all users and data from one to another. On the left the organisation to merge, on the right the target one. +Merge Organisation menu is available only in the organisation view, under the left menu. Merging one organisation into another will transfer all users and data from one organisation to a different one. The organisation of which the users and data will be transferred is displayed on the left, the target organisation is displayed on the right. ![Merge organisations.](figures/merge_org.png) @@ -149,10 +150,10 @@ Merge Organisation menu is available only in the organisation view, under the le Privileges are assigned to users by assigning them to rule groups. Rule groups use one of four options determining what they can do with events as well as four additional privilege elevation settings. These are the four options to edit the full options available in the Roles section: Read Only, Manage My Own Events, Manage Organisation Events, Manage & Publish Organisation Events. A short description is provided below: -* **Read Only:** This allows a user to browse events that his organisation has access to, but doesn't allow any changes to be made to the database. -* **Manage My Own Events:** The second option, gives its users the rights to create, modify or delete their own events, but they cannot publish them. +* **Read Only:** Allows a user to browse events that his organisation has access to, but doesn't allow any changes to be made to the database. +* **Manage My Own Events:** Allows users to create, modify or delete their own events, but they cannot publish them. * **Manage Organization Events:** Allows users to create events or modify and delete events created by a member of their organisation. -* **Manage & Publish Organisation Events:** This last setting, gives users the right to do all of the above and also to publish the events of their organisation. +* **Manage & Publish Organisation Events:** Gives users the right to do all of the above and to publish the events of their organisation. The extra permissions are defined below: @@ -176,7 +177,7 @@ When creating a new role, you will have to enter a name for the role to be creat #### Listing roles -By clicking on the List Roles button, you can view a list of all currently registered roles and a list of the permission flags enabled for each. In addition, you can find buttons that allow you to edit and delete said roles. Keep in mind that you will need to first remove every member from a role before you can delete it. +By clicking on the List Roles button, you can view a list of all currently registered roles and their enabled permissions. In addition, you can find buttons that allow you to edit and delete said roles. Keep in mind that you will need to first remove every member from a role before you can delete it. ![You can Edit or Delete roles using the action buttons to the right in each row. Keep in mind that in order to Delete a role, all members of a Role must be removed from said role before it can be deleted.](figures/list_roles.png) @@ -208,7 +209,6 @@ Since version 2.3, MISP has a settings and diagnostics tool that allows site-adm ### Server settings and diagnostics - ![Server settings overview with all of the tabs explained.](figures/settings_1.png) The settings and diagnostics tool is split up into several aspects, all accessible via the tabs on top of the tool. For any unset or incorrectly set setting, or failed diagnostic a number next to the tab name will indicate the number and severity of the issues. If the number is written with a red font, it means that the issue is critical. First, let's look at the various tabs: @@ -220,7 +220,7 @@ The settings and diagnostics tool is split up into several aspects, all accessib * **Misc settings**: Settings controlling debug options, please ensure that debug is always disabled on a production system. * **Diagnostics**: The diagnostics tool checks if all directories that MISP uses to store data are writeable by the apache user. Also, the tool checks whether the STIX libraries and GnuPG are working as intended. * **Workers**: Shows the background workers (if enabled) and shows a warning if they are not running. Admins can also restart the workers here. -* **Download report**: Download a report in JSON format, compiled of all of the settings visible in the tool. +* **Download report**: Download a report of all the settings visible in the tool, in JSON format. ![The settings tabs explained.](figures/settings_2.png) @@ -229,13 +229,13 @@ Each of the setting pages is a table with each row representing a setting. Colou * **Setting**: The setting name. * **Value**: The current value of the setting. * **Description**: A description of what the setting does. -* **Error Message**: If the setting is incorrect / not set, then this field will let the user know what is wrong. +* **Error Message**: If the setting is incorrect / not set, this field will let the user know what is wrong. ![The workers tab.](figures/settings_3.png) The workers tab shows a list of the workers that MISP can use. You can restart workers using the "restart all workers" button. If the button doesn't work, make sure that the workers were started using the apache user. This can however only be done using the command line, refer to the INSTALL.txt documentation on how to let the workers automatically start on each boot. -* **Worker Type**: The worker type is determined by the queue it monitors. MISP currently has 5 queues (cache, default, prio, email and a special _schdlr_ queue). +* **Worker Type**: The worker type is determined by the queue it monitors. MISP currently has 6 queues (cache, default, prio, email, update and a special _schdlr_ queue). * **Worker Id**: The ID is made up of the machine name, the PID of the worker and the queue it monitors. * **Status**: Displays OK if the worker is running. If the _schdlr_ worker is the only one not running, make sure that you copy the config file into the cakeresque directory as described in the INSTALL.txt documentation. @@ -259,6 +259,12 @@ The workers tab shows a list of the workers that MISP can use. You can restart w Interdependence: +**update** + + Role: + Interdependence: + + **prio** Role: @@ -266,9 +272,11 @@ The workers tab shows a list of the workers that MISP can use. You can restart w **scheduler** + Role: Interdependence: + #### Workers dead Even if the workers are dead, any actions related to them are on-hold. Nothing is lost. @@ -422,6 +430,46 @@ Apart from off-loading long-lasting jobs to the background workers, there is a s ### Various administration tips & tricks + +#### Setting a Publish Alert Filter + +To regulate the reception of e-mail from MISP it is possible to create filters. Each individual user account can apply such filter. + +The filter can be configured by the user but also by the organization administrator. + +After login goto Administration -> Set User Setting: + +![Set User settings](figures/setUserSetting.png) + +A new screen appears. Make sure the “Setting” drop down box shows “publish_alert_filter”: + +![Set User settings](figures/setUserSetting2.png) + +The text field “Value” contains the filter, which needs to be provided in JSON format. Important JSON-objects which can be used here go by the name AND”, “OR” and “NOT”. These should be structured in a logical tree. + +The filtering can be applied to tags or to a publishing organization. + +In the following example, all notifications will be filtered which carry ‘tlp.white’ and ‘tlp.green’ in the name of the tag: + +``` +{ + + "NOT": { + + "Tag.name" : [ "tlp.white", "tlp.green" ] + + } + +} +``` + +The publish_alert_filter setting allows one filter definition to be active. + +After applying the configuration, the filter will show up in the “My Settings” menu: + +![Set User settings](figures/setUserSetting3.png) + + #### Default sharing level Choose your default sharing level to match your usage scenario for MISP. The setting is named *default_event_distribution* and the values can be: diff --git a/administration/figures/setUserSetting.png b/administration/figures/setUserSetting.png new file mode 100644 index 0000000..1a177f1 Binary files /dev/null and b/administration/figures/setUserSetting.png differ diff --git a/administration/figures/setUserSetting2.png b/administration/figures/setUserSetting2.png new file mode 100644 index 0000000..37638db Binary files /dev/null and b/administration/figures/setUserSetting2.png differ diff --git a/administration/figures/setUserSetting3.png b/administration/figures/setUserSetting3.png new file mode 100644 index 0000000..df4d7f4 Binary files /dev/null and b/administration/figures/setUserSetting3.png differ diff --git a/appendices/README.md b/appendices/README.md index 0cc3e16..9500569 100644 --- a/appendices/README.md +++ b/appendices/README.md @@ -233,6 +233,7 @@ This section lists the projects that can be found on the main [MISP GitHub](http | Project | Description | Status | | -- | -- | -- | | [misp-objects](https://github.com/MISP/misp-objects) | Definition, description and relationship types of MISP objects | Core to MISP, frequently updated and tested | +| [Best Practices in ThreatIntel](https://github.com/MISP/best-practices-in-threat-intelligence) | Best practices in threat intelligence | Book available here: https://www.misp-project.org/best-practices-in-threat-intelligence.html | +# Appendix E: Other Threat Intel Ressources + +A brief list of online ressources that around #ThreatIntel + +* [A curated list of awesome malware analysis tools and resources](https://github.com/rshipp/awesome-malware-analysis/blob/master/README.md). Inspired by [awesome-python](https://github.com/vinta/awesome-python) and [awesome-php](https://github.com/ziadoz/awesome-php). +* [An authoritative list of awesome devsecops tools with the help from community experiments and contributions](https://github.com/devsecops/awesome-devsecops/blob/master/README.md).[DEV.SEC.OPS](http://devsecops.org) +* [Advance Python IoC extractor](https://github.com/InQuest/python-iocextract) + # Appendix F: LDAP Authentication MISP supports LDAP authentication from version 2.4.xxx. This manual will show how to configure LDAP authentication. @@ -377,4 +386,4 @@ Because LDAP and MISP users are paired by e-mail address, it is possible to migr * When a user is disabled in LDAP and also in MISP and then enabled in LDAP, it will be enabled in MISP for next login just when `updateUser` is set to `true`. * Currently it is not possible to log in with both LDAP and local (MISP) accounts. * Admins can change users email address. But when `updateUser` is set to true, when the user will log in again, the e-mail address will be updated from LDAP. -* `Security.require_password_confirmation` setting currently doesnt work with LDAP authentication. But on the other hand, since user cannot change e-mail address and password, this setting is not important. +* `Security.require_password_confirmation` setting currently doesnt work with LDAP authentication. But on the other hand, since user cannot change e-mail address and password, this setting is not important. \ No newline at end of file diff --git a/automation/README.md b/automation/README.md index d742ef8..3aea3fd 100644 --- a/automation/README.md +++ b/automation/README.md @@ -75,13 +75,84 @@ To be done #### Example ~~~~ -curl --header "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf " --header "Accept: application/json" --header "Content-Type: application/json" http://10.50.13.60/servers/gaaa +curl --header "Authorization: YOUR API KEY " --header "Accept: application/json" --header "Content-Type: application/json" http://10.50.13.60/servers/gaaa ~~~~ ~~~~json {"name":"Not Found","message":"Not Found","url":"\/servers\/gaaa"} ~~~~ +## Search + +It is possible to search in the database for a list of attributes or events based on a list of criterias. + +To return attributes or events in a desired format, use the following URL and header settings: + +URL: +~~~~ +YOUR_MISP_URL/attributes/restSearch +YOUR_MISP_URL/events/restSearch +~~~~ + +Headers: +~~~~ +Accept: application/json +Content-type: application/json +Authorization: YOUR_API_KEY +~~~~ + +The next feature to take care of then is the body of the query. This is where you are going to put your filters. +As an example, if we want to export all the IP addresses that have a TLP marking and not marked as TLP:red, you can find below the corresponding filters to use: +~~~~json +{ + "returnFormat": "json", + "type": { + "OR": [ + "ip-src", + "ip-dst" + ] + }, + "tags": { + "NOT": [ + "tlp:red" + ], + "OR": [ + "tlp:%" + ] + } +} +~~~~ + +Find below a non exhaustive list of parameters that can be used to filter data in your search (some parameters specific to given export formats are not mentioned): +- **returnFormat**: Set the return format of the search (Currently supported: json, xml, openioc, suricata, snort - more formats are being moved to restSearch with the goal being that all searches happen through this API). Can be passed as the first parameter after restSearch or via the JSON payload. +- **limit**: Limit the number of results returned, depending on the scope (for example 10 attributes or 10 full events). +- **page**: If a limit is set, sets the page to be returned. page 3, limit 100 will return records 201->300). +- **value**: Search for the given value in the attributes' value field. +- **type**: The attribute type, any valid MISP attribute type is accepted. +- **category**: The attribute category, any valid MISP attribute category is accepted. +- **org**: Search by the creator organisation by supplying the organisation identifier. +- **tags**: To include a tag in the results just write its names into this parameter. To exclude a tag prepend it with a '!'. +- **quickfilter**: Enabling this (by passing "1" as the argument) will make the search ignore all of the other arguments, except for the auth key and value. MISP will return an xml / json (depending on the header sent) of all events that have a sub-string match on value in the event info, event orgc, or any of the attribute value1 / value2 fields, or in the attribute comment. +- **from**: Events with the date set to a date after the one specified in the from field (format: 2015-02-15). This filter will use the date of the event. +- **to**: Events with the date set to a date before the one specified in the to field (format: 2015-02-15). This filter will use the date of the event. +- **eventid**: The events that should be included / excluded from the search +- **withAttachments**: If set, encodes the attachments / zipped malware samples as base64 in the data field within each attribute +- **metadata**: Only the metadata (event, tags, relations) is returned, attributes and proposals are omitted. +- **uuid**: Restrict the results by uuid. +- **publish_timestamp**: Restrict the results by the timestamp of the last publishing of the event. The input can be a timetamp or a short-hand time description (7d or 24h for example). You can also pass a list with two values to set a time range (for example ["14d", "7d"]). +- **last**: (Deprecated synonym for publish_timestamp) Restrict the results by the timestamp of the last publishing of the event. The input can be a timetamp or a short-hand time description (7d or 24h for example). You can also pass a list with two values to set a time range (for example ["14d", "7d"]). +- **timestamp**: Restrict the results by the timestamp (last edit). Any event with a timestamp newer than the given timestamp will be returned. In case you are dealing with /attributes as scope, the attribute's timestamp will be used for the lookup. The input can be a timetamp or a short-hand time description (7d or 24h for example). You can also pass a list with two values to set a time range (for example ["14d", "7d"]). +- **published**: Set whether published or unpublished events should be returned. Do not set the parameter if you want both. +- **enforceWarninglist**: Remove any attributes from the result that would cause a hit on a warninglist entry. +- **to_ids**: By default (0) all attributes are returned that match the other filter parameters, irregardless of their to_ids setting. To restrict the returned data set to to_ids only attributes set this parameter to 1. You can only use the special "exclude" setting to only return attributes that have the to_ids flag disabled. +- **deleted**: If this parameter is set to 1, it will return soft-deleted attributes along with active ones. By using "only" as a parameter it will limit the returned data set to soft-deleted data only. +- **includeEventUuid**: Instead of just including the event ID, also include the event UUID in each of the attributes. +- **event_timestamp**: Only return attributes from events that have received a modification after the given timestamp. The input can be a timetamp or a short-hand time description (7d or 24h for example). You can also pass a list with two values to set a time range (for example ["14d", "7d"]). +- **sgReferenceOnly**: If this flag is set, sharing group objects will not be included, instead only the sharing group ID is set. +- **eventinfo**: Filter on the event's info field. +- **searchall**: Search for a full or a substring (delimited by % for substrings) in the event info, event tags, attribute tags, attribute values or attribute comment fields. +- **attackGalaxy**: Select the ATT&CK matrix like galaxy to use when using returnFormat = attack. Defaults to the Mitre ATT&CK library via mitre-attack-pattern. + ## Events management ### /events @@ -125,7 +196,7 @@ curl --header "Authorization: YOUR API KEY" --header "Accept: application/json" #### Example ~~~~ -curl -i -H "Accept: application/json" -H "content-type: application/json" -H "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf" --data "@event.json" -X POST http://10.50.13.60/events +curl -i -H "Accept: application/json" -H "content-type: application/json" -H "Authorization: YOUR API KEY" --data "@event.json" -X POST http://10.50.13.60/events ~~~~ That is how an event JSON object should look like @@ -159,7 +230,7 @@ Delete events based on criteria curl --header "Authorization: YOUR API KEY" --header "Accept: application/json" --header "Content-Type: application/json" https:/// ~~~~ -curl --header "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf " --header "Accept: application/json" --header "Content-Type: application/json" -X "DELETE" http://10.50.13.60/events/1 +curl --header "Authorization: YOUR API KEY " --header "Accept: application/json" --header "Content-Type: application/json" -X "DELETE" http://10.50.13.60/events/1 ~~~~ ### GET /events/index @@ -176,7 +247,7 @@ Return the event index. - Warning, there's a limit on the number of results #### Example ~~~~ -curl --header "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf " --header "Accept: application/json" --header "Content-Type: application/json" http://10.50.13.60/events/index +curl --header "Authorization: YOUR API KEY " --header "Accept: application/json" --header "Content-Type: application/json" http://10.50.13.60/events/index ~~~~ @@ -447,12 +518,12 @@ Attaches an Tag to an Object by a given UUID #### Example ~~~~ -curl --header "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf " --header "Accept: application/json" --header "Content-Type: application/json" -X POST http://10.50.13.60/tags/attachTagToObject/5a0d68b3-6da0-4ced-8233-77bb950d210f/tlp3Awhite +curl --header "Authorization: YOUR API KEY " --header "Accept: application/json" --header "Content-Type: application/json" -X POST http://10.50.13.60/tags/attachTagToObject/5a0d68b3-6da0-4ced-8233-77bb950d210f/tlp3Awhite ~~~~ ~~~~ -curl --header "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf " -d "{"uuid"="5a0d68b3-6da0-4ced-8233-77bb950d210f" "tag"="tlp:white"}" --header "Accept: application/json" --header "Content-Type: application/json" -X POST http://10.50.13.60/tags/attachTagToObject/ +curl --header "Authorization: YOUR API KEY " -d "{"uuid"="5a0d68b3-6da0-4ced-8233-77bb950d210f" "tag"="tlp:white"}" --header "Accept: application/json" --header "Content-Type: application/json" -X POST http://10.50.13.60/tags/attachTagToObject/ ~~~~ @@ -479,7 +550,7 @@ Removes an Tag to an Object by a given UUID #### Example ~~~~ -curl --header "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf " --header "Accept: application/json" --header "Content-Type: application/json" -X POST http://10.50.13.60/tags/removeTagFromObject/5a0d68b3-6da0-4ced-8233-77bb950d210f/tlp3Awhite +curl --header "Authorization: YOUR API KEY " --header "Accept: application/json" --header "Content-Type: application/json" -X POST http://10.50.13.60/tags/removeTagFromObject/5a0d68b3-6da0-4ced-8233-77bb950d210f/tlp3Awhite ~~~~ @@ -508,7 +579,7 @@ Will give an overview of the used attribute tags #### Example ~~~~ -curl --header "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf " --header "Accept: application/json" --header "Content-Type: application/json" -X GET http://10.50.13.60/tags/tagStatistics/ +curl --header "Authorization: YOUR API KEY " --header "Accept: application/json" --header "Content-Type: application/json" -X GET http://10.50.13.60/tags/tagStatistics/ ~~~~ ## Attribute management @@ -525,7 +596,7 @@ Adds an Attribute to an event #### Example ~~~~ -curl --header "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf " --header "Accept: application/json" --header "Content-Type: application/json" -d "{"event_id":"3542","value":"1.2.3.4","category":"Network activity","type":"ip-dst"}" http://10.50.13.60/attributes/add/3542 +curl --header "Authorization: YOUR API KEY " --header "Accept: application/json" --header "Content-Type: application/json" -d "{"event_id":"3542","value":"1.2.3.4","category":"Network activity","type":"ip-dst"}" http://10.50.13.60/attributes/add/3542 ~~~~ ### GET /attributes @@ -545,11 +616,11 @@ Get an attribute #### Example ~~~~ -curl --header "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf " --header "Accept: application/json" --header "Content-Type: application/json" http://10.50.13.60/attributes/548847db-060c-4275-a0c7-15bb950d210b +curl --header "Authorization: YOUR API KEY " --header "Accept: application/json" --header "Content-Type: application/json" http://10.50.13.60/attributes/548847db-060c-4275-a0c7-15bb950d210b ~~~~ -### GET /attributes/delete/ +### POST /attributes/delete/ #### Description @@ -570,18 +641,18 @@ Delete attributes. #### Example ~~~~ -curl --header "Authorization: YOUR API KEY" --header "Accept: application/json" --header "Content-Type: application/json" https:///attributes/delete/12345 +curl -X POST --header "Authorization: YOUR API KEY" --header "Accept: application/json" --header "Content-Type: application/json" https:///attributes/delete/12345 ~~~~ ~~~~ -curl --header "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf " --header "Accept: application/json" --header "Content-Type: application/json" http://10.50.13.60/attributes/delete/548847db-060c-4275-a0c7-15bb950d210b +curl -X POST --header "Authorization: YOUR API KEY " --header "Accept: application/json" --header "Content-Type: application/json" http://10.50.13.60/attributes/delete/548847db-060c-4275-a0c7-15bb950d210b ~~~~ Hard delete: ~~~~ -curl --header "Authorization: YOUR API KEY" --header "Accept: application/json" --header "Content-Type: application/json" https:///attributes/delete/12345/1 +curl -X POST --header "Authorization: YOUR API KEY" --header "Accept: application/json" --header "Content-Type: application/json" https:///attributes/delete/12345/1 ~~~~ @@ -614,7 +685,7 @@ Will give an overview of the used attribute types #### Example ~~~~ -curl --header "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf " --header "Accept: application/json" --header "Content-Type: application/json" -X GET http://10.50.13.60/attributes/attributeStatistics/ +curl --header "Authorization: YOUR API KEY " --header "Accept: application/json" --header "Content-Type: application/json" -X GET http://10.50.13.60/attributes/attributeStatistics/ ~~~~ ### GET /attributes/describeTypes Describe types API @@ -643,7 +714,7 @@ Depending on the headers passed the returned data will be a JSON object or an XM #### Example ~~~~ -curl --header "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf " --header "Accept: application/json" --header "Content-Type: application/json" http://10.50.13.60/servers/getPyMISPVersion.json +curl --header "Authorization: YOUR API KEY " --header "Accept: application/json" --header "Content-Type: application/json" http://10.50.13.60/servers/getPyMISPVersion.json ~~~~ ### GET /servers/getVersion @@ -656,7 +727,7 @@ curl --header "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf " --heade #### Example ~~~~ -curl --header "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf " --header "Accept: application/json" --header "Content-Type: application/json" http://10.50.13.60/servers/getPyMISPVersion.json +curl --header "Authorization: YOUR API KEY " --header "Accept: application/json" --header "Content-Type: application/json" http://10.50.13.60/servers/getPyMISPVersion.json ~~~~ @@ -776,7 +847,7 @@ Will output all users "server_id": "0", "email": "admin@admin.test", "autoalert": false, - "authkey": "a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf", + "authkey": "YOUR API KEY", "invited_by": "0", "gpgkey": null, "certif_public": "", @@ -810,7 +881,7 @@ Will output all users #### Example ~~~~ -curl --header "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf " --header "Accept: application/json" --header "Content-Type: application/json" -X GET http://10.50.13.60/admin/users +curl --header "Authorization: YOUR API KEY " --header "Accept: application/json" --header "Content-Type: application/json" -X GET http://10.50.13.60/admin/users ~~~~ @@ -836,7 +907,7 @@ Will return a single user. To view a user simply send a GET request. "server_id": "0", "email": "admin@admin.test", "autoalert": false, - "authkey": "a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf", + "authkey": "YOUR API KEY", "invited_by": "0", "gpgkey": null, "certif_public": "", @@ -857,7 +928,7 @@ Will return a single user. To view a user simply send a GET request. ~~~~ #### Example ~~~~ -curl --header "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf " --header "Accept: application/json" --header "Content-Type: application/json" -X GET http://10.50.13.60/admin/users/view/1 +curl --header "Authorization: YOUR API KEY " --header "Accept: application/json" --header "Content-Type: application/json" -X GET http://10.50.13.60/admin/users/view/1 ~~~~ @@ -1918,7 +1989,7 @@ Return the index of warninglists enabled on the MISP instance ~~~~ #### Example ~~~~ -curl --header "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf " --header "Accept: application/json" --header "Content-Type: application/json" -X "GET" https://10.50.13.60/warninglists/index +curl --header "Authorization: YOUR API KEY " --header "Accept: application/json" --header "Content-Type: application/json" -X "GET" https://10.50.13.60/warninglists/index ~~~~ ### GET warninglists/view/1 @@ -1939,7 +2010,7 @@ to long ~~~~ #### Example ~~~~ -curl --header "Authorization: a4PLf8QICdDdOmFjwdtSYqkCqn9CvN0VQt7mpUUf " --header "Accept: application/json" --header "Content-Type: application/json" -X "GET" https://10.50.13.60/warninglists/view/17 +curl --header "Authorization: YOUR API KEY " --header "Accept: application/json" --header "Content-Type: application/json" -X "GET" https://10.50.13.60/warninglists/view/17 ~~~~ diff --git a/book-convention/README.md b/book-convention/README.md index 8b68ba6..4c7c37b 100644 --- a/book-convention/README.md +++ b/book-convention/README.md @@ -16,13 +16,13 @@ description: Convention Used in MISP-Book ## Language -The language in this book is american english. -All the screenshots and examples are in english. +The language in this book is American English. +All the screenshots and examples are in English. ## CoC The same code of conduct applies to this book as for the main MISP project. -As a book can some times be considered the inadvertent sould of a piece of software, please take good care and consideration of our `Code of Conduct`. The CoC [can be read here](https://github.com/MISP/MISP/blob/2.4/code_of_conduct.md). +As a book can some times be considered the inadvertent soul of a piece of software, please take good care and consideration of our `Code of Conduct`. The CoC [can be read here](https://github.com/MISP/MISP/blob/2.4/code_of_conduct.md). ## Example install diff --git a/categories-and-types/README.md b/categories-and-types/README.md index bf5b196..5cca646 100644 --- a/categories-and-types/README.md +++ b/categories-and-types/README.md @@ -19,6 +19,7 @@ |campaign-name| | | X | | | | |cc-number| | | | | X | | |cdhash| | X | | | | | +|chrome-extension-id| | | | | | | |comment| X | X | X | X | X | X | |community-id| | | | X | | | |cookie| | X | | | | | @@ -26,6 +27,7 @@ |counter| | | | | | | |country-of-residence| | | | | | | |cpe| | | | | | | +|dash| | | | | X | | |date-of-birth| | | | | | | |datetime| | | | | | | |dns-soa-email| | | X | | | | @@ -44,6 +46,7 @@ |email-subject| | | | | | | |email-thread-index| | | | | | | |email-x-mailer| | | | | | | +|eppn| | | | | | | |filename| | X | | X | | | |filename|authentihash| | X | | | | | |filename|impfuzzy| | X | | | | | @@ -84,6 +87,7 @@ |issue-date-of-the-visa| | | | | | | |ja3-fingerprint-md5| | | | X | | | |jabber-id| | | | | | | +|kusto-query| | X | | | | | |last-name| | | | | | | |link| X | | | X | | X | |mac-address| | | | X | | | @@ -182,6 +186,7 @@ |campaign-name| | | | | | | |cc-number| | | | | | | |cdhash| | | X | X | | | +|chrome-extension-id| | | X | X | | | |comment| X | X | X | X | X | X | |community-id| X | | | | | | |cookie| X | | | | | | @@ -189,6 +194,7 @@ |counter| | X | | | | | |country-of-residence| | | | | | | |cpe| | X | | | | | +|dash| | | | | | | |date-of-birth| | | | | | | |datetime| | X | | | | | |dns-soa-email| | | | | | | @@ -202,11 +208,12 @@ |email-message-id| | | X | | | | |email-mime-boundary| | | X | | | | |email-reply-to| | | X | | | | -|email-src| | | X | | | | +|email-src| X | | X | | | | |email-src-display-name| | | X | | | | |email-subject| X | | X | | | | |email-thread-index| | | X | | | | |email-x-mailer| | | X | | | | +|eppn| X | | | | | | |filename| | | X | X | | X | |filename|authentihash| | | X | X | | | |filename|impfuzzy| | | X | X | | | @@ -247,6 +254,7 @@ |issue-date-of-the-visa| | | | | | | |ja3-fingerprint-md5| X | | X | | | | |jabber-id| | | | | | | +|kusto-query| | | | | | | |last-name| | | | | | | |link| | | X | | | | |mac-address| X | | X | | | | @@ -345,6 +353,7 @@ |campaign-name| | | | | |cc-number| | | | | |cdhash| | | | | +|chrome-extension-id| | | | | |comment| X | X | X | X | |community-id| | | | | |cookie| | | | | @@ -352,6 +361,7 @@ |counter| | | | | |country-of-residence| X | | | | |cpe| | | | | +|dash| | | | | |date-of-birth| X | | | | |datetime| | | | | |dns-soa-email| | | | | @@ -370,6 +380,7 @@ |email-subject| | | | | |email-thread-index| | | | | |email-x-mailer| | | | | +|eppn| | X | | | |filename| | | | | |filename|authentihash| | | | | |filename|impfuzzy| | | | | @@ -410,6 +421,7 @@ |issue-date-of-the-visa| X | | | | |ja3-fingerprint-md5| | | | | |jabber-id| | X | | | +|kusto-query| | | | | |last-name| X | | | | |link| | | X | | |mac-address| | | | | @@ -528,6 +540,7 @@ * **campaign-name**: Associated campaign name * **cc-number**: Credit-Card Number * **cdhash**: An Apple Code Directory Hash, identifying a code-signed Mach-O executable file +* **chrome-extension-id**: Chrome extension id * **comment**: Comment or description in a human language * **community-id**: a community ID flow hashing algorithm to map multiple traffic monitors into common flow id * **cookie**: HTTP cookie as often stored on the user web client. This can include authentication cookie or session cookie. @@ -535,6 +548,7 @@ * **counter**: An integer counter, generally to be used in objects * **country-of-residence**: The country of residence of a natural person * **cpe**: Common platform enumeration +* **dash**: Dash Address * **date-of-birth**: Date of birth of a natural person (in YYYY-MM-DD format) * **datetime**: Datetime in the ISO 8601 format * **dns-soa-email**: RFC1035 mandates that DNS zones should have a SOA (Statement Of Authority) record that contains an email address where a PoC for the domain could be contacted. This can sometimes be used for attribution/linkage between different domains even if protected by whois privacy @@ -553,6 +567,7 @@ * **email-subject**: The subject of the email * **email-thread-index**: The email thread index header * **email-x-mailer**: Email x-mailer header +* **eppn**: eduPersonPrincipalName - eppn - the NetId of the person for the purposes of inter-institutional authentication. Should be stored in the form of user@univ.edu, where univ.edu is the name of the local security domain. * **filename**: Filename * **filename|authentihash**: A checksum in md5 format * **filename|impfuzzy**: Import fuzzy hash - a fuzzy hash created based on the imports in the sample. @@ -580,19 +595,20 @@ * **hasshserver-md5**: hasshServer is a network fingerprinting standard which can be used to identify specific Server SSH implementations. The fingerprints can be easily stored, searched and shared in the form of an MD5 fingerprint. * **hex**: A value in hexadecimal format * **hostname**: A full host/dnsname of an attacker -* **hostname|port**: Hostname and port number seperated by a | +* **hostname|port**: Hostname and port number separated by a | * **http-method**: HTTP method used by the malware (e.g. POST, GET, ...). * **iban**: International Bank Account Number * **identity-card-number**: Identity card number * **impfuzzy**: A fuzzy hash of import table of Portable Executable format * **imphash**: Import hash - a hash created based on the imports in the sample. * **ip-dst**: A destination IP address of the attacker or C&C server -* **ip-dst|port**: IP destination and port number seperated by a | +* **ip-dst|port**: IP destination and port number separated by a | * **ip-src**: A source IP address of the attacker -* **ip-src|port**: IP source and port number seperated by a | +* **ip-src|port**: IP source and port number separated by a | * **issue-date-of-the-visa**: The date on which the visa was issued * **ja3-fingerprint-md5**: JA3 is a method for creating SSL/TLS client fingerprints that should be easy to produce on any platform and can be easily shared for threat intelligence. * **jabber-id**: Jabber ID +* **kusto-query**: Kusto query - Kusto from Microsoft Azure is a service for storing and running interactive analytics over Big Data. * **last-name**: Last name of a natural person * **link**: Link to an external information * **mac-address**: Mac address diff --git a/connectors/README.md b/connectors/README.md index 3312bdc..b2ef301 100644 --- a/connectors/README.md +++ b/connectors/README.md @@ -1,15 +1,20 @@ # External Connectors -Below you will find various tweaks and tips when integrating 3rd party connectors. +The MISP to Microsoft Graph Security Script enables you to connect your custom threat indicators or Indicators of Comprosmise (IoCs) and make these available in the following Microsoft products. -## Microsoft Azure Sentinel +## Azure Sentinel [Azure Sentinel](https://azure.microsoft.com/en-us/services/azure-sentinel/) -# MISP to Microsoft Graph Security Script -The script provides clients with MISP instances to migrate threat indicators to the Microsoft Graph Security API. +## Microsoft Defender ATP -For more information on Microsoft Security Graph visit [Microsoft Graph] (https://developer.microsoft.com/en-us/graph) +[Microsoft Defender ATP](https://www.microsoft.com/en-us/microsoft-365/windows/microsoft-defender-atp/) + +# MISP to Microsoft Graph Security Script +The script provides clients with MISP instances to migrate threat indicators to the [Microsoft Graph Security API](https://aka.ms/graphsecuritydocs). + +For more information on Microsoft Graph Security API visit [Microsoft Graph Security API](https://aka.ms/graphsecuritydocs).
+For more information on Microsoft Graph visit [Microsoft Graph](https://developer.microsoft.com/en-us/graph). ## Prerequisites Before installing the sample: @@ -25,21 +30,21 @@ After the prerequisites are installed or met, perform the following steps to use 1. To run script, go to the root directory of misp-graph-script and enter `PYTHONHASHSEED=0 python3 script.py` in the command line. ## App Registration -To configure the samples, you'll need to register a new application in the Microsoft [Application Registration Portal](https://apps.dev.microsoft.com/). -### Follow these steps to register a new application -1. Sign in to the [Azure Portal](https://portal.azure.com/) using either your personal or work or school account. +To configure the sample, you'll need to register a new application in the Microsoft [Application Registration Portal](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps). +Follow these steps to register a new application: +1. Sign in to the [Application Registration Portal](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps) using either your personal or work or school account. -1. Under My Azure Active Directory, choose App registrations (if you are suggested to use the preview, use that) choose New registration. +1. Choose **New registration**. -1. Enter an application name, and choose Register +1. Enter an application name, and choose **Register**. -1. Next you'll see the registration page for your app. Copy and save the `Application (client) Id` & `Directory (tenant) ID` field.You will need it later to complete the configuration process. +1. Next you'll see the overview page for your app. Copy and save the **Application Id** field. You will need it later to complete the configuration process. -1. Under Certificates & secrets, choose `New client secret` and give it a name. A new password will be displayed under Client secrets. Copy this password. This will be your `client secret`. You will need it later to complete the configuration process. +1. Under **Certificates & secrets**, choose **New client secret** and add a quick description. A new secret will be displayed in the **Value** column. Copy this password. You will need it later to complete the configuration process and it will not be shown again. -1. Under Authentication, find Implicit grant choose both `Access tokens` & `ID tokens` and save. +1. Under **API permissions**, choose **Add a permission > Microsoft Graph**. -1. Under API permissions click `Add a permission`, choose Microsoft Graph, under `Application permissions`, under ThreatIndicators add ThreatIndicators.ReadWrite.OwnedBy. You will be taken back to the API permissions screen, click `Grant admin consent for Default Directory` +1. Under **Application Permissions**, add the permissions/scopes required for the sample. This sample requires **ThreatIndicators.ReadWrite.OwnedBy**. >Note: See the [Microsoft Graph permissions reference](https://developer.microsoft.com/en-us/graph/docs/concepts/permissions_reference) for more information about Graph's permission model. 1. Modify the RequestManager.py file to comment out line 121-124. (This allows the script to run without failing due to line 123 being divided by `avg_speed` incase it starts as `0`. @@ -49,11 +54,11 @@ To configure the samples, you'll need to register a new application in the Micro misp = PyMISP(config.misp_domain, config.misp_key, config.misp_verifycert) ``` -1. Modify config.py file to add in `misp_verifycert = False` anywhere in the file. +10. Modify config.py file to add in `misp_verifycert = False` anywhere in the file. As the final step in configuring the script, modify the config.py file in the root folder of your cloned repo. -Update tenent, client_id, and client_secret in config.py +Update tenant, client_id, and client_secret in config.py ``` graph_auth = { 'tenant': '', @@ -66,6 +71,8 @@ Once changes are complete, save the config file. ## Configurations ### Target Product `targetProduct = "Azure Sentinel"` +**or** +`targetProduct = "Microsoft Defender ATP"` ### Misp Event Filter Filters can be set in the config.py file under the "misp_event_filters" property @@ -131,6 +138,8 @@ misp_event_filters = [] This gets all events. ### Action +Possible **action** values are: `alert`, `allow`, `block`. + `action = "alert"` (This is default). ### Passive Only @@ -161,7 +170,7 @@ In the command line, run `python3 script.py -r` * To aggregate all the requests that resulted in errors to a file, run `cat *_error_* > .txt` in the command line. ## Script Output -As the script runs, it prints out the request body sent to the Graph API and the response from the Graph API. +As the script runs, it prints out the request body sent to the Microsoft Graph Security API and the response from the Microsoft Graph Security API. Every request is logged as a json file under the directory "logs". The name of the json file is the datetime of when the request is completed. @@ -172,4 +181,4 @@ Below is a CRONTAB entry example of running the script every Sunday at 2am -This README.md has been adapted from the README.md found here [Microsoft Graph MISP sample](https://github.com/microsoftgraph/security-api-solutions/blob/master/Samples/MISP/README.md) +This README.md has been adapted from the README.md found in the [Microsoft Graph Security API MISP sample](https://aka.ms/tipmispsample). For most recent changes, visit [Microsoft Graph Security API MISP sample](https://aka.ms/tipmispsample). Provide your feedback on this sample by [filing a GitHub request](https://github.com/microsoftgraph/security-api-solutions/issues/new). diff --git a/faq/README.md b/faq/README.md index aaa1256..6daa5fe 100644 --- a/faq/README.md +++ b/faq/README.md @@ -2,13 +2,317 @@ # Frequently Asked Questions -The following page hosts most frequently asked questions as seen on our [issues](https://github.com/MISP/issues) and [gitter](https://gitter.im/MISP/Support). +The following page hosts some frequently asked questions as noticed in our [issues](https://github.com/MISP/issues) and [gitter](https://gitter.im/MISP/Support) channels. -## Usage +*** +## General questions +### Where can I get support? +If you have feature requests or you found a bug you can open a ticket on [MISP's GitHub repository issue](https://github.com/MISP/MISP/issues) tracker. + +If you want to discuss something related to MISP or want help from the MISP community, join the appropriate MISP Gitter channel: + +- [MISP Developer Room](https://gitter.im/MISP/MISP) Dev discussions +- [MISP Support Room](https://gitter.im/MISP/Support) OMGoo! My MISP doesn't work discussions +- [MISP Sharing Room](https://gitter.im/MISP/Sharing) Threat Intelligence Sharing discussions +- [misp-cloud Room](https://gitter.im/MISP/misp-cloud) Using MISP in the clouds discussions + +### What are the hardware requirements? + +From a hardware perspective, MISP's requirements are quite humble, a web server with 2+ cores and 8-16 GB of memory should be plenty, though more is always better of course. A lot of it depends on the data set and the number of users you are dealing with. + +We recommend a standard LAMP stack on top of Ubuntu >18.04 LTS. For details on the exact dependencies please refer to the [installation guide](https://misp.github.io/MISP/INSTALL.ubuntu1804/) as well as the [requirements for the MISP modules](https://github.com/MISP/misp-modules/blob/master/REQUIREMENTS). + +During a [Hackathon](https://hackathon.hack.lu) a small tool called [MISP-Sizer](https://misp-project.org/MISP-sizer/) was conceived. It will give you a **very rough** idea on what requirements are if you have a bigger installation. [source-code is here](https://github.com/MISP/MISP-sizer) + +*** +## Specific questions +### Can I configure MISP encrypted notification emails to contain more information in the subject? + +The setting 'MISP.extended_alert_subject' allows you to have an extended subject. /!\ Beware if you’re using encryption: the subject will not be encrypted. Be aware that you might leak some sensitive information this way. Below is an example how the two subject types look like. First with the option disabled, then with the option enabled. + + Event 7 - Low - TLP Amber + Event 8 - OSINT - Dissecting XXX... - Low - TLP Amber + +(Source: [Getting started with MISP](http://www.vanimpe.eu/2015/05/31/getting-started-misp-malware-information-sharing-platform-threat-sharing-part-3/)) + +### How can I restart the workers? + +The workers can be restarted from the web interface: + + administration -> server settings -> workers -> restart all + +You can also follow the manual process below. + +If you are on Ubuntu / Debian based systems: + + sudo su -l www-data -s /bin/bash -c "bash /var/www/MISP/app/Console/worker/start.sh" + +If you are on RHEL / Fedora based systems: + + su -s /bin/bash apache -c 'bash /var/www/MISP/app/Console/worker/start.sh' + +### How can I redirect HTTP to HTTPs? + +``` + + ServerAdmin misp@misp.misp + ServerName misp.misp.misp + ServerAlias misp-int.misp.misp + + Redirect permanent / https://misp.misp.misp + + LogLevel warn + ErrorLog /var/log/apache2/misp.local_error.log + CustomLog /var/log/apache2/misp.local_access.log combined + ServerSignature Off + + + + ServerAdmin misp@misp.misp + ServerName misp.misp.misp + ServerAlias misp-int.misp.misp + + DocumentRoot /var/www/MISP/app/webroot + + Options -Indexes + AllowOverride all + Order allow,deny + allow from all + + + SSLEngine On + SSLCertificateFile /etc/ssl/misp.misp.misp/misp.crt + SSLCertificateKeyFile /etc/ssl/misp.misp.misp/misp.key + SSLCertificateChainFile /etc/ssl/misp.misp.misp/mispCA.crt + + LogLevel warn + ErrorLog /var/log/apache2/misp.local_error.log + CustomLog /var/log/apache2/misp.local_access.log combined + ServerSignature Off + +``` + +Source: [Getting started with MISP](http://www.vanimpe.eu/2015/05/31/getting-started-misp-malware-information-sharing-platform-threat-sharing-part-3/) + +### When I try to access my new installation, I am redirected to localhost:8443 and get an error. + +By default, MISP runs on a local instance and is setup for local access upon installation. This allows you to setup security and customizations before making it available elsewhere. If you would like to access the MISP instance from a remote host (including another VM host/client), assign an IP to the MISP host and point your browser accordingly. Upon login, you may get the “localhost:8443” redirection. Change that piece of the URL back to the IP assigned to the MISP host (or associated DNS name) and refresh the browser. Once in, go to Administration - Server Settings and Maintenance - MISP settings. You can change the top two items to your MISP IP or DNS name and the redirect will start using that address instead of 'localhost'. + +### How can I define the default sharing level? + +MISP allows you to define the group of people with whom you want to share your threat data. If you do not set it to your preferred default then it’s likely that at one given moment you’ll make an error and share your intel with the wrong group. Defining the sharing level is done with the setting default_event_distribution in the configuration file. There are three levels: + + 0 : Your organisation only (default) + 1 : This community only + 2 : Connected communities + 3 : All communities + +You can set a similar configuration setting for the attributes. The setting default_attribute_distribution has the same values as default_event_distribution. Additionally it has the value event which allows the attribute to get the setting from the event to which it belongs. + +Source: [Getting started with MISP](http://www.vanimpe.eu/2015/05/31/getting-started-misp-malware-information-sharing-platform-threat-sharing-part-3/) + +### How can I add an organisation logo and/or foter logo? + +MISP can be made more appealing to the eye by adding some graphics. + +As Org.- or Site-admin navigate to *Administration* -> *List organisations* and edit the corresponding organization. +Withing this editor you will be able to update the logo. + +Other ways to achieve this, would be: + +Set your organisation logo by adding an image (.png) that has the same name as your organisation in the directory */var/www/MISP/app/webroot/img/orgs/*. + +Yet another way of doing this is by logging into your MISP instance with Admin rights, navigate to *Administration* -> *Server Settings*, tab -> *Manage files*. + +You can add a footer logo. Add an image to the directory */var/www/MISP/app/webroot/img/custom/* and define the footer logo in the config file (config.php) or in *Adminitration* -> *Server Settings...* -> *MISP settings* (search for: "footer_logo") point to the location on-disk of the image. + +Partial source: [Getting started with MISP](http://www.vanimpe.eu/2015/05/31/getting-started-misp-malware-information-sharing-platform-threat-sharing-part-3/) + +### All workers are starting correctly except _schdlr_ . How can I fix this? + +This can happen if the [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) of the server hosting the instance has changed. A way to fix this is to flush temporary data stored in redis. This can be done by logging in redis, for example when logging in with redis-cli, and issuing a _*flushall*_ command. + +### How can I import data directly from PDF reports? + +/!\ This section needs review, verification and eventual amendments to make sure it works. + +You can use a generic script called IOC parser (https://github.com/armbues/ioc_parser) or use a script published by Palo Alto to convert IOC parser output to a MISP event (https://github.com/PaloAltoNetworks-BD/report_to_misp/). You have also the option to select all the text and paste it in the free-text import form. + +Another option is the new [OCR import module](https://github.com/MISP/misp-modules) that can be used via the import modules. You will need to install the OCR software tesseract. + +### I am having trouble updating beyond version 2.4.50 (stuck loading any page beyond the login), what can I do? + +/!\ This applies to an earlier version of MISP, do not randomly try this fix on valuable data. By all means try it on a test-machine and report back if your problem was solved by this. + +This is most likely due to the fact that MISP did not clean up expired sessions prior to version 2.4.51 automatically and relied on a site-admin occasionally cleaning it up using the button found on the diagnostics page. Once you upgrade to 2.4.51, MISP will try to cull the table with each page load by a site-admin, which in some cases if the table has grown to extreme sizes it will get stuck on. To resolve the issue, log into mysql: + +`mysql -u [misp-db-user-name] -p [misp-db-name];` + +and execute the following commands: + + DROP cake_sessions; + CREATE TABLE IF NOT EXISTS `cake_sessions` ( + `id` varchar(255) COLLATE utf8_bin NOT NULL DEFAULT '', + `data` text COLLATE utf8_bin NOT NULL, + `expires` int(11) NOT NULL, + PRIMARY KEY (`id`), + INDEX `expires` (`expires`) + ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_bin; + +After this everything should work and the session table will be trimmed each time a site-admin loads a page. + +### I have many failed jobs when doing email notification. What should I do? + +This is most probably due to some encryption failing for some users. We strongly advise to review the current +PGP keys and to ensure that they keys are not expired or perhaps not supported anymore (weak keys). The keys can be reviewed at the following +location in MISP: + + ``` + https:///users/verifyGPG + ``` + +### Upgrading from MISP 2.4.65 to MISP 2.4.66 - Unable to merge due to the Composer file. + +In MISP 2.4.66, Composer is included by default to avoid the risk of downloading a rogue PHP Composer version (if the composer repository is compromised or MiTM are performed) via the download and php execution. But when upgrading (via a git pull), the git merge process might complain about the composer phar file still being there. You can safely remove that file and `git pull origin 2.4` again. + +### I have issues with pushing events + +- What does the 'Connection test' for the specific server report? (*Sync Actions* -> *List Servers*) + +- Is the event you assume to push/pull ready to be published? + +- Is the distribution level set not too restrictive? + +- Have you enabled push in the servers config you want to push to? + +- Do you have any limitations to the push rules e.g. limited to a certain TLP Level tag or other? + +- What is written in your job log? + + https:///jobs/index + +Have a look at: /var/www/MISP/app/tmp/logs and /var/log/apache2/misp (or the relevant apache log folder of the instance in cause) + +### I have many users or API accesses, what's the best PHP session handler? + +We strongly recommend production-level MISP installations to rely on PHP session in Redis. As Redis is already part +of a standard MISP setup, we recommend to enable the redis session handling. + +To configure the redis session handling in PHP, edit : + +~~~ + session.save_handler = redis + session.save_path = "tcp://127.0.0.1:6379 +~~~ + +### Is there TAXII support? + +A TAXII 1 implementation can be found at https://github.com/MISP/MISP-Taxii-Server . +This is mostly a TAXII server hooked up to MISP, meant to receive STIX files to its in box and uploading them to MISP. +There is also an experimental feature to push MISP events to the TAXII server when they're published - that's in `scripts/push_published_to_taxii.py`. It seems to work, but may occasionally re-upload duplicate events to MISP. + +TAXII 2 is provided in the future once the specification, which is at time of writing in draft, reaches a stable form. + +### Wipe MISP data - Remove all data + +If you need to start from scratch with your MISP database and remove all data you can use the [`misp-wipe`](https://github.com/MISP/MISP/tree/2.4/tools/misp-wipe) script provided in the `tools/` folder. + +### Constantly acknowledging my self-signed certificate drives me nuts + +You want to add it in 2 places: Your browser(s) and your OS. + +The following steps can be performed on the CLI to install the Certificate: + +```bash +sudo mkdir -m 0755 /usr/local/share/ca-certificates/MISP +sudo cp /etc/ssl/private/misp.local.crt /usr/local/share/ca-certificates/MISP +sudo chmod 0644 /usr/local/share/ca-certificates/MISP/misp.local.crt +sudo update-ca-certificates +``` + +For the Chrome Browser: + +1. Visit: "Advanced Settings" -> chrome://settings/?search=Manage+certificates +2. Scroll down to: Manage Certificates (click) +3. Select: "Authorities" +4. Click: "Import" +5. Browse to your .crt file and import it. +6. On the next screen tick: "Trust this certificate for identifying websites" +7. Done, enjoy the new gained quality of life + +Note: Chrome might expect a [Subject Alternative Name](https://en.wikipedia.org/wiki/Subject_Alternative_Name) make sure you created your certificate with '-extension san'. + +To allow insecure localhost connections enable this option: chrome://flags/#allow-insecure-localhost + +Sources: [CLI](https://askubuntu.com/questions/645818/how-to-install-certificates-for-command-line) and [Chrome](https://origin-symwisedownload.symantec.com/resources/webguides/sslv/sslva_first_steps/Content/Topics/Configure/ssl_chrome_cert.htm)/[Chrome insecure localhost](https://stackoverflow.com/questions/7580508/getting-chrome-to-accept-self-signed-localhost-certificate) + +[For the Firefox Browser](https://superuser.com/questions/1054724/how-to-make-firefox-ignore-all-ssl-certification-errors) + +### How can I change the theme? + +MISP uses [bootstrap.css](https://getbootstrap.com) the specific CSS file can be found on a typical MISP install at `/var/www/MISP/app/webroot/css/bootstrap.css`. + +You can customize this for your own needs. There are also pre-made boostrap themes which you can use as-is or build upon. + +Before making any changes, confirm the version of boostrap currenlty used by running `head -5 /var/www/MISP/app/webroot/css/bootstrap.css`. You can find themes on sites like [Bootswatch](https://bootswatch.com/2/). + +To replace the current theme with a theme you found on bootsplash, run: `wget https://bootswatch.com/2/readable/bootstrap.css -O /var/www/MISP/app/webroot/css/bootstrap.css` , replacing the URL as needed. + +Some bootswatch themes applied on MISP: +* https://i.imgur.com/usONTLk.png +* https://i.imgur.com/5XMjB7o.png +* https://i.imgur.com/5gc57VU.png +* https://i.imgur.com/4AJCPgf.png +* https://i.imgur.com/JuMGm8U.png +* https://i.imgur.com/v1Wu6xW.png + +### How can I deal with a MISP instance that has pulled in feeds over and over into new events, generating hundreds of GBs of junk correlations, rendering the instance unusable? + +*Step 1:* ensure that all your CSV/freetext source_format feeds are using the fixed event setting. If you want to make sure this is the case, you can run this SQL query instead of doing it manually: + +``` +UPDATE feeds SET fixed_event = 1 WHERE source_format="csv" OR source_format="freetext"; +``` + +*Step 2:* purge all of your correlations (this will make the next steps much faster), for which you have two methods at your disposal: + - either go to your administration -> server settings -> MISP tab and set `MISP.completely_disable_correlation` to true + - via MYSQL run `TRUNCATE correlations;` + +*Step 3:* purge all of your feed data that have been pulled into multiple events. The easiest way of doing this: check which feeds are enabled (ignore misp source format feeds, they are not causing issues) and note down the IDs. Afterwards, use the CLI cleanup tool to remove all the feed events: + +`/var/www/MISP/app/Console/cake Admin purgeFeedEvents [user_id] [feed_id]` + +Execute this for each feed that you had enabled, replacing user_id with your admin user's ID and feed_id with the individual feed IDs on your list. + +*Step 4:* recorrelate your data, depending on which method you've used in *Step 2* you have two options: + - either go to your *Administration* -> *Server Settings...* -> *MISP...* tab and set `MISP.completely_disable_correlation` to *false* + - recorrelate your current data-set via the recorrelate attributes tool on `/pages/display/administration` + +### I have a long list of events that I want to delete via the API, do I really have to loop through each and issue a delete to /events/delete? + +No, the delete action also accepts a list of IDs when it comes to bulk event deletions. + +Simply POST your ID list to `/events/delete` in the following format: + +``` +{ + "id": [1,3,5,7,9] +} +``` + +### I can no longer log in. How do I reset the admin password? + +You can reset the password via the console. +See [Issue #1160](https://github.com/MISP/MISP/issues/1160) + +`/var/www/MISP/app/Console/cake Password [email] [password]` + +*** +## Usage questions ### How can I see all the deleted events in a MISP instance? -You can use the logging system for this, to see all deleted events, simply go to audit actions -> search logs and use the following parameters: +You can use the logging system for this, to see all deleted events, simply go to *Audit* -> *Search Logs* and use the following parameters: ~~~~ model: Event @@ -67,7 +371,7 @@ There are a plethora of issues that might arise when using SELinux when it comes First, please familiarize yourself with [the basics](https://opensource.com/article/18/7/sysadmin-guide-selinux) of SELinux. RedHat has a comprehensive [SELINUX USER'S AND ADMINISTRATOR'S GUIDE](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html-single/selinux_users_and_administrators_guide/index). -For file system permissions, refer to the [install guide](https://misp.github.io/MISP/INSTALL.rhel7/#5-set-file-permissions) first. +For file system permissions, refer to the [install guide](https://misp.github.io/MISP/INSTALL.rhel8/#5-set-file-permissions) first. Another way to see what SELinux might not be happy about is to use **ausearch**. This assumes Audit is enabled. @@ -131,7 +435,7 @@ To run sealert from the command-line, we need to point it to the SELinux audit l sudo sealert -a /var/log/audit/audit.log ``` -#### Clearing the audit logs +### Clearing the audit logs It is not recommended to clear the audit logs as they might contain information needed in the future for troubleshooting or security investigations. However, if that is not the case, just empty the audit log: @@ -156,6 +460,68 @@ This means that the main repository has an update available. If you want to play it safer or want to integrate it in your Weekly/Bi-Monthly update routine you can track our [Changelog](https://www.misp-project.org/Changelog.txt) a more up to date version is available [here](https://misp.github.io/MISP/Changelog/) +Further on we do regular tagged releases. (Approximately once per month.) +The releases happen either if a milestone has been hit for a certain feature/improvement/fix or for any security related matters. + +Thus you have the choice of either tracking 2.4 which is on a rolling release schedule, or track the tagged releases. + +### How to switch from tagged releases and back? + +This can be achieved with the following git commands: + +```bash +$ cd /var/www/MISP # aka. $PATH_TO_MISP +$ sudo -H -u www-data git checkout tags/$(git describe --tags `git rev-list --tags --max-count=1`) + +## OS Upgrades + +In theory all should "just work"(tm), but in practice the following dependencies might make your install unstable and need a little though before just doing the updates. + +* php/pear +* python +* apache +* init scheme/scripts +* mariadb/mysql +* redis +* git + +### PHP + +This is probably the most likely one that might get you into trouble. +The following happened on a Debian Testing lately. During the upgrade php got upgraded to php-7.3 and seemingly some php-7.2 dependencies were deinstalled and the system now had 2 concurrent versions of php installed. +The fix was to remove any *libapache2-mod-php7.2* packages and make sure that *apt remove libapache2-mod-php7.3* was installed. Most certainly you need to add symbolic links to */etc/apache2/mods-enabled* to make php7.3 work. +Then double check if all the php dependencies are install, refer to the install documents. + +The same for pear, where we mostly use 2 (bundled) packages: Console Command Line, Crypt GPG. +If you upgrade from a very old and out of date version of MISP this might raise issues. + +php.ini might also become problematic if you just erase the recommended defaults. + +### Python3 + +If you use python2 for MISP, please read the install docs about MISP being Python 3 only. +Currently Python3.6 is minimum. It is known working on 3.7 with some minor difficulties (see PyMISP issues). +The biggest issue is certainly with PyMISP doig unexpected things when python might be updated. +Using a virtualenv, whilst not always ideal for all setups, will at least make sure that problems are contained a little more. + +### Apache + +Mostly config issues might be a show stopper. And major version updates where some underlying config might need to be changed. + +### init/systemd + +MISP launches a couple of things on boot. Changing what handles boot behavious might have an impact. + +### MariaDB/MySQL/redis + +Similar to apache, most importantly always take good care that the DB engine is not all of a sudden changed without you noticing it. +From minor to major updates, rarely things might need to be adapted. + +### git + +Currently (as of v2.4.108) the git-cli command is used in MISP core. In very rare cases where the expected output changes, this might be an issue. +Included here more as an FYI then anything else. + ## Hardening ### How do I harden my MISP instance? @@ -177,7 +543,7 @@ Other related MISP Settings Optional MISP.maintenance_message Great things are happening! MISP is undergoing maintenance, but will return shortly. You can contact the administration at $email or call CIRCL. The message that users will see if the instance is not live. -Critical MISP.live true Unless set to true, the instance will only be accessible by site admins. +Critical MISP.live true Unless set to true, the instance will only be accessible by site-admins. ## Update MISP fails @@ -312,9 +678,9 @@ Now, I only have Org Admin. You have several options: -1. Delete the org admin. MISP automatically creates a new default site admin user if no users are found in the db (mysql: truncate users;) +1. Delete the org admin. MISP automatically creates a new default site-admin user if no users are found in the db (mysql: truncate users;) -2. Upgrade a user to a site admin, such as an org admin user: +2. Upgrade a user to a site-admin, such as an org admin user: ``` SELECT id, email from users; ``` @@ -536,6 +902,120 @@ Created symlink from /etc/systemd/system/multi-user.target.wants/php73-php-fpm.s A galaxy can be assigned like a tag. You can use the add tag function and copy the full conntector-tag. Example `misp-galaxy:ransomware=“Locky”`, which can be found in `/galaxy_clusters/view/` +## Updating PHP from 7.2 to 7.4.5 on Ubuntu 18.04 + +### Installation + +1. Disable and Uninstall Currently Installed SSDEEP +```bash +sudo phpdismod ssdeep +sudo pecl uninstall ssdeep +sudo apt purge ssdeep +sudo rm -rf /etc/php/7.2/mods-available/ssdeep.ini +``` + +2. Install PHP 7.4.5 +```bash +sudo apt install software-properties-common -qy +sudo add-apt-repository ppa:ondrej/php -y +sudo apt update +sudo apt install -qy \ + libapache2-mod-php7.4 \ + php7.4 \ + php7.4-cli \ + php7.4-dev \ + php7.4-json \ + php7.4-xml \ + php7.4-mysql \ + php7.4-opcache \ + php7.4-readline \ + php7.4-mbstring \ + php-redis \ + php-gnupg \ + php-gd +sudo apt update +sudo apt upgrade -y +``` + +3. Install SSDEEP +```bash +cd /usr/local/src +sudo rm -rf ssdeep-2.14.1.tar.gz ssdeep-2.14.1 +sudo wget https://github.com/ssdeep-project/ssdeep/releases/download/release-2.14.1/ssdeep-2.14.1.tar.gz +sudo tar zxvf ssdeep-2.14.1.tar.gz +cd ssdeep-2.14.1 +sudo ./configure --datadir=/usr --prefix=/usr --localstatedir=/var --sysconfdir=/etc +sudo make +sudo make install +``` + +4. Test SSDEEP +```bash +ssdeep -h +``` + +5. Install ssdeep_php +```bash + sudo pecl channel-update pecl.php.net + sudo pecl install ssdeep +``` + +6. Enable SSDEEP in both 7.2 and 7.4 (** as root** `sudo su`) +```bash +echo 'extension=ssdeep.so' > /etc/php/7.2/mods-available/ssdeep.ini +echo 'extension=ssdeep.so' > /etc/php/7.4/mods-available/ssdeep.ini +``` + +7. Enable SSDEEP PHP Mod +```bash +sudo phpenmod ssdeep +``` + +8. Set PHP 7.4.5 to default PHP +```bash +sudo a2dismod php7.2 +sudo a2enmod php7.4 +sudo update-alternatives --set php /usr/bin/php7.4 +``` + +9. [Optional] Set better values for defaults +```bash +sudo sed -i "s/max_execution_time = 30/max_execution_time = 300/" /etc/php/7.4/apache2/php.ini ; \ +sudo sed -i "s/memory_limit = 128M/memory_limit = 2048M/" /etc/php/7.4/apache2/php.ini ; \ +sudo sed -i "s/upload_max_filesize = 2M/upload_max_filesize = 500M/" /etc/php/7.4/apache2/php.ini ; \ +sudo sed -i "s/post_max_size = 8M/post_max_size = 500M/" /etc/php/7.4/apache2/php.ini ; \ +sudo sed -i "s/max_execution_time = 30/max_execution_time = 300/" /etc/php/7.4/cli/php.ini ; \ +sudo sed -i "s/upload_max_filesize = 2M/upload_max_filesize = 500M/" /etc/php/7.4/cli/php.ini ; \ +sudo sed -i "s/post_max_size = 8M/post_max_size = 5000M/" /etc/php/7.4/cli/php.ini ; +``` + +10. Restart Apache to implement changes +```bash +sudo sudo systemctl restart apache2 +``` + +### Verification of php 7.2 to 7.4 + +1. **Administration** > **Server Settings & Maintenance** + +2. **Diagnostics** + +3. Scroll down to the **PHP Settings** section and verify + + +### What are the required steps after a MISP installation to have a properly running instance? + +- First login with the installation credentials and change the password immediatly (especially if your instance is publicly accessible) +- Set the base_url to the hostname of your machine (apache virtualhost name) +- Create a new organisation which will be the host organisation running the MISP instance +- Set the new organisation in `MISP.host_org_id` to replace the default one +- Set messages like `MISP.footermidleft` and alike to a proper message to help your users +- Create a new user as `admin` role with the new organisation +- Log with the new user, if successful, remove the default user used during the installation such as `admin@admin.test` +- Select and enable required taxonomies for your sharing community +- Select and enable the external feeds (as caching only if you don't want full events but you can get the full feeds too) +- Select and enable the warning-list (if you don't know what to enable, select all) +- Add the remote MISP instances where you have access to (either caching only or full pull if you want the complete events)