Beginner guide - How to setup a PiRogue

PiRogue tool suite (PTS) is an open-source tool suite that provides a comprehensive mobile forensic and network traffic analysis platform targeting mobile devices both Android and iOS, internet of things devices (devices that are connected to the user mobile apps), and in general any device using wi-fi to connect to the Internet.

Main PiRogue capabilities #

The PiRogue is an open hardware device based on a Raspberry Pi operating as a network router (like any ISP router) analyzing network traffic in real time.

It can operate in different modes:

• an on-the-field mode

  • for emergency response (active spying, device tampering, …) useful for responders in repressive environment
  • conduct forensics analysis and network detection using a pre-installed set of tools

• an expert mode for technical people to:

  • determine the list of collected data
  • assess regulatory compliance
  • conduct penetration testing
  • analyze malware’s behavior
  • ensure reproducible analysis
  • generate comprehensive reports

The hardware you need #

In addition to a computer and an Internet connection, you will need, at least, a Raspberry Pi (+ its power supply), a micro SD-card and an ethernet cable.

Pick a Raspberry Pi #

First, you need a Raspberry Pi. We support the following versions of Raspberry Pi:

• Raspberry Pi 3 Model B
• Raspberry Pi 3 Model B+
• Raspberry Pi 4 Model B - 1GB
• Raspberry Pi 4 Model B - 2GB
• Raspberry Pi 4 Model B - 4GB
• Raspberry Pi 4 Model B - 8GB

Important note: Suricata is disabled on devices having less then 1.5GB of RAM.

If you want to buy a Raspberry Pi, visit the rpilocator website to check for availability.

Pick a micro SD-card #

Second, you need a SD-card to run your PiRogue. The SD-card has to be large enough to store the operating system and all the data generated by the PiRogue itself. By default, it stores 5 days of network traffic history.

You may choose:

• a 32GB micro SD-card for regular use
• a 64GB micro SD-card if you plan doing long runs, analyzing the traffic of multiple devices simultaneously

Pick an Ethernet cable #

In order to connect the PiRogue to the Internet, you should have an ethernet cable connecting your PiRogue to your network. A simple cat. 5 ethernet cable will do the job.

Optional stuff #

Depending on your needs, you would want to add a hat to your PiRogue and protect everything with a case. Check the documentation for more details.

Install PiRogue OS #

Get PiRogue OS #

PiRogue OS is periodically released. The OS is pre-configured so you just need to flash it on a micro SD-card. The image (the binary file to be flashed on the SD-card) is compressed. The file you have to download on your computer has a name following this schema PiRogue-OS-<year>-<month>-<day>.img.xz.

Download the latest version of PiRogue OS →

Check the integrity of the image #

Once you have downloaded the image, you can check its integrity (check if the file has not been modified or corrupted) by comparing its SHA256 and the SHA256 displayed on the GitHub page. If both SHA256 are the same, the file you downloaded has not been tampered.

To compute the SHA256 of the file you downloaded, run the following command in a terminal:

• on Linux: sha256sum PiRogue-OS-<year>-<month>-<day>.img.xz
• on Windows Powershell: Get-FileHash .\PiRogue-OS-<year>-<month>-<day>.img.xz -Algorithm SHA256 | Format-List

Set up your SD card #

Advanced Linux users can use a combination of xz and dd commands to flash their SD-card.

We recommend to download Balena Etcher and install it on your computer. Run Balena Etcher as administrator and follow the steps illustrated by the screenshots below.

Download Balena Etcher →

Once the flashing is complete, eject the SD-card from your computer.

Set up the PiRogue #

If you have the hat for your PiRogue, it is the good time for you to plug it in and put everything into the case. Insert your freshly flashed micro SD-card into the PiRogue, plug the ethernet cable to the PiRogue. Remember, this cable connects your PiRogue directly (or through network switch) to your ISP router.

First boot #

First, check that the SD card is correctly inserted into the appropriate slot of your PiRogue and the ethernet cable is properly connected. Then, plug the power supply. Wait a few minutes before trying to access your PiRogue.

Now, connect to your PiRogue using SSH.

ssh pi@pirogue.local

Type raspberry which is the default password and press Entrer.

Once connected, you have to finalize the installation of your PiRogue by running the following commands, copy each line separately one by one:

During the installation, when prompted, you will have to answer:

• No to save iptables rules for IP v4
• No to save iptables rules for IP v6
• Yes to allow non-root users to capture network traffic

After the reboot, wait a few minutes, you will then be able to connect a Wi-Fi device and use the PiRogue’s dashboard.

First, connect a wi-fi device such as your smartphone to the PiRogue’s wi-fi network PiRogue1 (default password: superlongkey). Next, open the PiRogue’s dashboard by going at http://<PiRogue IP address>:3000 with your Web browser or directly with this link:

Open your dashboard →

It will take around 4 minutes before network flows start appearing in the dashboard. At the first start of your PiRogue the dashboard will look empty or broken. Don’t worry, connect a device to the PiRogue’s WiFi network, wait 5 minutes and refresh the dashboard by pressing F5 key on your keyboard.

Once your PiRogue is running, it will be accessible to you from the network. There are 2 ways to get the IP address of your PiRogue.

The first way is by looking at the screen of the PiRogue Hat.

The second way is to use the ping command. To do so, on your computer connected to the same network as your PiRogue, run the following command:

ping -c1 pirogue.local

The dashboard #

By default, your PiRogue exposes a Grafana dashboard showing in realtime the ongoing network connections, security alerts and few other information. Checkout the cheatsheet to get default user and password of the dashboard.

Open your dashboard →

Depending on your network configuration, this link above may not work. If so, check how to get the IP address of your PiRogue in the previous section.

The default dashboard is composed of different panels, we will go through the main ones.

General statistics #

This panel displays various information:

1. the number of different devices that have been connected to the PiRogue’s Wi-Fi network during the selected period of time
2. the number of security alerts that have occurred during the selected period of time
3. the amount of network traffic exchanged between connected devices and the Internet during the selected period of time
4. the number of network flows that have occurred during the selected period of time
5. the number of different domains that have been contacted during the selected period of time

World map #

This panel displays the location of the different servers the connected devices have been communicating with during the selected period of time.

List of flows #

This panel displays the different network flows that have occurred during the selected period of time:

1. the time at which the flow as started
2. the category of traffic that has been identified by NFStream
3. the type of application that has generating this flow
4. the domain name of the contacted server
5. the IP address of the source of the flow
6. the IP address of the destination of the flow
7. the country where the remote server is located at
8. the amount of network traffic associated to this flow

List of security alerts #

This panel displays the different security alerts generated by Suricata that have occurred during the selected period of time:

1. the time of the alert. If you click on it, you will get the details of the selected alert)
2. the severity of the alert
3. the type of threat associated to the alert
4. the name of the rule corresponding to the alert
5. the IP address of the source of the flow associated to the alert
6. the IP address of the destination of the flow associated to the alert