Installing Unicornscan

1.1 Introduction

Unicornscan is an asynchronous stateless network stimulus delivery/response recording tool designed for scalable, high-speed network reconnaissance. This guide describes how to compile and install unicornscan from source code on POSIX platforms. Use the table of contents to skip directly to sections that seem relevant to you.

If you prefer pre-built packages (.deb or .rpm), see the INSTALL-package.md file.

1.1.1 Requirements

Unicornscan requires the following libraries to be installed on your system:

• ▸libpcap - Packet capture library
• ▸libdnet - Low-level networking (called libdumbnet on Debian/Ubuntu)
• ▸libltdl - Dynamic library loading (part of libtool)
• ▸flex/bison - Parser generators (build-time only)

Optional dependencies for additional features:

• ▸libpq - PostgreSQL client library (for database export)
• ▸libmaxminddb - MaxMind GeoIP database library (for country/city lookup)

1.2 Installing the Prerequisites

Use your distribution's package manager to install the required build dependencies. Modern distributions provide all necessary libraries.

1.2.1 Debian/Ubuntu

sudo apt install build-essential autoconf automake libtool pkg-config \
    libpcap-dev libdumbnet-dev libltdl-dev flex bison

Optional for PostgreSQL support (recommended for the Web UI):

sudo apt install libpq-dev

Optional for GeoIP country/city lookups:

sudo apt install libmaxminddb-dev

1.2.2 Fedora/RHEL/Rocky

On Rocky/RHEL 9, you may need to enable EPEL and CRB first:

sudo dnf install epel-release
sudo dnf config-manager --set-enabled crb

Then install the build dependencies:

sudo dnf install gcc make autoconf automake libtool pkg-config \
    libpcap-devel libdnet-devel libtool-ltdl-devel flex bison

Optional for PostgreSQL support (recommended for the Web UI):

sudo dnf install postgresql-devel

Optional for GeoIP country/city lookups:

sudo dnf install libmaxminddb-devel

1.2.3 Arch Linux

sudo pacman -S base-devel autoconf automake libtool pkgconf \
    libpcap libdnet flex bison

Optional for PostgreSQL support:

sudo pacman -S postgresql-libs

Optional for GeoIP lookups:

sudo pacman -S libmaxminddb

1.2.4 Library Name Differences

Note that the low-level networking library has different package names:

Both refer to the same library (libdnet by Dug Song). The Debian name change was made to avoid confusion with the DECnet library.

1.3 Installing Unicornscan

1.3.1 Downloading Unicornscan

Latest:v0.4.51

Source code and releases are available on GitHub:

https://github.com/robertelee78/unicornscan

Download the latest source tarball:

tar.gzzip
wget https://github.com/robertelee78/unicornscan/archive/refs/tags/v0.4.51.tar.gz
Copy

Or clone the Git repository for the development version:

git clone https://github.com/robertelee78/unicornscan.git

1.3.2 Compiling from Source

Source installation is designed to be a painless process. The build system auto-detects most configuration options. Here are the steps for a default install:

1. ▸

   Extract the downloaded tarball (skip if using git clone):

   tar xzf unicornscan-v0.4.51.tar.gz
   cd unicornscan-v0.4.51
   Copy

2. ▸

   If building from a git clone, generate the configure script:

   autoreconf -fi
   

3. ▸

   Configure the build system:

   ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var
   

   This configures unicornscan to install in standard system locations:

   • ▸Binaries in /usr/bin/
   • ▸Libraries in /usr/lib/unicornscan/
   • ▸Configuration in /etc/unicornscan/
   • ▸Runtime state in /var/unicornscan/

   Run ./configure --help to see all available options (described below).

4. ▸

   Build unicornscan:

   make
   

   Note: GNU Make is required. On BSD-derived systems, this is often installed as gmake. If make returns errors like "Need an operator", try running gmake instead.

5. ▸

   As a privileged user, install unicornscan:

   sudo make install
   

6. ▸

   Enable non-root scanning by setting Linux capabilities:

   sudo make setcap
   

   This sets the following capabilities on the binaries:

   • ▸cap_net_raw - Create raw sockets for packet capture/injection
   • ▸cap_net_admin - Network interface configuration
   • ▸cap_sys_chroot - Chroot for privilege dropping
   • ▸cap_setuid/gid - UID/GID operations for privilege separation

   Note: File capabilities require a real filesystem (ext4, btrfs, xfs). They do not work on tmpfs or in some container environments.

7. ▸

   Congratulations! Unicornscan is now installed. Run it with -h for help:

   unicornscan -h
   

   You can now scan without sudo:

   unicornscan target.com
   

8. ▸

   To uninstall:

   sudo make uninstall
   

1.3.3 Configure Options

Common configuration options:

Example for a local user installation:

./configure --prefix=$HOME/.local/unicornscan
make && make install

1.4 Compilation Problems

If you run into trouble compiling, you can:

• ▸Check the GitHub Issues: https://github.com/robertelee78/unicornscan/issues
• ▸Open a new issue with your error message and system details

Common issues:

1.5 Getting the Web UI Working

Unicornscan includes a modern web interface called Alicorn for viewing and analyzing scan results. It requires Docker and PostgreSQL for data storage.

1.5.1 Prerequisites

Install Docker on your system. The easiest method is the convenience script:

curl -fsSL https://get.docker.com | sh

Ensure your user can run docker commands:

sudo usermod -aG docker $USER

Log out and back in for the group change to take effect.

1.5.2 Starting the Web UI

If you installed unicornscan with --with-pgsql and the binaries have been installed, use the web management command:

sudo unicornscan-alicorn start

This will:

• ▸Generate a secure random 32-character password
• ▸Save credentials to /var/lib/unicornscan/alicorn/.env (for Docker)
• ▸Update /etc/unicornscan/modules.conf with the password (for unicornscan)
• ▸Start PostgreSQL in a Docker container
• ▸Initialize the database schema
• ▸Start the PostgREST API and Alicorn web server

The password is stored in three places:

• ▸/var/lib/unicornscan/alicorn/.env - Docker Compose environment
• ▸/var/lib/unicornscan/alicorn/.db_password - Plain text for easy retrieval
• ▸/etc/unicornscan/modules.conf - Unicornscan pgsqldb module config

Because modules.conf is auto-configured, you can run scans with database export immediately without specifying connection parameters:

unicornscan -epgsqldb 192.168.1.0/24

To retrieve the password later:

unicornscan-alicorn password

1.5.3 Accessing the Web UI

Open your browser to: http://localhost:31337

The web interface shows:

• ▸Scan history and results
• ▸Host and port statistics
• ▸OS fingerprinting results
• ▸Network topology visualization

1.5.4 Storing Scan Results

For remote databases or manual configuration, override the modules.conf settings with command-line parameters:

unicornscan -epgsqldb,host=dbserver.example.com,user=alicorn,pass=SECRET,db=unicornscan \
    192.168.1.0/24

You can combine pgsqldb with other modules like OS detection:

unicornscan -epgsqldb,osdetect 192.168.1.0/24

1.5.5 Managing the Web UI

Common unicornscan-alicorn commands:

1.5.6 GeoIP Location Data

For geographic information in scan results (country, city, ASN), download free GeoIP databases:

sudo unicornscan-geoip-update

This downloads DB-IP Lite databases (~130 MB) which provide:

• ▸City and region names
• ▸Country information
• ▸Latitude/longitude coordinates
• ▸ASN and ISP data

The databases are updated monthly. Re-run the command periodically to get fresh data.

1.6 Getting Help

For usage examples and detailed documentation:

For support and bug reports:

• ▸Website: http://www.unicornscan.org/
• ▸GitHub Issues: https://github.com/robertelee78/unicornscan/issues