dshield is a collection of scripts that turn a dedicated Raspberry Pi or Ubuntu box into an automated honeypot sensor running Cowrie SSH and an HTTP honeypot, submitting firewall logs to the DShield portal for the security community.
| Tool | DShield-ISC/dshield — automated installer and configuration scripts for a DShield honeypot sensor (536 stars, GPL-2.0, Python) |
| Category | Honeypot / network telemetry collection |
| Primary Use | Deploying a dedicated Internet-exposed sensor that runs Cowrie SSH and an HTTP honeypot and submits firewall logs to the DShield portal twice an hour |
| Safe Use | Defensive research and community threat-intelligence contribution: operators place the sensor on networks they own or administer, in a DMZ or exposed-host configuration, to document Internet scanning activity for authorized security research |
| Telemetry Note | The sensor is deliberately loud and visible: it changes sshd to port 12222, disables IPv6, logs to /var/log/dshield.log, and ships summaries via the cron job /etc/cron.d/dshield — attackers who compromise it will interact with emulated, contained services |
dshield is the official tooling behind the Internet Storm Center's volunteer sensor network, a project that has aggregated firewall and honeypot logs from thousands of contributors for over two decades. The repository, maintained under the DShield-ISC organization and licensed GPL-2.0, is not an attack tool at all — it is a defensive instrumentation package. What it does is take a bare Raspberry Pi or Ubuntu server and turn it into a disposable, deliberately Internet-exposed sensor whose job is to absorb scans, brute-force attempts, and exploit probes, then normalize that telemetry and ship it to the DShield portal where it becomes part of the collective picture of malicious Internet activity. The README frames it explicitly as a contribution to the Internet security community, and every design decision in the installer reflects that mission.
The stated hardware requirements are modest but specific: a dedicated device — Raspberry Pi 3 or later, an n100 mini PC, or a virtual machine — with a minimum of 1GB RAM and 16GB of storage, though the authors recommend 4GB RAM and a larger SD card (64GB is suggested) so logs don't fill the disk. The emphasis on "dedicated" and "disposable" is repeated twice in the design goals, and it matters: the sensor is expected to be attacked, potentially compromised, and rebuilt from scratch. When something breaks during an upgrade, the recommended fix is reinstallation, not repair. There is also a deliberate refusal of virtualization — no Docker containers — in the name of minimizing complexity and overhead, which tells you the authors prioritize a small, auditable attack surface on the sensor itself over deployment convenience.
Platform support is deliberately narrow. The current version is tested only on Raspberry Pi OS 64-bit ("Lite" is sufficient) and Ubuntu 24.04 LTS Server, and the README is blunt that other distributions are unsupported unless "someone" steps up to maintain the installation script for them. Install guides exist for Raspbian (recommended), Ubuntu, openSUSE, and AWS under docs/install-instructions/. Two other constraints shape placement: internal networking is IPv4 only, and the sensor expects exactly one network interface such as eth0. These limitations are the kind of scoping decision a mature project makes — the sensor does one thing in a known environment rather than trying to be general-purpose.
The heart of the repository is install.sh, and the README enumerates exactly what it does to the system. It disables IPv6, enables firewall logging with automated submission of logs to DShield, moves the real SSH server to port 12222, installs the well-known Cowrie SSH honeypot in its place on the standard port, installs an HTTP honeypot called isc_agent, and pulls in the supporting environment of Python packages and stunnel for HTTPS. This is a classic port-swap honeypot layout: legitimate administration moves out of the way, and everything that knocks on the default doors gets an emulated service that looks vulnerable while recording the interaction. The real SSH daemon remains reachable for the operator, just on a nonstandard port.
After deployment, the sensor operates largely autonomously. Firewall logs are sent twice an hour to the dshield portal by the cron job at /etc/cron.d/dshield, and submission can be verified through the portal's "My Reports" page. Local visibility comes from /srv/dshield/status.sh, which reports sensor health, and raw events land in /var/log/dshield.log. Configuration persists in /etc/dshield.ini — including the operator's DShield API key — while firewall rules live in /etc/network/iptables with the NAT table also in play. This clean separation of config, firewall state, and log output makes the sensor reasonably easy to reason about even though the install is automated and, by the authors' own admission, "not that configurable."
Updates follow the same philosophy. From inside the cloned directory, the operator runs sudo git pull followed by sudo bin/install.sh --update, which reuses the existing configuration without prompting. A nice operational touch is the hook: if /root/bin/postinstall.sh exists and is executable, the installer runs it at the end, giving operators a sanctioned place to re-apply local customizations after each rebuild. The README warns that newly added honeypot ports — telnet and web ports are mentioned — may need manual firewall adjustments, and that the surest fallback is deleting the relevant lines from /etc/dshield.ini and re-running the installer.
The placement guidance in the README is the most interesting section from a tradecraft standpoint, because it is fundamentally about privacy and containment rather than collection volume. The sensor is meant to see only public Internet traffic, never connections from internal networks, for two reasons: DShield's dataset is about the state of the Internet, and — more importantly — restricting exposure to public sources ensures no internal, non-public information leaks from the Pi to DShield. For SoHo users this means configuring the router's "exposed host" or DMZ option to forward all traffic from the ISP-assigned public IP to the Pi, not just selected ports. For enterprises, the recommendation is a protected DMZ segment so that if the honeypot is hacked, the blast radius is contained.
There is also an honest disclosure about attribution: with static IPs, you are exposing the attacks against your address to the DShield project and community, and your organization can be tracked via whois. This is the kind of caveat that separates a serious community project from a toy — contributors should understand that their participation is not anonymous at the network level. The README even asks operators who want to verify their setup with an external port scan to keep testing brief and limited, so the shared dataset isn't falsified by synthetic scans. Community standards are enforced as much by documentation as by code here.
Troubleshooting documentation is practical. Beyond the status script and log inspection, the README offers a pip-specific remedy for Python errors during install or update — as root, pip freeze --local | grep -v '^\-e' | cut -d = -f 1 | xargs -n1 pip install -U — which force-refreshes the local Python package set. A dedicated troubleshooting guide lives at docs/general-guides/Troubleshooting.md. The TODO list is refreshingly candid: enabling honeypot ports beyond SSH, packaging updates better, moving tools like status.sh into a cleaner /srv directory structure, and restructuring the installer so all user input happens up front before long-running steps execute.
The repository also contains experimental developer tooling that hints at the project's direction. sitecopy.py clones an arbitrary site — python sitecopy.py http://www.yoursite.com is the documented example — and web.py serves the copy locally, logging any posted data or request strings to a webserver.sqlite database. The stated ambitions include serving deliberately vulnerable pages, an SQL injection dork database, and eventually integrating with Cowrie for shell-level attack capture, which the author labels a big hairy audacious goal. Even unfinished, this shows the HTTP honeypot evolving from a generic page into something that can capture web-application attack telemetry, not just connection logs.
For defenders, dshield occupies a distinct niche: it is not a detection tool for your production network but a measurement instrument for the Internet at large, and running one is one of the lowest-friction ways an authorized professional can contribute original threat intelligence. Every compromise attempt against the sensor is contained by emulated services, every credential guessed at Cowrie is a data point, and the aggregate feeds the ISC's daily attack charts and research. The operational discipline the README demands — dedicated hardware, public-only exposure, DMZ containment, disposable rebuilds — is itself a useful template for anyone deploying any honeypot. An active Slack community accessible via dshield.org/slack rounds out the support story for what is one of the longest-running citizen-science projects in security.
DShield-ISC/dshield.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.