Bjorn on a Raspberry Pi: an autonomous network scanner behind a 2.13-inch e-Paper HAT

The gap Bjorn fills: an unattended scanner you can leave on a shelf

Most network scanning is a command you run and watch. Bjorn is built around the opposite assumption. It is a Python application for a Raspberry Pi with a 2.13-inch e-Paper HAT, and the README describes it as a Tamagotchi-like autonomous tool: it discovers live hosts, identifies open ports, runs vulnerability scans through Nmap, attempts brute-force attacks against FTP, SSH, SMB, RDP, Telnet and SQL, and extracts files from services it gets into. The display shows status indicators, and a web interface serves the rest.

The target user is narrow. You need a Raspberry Pi, a compatible e-Paper HAT wired to the GPIO pins, and a network you are authorized to test. The README states the project is for educational and authorized testing purposes only, and that restriction is not decorative: the tool ships brute-force modules and file-stealing actions, so running it against hosts you do not control is the whole failure mode. If you want a scanner you invoke from a laptop, Bjorn's appliance shape is overhead rather than an advantage.

How Bjorn actually works: an orchestrator, an action library and a display loop

The repository layout is the clearest description of the architecture. Bjorn.py is the entry point. orchestrator.py coordinates work, actions/ holds the attack and scan modules, config/ holds settings, and display.py plus epd_helper.py drive the e-Paper panel. webapp.py and the web/ directory serve the browser interface. shared.py and init_shared.py carry state that the modules share, and logger.py writes output.

Results land in data/output/, which the README says is organized automatically and viewable through both the display and the web interface. The dependency list confirms the mechanism rather than the marketing: python-nmap wraps Nmap, paramiko handles SSH, pysmb and smbprotocol handle SMB, pymysql and sqlalchemy handle database access, ping3 and get-mac handle host discovery and MAC resolution, and Pillow with numpy and spidev drive the panel over SPI. RPi.GPIO is pinned at 0.7.1. Nothing in that list suggests a daemon with a scheduler; the autonomy comes from the orchestrator sequencing actions against discovered targets. The README's usage example, which it labels a fake demo for illustration, shows the intended flow: discovery, then vulnerability scanning, then brute force, then file extraction.

Installing Bjorn on Raspberry Pi OS and reaching the web UI

The prerequisites are specific. Raspberry Pi OS 32-bit with kernel 6.6 and Debian 12 (bookworm), from the 2024-10-22-raspios-bookworm-armhf-lite image, with the username and hostname both set to bjorn. For the Pi Zero W2 64-bit build, the README says the author did not develop for it but that feedback reports the installation worked. The README also states that e-Paper screen v2 and v4 have been tested and implemented, and that v1 and v3 are expected to behave the same, which is an expectation rather than a verified claim.

The documented installation path is a shell script fetched from the repository and run with sudo:

wget https://raw.githubusercontent.com/infinition/Bjorn/refs/heads/main/install_bjorn.sh
sudo chmod +x install_bjorn.sh && sudo ./install_bjorn.sh

The README says to choose option 1 for automatic installation, that it may take a while because many packages and modules are installed, and that a reboot is required at the end. INSTALL.md is the reference for anything the script does not cover.

After the reboot, the README points to a companion project, infinition/bjorn-detector, for finding Bjorn's IP and launching SSH. The web interface is served by webapp.py; the repository also contains kill_port_8000.sh, which is consistent with the web app binding to port 8000, though the README does not document the port or the URL to open. Treat the IP and port as something you confirm on your own device rather than something the documentation hands you.

For configuration, the config/ directory is where settings live, and requirements.txt shows what the installer is pulling in:

pip install -r requirements.txt

That is useful for a manual install, but the README's supported path is the script.

Where Bjorn breaks: hardware assumptions, a single release and no rollback story

The strongest constraint is hardware. Bjorn needs a 2.13-inch e-Paper HAT on the GPIO header, and only v2 and v4 panels are documented as tested. If you have a v1 or v3 board, the README offers hope and nothing else. If you have no HAT at all, you are outside the design.

The second constraint is the operating system. The prerequisites name one specific Raspberry Pi OS image and a kernel version. That is a snapshot, not a support matrix, and the README does not describe what happens on a newer Debian release.

Third, the release history is thin. The only release listed is v1.0.0 from 2025-12-02, tagged as the original version. The repository is not archived and the last push was on 2026-07-20, so work continues, but there is no pattern of versioned releases to read. The README does not document rollback, and uninstall_bjorn.sh exists in the tree without an explanation in the README of what it removes. If an upgrade goes wrong on a headless Pi, the troubleshooting document is your starting point, not a downgrade procedure.

Finally, the offensive modules are a liability in mixed environments. An autonomous brute-force run against the wrong subnet is not a bug you patch; it is a decision you made when you powered the device on.

Bjorn compared with running Nmap and a script from a laptop

The honest alternative is Nmap plus your own orchestration on a general-purpose machine. The difference is not capability, since Bjorn wraps Nmap through python-nmap and adds paramiko, pysmb and pymysql for the follow-up actions. The difference is form factor and persistence. A laptop running Nmap is interactive: you choose the target, read the output, and stop. Bjorn is designed to keep going, writing into data/output/ and reporting through a small e-paper panel and a web page.

That trade favors Bjorn when you want a fixed appliance on a lab network and you want the results collected without you sitting there. It favors the laptop when you need a current Nmap version, a full scripting environment, or an auditable record of exactly which commands ran. Bjorn's value is the packaging, not a scanning technique you cannot get elsewhere.

Licence, upgrade cost and what MIT does not cover

Bjorn is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. That is a permissive position, and it also means the author offers no warranty. For a tool that performs brute-force attacks and file extraction, the licence text is not where your risk lives; your authorization to test the target network is. Nothing in the repository grants that.

Upgrade cost is real because of the pinned dependencies. RPi.GPIO 0.7.1, Pillow 9.4.0, numpy 2.1.3 and the rest are fixed versions, and the e-paper driver code in epd_helper.py is tied to the panels the author tested. Moving to a newer Raspberry Pi OS or a different HAT means working through the display layer yourself. The repository gives you INSTALL.md, TROUBLESHOOTING.md and the install script; it does not give you a migration guide.

Editorial conclusion

Adopt Bjorn only if you own the network, want a fixed Raspberry Pi appliance with an e-Paper HAT, and accept a project whose last push was on 2026-07-20 with a single v1.0.0 release. Do not deploy it on production or client networks, and do not expect a packaged, reviewed distribution. Before flashing anything, read INSTALL.md and TROUBLESHOOTING.md, confirm your HAT is a v2 or v4 board, and set the username and hostname to bjorn as the prerequisites require.

Frequently asked questions

Official sources

1. infinition/Bjorn on GitHub
2. License: MIT
3. Project website
4. README
5. Releases