Skip to content

Latest commit

 

History

History
221 lines (159 loc) · 9.75 KB

INSTALL.md

File metadata and controls

221 lines (159 loc) · 9.75 KB
Raw

FACT installation

The Firmware and Comparison Tool (FACT) consists of three components: frontend, database and backend. All components can be installed on different machines (see Distributed setup), but you can also install everything on one machine (see Simple (non-distributed) setup). There is an automated installation script supporting Ubuntu 20.04 and 22.04 systems. :exclamation: The automated installation script might remove some packages of your Ubuntu installation. In some cases, FACT relies on newer software versions than the ones provided by the Ubuntu repositories.

TL;DR

Execute the following commands (not as root!):

sudo apt update && sudo apt upgrade && sudo apt install git
git clone https://github.com/fkie-cad/FACT_core.git ~/FACT_core
~/FACT_core/src/install/pre_install.sh && sudo mkdir /media/data && sudo chown -R $USER /media/data

Then reboot (e.g., with sudo reboot) and afterward run

~/FACT_core/src/install.py
~/FACT_core/start_all_installed_fact_components

Wait a few seconds, open your browser and go to http://localhost:5000. Use Ctrl + c in your terminal to shut down FACT.

WSL only

Follow the first three installation steps above (stop before the reboot). To make sure that docker starts when you log in to a WSL machine, follow the instructions on this webpage. Then continue the installation as usual.

Virtual environment

It is highly advisable to install FACT in a virtual python environment to avoid conflicts with system python packages. Python usually comes with its own venv module but for a packaged python installations in distributions like Ubuntu or Debian you may need to install the python3-venv package first:

sudo apt install -y python3-venv

Now you can create a virtual environment with:

python3 -m venv .venv

Before using your new venv, you need to activate it:

# this is for bash and compatible shells. If you use a different shell, you may need a different script from .venv/bin/
source .venv/bin/activate

For more information, see the official documentation. Now that the venv is active, you can start with the installation of FACT as usual. Please mind that you always need to activate the venv before you can start FACT. If you have an existing FACT installation without venv, you can create one, activate it, and rerun the installation.

Simple (non-distributed) setup

Pre-installation

Some components of FACT depend on docker. Since a restart is necessary before docker can run. The system has to be rebooted in between FACT installation. Thus, the docker setup and some auxiliary stuff have been moved to the pre_install.sh script.

The following lines will handle the first half of the installation (based on git not tarball):

sudo apt update && sudo apt upgrade && sudo apt install git
git clone https://github.com/fkie-cad/FACT_core.git
cd FACT_core
src/install/pre_install.sh

Now modify src/config/fact-core-config.toml to suit your needs. Especially, you should change the postgres passwords. The database is initialized with these passwords on first start.

Create the firmware_file_storage_directory defined in fact-core-config.toml. Make sure that the log directory exists as well.

If you have any additional plug-ins, copy/clone them into corresponding src/plugins/ directory.

❗ Reboot before executing the src/install.py ❗ ❗ You have to do the above steps before you do anything else ❗

Main installation

🛃 The installation script installs a lot of dependencies that may have different licenses After reboot, enter the FACT_core directory and execute:

src/install.py

🍺 Get a drink... Installation of the dependencies might take some time... 🍵

More advanced setup options can be viewed using the help function of the installer src/install.py --help and are explained in some detailed in the following paragraphs.

If the environment variable FACT_INSTALLER_SKIP_DOCKER is set the installer will skip all pulling/building of docker images. This is primarily used for the docker container of FACT but can also be used to save some time when you already have the images.

Distributed setup

The three components (database, backend and frontend) can be installed independently to create a distributed installation. For this, the components can be individually installed using the command line options --frontend, --backend, and --db (see src/install.py --help). The two worker components (frontend, backend) both use the database and communicate through Redis. This means the database and Redis need to be accessible from these systems. The database in turn does not need any knowledge of its place in the network, other than on which ip:port combination the database server has to be hosted. The configuration on the frontend system has to be changed so that the values of common.postgres.server and common.postgres.port match the ip:port for the database. The same has to be done for Redis and the backend. In addition, since the raw firmware and file binaries are stored in the backend, the backend.firmware-file-storage-directory has to be created (by default /media/data/fact_fw_data).

Installation with Nginx (--nginx)

The installer supports automated installation and configuration of nginx. This will enable SSL protected access to the frontend via port 443. To activate nginx support, add the -N option. See our radare wiki page for some additional steps to allow forwarding of the radare webUI.

Making FACT available over the network

Using the default configuration, FACT is only reachable from the system it is running on. Making FACT reachable from other systems (e.g., on your local network) is simple, though: All you have to do is replacing 127.0.0.1:5000 in the uwsgi_config.ini with 0.0.0.0:5000 (:5000 also works). This is not necessary if you are using nginx, because nginx is configured to accept external connections by default. You may have to reconfigure your firewall to allow connections if you are using one.

Install Statistic Generation Cron Job (--statistic_cronjob)

FACT provides statistics generated by triggering the update_statistic script. The installation script can add a cronjob to trigger this script once an hour. To do this, add the -U option when installing.

Installation with/without radare (--no_radare)

In contrast to nginx, radare has to be deselected as it is installed by default. This can be done with the -R parameter. On additional notes regarding the setup of the radare web GUI see the extensive notes in the wiki.

Update an older Installation

Simply checkout the new sources, rerun the src/install/pre_install.sh and then src/install.py. Rebooting is not necessary if docker is already present. For tarball installations, the easiest way is to back up the config files, remove the FACT folder, extract the new one and put the configuration back in. Then also re-run src/install/pre_install.sh and src/install.py.

If your FACT installation is v3.2 or lower and you use authentication, then you have to migrate the user database. To do so, run the migrate_database.py script.

FACT and your HTTP Proxy

In some advanced network setups, you might need to configure an HTTP proxy for internet connectivity. Most components of FACT do not require internet access during runtime. The hash lookup plugin, which polls https://hashlookup.circl.lu/ during analysis, is an exemplary exception.

However, FACT's installation routine requires a lot of internet I/O, ranging from fetching APT packages, over static assets from CDNs using curl or wget, to docker image builds. Thus, it is important to properly configure your system. Below, you will find some hints for system-wide proxy configuration.

Proxy environment variables

Most dependencies and tools used by FACT honor *_PROXY environment variables. You can set these on a system-wide scope inside /etc/environment.

echo 'HTTP_PROXY=http://<YOUR-PROXY-HERE>:<PORT>/
HTTPS_PROXY=http://<YOUR-PROXY-HERE>:<PORT>/
http_proxy=http://<YOUR-PROXY-HERE>:<PORT>/
https_proxy=http://<YOUR-PROXY-HERE>:<PORT>/
no_proxy="localhost,127.0.0.1,::1"
NO_PROXY="localhost,127.0.0.1,::1"' | sudo tee -a /etc/environment

apt

apt is usually called via sudo in our installation scripts. While apt honors the previously set *_PROXY environment variables, sudo is configured on some distributions to drop them upon privilege elevation. You have two options to fix this issue.

Option 1: Configure sudo to not drop these variables:

Open the sudoers file with sudo visudo and append the following line:

Defaults env_keep += "ftp_proxy http_proxy https_proxy no_proxy"

Option 2: Directly configure apt to use those env vars:

echo 'Acquire::http::Proxy "http://<YOUR-PROXY-HERE>:<PORT>/";
Acquire::https::Proxy "http://<YOUR-PROXY-HERE>:<PORT>/";' | sudo tee /etc/apt/apt.conf.d/00proxy

Docker

Please refer to the official docker documentation to configure it for proxy usage.

Troubleshooting

If you encounter any problems, check out our Troubleshooting wiki before opening an issue on GitHub.