Operating system

The PiRogue runs PiRogueOS which is based on Debian 12 by the time we are writing this document (Dec. 2023). Debian is a renowned Linux distribution recognized for its stability, reliability, and commitment to open-source principles. It serves as a foundational platform for numerous other distributions and is widely adopted in various industries, including enterprise environments, scientific research, and embedded systems. Debian’s trustworthiness stems from its long-standing reputation for quality, its rigorous testing and development processes, and its commitment to open and transparent collaboration.

Debian’s stability is attributed to its conservative approach to software updates, ensuring that only thoroughly tested and stable packages are included in its repositories. This emphasis on stability makes Debian a preferred choice for mission-critical systems where reliability is paramount.

Debian’s commitment to open-source principles fosters a collaborative development model that leverages the expertise of a vast community of developers and users. This open approach promotes transparency, encourages peer review, and ensures that Debian remains a community-driven project with a focus on quality and security.

Pirogue Tool Suite uses a comprehensive set of software tools for network traffic analysis, device forensics, and threat intelligence gathering. These tools are categorized based on their functionalities:

• tcpdump: Captures network traffic and stores it in PCAP files for further analysis.
• suricata: Detects malicious traffic based on predefined rules and signatures.
• nfstream: Inspects network traffic in-depth to determine the specific applications involved in each data flow.
• adb: Provides a command-line interface for interacting with Android devices for forensic analysis.
• libimobiledevice: Enables communication and data extraction from iOS devices for forensic investigations.
• mvt: Conducts comprehensive device forensic analysis, identifying signs of compromise or spyware infection.
• frida: Injects code into running applications and processes on a device, enabling dynamic analysis through dynamic instrumentation.
• sha256: Computes file hashes to check data integrity.

Integration with Raspberry Pi#

PiRogue OS is a tailored version of Debian mainline, a popular Linux distribution known for its stability and reliability. However, the custom HAT (Hardware Attachment on Top) used in PiRogue requires additional configurations to integrate seamlessly with the Linux kernel. To achieve this compatibility, custom Device Tree Blobs (DTBs) and udev rules have been developed.

Device Tree Blobs (DTBs) are data structures that describe the hardware configuration of a device, providing the kernel with information about its components and their relationships. Custom DTBs for the PiRogue HAT enable the kernel to recognize and properly interact with the HAT’s unique hardware components, such as the TFT screen, RTC, and fan control circuitry.

Udev rules, on the other hand, are configuration files that govern how the Linux kernel handles device events and assigns device permissions. Custom udev rules for the PiRogue HAT ensure that the kernel properly detects the HAT’s devices, assigns them appropriate permissions, and triggers the necessary actions when events occur.

The definition of the different DTB overlays and udev rules can be reviewed on GitHub:

• https://github.com/PiRogueToolSuite/deb-packages/tree/debian-12/pirogue-hat/linux/arm64
• https://github.com/PiRogueToolSuite/deb-packages/tree/debian-12/pirogue-screen-st7789-240x240/linux/arm64

By implementing custom DTB overlays and udev rules, PiRogue OS ensures seamless integration between the Raspberry Pi, the custom HAT, and the Linux kernel. This tailored approach enables the PiRogue to operate smoothly within the Debian environment. The Linux Kernel uses the RTC as a reference of time and takes care synchronizing the system time with the RTC one at its boot if NTP is not available.

The generation of the operating system image to be flashed on an SD-card is ensured by Packer. It takes the official Debian image and applies changes such as creating a default user and configuring a PPA. The modifications applied to the official Debian image is available on GitHub https://github.com/PiRogueToolSuite/pirogue-images.

PiRogue features can be installed on a Raspberry Pi as well as on a regular computer equipped with a Wi-Fi interface and an Ethernet interface.

Packaging for PiRogue#

All features and software installed on the PiRogue are packaged for Debian 12. These packages are published on our PPA.

A Personal Package Archive (PPA) serves as a repository for software packages maintained by individuals or teams outside of the official Debian distribution. It allows developers to distribute and update their software independently, providing users with access to newer versions or packages not yet included in Debian’s main repositories. PPAs offer a convenient way to access other software but require cautious use as they may not undergo the same rigorous testing as official Debian packages.

PTS’s PPAs contain both PiRogue-specific tools as well as external tools that are not available on official Debian repository.

By the time writing this document, PiRogue-specific packages are:

• pirogue-networking to set up the network
• pirogue-base is a meta-package to install all PiRogue-specific packages
• pirogue-cli to install the PiRogue command line tools
• pirogue-dashboard to setup the PiRogue dashboard
• pirogue-eve-collector to configure Suricata and setup the tools managing Suricata alerts
• pirogue-flow-inspector to setup the deep packet inspection
• pirogue-hat to setup the HAT of the PiRogue
• pirogue-maintenance to setup the daily maintenance such as detection rules update
• pirogue-screen-st7789-240x240 to setup the TFT screen of the HAT
• pirogue-tools to install all other necessary software such as MVT or Frida

We also packaged, for Debian, tools that are not maintained by PTS team:

• python3-adb-shell
• python3-ahocorasick
• python3-communityid
• python3-geoip2
• python3-iosbackup
• python3-mvt
• python3-nskeyedunarchiver
• python3-nfstream
• frida

All PiRogue-specific packages are defined in the GitHub repository https://github.com/PiRogueToolSuite/deb-packages for Debian 12.

PiRogue Debian packages can be installed on any compatible hardware running Debian 12 (without graphical environment). The package hardware-detection will be taking care of installing the HAT drivers if the installation is done on a Raspberry Pi.

PiRogue packages dependency tree

Installation#

Have a look to the guide dedicated to building a PiRogue →

Upgrade#

All PiRogue features are bundled as Debian packages. So, by upgrading Debian (which is the only supported operating system) you are also upgrading your PiRogue.

To upgrade both the OS and the PiRogue features, run the following two commands:

sudo apt update
sudo apt dist-upgrade

This operation could take some time and would require a reboot to make your PiRogue operates properly.

How often?#

We advice you to upgrade your PiRogue weekly.

Heavily customized PiRogue#

Some users would want to customize their PiRogue by playing with the different configuration files of the system. If so, be sure to backup your changes BEFORE upgrading your PiRogue. The upgrade will override your customization.

For PiRogue v1.x series#

The following configuration files are managed by the PiRogue packages:

• /etc/hostapd/hostapd.conf
• /etc/dnsmasq.conf
• /etc/dhcpcd.conf
• /etc/iptables/rules.v4
• /etc/iptables/rules.v6
• /etc/suricata/suricata.yaml
• /etc/grafana/grafana.ini
• /etc/grafana/provisioning/datasources/datasources.yml
• /etc/grafana/provisioning/dashboards/grafana_dashboards.yml
• /var/lib/grafana/dashboards/pirogue-dashboard.json
• /var/lib/grafana/dashboards/pirogue-flow-details-dashboard.json

For PiRogue v2.x series#

A best effort is done to keep user configured PiRogue configuration files. That said, be sure to keep a copy of the following files in case an update doesn’t go as planned:

• /var/lib/pirogue/admin/config.yaml
• /var/lib/pirogue/admin/wireguard/config.yaml (if any)
• /var/lib/pirogue/admin/client.yaml
• /var/lib/pirogue/admin/daemon.yaml
• /var/lib/pirogue/admin/pirogue-external-exposure/fullchain.pem
• /var/lib/pirogue/admin/pirogue-external-exposure/privkey.pem