The Problem
Enterprises and hobbyist homelabs need a lightweight way to discover devices on one or many sub‑nets, keep persistent labels (e.g., “Server”, “IoT”), and view the data through a single UI. Existing tools either require heavyweight agents or lack a simple CLI/web combo, making inventory audits tedious and error‑prone.
What This Does
LAN‑Orangutan bundles an nmap‑based scanner with a Go‑implemented REST API and a minimal web dashboard. The core binary lives in cmd/orangutan/main.go; it wires together the CLI (internal/cli/), the scanner (internal/scanner/scanner.go + Python helpers in scanner/scan.py), and the web server (internal/web/handler.go). Persistent device data is stored by internal/storage/storage.go and typed definitions reside in internal/types/types.go.
The web assets are static files under internal/web/static/ and HTML templates in internal/web/templates/. A separate PHP front‑end (web/.php) is provided for environments that prefer a LAMP stack. Tailscale integration is handled in internal/network/tailscale.go, allowing the scanner to operate across VPN‑linked sub‑nets without extra routing.
How To Use It
Setup – Build the single binary or run the Docker image. The repository supplies a Dockerfile and a Makefile target:
Build locally
go build -o orangutan ./cmd/orangutan
Or containerise
docker build -t lan-orangutan .
Configuration – Copy config.example.ini to the platform‑specific location (e.g., ~/.config/lan-orangutan/config.ini) and adjust sections such as [network] or [tailscale]. The CLI reads this file via internal/cli/config.go.
Running – The binary exposes sub‑commands defined in internal/cli/.go. Typical usage (mirrored in the README) is:
Scan the default network (requires sudo for MAC/vendor data) sudo ./orangutan scan
Scan a specific CIDR
sudo ./orangutan scan 192.168.1.0/24
Start the web UI on the default port 291 sudo ./orangutan serve
Custom port
sudo ./orangutan serve --port 8080
List devices, JSON output
orangutan list --format json
The Docker image can be started with:
docker run -d -p 291:291 --cap-add=NETRAW --cap-add=NETADMIN \ -v $HOME/.config/lan-orangutan:/config lan-orangutan serve
Dependencies – Go modules are declared in go.mod; Python‑side scanning utilities require the packages listed in scanner/requirements.txt (e.g., python-nmap). The CI pipeline (.github/workflows/ci.yml) runs go test ./... (though no test files exist) and builds the Docker image.
Real‑World Use
A small office network runs a Raspberry Pi as a host:
Initial install
curl -L https://github.com/291-Group/LAN-Orangutan/releases/download/v1.2.0/lan-orangutan-linux-amd64.tar.gz | tar xz sudo ./orangutan serve --port 8080 &
A nightly cron job invokes sudo ./orangutan scan all and pipes JSON output to a CMDB ingestion script. The web UI (http://office-pi:8080) lets staff tag new printers or IoT sensors without touching the scanner code.
Code Health & Issues
Medium – No test suite – Repository contains zero _test.go files; CI still runs go test, providing no coverage verification. Low – Limited input validation – CLI parsers in internal/cli/*.go trust raw arguments (e.g., CIDR strings) before passing to the scanner, increasing risk of malformed input causing runtime errors. Medium – External Python dependency – scanner/scan.py relies on the system nmap binary and Python packages; the Dockerfile does not install them, so the container image may fail at runtime unless the user extends it. Low – License present but not referenced in CI – MIT license exists, yet CI does not enforce SPDX headers, which could cause compliance checks downstream. Medium – Secrets handling – No .env.example or secret management guidance; Tailscale keys, if required, must be placed manually in the config, risking accidental commit. Low – Documentation gaps – docs/INSTALL.md and docs/TROUBLESHOOTING.md are present, but API endpoints lack Swagger/OpenAPI definitions, limiting automated client generation.
The Bottom Line
LAN‑Orangutan delivers a functional, single‑binary network discovery tool with both CLI and web interfaces, suitable for small to medium homelabs or edge deployments. The codebase is cleanly organized but lacks automated tests and has a few operational gaps (Python dependency handling, input validation). Teams comfortable adding modest test coverage and tightening Docker builds will find it a practical, low‑overhead solution for device inventory and labeling.