Merge branch 'master' of github.com:MISP/misp-book

USAGE.md

@@ -41,7 +41,7 @@ found 368 vulnerabilities (48 low, 250 moderate, 62 high, 8 critical)
 ```
 
 
-Tested on: *Ubuntu 18.04 LTS* *Debian 9.5/sid/testing*
+Tested on: *Ubuntu 18.04/20.04 LTS* *Debian 10.5/sid/testing*
 [Terminal Recording of npm install lines on Ubuntu 18.04](https://asciinema.org/a/84JZMuGu2QlFH59q6mK8jbdQS)
 
 ```bash

appendices/README.md

@@ -309,3 +309,81 @@ 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. 
+
+#### Installation and configuration
+
+1. Install `mod_ldap` PHP module
+    ```bash
+    # for Centos or RHEL
+    yum install rh-php72-php-ldap
+    # for Ubuntu or debian
+    apt install php-ldap
+    ```
+2. Prepare variables for configuration
+
+* `{{ LDAP_SERVER }}` – a full LDAP URI of server. For example: `ldap://example.com`.
+* `{{ LDAP_BASE_DN }}` – DN for path that contains users. For example: `cn=users,cn=accounts,dc=example,dc=com`.
+* `{{ LDAP_BIND_DN }}` – user that can read. For example: `uid=misp,cn=sysaccounts,cn=etc,dc=example,dc=com`.
+* `{{ LDAP_BIND_PASSWORD }}` – password for that user.
+* `{{ LDAP_USER_GROUP }}` – group with access to MISP. For example: `cn=misp-users,cn=groups,cn=accounts,dc=example,dc=com`.
+   
+3. Configure MISP ApacheSecureAuth in `app/Config/config.php`
+
+    ```php
+    'LdapAuth' => array(
+      'enabled' => true,
+      'name' => 'My Identity provider',
+      'ldapServer' => '{{ LDAP_SERVER }}',
+      'ldapDN' => '{{ LDAP_BASE_DN }}',
+      'ldapSearchFilter' => '(objectclass=inetuser)',
+      'ldapReaderUser' => '{{ LDAP_BIND_DN }}',
+      'ldapReaderPassword' => '{{ LDAP_BIND_PASSWORD }}',
+      'ldapUserGroup' => '{{ LDAP_USER_GROUP }}',
+      'updateUser' => true,
+    );
+    ```
+
+Required variables:
+
+* `enabled` – if it is true, all users must log in through LDAP account.
+* `ldapServer` – a full LDAP URI of the form ldap://hostname:port or ldaps://hostname:port for TLS encryption.
+* `ldapDN` – DN for a path that contains users.
+
+Optional variables:
+
+* `name` – identity provider name. Will be shown in the login screen and user editing for. Can contain HTML.
+* `ldapReaderUser` – DN or RDN LDAP user with permission to read LDAP information about users.
+* `ldapReaderPassword` – password for that user.
+* `ldapSearchFilter` - LDAP search filter.
+* `ldapSearchAttribute` - LDAP attribute that contains username. Default: `uid`.
+* `ldapEmailField` - LDAP attribute (string) or attributes (array) that will be checked if contains user e-mail address. If you want to change or add field, you should also add that field/fields to `ldapAttributes`. Default: `mail`.
+* `ldapAttributes` – fields that will be fetched from LDAP server. Default: `mail` and `memberof`.
+* `ldapUserGroup` - LDAP group that must be assigned to user to access MISP. Default: not set.
+* `createUser` - if `true`, MISP will create new user from LDAP. Default `true`.
+* `updateUser` - if `true`, MISP will update existing users information (e-mail address and role) from LDAP after login. Default: `false`.
+* `ldapDefaultOrg` – default organization ID for user from LDAP. By default it is the first organization in the database.
+* `ldapDefaultRoleId` - default role for newly created user. It can be integer or array when key contains LDAP group and value assigned role ID. Must be defined if `updateUser` is set to `true` (without that variable, user will be disabled).
+* `ldapProtocol` - protocol version used. Default: 3.
+* `ldapNetworkTimeout` - timeout for communication with LDAP server in seconds. Default: 5 seconds.
+* `ldapAllowReferrals` - follow referrals returned by the LDAP server. Default: `false`.
+* `ldapStartTls` - enable STARTTLS. Default: `true`.
+
+#### Debugging
+
+Setting LDAP authentication can be sometimes tricky. For debugging, you can check MISP error log (by default in `/var/www/MISP/app/tmp/logs/error.log`) or debug log (by default in `/var/www/MISP/app/tmp/logs/debug.log`) that can contain useful information with problem description.
+
+#### Migrating existing user to LDAP
+
+Because LDAP and MISP users are paired by e-mail address, it is possible to migrate existing user account to LDAP managed. When you enable LDAP support and LDAP user will try to log in, an existing user in MISP with the same e-mail address will be found and then assigned to LDAP user.
+
+#### Caveats
+
+* When a user is disabled in LDAP or is removed from the required group, it will be not automatically disabled in MISP. That means that user will be disabled when he tries to login (with form or with Auth key), but for example, notification e-mails will still work until he tries to log in.
+* 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.

faq/README.md

@@ -25,6 +25,14 @@ We recommend a standard LAMP stack on top of Ubuntu >18.04 LTS. For details on t
 
 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)
 
+
+### How to monitor MISP?
+
+Currently there are 2 documented ways to monitor MISP.
+
+Either with [MUNIN](http://munin-monitoring.org/) -> [misp-monitor](https://github.com/SteveClement/misp-monitor) for instructions.
+Or [OpenNMS](https://www.opennms.com/) -> [Instructions here](https://www.misp-project.org/2020/08/18/MISP-Monitoring-with-OpenNMS.html) 
+
 ***
 ## Specific questions
 ### Can I configure MISP encrypted notification emails to contain more information in the subject?

general-concepts/README.md

@@ -30,7 +30,6 @@ A user of a role that grants sync permissions, these users (and their authentica
 ### Synchronisation
 What we call synchronisation is an exchange of data between two (or more) MISP instances through our pull and push mechanisms.
 ### Tagging
-Users with tagging rights can assigned various dynamically created tags to events, allowing an arbitrary link between events to be created. It is possible to filter events based on these tags and they can also be used to filter events for the automation.
+Users with tagging rights can assign various dynamically created tags to events, allowing an arbitrary link between events to be created. It is possible to filter events based on these tags and they can also be used to filter events for the automation.
 ### Templating
 Users with templating rights can create easy to fill forms that help with the event creation process.
-

quick-start/README.md

@@ -3,6 +3,7 @@ And Justice for All! -->
 
 # Quick Start
 
+![A Logo :)_](figures/logo.png)
 MISP (Open Source Threat Intelligence and Sharing Platform) software facilitates the exchange and sharing of threat intelligence, Indicators of Compromise (IoCs) about targeted malware and attacks, financial fraud or any intelligence within your community of trusted members. MISP sharing is a distributed model containing technical and non-technical information which can be shared within closed, semi-private or open communities. Exchanging such information should result in faster detection of targeted attacks and improve the detection ratio, whilst also reducing the number of false positives.
 
 With the focus on automation and standards, MISP provides you with a powerful ReST API, extensibility (via misp-modules) or additional libraries such as PyMISP, jump ahead to these chapters to get started.

styles/website.css

@@ -1 +1,5 @@
 // Place holder, in case custom css for the HTML is needed
+
+.image-wrapper.quick-start-README {
+    clear: right;
+}

using-the-system/README.md

@@ -7,7 +7,7 @@
 The process of entering an event can be split into 3 phases, the creation of the event itself, populating it with attributes
 and attachments and finally publishing it.
 
-During this first step, you will be create a basic event without any actual attributes, but storing general information such as a description, time and risk level of the incident. To start creating the event, click on the New Event button on the left and fill out the form you are presented with. The following fields need to be filled out:
+During this first step, you will create a basic event without any actual attributes, but storing general information such as a description, time and risk level of the incident. To start creating the event, click on the New Event button on the left and fill out the form you are presented with. The following fields need to be filled out:
 
 ![Fill this form out to create a skeleton event, before proceeding to populate it with attributes and attachments.](figures/add_event.png)
 
@@ -328,7 +328,7 @@ The last option is a checkbox that restricts all of the results to attributes th
 ## Updating and modifying events and attributes
 
 Every event and attribute can easily be edited. First of all it is important to find the event or attribute that is to be edited, using any of the methods mentioned in the section on [browsing past events](#browsing_events).
-Once it is found, the edit button (whether it be under actions when events/attributes get listed or simply on the event view) will bring up the same screen as what is used to create the entry of the same type (for an event it would be the event screen as [seen here](#Creating an event), for an attribute the attribute screen as [described here](#add-attributes-to-the-event)). You can also simply double-click on the event you wish to edit and enter the edit mode. 
+Once it is found, the edit button (whether it be under actions when events/attributes get listed or simply on the event view) will bring up the same screen as what is used to create the entry of the same type (for an event it would be the event screen as [seen here](#Creating an event), for an attribute the attribute screen as [described here](#add-attributes-to-the-event)). You can also simply double-click on the event you wish to edit and enter the edit mode.
 Keep in mind that editing any event (either directly or indirectly through an attribute) will unpublish it, meaning that you'll have to publish it (through the event view) again once you are done.
 
 ## Tagging