DShield turns a spare Raspberry Pi into a sensor for internet-wide attack data

What a DShield sensor is and who it is for

The repository is a set of scripts to set up a DShield Sensor, and the README opens with design goals rather than features, which tells you what kind of project this is. The goals are use of a dedicated device, where a Raspberry Pi 3 or later, an n100 mini PC or a virtual machine work fine; a minimum of 1GB of RAM and 16GB of disk, with the SD card for Raspberry Pis, 4GB of RAM working better, and larger SD cards such as 64GB recommended for longevity and to prevent logs from filling up the disk; current Raspberry Pi OS, where the Lite version will suffice, or current version of Ubuntu Linux; easy installation and configuration, and therefore not that configurable; disposable, so when something breaks during an upgrade you re-install from scratch; and minimizing complexity and overhead, with no virtualization like Docker. The last three goals are the design. This is a sensor appliance, not a platform, and the person running it is a security practitioner who wants to contribute data rather than build a service.

The install script and what it changes on your machine

The install.sh script is the centre of the project and the README lists what it does. It disables IPv6 on the Pi. It enables firewall logging and submission of logs to DShield. It changes your SSH server to listen on port 12222. It installs the SSH honeypot Cowrie for SSH and installs the HTTP honeypot called isc_agent. And it installs the needed environment, including Python packages and stunnel for https. The repository layout backs this up, with an etc directory holding the configuration, a lib directory, an srv directory for the status script, a bin directory, a dict directory, docs for the installation guides, and a terraform directory with a separate README_Terraform.md for infrastructure-as-code deployments. The Dockerfile at the root is a thin wrapper around the same script on ubuntu:18.04, exposing 2223, 2222 and 8000.

Placement: why the sensor has to face the internet

The hints section is the most consequential part of the README, and it explains a constraint that surprises people. The sensor and honeypot is meant to only analyze Internet-related traffic, that is traffic issued from public IP addresses. The stated reasons are that this is due to how the DShield project works, since it is a collection of information about the current state of the Internet, that only in this way can information which is interesting for the Internet security community be gathered, and that only in this way can it be ensured that no internal, non-public information is leaked from your Pi to DShield. So the machine must sit on a network where it can be exposed to the internet, and will not be connected to from inner networks except for administrative tasks. For a home user the usual option in the DSL or cable router is to direct all traffic from the public IP to an internal IP, a feature named exposed host or DMZ, and the README warns that further configuration may be needed to ensure all traffic is routed to the Pi rather than only port 80. For enterprises a protected DMZ is the right place, so that if the sensor is hacked the incident is contained. There is a warning there worth reading: with static IPs you are exposing attacks and scans to your address, trackable via whois to your company.

Running and updating the installation

Operating system specific instructions live in the docs directory, with files for Raspberry Pi OS, which is the recommended path, Ubuntu, openSUSE and AWS. The current version is only tested on Raspberry Pi OS 64-bit and Ubuntu 24.04 LTS Server, and the README is blunt about the rest: it is not tested on other distributions, and if there is a need for other distros, someone has to check and maintain the installation script. Normal updates happen inside the dshield directory created by the clone.

cd install/dshield
sudo git pull
sudo bin/install.sh --update

The --update parameter automatically uses the existing configuration and does not prompt for configuration options, and configuration parameters such as your API Key are retained. To change the configuration you edit /etc/dshield.ini, and to configure the firewall you edit /etc/network/iptables, where the nat table is also used. A new feature added for automatic updates is that at the end of the installation the script searches for the file /root/bin/postinstall.sh and executes its content if it exists, which needs execute rights, and that is where extra changes to newly installed files belong. One manual chore remains: keeping special port and network configuration up to date, such as manually configuring recently added telnet or web ports, which cannot be done automatically as of now.

Checking that logs are actually arriving

Troubleshooting starts with verifying data flow, and the README gives three concrete checks. Logs are sent twice an hour to the dshield portal by the cron job /etc/cron.d/dshield, which can be verified from My Account and then My Reports. There is a status script whose output you should look at, at /srv/dshield/status.sh. And for strange Python or pip related errors during installation or updates, the README suggests running a pipeline as root that upgrades every local package except editable installs.

pip freeze --local | grep -v '^\-e' | cut -d = -f 1  | xargs -n1 pip install -U

The project also maintains a Trouble Shooting Guide in docs/general-guides, and a STATUSERRORS.md file at the repository root, plus an ACKNOWLEDGEMENTS.md and a privacy.md. The privacy document is worth noting for anyone deploying this, since the sensor is sending data about traffic aimed at your address to a third party, and the README's placement guidance is written around that.

Where the DShield sensor is the wrong tool

The design goals themselves tell you when not to use it, and there are three cases. The first is a machine you care about. The disposable goal means that when something breaks during an upgrade you re-install from scratch, and the placement guidance tells you to put the device in a DMZ so that if it is hacked the incident is contained. Running this on a production host is not what it is for. The second is a honeypot you want to customise. Easy installation and configuration, and therefore not that configurable, is an explicit goal, and the TODO list still contains enabling other honeypot ports than ssh, doing the user input at the beginning of the script, creating an update script and moving tools such as status.sh into the /srv directory structure. The project is happy to be opinionated in exchange for being installable by someone who is not going to maintain it. The third is anyone without a spare public address. The sensor has to receive traffic from the internet to produce data, and for a home connection that means putting the machine in the router's DMZ or exposed host, which changes the risk profile of the whole site. For a security team with a perimeter network and staff to run it, that trade is worth it. For an individual on a laptop, it is not.

The development instance for testing detection

The last part of the README describes a development instance with web.py and sitecopy.py, which is a deliberately vulnerable local target used to check that the sensor detects what it should. sitecopy.py copies a site and serves it through the web.py script.

python sitecopy.py http://www.yoursite.com

The README notes that it will not change the links at this time, and that any data posted or user request strings will be logged to the DB webserver.sqlite file. web.py does not need sitecopy running and serves a very basic page that can accept input and files, with the stated todos being to work out how to serve up vulnerable pages, probably from the path, to use a separate dorked database for SQL injection, and other items. That file is a test fixture rather than part of the sensor, and it is the piece of the repository that should never be exposed. The licence is GPL-2.0 with the text in the LICENSE file, and the last push to the repository was on 2026-10-05, with no GitHub releases, so the version history is the commit log rather than a release list.

Editorial conclusion

Adopt the DShield sensor if you can dedicate a machine to being publicly exposed and want your firewall logs to contribute to internet-wide attack data. Skip it if you need a honeypot you can tune, since the design goals call for a disposable device that is not that configurable. Before you deploy, read the placement guidance about DMZ hosting, and set up the router to forward all traffic to the sensor rather than only selected ports.

Frequently asked questions

Official sources

1. DShield-ISC/dshield on GitHub
2. Issues
3. License: GPL-2.0
4. Project website
5. README