Quick start
You want to start straight away? Pick a tool, copy the commands, paste them in a terminal, and it runs.
| Tool | What it does | You need | Time |
|---|---|---|---|
| PiRogue | Captures and analyzes the network traffic of a device | A Debian 12 machine | 10 min |
| Colander | Case and digital investigation platform | Docker, Node.js | 10 min |
| Threatr | Threat intelligence aggregation | Docker | 2 min |
- PiRogue
- Colander
- Threatr
You need: a machine with a fresh Debian 12 installation, on amd64 or arm64, with at least 4 GB of RAM and 40 GB of disk, and Internet access. It can be a physical machine, a virtual machine, or a Raspberry Pi. The PiRogue changes the network configuration of the machine, so use a dedicated one.
Connect to it with SSH and run the following block:
sudo apt-get update
sudo apt-get dist-upgrade
sudo apt-get install wget
sudo wget -O /etc/apt/sources.list.d/pirogue.list https://pts-project.org/debian-12/pirogue.list
sudo wget -O /etc/apt/trusted.gpg.d/pirogue.gpg https://pts-project.org/debian-12/pirogue.gpg
sudo apt-get update
sudo apt-get install pirogue-base
If the installer asks whether non-superusers may capture network traffic, answer Yes.
The operating mode is selected automatically from the network interfaces of the machine:
- a second Wi-Fi interface: Access point, the devices to analyze connect to the Wi-Fi network of the PiRogue
- a second Ethernet interface: Appliance
- a single interface: VPN, the devices connect with WireGuard. This is the simplest way to try a PiRogue in a virtual machine.
See Installation for the details of each mode.
Check that it works
Display the configuration of your PiRogue, including the generated passwords:
pirogue-admin-client system get-configuration
Check that SYSTEM_OPERATING_MODE is the mode you expect, and note DASHBOARD_PASSWORD (also displayed with pirogue-admin-client dashboard get-configuration) and, in access point mode, WIFI_PASSPHRASE.
Then open the dashboard in your browser, with the user admin and the password above:
https://<EXTERNAL_ADDRESS>/dashboard
Your browser warns about the certificate because it is self-signed. For a first try, accept the warning and continue.
What's next
- Administer your PiRogue from the browser at
https://<EXTERNAL_ADDRESS>/admin, see the admin web interface. - Capture and analyze the traffic of a device, see Traffic capture.
- Connect a phone to a PiRogue used as a VPN, see Installation.
- Enroll your PiRogue in Colander, see PiRogue fleet.
You need: Docker with Docker Compose, git, Node.js and openssl. Allow about 10 GB of disk space and 8 GB of RAM, and 5 to 10 minutes for the first start.
Copy and paste the following block in a terminal. It downloads Colander, builds it, starts the full stack (database, storage, search engine, workers, Mandolin, CyberChef, etc.) and creates an administrator.
git clone --depth 1 https://github.com/PiRogueToolSuite/colander.git
cd colander
# Build the frontend and the containers
npm ci && npm run dist
docker compose -f local.yml build
# Start Colander and wait until it answers
docker compose -f local.yml up -d
until curl -s -o /dev/null http://127.0.0.1:8080/; do sleep 3; done
# Load the default data and create the administrator
docker compose -f local.yml run --rm django python manage.py insert_default_data
ADMIN_PASSWORD=$(openssl rand -hex 12)
docker compose -f local.yml run --rm -e DJANGO_SUPERUSER_PASSWORD="$ADMIN_PASSWORD" \
django python manage.py createsuperuser --noinput --username admin --email admin@localhost
echo "Colander: http://127.0.0.1:8080 (user: admin, password: $ADMIN_PASSWORD)"
Check that it works
Open http://127.0.0.1:8080 and log in with the user and the password displayed at the end of the block. You land on the dashboard, from where you can create your first case, see Case management.
Registration is disabled. To create the accounts of your colleagues, use the administration panel at http://127.0.0.1:8080/admin/, see Accounts. Emails, such as the account verification, are printed in the logs: docker compose -f local.yml logs -f django.
What's next
To stop Colander, run docker compose -f local.yml stop. To remove it with all its data, run docker compose -f local.yml down -v.
This is the development stack of Colander: it is meant to try Colander on your own computer, it listens on plain HTTP and it does not include the reverse proxy, the TLS certificate and the automatic updates. To host Colander for your team on a server with a domain name, follow the deployment procedure.
You prefer having a managed server? Feel free to reach out to us.
You need: Docker with Docker Compose, curl and openssl.
Copy and paste the following block in a terminal. It downloads the configuration, generates new secrets, starts Threatr, creates an administrator and creates an API key.
mkdir -p threatr && cd threatr
BASE=https://raw.githubusercontent.com/PiRogueToolSuite/threatr/refs/heads/main/deployment
curl -fsSLO $BASE/.env
curl -fsSLO $BASE/threatr-local.yml
# Generate new secrets
sed -i "s|^DJANGO_SECRET_KEY=.*|DJANGO_SECRET_KEY=$(openssl rand -hex 32)|; s|^POSTGRES_PASSWORD=.*|POSTGRES_PASSWORD=$(openssl rand -hex 24)|" .env
# Start Threatr and wait until it answers
docker compose -f threatr-local.yml up -d
until curl -s -o /dev/null http://127.0.0.1:9080/admin/login/; do sleep 2; done
# Create the administrator and an API key
ADMIN_PASSWORD=$(openssl rand -hex 12)
docker compose -f threatr-local.yml run --rm -e DJANGO_SUPERUSER_PASSWORD="$ADMIN_PASSWORD" \
threatr-local-front python manage.py createsuperuser --noinput --username admin --email admin@localhost
API_KEY=$(docker compose -f threatr-local.yml run --rm threatr-local-front python manage.py drf_create_token admin | awk '/Generated token/{print $3}')
echo "Administration panel: http://127.0.0.1:9080/admin (user: admin, password: $ADMIN_PASSWORD)"
echo "API key: $API_KEY"
On macOS, replace sed -i with sed -i ''.
Check that it works
List the available integrations with the API key displayed at the end of the block:
curl -s http://127.0.0.1:9080/api/modules/ -H "Authorization: Token $API_KEY"
Every integration is listed with "configured": 0: no third-party service is connected yet. Ask for threat intelligence about an observable:
curl -s -X POST http://127.0.0.1:9080/api/request/ \
-H "Content-Type: application/json" -H "Authorization: Token $API_KEY" \
-d '{"super_type": "observable", "type": "sha256", "value": "854774a198db490a1ae9f06d5da5fe6a1f683bf3d7186e56776516f982d41ad3", "force": false}'
What's next
Threatr only returns data from the services you connect. Add your VirusTotal, OTX, Shodan, Scarlet Shark or MISP credentials in the administration panel, see Integrations. To go further, read the deployment and the REST API pages.
To stop Threatr, run docker compose -f threatr-local.yml stop. To remove it with all its data, run docker compose -f threatr-local.yml down -v.
This deployment is meant for a local use. Threatr listens on all the interfaces of the machine and must not be exposed to the Internet.
Prerequisites
This documentation is designed to be readable and provide clear instructions for users with some network and Linux experience. However, experienced security professionals, network administrators, and system administrators will also find valuable information here.
Minimum Requirements
We recommend that you have experience interacting with the command line interface (CLI) for your operating system.
Additional Helpful Skills
This documentation assumes you have:
- Some understanding of security concepts
- Basic familiarity with internet and networking protocols
- Some experience interpreting network traffic anomalies and responding to incidents