Installation

Requirements

The project leverages docker-compose with a custom python script so you need to have the following packages installed in your machine:

  • docker - v1.13.0+

  • docker-compose - v1.23.2+

  • python - v3.6+

  • There are additional python dependencies (mentioned in the requirements/pre-requirements.txt file) that can be installed using the initialize.sh script.

In some systems you could find pre-installed older versions. Please check this and install a supported version before attempting the installation. Otherwise it would fail.

Note

  • The project uses public docker images that are available on Docker Hub
  • IntelOwl is tested and supported to work in a Linux-based OS. It may also run on windows, but that is not officially supported yet.
  • Before installing remember that you must comply with the LICENSE and the Legal Terms

TL;DR

Obviously we strongly suggest reading through all the page to configure IntelOwl in the most appropriate way.

However, if you feel lazy, you could just install and test IntelOwl with the following steps. Be sure to run docker and python commands with sudo if permissions/roles have not been set

Note: We’ve added a new script initialize.sh that will check compatibility with your system and attempt to install the required dependencies.

# clone the IntelOwl project repository
git clone https://github.com/intelowlproject/IntelOwl
cd IntelOwl/

# construct environment files from templates
cd docker/
cp env_file_app_template env_file_app
cp env_file_postgres_template env_file_postgres
cp env_file_integrations_template env_file_integrations

# verify installed dependencies
cd ..
./initialize.sh

# start the app
python3 start.py prod up

# now the application is running on http://localhost:80
# create a super user 
docker exec -ti intelowl_uwsgi python3 manage.py createsuperuser

# now you can login with the created user form http://localhost:80

# Have fun!

Hint

There is a YouTube video that may help in the installation process. (ManySteps have changed since v2.0.0)

Deployment Components

IntelOwl is composed of various different technologies, namely:

  • React: Frontend, using CRA and certego-ui

  • Django: Backend

  • PostgreSQL: Database

  • Rabbit-MQ: Message Broker

  • Celery: Task Queue

  • Nginx: Reverse proxy for the Django API and web asssets.

  • Uwsgi: Application Server

  • Elastic Search (optional): Auto-sync indexing of analysis’ results.

  • Kibana (optional): GUI for Elastic Search. We provide a saved configuration with dashboards and visualizations.

  • Flower (optional): Celery Management Web Interface

All these components are managed via docker-compose.

Deployment Preparation

Open a terminal and execute below commands to construct new environment files from provided templates.

cd docker/
cp env_file_app_template env_file_app
cp env_file_postgres_template env_file_postgres
cp env_file_integrations_template env_file_integrations
cd ..
./initialize.sh

Environment configuration (required)

In the env_file_app, configure different variables as explained below.

REQUIRED variables to run the image:

  • DB_HOST, DB_PORT, DB_USER, DB_PASSWORD: PostgreSQL configuration (The DB credentals should match the ones in the env_file_postgres).

Strongly recommended variable to set:

  • DJANGO_SECRET: random 50 chars key, must be unique. If you do not provide one, Intel Owl will automatically set a new secret on every run.

  • INTELOWL_WEB_CLIENT_DOMAIN (example: localhost/mywebsite.com): the web domain of your instance, this is used for generating links to analysis results.

Optional configuration:

  • OLD_JOBS_RETENTION_DAYS: Database retention for analysis results (default: 3 days). Change this if you want to keep your old analysis longer in the database.

Deprecated environment configuration

The following variables are related to the specific services integrated in IntelOwl. They are deprecated and will be removed in the future: the new way to configure plugin secrets is to use the Plugin Secrets page in the GUI. This change not only promotes a better user experience and overall security, but allows to configure these secrets at either user or org level instead of globally.

If you had previously specified any variables in the environment, IntelOwl will migrate those variables for you once you update the software to the v4.1.0 and restart the containers. (Under the hood IntelOwl runs docker exec -ti intelowl_uwsgi python3 manage.py migrate_secrets). Then you can remove those secrets from the env file.

**Optional** variables needed to enable specific analyzers:
* `ABUSEIPDB_KEY`: AbuseIPDB API key
* `AUTH0_KEY`: Auth0 API Key
* `SECURITYTRAILS_KEY`: Securitytrails API Key
* `SHODAN_KEY`: Shodan API key
* `HUNTER_API_KEY`: Hunter.io API key
* `GSF_KEY`: Google Safe Browsing API key
* `OTX_KEY`: Alienvault OTX API key
* `CIRCL_CREDENTIALS`: CIRCL PDNS credentials in the format: `user|pass`
* `VT_KEY`: VirusTotal API key
* `HA_KEY`: HybridAnalysis API key
* `INTEZER_KEY`: Intezer API key
* `INQUEST_API_KEY`: InQuest API key
* `FIRST_MISP_API`: FIRST MISP API key
* `FIRST_MISP_URL`: FIRST MISP URL
* `MISP_KEY`: your own MISP instance key
* `MISP_URL`: your own MISP instance URL
* `DNSDB_KEY`: DNSDB API key
* `CUCKOO_URL`: your cuckoo instance URL
* `HONEYDB_API_ID` & `HONEYDB_API_KEY`: HoneyDB API credentials
* `CENSYS_API_ID` & `CENSYS_API_SECRET`: Censys credentials
* `ONYPHE_KEY`: Onyphe.io's API Key 
* `GREYNOISE_API_KEY`: GreyNoise API ([docs](https://docs.greynoise.io))
* `INTELX_API_KEY`: IntelligenceX API ([docs](https://intelx.io/product))
* `UNPAC_ME_API_KEY`: UnpacMe API ([docs](https://api.unpac.me/))
* `IPINFO_KEY`: ipinfo API key
* `ZOOMEYE_KEY`: ZoomEye API Key([docs](https://www.zoomeye.org/doc))
* `TRIAGE_KEY`: tria.ge API key([docs](https://tria.ge/docs/))
* `WIGLE_KEY`: WiGLE API Key([docs](https://api.wigle.net/))
* `XFORCE_KEY` & `XFORCE_PASSWORD`: IBM X-Force Exchange API ([docs](https://api.xforce.ibmcloud.com/doc/))
* `MWDB_KEY`: API key for [MWDB](https://mwdb.cert.pl/)
* `SSAPINET_KEY`: screenshotapi.net ([docs](https://screenshotapi.net/documentation))
* `MALPEDIA_KEY`: MALPEDIA API KEY ([docs](https://malpedia.caad.fkie.fraunhofer.de/usage/api))
* `OPENCTI_KEY`: your own OpenCTI instance key
* `OPENCTI_URL`: your own OpenCTI instance URL
* `YETI_KEY`: your own YETI instance key
* `YETI_URL`: your own YETI instance URL
* `SPYSE_API_KEY`: [Spyse](https://spyse.com/) API key. Register here: https://spyse.com/user/registration"
* `DRAGONFLY_API_KEY`: Dragonfly API key. Register [here](https://dragonfly.certego.net/register?utm_source=intelowl).
* `VIRUSHEE_API_KEY`: Virushee API key. ([docs](https://api.virushee.com/))
* `STALKPHISH_KEY`: Stalkphish.io API key. [Register here](https://www.stalkphish.io/accounts/register/).
* `GREEDYBEAR_API_KEY`: GreedyBear API key
* `MALPEDIA_TOKEN`: your own Malpedia token
* `YARAIFY_KEY`: YARAify identifier ([docs](https://yaraify.abuse.ch/api/#identifiers))

**Optional** variables needed to work with specific connectors:
* `CONNECTOR_MISP_KEY`: your own MISP instance key to use with `MISP` connector
* `CONNECTOR_MISP_URL`: your own MISP instance URL to use with `MISP` connector
* `CONNECTOR_OPENCTI_KEY`: your own OpenCTI instance key to use with `OpenCTI` connector
* `CONNECTOR_OPENCTI_URL`: your own OpenCTI instance URL to use with `OpenCTI` connector
* `CONNECTOR_YETI_KEY`: your own YETI instance key to use with `YETI` connector
* `CONNECTOR_YETI_URL`: your own YETI instance API URL to use with `YETI` connector

Database configuration (required)

In the env_file_postgres, configure different variables as explained below.

Required variables:

  • POSTGRES_PASSWORD (same as DB_PASSWORD)

  • POSTGRES_USER (same as DB_USER)

  • POSTGRES_DB (default: intel_owl_db)

If you prefer to use an external PostgreSQL instance, you should just remove the relative image from the docker/default.yml file and provide the configuration to connect to your controlled instances.

Web server configuration (optional)

Intel Owl provides basic configuration for:

  • Nginx (configuration/nginx/http.conf)

  • Uwsgi (configuration/intel_owl.ini)

In case you enable HTTPS, remember to set the environment variable HTTPS_ENABLED as “enabled” to increment the security of the application.

There are 3 options to execute the web server:

  • HTTP only (default)

    The project would use the default deployment configuration and HTTP only.

  • HTTPS with your own certificate

    The project provides a template file to configure Nginx to serve HTTPS: configuration/nginx/https.conf.

    You should change ssl_certificate, ssl_certificate_key and server_name in that file and put those required files in the specified locations.

    Then you should call the start.py script with the parameter --https to leverage the right Docker Compose file for HTTPS.

    Plus, if you use Flower, you should change in the docker/flower.override.yml the flower_http.conf with flower_https.conf.

  • HTTPS with Let’s Encrypt

    We provide a specific docker-compose file that leverages Traefik to allow fast deployments of public-faced and HTTPS-enabled applications.

    Before using it, you should configure the configuration file docker/traefik.override.yml by changing the email address and the hostname where the application is served. For a detailed explanation follow the official documentation: Traefix doc.

    After the configuration is done, you can add the option --traefik while executing the start.py

Analyzers or connectors configuration (optional)

Refer to Analyzers customization and Connectors customization.

Run

Important Info

IntelOwl depends heavily on docker and docker compose so as to hide this complexity from the enduser the project leverages a custom script (start.py) to interface with docker-compose.

You may invoke $ python3 start.py –help to get help and usage info.

The CLI provides the primitives to correctly build, run or stop the containers for IntelOwl. Therefore,

  • It is possible to attach every optional docker container that IntelOwl has: multi_queue with traefik enabled while every optional docker analyzer is active.
  • It is possible to insert an optional docker argument that the CLI will pass to docker-compose

Now that you have completed different configurations, starting the containers is as simple as invoking:

$ python3 start.py prod up

You can add the parameter -d to run the application in the background.

Hint

Starting from IntelOwl 4.0.0, with the startup script you can select which version of IntelOwl you want to run (--version). This can be helpful to keep using old versions in case of retrocompatibility issues. The --version parameter checks out the Git Repository to the Tag of the version that you have chosen. This means that if you checkout to a v3.x.x version, you won't have the --version parameter anymore so you would need to manually checkout back to the master branch to use newer versions.

Stop

To stop the application you have to:

  • if executed without -d parameter: press CTRL+C

  • if executed with -d parameter: python3 start.py prod down

Cleanup of database and application

This is a destructive operation but can be useful to start again the project from scratch

python3 start.py prod down -v

After Deployment

Users creation

You may want to run docker exec -ti intelowl_uwsgi python3 manage.py createsuperuser after first run to create a superuser. Then you can add other users directly from the Django Admin Interface after having logged with the superuser account. To manage users, organizations and their visibility please refer to this section

Update and Re-build

Rebuilding the project / Creating custom docker build

If you make some code changes and you like to rebuild the project, follow these steps:

  1. python3 start.py test build --tag=<your_tag> . to build the new docker image.

  2. Add this new image tag in the docker/test.override.yml file.

  3. Start the containers with python3 start.py test up --build.

Update to the most recent version

To update the project with the most recent available code you have to follow these steps:

$ cd <your_intel_owl_directory> # go into the project directory
$ git pull # pull new changes
$ python3 start.py prod down # kill and destroy the currently running IntelOwl containers 
$ python3 start.py prod up # restart the IntelOwl application

Warning

Major versions of IntelOwl are usually incompatible from one another. Maintainers strive to keep the upgrade between major version easy but it's not always like that. Below you can find the additional process required to upgrade from each major versions.

Updating to >=4.0.0 from a 3.x.x version

Right now there is an issue regarding the chance to provide a script for migrate the Users DB to the new IntelOwl v4 schema. IntelOwl v4 introduced some major changes regarding the permission management, allowing an easier way to manage users and visibility. But that did break the previous available DB. So, while we find time and effort to develop this script, to migrate to the the new major version you would need to delete your DB. To do that, you would need to delete your volumes and start the application from scratch.

python3 start.py prod down -v

Please be aware that, while this can be an important effort to manage, the v4 IntelOwl provides a easier way to add, invite and manage users from the application itself. See the Organization section.

Updating to >=2.0.0 from a 1.x.x version

Users upgrading from previous versions need to manually move env_file_app, env_file_postgres and env_file_integrations files under the new docker directory.

Updating to >v1.3.x from any prior version

If you are updating to >v1.3.0 from any prior version, you need to execute a helper script so that the old data present in the database doesn’t break.

  1. Follow the above updation steps, once the docker containers are up and running execute the following in a new terminal

    docker exec -ti intelowl_uwsgi bash

    to get a shell session inside the IntelOwl’s container.

  2. Now just copy and paste the below command into this new session,

    curl https://gist.githubusercontent.com/Eshaan7/b111f887fa8b860c762aa38d99ec5482/raw/758517acf87f9b45bd22f06aee57251b1f3b1bbf/update_to_v1.3.0.py | python -

  3. If you see “Update successful!”, everything went fine and now you can enjoy the new features!