Merge pull request #100 from SteveClement/master

Minor formatting updates and some clarifications. misp-book generation overhaul

USAGE

@@ -1,28 +0,0 @@
-
-Install notes
-=============
-
-~~~
-npm install gitbook
-sudo npm install gitbook-cli -g
-npm install gitbook-plugin-autocover
-npm install gitbook-plugin-github
-npm install gitbook-plugin-toc
-npm install gitbook-plugin-anchors
-gitbook install
-~~~
-
-Usage
-=====
-
-If you want to generate the PDF output (you need to have Calibre installed):
-
-~~~
-gitbook pdf
-~~~
-
-and if you want to want to serve the HTML pages on 127.0.0.1:4000:
-
-~~~
-gitbook serve
-~~~

USAGE.md

@@ -0,0 +1,125 @@
+
+Install notes
+=============
+
+:warning: Make sure to be in the *misp-book* repository directory for the *npm magic*.
+Also: The *npm* plugin *autocover* is broken. It pulls an incompatible *canvas* module version. Thus patched repository used (forked from original)
+
+Tested on: *Ubuntu 16.04.4 LTS*
+
+```bash
+curl -sL https://deb.nodesource.com/setup_9.x | sudo -E bash -
+sudo apt-get install -y nodejs
+sudo apt-get install -y build-essential
+sudo apt install -y npm pkg-config libcairo2-dev
+npm install gitbook git+https://github.com/SteveClement/plugin-autocover.git gitbook-plugin-github gitbook-plugin-toc gitbook-plugin-anchors
+sudo npm install gitbook-cli -g
+gitbook install
+```
+
+Usage
+=====
+
+If you want to generate the PDF output (you need to have Calibre installed):
+
+```bash
+$ time gitbook pdf
+info: 13 plugins are installed
+info: 12 explicitly listed
+info: loading plugin "autocover"... OK
+info: loading plugin "github"... OK
+info: loading plugin "toc"... OK
+info: loading plugin "anchors"... OK
+info: loading plugin "alerts"... OK
+info: loading plugin "advanced-emoji"... OK
+info: loading plugin "highlight"... OK
+info: loading plugin "search"... OK
+info: loading plugin "lunr"... OK
+info: loading plugin "sharing"... OK
+info: loading plugin "fontsettings"... OK
+info: loading plugin "theme-default"... OK
+info: found 23 pages
+info: found 201 asset files
+warn: "options" property is deprecated, use config.get(key) instead
+info: >> generation finished with success in 58.8s !
+info: >> 1 file(s) generated
+gitbook pdf  47.51s user 2.51s system 81% cpu 1:01.21 total
+```
+
+on macOS (ebook-convert is not in path):
+
+```bash
+$ PATH=$PATH:/Applications/calibre.app/Contents/MacOS/ ; gitbook pdf
+```
+
+and if you want to want to serve the HTML pages on 127.0.0.1:4000:
+
+```bash
+$ time gitbook serve
+Live reload server started on port: 35729
+Press CTRL+C to quit ...
+
+info: 13 plugins are installed
+info: loading plugin "autocover"... OK
+info: loading plugin "github"... OK
+info: loading plugin "toc"... OK
+info: loading plugin "anchors"... OK
+info: loading plugin "alerts"... OK
+info: loading plugin "advanced-emoji"... OK
+info: loading plugin "livereload"... OK
+info: loading plugin "highlight"... OK
+info: loading plugin "search"... OK
+info: loading plugin "lunr"... OK
+info: loading plugin "sharing"... OK
+info: loading plugin "fontsettings"... OK
+info: loading plugin "theme-default"... OK
+info: found 23 pages
+info: found 201 asset files
+warn: "options" property is deprecated, use config.get(key) instead
+info: >> generation finished with success in 42.1s !
+
+Starting server ...
+Serving book on http://localhost:4000
+^C
+gitbook serve  37.61s user 3.75s system 52% cpu 1:19.15 total
+```
+
+:warning: It can take up to 60 seconds for the entire *misp-book* to be generated before the content is available on port 4000. Please be patient ;)
+
+
+macOS Notes
+===========
+
+canvas needs to be compiled and needs the following dependencies:
+
+```
+xcode-select --install
+# If you have homebrew not installed yet:
+## /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+# For the more adventureous you can install a cask of calibre which gives you access to *ebook-convert*
+## brew cask install calibre
+brew install pkg-config cairo pango libpng jpeg giflib
+```
+
+:warning: Make sure to be in the *misp-book* repository directory for the npm magic.
+
+Installing gitbook and all dependencies wants to look like this (Tested on *macOS 11.13.3*):
+
+```bash
+npm install gitbook git+https://github.com/SteveClement/plugin-autocover.git gitbook-plugin-github gitbook-plugin-toc gitbook-plugin-anchors
+npm install gitbook-cli -g
+gitbook install
+```
+
+npm salvage
+===========
+
+In case something with npm breaks, this brings you back to a sane default.
+We still assume we are in the *misp-book* repository working directory.
+
+```bash
+rm -rf node_modules
+rm package-lock.json
+rm -rf ~/.gitbook
+sudo rm -rf /usr/local/lib/node_modules/gitbook-cli
+```

book-convention/README.md

@@ -1,7 +1,12 @@
+---
+description: Convention Used in MISP-Book
+---
+
 # Convention Used in This Book
 
 `code block or value`
-  - Used for variable, function or menu names in MISP.
+
+* Used for variable, function or menu names in MISP.
 
 ## Example Organisations
 
@@ -11,9 +16,10 @@ A set of users and organisations are used in the different examples.
 
 The following two organisations are regularly used as example:
 
-- Setec Astronomy with UUID `58d38339-7b24-4386-b4b4-4c0f950d210f`
+* Setec Astronomy with UUID `58d38339-7b24-4386-b4b4-4c0f950d210f`
-- Acme Finance with UUID `58d38326-eda8-443a-9fa8-4e12950d210f`
+* Acme Finance with UUID `58d38326-eda8-443a-9fa8-4e12950d210f`
 
-Starting from MISP 2.4.71, the example organisations with the above mentioned UUID are black-listed to avoid
+Starting from MISP 2.4.71, the example organisations with the above mentioned UUID are **black-listed** to avoid  
-large distribution of sample events while testing a MISP instance. If you want to test your distribution, the
+large distribution of sample events while testing a MISP instance. If you want to test your distribution, the  
 sample organisation black-listing can be removed in `Administration` under `Manage Org Blacklists`.
+

quick-start/README.md

@@ -3,7 +3,7 @@ And Justice for All! -->
 
 # Quick Start
 The Malware Information Sharing Platform (MISP) tool facilitates the exchange of Indicators of Compromise (IOCs) about targeted malware and attacks, within your community of trusted members. MISP is a distributed IOC database containing technical and non-technical information. 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 API via PyMISP, jump ahead to these chapters to get started.
 
 ## Create an Event
 
@@ -13,8 +13,7 @@ You only have to add a few pieces of information to register your Event. Further
 
 ## Describe Event
 
-
+Red is totally normal. No worries. (In future releases this will potentially change to a more harmonious color)
-Red is totally normal. No worries.
 
 ![Describe Event](figures/AddEventOK.jpg)