[api/frontend/doc] Enhance the doc and fix bugs (#442, #452, #413)

* Sanitize
* [documentation] Enhance the documentation
* Fix some bugs

opencti-documentation/docs/development/installation.md

@@ -6,12 +6,17 @@ sidebar_label: Development environment
 
 ## Prerequisites
 
-- Docker
-- Node.JS (>= 12.* < 13.0.0)
-- Python (>= 3)
-- Yarn (>= 1.16)
+| Component     | Version               | Link                                                      |
+| ------------- |-----------------------| ----------------------------------------------------------|
+| Docker        | `>= 19.*`             | https://docs.docker.com/install                           |
+| NodeJS        | `>= 12.* && < 13.0.0` | https://nodejs.org/en/download                            |
+| Yarn          | `>= 1.16`             | https://yarnpkg.com/getting-started/install               |
+| Python        | `>= 3.6`              | https://www.python.org/downloads                          |
 
-### Installation of dependencies (Ubuntu 18.04)
+
+### Installation of dependencies (Ubuntu 19.10)
+
+If you are on a version of Debian/Ubuntu prior to 19.04, please refer to this [GIthub issue](https://github.com/OpenCTI-Platform/opencti/issues/413).
 
 ```bash
 $ sudo apt-get install nodejs python3 python3-pip

opencti-documentation/docs/installation/docker.md

@@ -29,10 +29,10 @@ And change the variable `OPENCTI_TOKEN` (for the `worker` and all connectors) ac
 - OPENCTI_TOKEN=ChangeMe
 ```
 
-As OpenCTI has a dependency to ElasticSearch, you have to set the `vm.max_map_count` before running the containers, as mentioned in the [ElasticSearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html#docker-cli-run-prod-mode).
+As OpenCTI has a dependency to ElasticSearch and Grakn, you have to set the `vm.max_map_count` before running the containers, as mentioned in the [ElasticSearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html#docker-cli-run-prod-mode).
 
 ```bash
-$ sysctl -w vm.max_map_count=262144 
+$ sysctl -w vm.max_map_count=1048575
 ```
 
 ## Run

opencti-documentation/docs/installation/maintenance.md

@@ -0,0 +1,11 @@
+---
+id: maintenance
+title: Maintenance
+sidebar_label: Maintenance
+---
+
+## Reindexing ElasticSearch from Grakn
+
+```bash
+$ yarn index
+```

opencti-documentation/website/sidebars.json

@@ -9,6 +9,7 @@
       "installation/docker",
       "installation/manual",
       "installation/connectors",
+      "installation/maintenance",
       "development/installation"
     ],
     "Usage": [

opencti-documentation/website/siteConfig.js

@@ -104,6 +104,9 @@ const siteConfig = {
 
   // Sidebars
   docsSideNavCollapsible: true,
+
+  // Edit URL
+  editURL: 'https://github.com/OpenCTI-Platform/opencti/tree/master/opencti-documentation/docs/'
 };
 
 module.exports = siteConfig;

opencti-documentation/website/versioned_docs/version-2.1.3/development/installation.md

@@ -0,0 +1,143 @@
+---
+id: version-2.1.3-installation
+title: Development environment installation
+sidebar_label: Development environment
+original_id: installation
+---
+
+## Prerequisites
+
+| Component     | Version               | Link                                                      |
+| ------------- |-----------------------| ----------------------------------------------------------|
+| Docker        | `>= 19.*`             | https://docs.docker.com/install                           |
+| NodeJS        | `>= 12.* && < 13.0.0` | https://nodejs.org/en/download                            |
+| Yarn          | `>= 1.16`             | https://yarnpkg.com/getting-started/install               |
+| Python        | `>= 3.6`              | https://www.python.org/downloads                          |
+
+
+### Installation of dependencies (Ubuntu 19.10)
+
+If you are on a version of Debian/Ubuntu prior to 19.04, please refer to this [GIthub issue](https://github.com/OpenCTI-Platform/opencti/issues/413).
+
+```bash
+$ sudo apt-get install nodejs python3 python3-pip
+$ sudo curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
+$ sudo echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
+$ sudo apt-get update && sudo apt-get install yarn
+```
+
+### Docker stack
+
+As OpenCTI has a dependency to ElasticSearch, you have to set the *vm.max_map_count* before running the containers, as mentioned in the [ElasticSearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html#docker-cli-run-prod-mode).
+
+```bash
+$ sysctl -w vm.max_map_count=262144
+```
+
+Clone the latest version of the dev docker compose and start
+
+```bash
+$ git clone https://github.com/OpenCTI-Platform/docker.git
+$ cd docker
+$ docker-compose -f ./docker-compose-dev.yml up -d
+```
+
+## Clone the project
+
+```bash
+$ git clone https://github.com/OpenCTI-Platform/opencti.git
+$ cd opencti
+```
+
+## Application dependencies
+
+### Install the API dependencies
+
+```bash
+$ cd opencti-platform/opencti-graphql
+$ yarn install
+```
+
+### Install the frontend dependencies
+```bash
+$ cd ../opencti-front
+$ yarn install
+```
+
+### Install the worker dependencies
+
+```bash
+$ cd ../../opencti-worker/src
+$ pip3 install -r requirements.txt
+```
+
+## Config and run
+
+### GraphQL API
+
+#### Configure
+
+```bash
+$ cd ../../opencti-platform/opencti-graphql
+$ cp config/default.json config/development.json
+```
+By default the configuration match the docker stack configuration.
+You just need to change the user part:
+```bash
+"admin": {
+  "email": "admin@opencti.io",
+  "password": "ChangeMe",
+  "token": "ChangeMe"
+}
+```
+
+#### Start
+
+```bash
+$ cd opencti-graphql
+$ yarn start
+```
+
+The first execution will create and migrate the schema.
+
+### Worker
+
+#### Configure
+
+```bash
+$ cd opencti-worker
+$ cp config.yml.sample config.yml
+```
+Change the *config.yml* file according to your <admin token>
+
+#### Start
+
+```bash
+$ python3 worker.py &
+```
+
+### Frontend
+
+#### Start
+
+```bash
+$ cd opencti-frontend
+$ yarn start
+```
+
+## Build for production use
+
+### Build the application
+
+```bash
+$ cd opencti-frontend
+$ yarn build
+$ cd ../opencti-graphql
+$ yarn build
+```
+
+### Start the production package
+
+```bash
+$ yarn serv
+```

opencti-documentation/website/versioned_docs/version-2.1.3/getting-started/achitecture.md

@@ -0,0 +1,31 @@
+---
+id: version-2.1.3-architecture
+title: Architecture of the application
+sidebar_label: Architecture
+original_id: architecture
+---
+
+The OpenCTI platform relies on several external databases and services in order to work. 
+
+![Architecture](assets/getting-started/architecture.png "Architecture")
+
+## The GraphQL API
+
+The API is the central part of the OpenCTI platorm, allowing the *clients* (including the *frontend*) to interact with the *databases* and the *brokers*. Built in NodeJS, it implements the [GraphQL](https://graphql.org/) query language. As the API has not a full documentation for the moment, you can explore the available methods and parameters through a GraphQL playground. An example is available on the [demonstration instance](https://demo.opencti.io/graphql).
+
+## The write workers
+
+The workers are standalone Python processes that just consume messages from the RabbitMQ broker in order to do asynchroneous write queries. You can launch as many workers as you need to increase the write performances.
+
+> Since `Grakn 1.6.1`, there is no more race conditions on duplicate keys, so we strongly advise you to launch more than one worker.
+
+## The connectors
+
+The connectors are third-party softwares (Python processes) that can play 4 different roles on the platform:
+
+| Type                    | Description                                                                                  | Examples                                                                      | 
+| ----------------------- |----------------------------------------------------------------------------------------------| ------------------------------------------------------------------------------|
+| `EXTERNAL_IMPORT`       | Pull data from remote sources, convert it to STIX2 and insert it on the OpenCTI platform.    | MITRE, MISP, CVE, AlienVault, FireEye, etc.                                   |
+| `INTERNAL_IMPORT_FILE`  | Extract data from files uploaded on OpenCTI trough the UI or the API.                        | Extract indicators from PDFs, STIX2 import, etc.                              |
+| `INTERNAL_ENRICHMENT`   | Listen for new OpenCTI entities or users requests, pull data from remote sources to enrich.  | Enrichment of observables though external servies, entities updates, etc.     |
+| `INTERNAL_EXPORT_FILE`  | Generate export from OpenCTI data, based on listing entities or one entity and its relations.| STIX2 export, PDF export, CSV list generation, etc.                           |

opencti-documentation/website/versioned_docs/version-2.1.3/installation/docker.md

@@ -0,0 +1,133 @@
+---
+id: version-2.1.3-docker
+title: Docker installation
+sidebar_label: Using Docker
+original_id: docker
+---
+
+OpenCTI could be deployed using the *docker-compose* command.
+
+## Clone the repository
+
+```bash
+$ mkdir /path/to/your/app && cd /path/to/your/app
+$ git clone https://github.com/OpenCTI-Platform/docker.git
+$ cd docker
+```
+
+### Configure the environment
+
+Before running the docker-compose command, please change the admin token (this token must be a [valid UUID](https://www.uuidgenerator.net/)) and password of the application in the file `docker-compose.yml`:
+
+```yaml
+- APP__ADMIN__PASSWORD=ChangeMe
+- APP__ADMIN__TOKEN=ChangeMe
+```
+
+And change the variable `OPENCTI_TOKEN` (for the `worker` and all connectors) according to the value of `APP__ADMIN__TOKEN`
+
+```yaml
+- OPENCTI_TOKEN=ChangeMe
+```
+
+As OpenCTI has a dependency to ElasticSearch and Grakn, you have to set the `vm.max_map_count` before running the containers, as mentioned in the [ElasticSearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html#docker-cli-run-prod-mode).
+
+```bash
+$ sysctl -w vm.max_map_count=1048575
+```
+
+## Run
+
+In order to have the best experience with Docker, we recommend to use the Docker stack feature. In this mode we will have the capacity to easily scale your deployment.
+
+### In Swarm or Kubernetes
+
+```bash
+$ docker stack deploy -c docker-compose.yml opencti
+```
+
+### In standard Docker
+```bash
+$ docker-compose --compatibility up
+```
+
+You can now go to http://localhost:8080 and log in with the credentials configured in your environment variables.
+
+### Behind a reverse proxy
+
+If you want to use OpenCTI behind a reverse proxy with a context path, like `https://myproxy.com/opencti`, please change the base_path configuration.
+
+```yaml
+- APP__BASE_PATH=/opencti
+```
+By default OpenCTI use Websockets so dont forget to configure your proxy for this usage.
+
+
+## Data persistence
+
+If you wish your OpenCTI data to be persistent in production, you should be aware of the  `volumes` section for `Grakn`, `ElasticSearch` and `MinIO` services in the `docker-compose.yml`.
+
+Here is an example of volumes configuration:
+
+```yaml
+volumes:
+  grakndata:
+    driver: local
+    driver_opts:
+      o: bind
+      type: none
+  esdata:
+    driver: local
+    driver_opts:
+      o: bind
+      type: none
+  s3data:
+    driver: local
+    driver_opts:
+      o: bind
+      type: none      
+```
+
+## Memory configuration
+
+OpenCTI default `docker-compose.yml` file does not provide any specific memory configuration. But if you want to adapt some dependencies configuration, you can find some links below.
+
+### OpenCTI - Platform
+
+OpenCTI platform is based on a NodeJS runtime, with a memory limit of **512MB by default**. We do not provide any option to change this limit today. If you encounter any `OutOfMemory` exception, please open a [Github issue](https://github.com/OpenCTI-Platform/opencti/issues/new?assignees=&labels=&template=bug_report.md&title=).
+
+### OpenCTI - Workers and connectors
+
+OpenCTI workers and connectors are Python processes. If you want to limit the memory of the process we recommend to directly use Docker to do that. You can find more information in the [official Docker documentation](https://docs.docker.com/compose/compose-file/). 
+
+> If you do not use Docker stack, think about `--compatibility` option.
+
+### Grakn 
+
+Grakn is a JAVA process that rely on Cassandra (also a JAVA process). In order to setup the JAVA memory allocation, you can use the environment variable `SERVER_JAVAOPTS` and `STORAGE_JAVAOPTS`. 
+
+> The current recommendation is `-Xms4G` for both options.
+
+You can find more information in the [official Grakn documentation](https://dev.grakn.ai/docs).
+
+### ElasticSearch
+
+ElasticSearch is also a JAVA process. In order to setup the JAVA memory allocation, you can use the environment variable `ES_JAVA_OPTS`. 
+
+> The minimal recommended option today is `-Xms512M -Xmx512M`.
+
+You can find more information in the [official ElasticSearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html).
+
+### Redis
+
+Redis has a very small footprint and only provides an option to limit the maximum amount of memory that can be used by the process. You can use the option `--maxmemory` to limit the usage. 
+
+You can find more information in the [Redis docker hub](https://hub.docker.com/r/bitnami/redis/).
+
+### MinIO
+
+MinIO is a small process and does not require a high amount of memory. More information are available for Linux here on the [Kernel tuning guide](https://github.com/minio/minio/tree/master/docs/deployment/kernel-tuning).
+
+### RabbitMQ
+
+The RabbitMQ memory configuration can be find in the [RabbitMQ official documentation](https://www.rabbitmq.com/memory.html). Basically RabbitMQ will consumed memory until a specific threshold. So it should be configure along with the Docker memory limitation.

opencti-documentation/website/versioned_docs/version-2.1.3/installation/maintenance.md

@@ -0,0 +1,12 @@
+---
+id: version-2.1.3-maintenance
+title: Maintenance
+sidebar_label: Maintenance
+original_id: maintenance
+---
+
+## Reindexing ElasticSearch from Grakn
+
+```bash
+$ yarn index
+```