LANimals

Local network intelligence platform — self-hosted, operator-driven, terminal-native.

LANimals discovers devices inside an explicitly approved private LAN scope, keeps durable host/service/event history, surfaces identity changes for review, fingerprints services, scores explainable risk signals, and exposes the resulting state through a local browser console and CLI.

The supported product is the self-hosted LANimals appliance. The public/hosted site is a representative workflow surface only: a normal hosted browser cannot directly inspect a visitor's LAN, so hosted mode never claims that it can.

The machine-readable source of truth is capabilities.json. CI checks that contract against the supported runtime, routes, command grammar, evidence paths, version, and hosted-demo boundary.

./scripts/demo.sh

Personality overlay mode assigns heuristic interface labels such as scout, mimic, parasite, and leech from configured risk signals. These labels are triage aids, not claims about device intent or behavior.

• Linux; Pop!_OS / Ubuntu are the tested path
• Python 3.10+
• python3-venv
• nmap
• iproute2
• optional VT_API_KEY for VirusTotal enrichment

Install system requirements on Debian/Ubuntu-family systems:

sudo apt install python3-venv nmap iproute2

git clone https://github.com/GnomeMan4201/LANimals.git
cd LANimals
./install.sh

install.sh creates an isolated .venv inside the checkout and links the checkout-aware LANimals commands into ~/.local/bin. It refuses to overwrite a real file already using one of those command names.

LANimals is intentionally checkout-first. The CLI, browser UI, assets, runtime, and local appliance lifecycle are operated together, so pip install . is not advertised as a supported installation path.

For unattended installation with an explicit scope:

./install.sh --scope 192.168.1.0/24

LANimals fails closed until an approved private network scope exists.

lanimals setup
# or explicitly:
lanimals setup 192.168.1.0/24

lanimals doctor
lanimals start

The local browser console is served at:

http://127.0.0.1:8080

Starting the appliance does not automatically scan the network. Collection begins only after an operator action.

Useful lifecycle commands:

lanimals status
lanimals open
lanimals config
lanimals stop

The dispatcher resolves its own checkout, so these commands can be run from any working directory after installation.

The supported v2.1 operator path is the local appliance plus its scoped collectors and persistent evidence store.

approved private CIDR
        │
        ▼
 scoped collectors
 nmap / ARP / host map / services
        │
        ▼
 normalization + SQLite evidence
        │
        ├── events / baseline review
        ├── services / notes / history
        └── explainable risk scoring
        │
        ▼
 FastAPI operator boundary
        │
        ├── local browser console
        └── allowlisted terminal bridge

Primary operations:

The self-hosted interface includes:

• force-directed network graph
• per-host identity, MAC/vendor, service, risk, timeline, and notes views
• hosts, events, and system-information views
• explicit baseline accept/defer decisions with an audit trail
• local HTML report export
• optional VirusTotal enrichment
• honest empty state by default

Synthetic graph data is available only when explicitly enabled with:

LANIMALS_DEMO_MODE=1 lanimals start

LANimals is designed to make the collection boundary visible rather than implicit.

• Scan targets must resolve inside the approved private CIDR.
• The appliance binds to 127.0.0.1:8080 by default.
• A non-loopback bind is refused unless both LANIMALS_HOST and LANIMALS_ALLOW_REMOTE=1 are explicitly set.
• The browser terminal is an allowlisted LANimals command bridge, not an OS shell.
• State-changing API requests require X-LANimals-Operator: 1.
• That header is a localhost/cross-site request boundary; it is not remote-user authentication.
• If remote access is required, put LANimals behind authenticated network access rather than treating the operator header as authentication.

See SECURITY.md for the security policy and reporting guidance.

LANimals separates durable evidence, configuration, logs, and disposable scan state using XDG paths:

${XDG_CONFIG_HOME:-~/.config}/lanimals/config.json
${XDG_DATA_HOME:-~/.local/share}/lanimals
${XDG_STATE_HOME:-~/.local/state}/lanimals
${XDG_CACHE_HOME:-~/.cache}/lanimals

The SQLite evidence store and durable state remain outside the checkout. Moving, replacing, or updating the repository does not move or delete that evidence.

On the first v2.1 start, LANimals can non-destructively import supported v2.0 checkout-relative state when the new XDG destination is empty. Legacy files are left untouched as a recovery copy.

The browser console uses the same local API boundary exposed by the appliance. Important route groups include:

GET  /api/health
GET  /api/scope
GET  /api/graph
GET  /api/hosts
GET  /api/events
GET  /api/sysinfo
GET  /api/baseline
GET  /api/jobs/{id}
POST /api/export/report

POST /api/scan/discovery
POST /api/scan/arp
POST /api/scan/hostmap
POST /api/scan/rogue
POST /api/scan/services/{ip}
POST /api/scan/inventory
POST /api/scan/anomaly
POST /api/scan/cve/{ip}
POST /api/scan/rescore
POST /api/enrich/vt/{ip}

PATCH /api/hosts/{ip}/notes
POST  /api/baseline/accept
POST  /api/baseline/defer

capabilities.json is authoritative when documentation and implementation disagree.

LANimals predates the current appliance architecture. Several standalone alerting, traffic, visualization, fortress, hunting, and advanced research scripts are intentionally preserved for lineage and experimentation.

They are not automatically promoted to supported appliance capabilities merely because a CLI wrapper still exists. Their status is experimental_legacy until they are brought behind the same scope, persistence, error-handling, and automated-test contracts as the v2.1 operator path.

This distinction is deliberate: the repository should never imply that an old experiment has the same support level as a machine-checked appliance capability.

CI runs on Python 3.10 with the required Linux network tooling and executes both the automated test suite and appliance smoke test:

pytest tests/ -v --tb=short
bash scripts/smoke_appliance.sh

The smoke path verifies the local browser-appliance lifecycle in addition to unit and contract coverage.

capabilities.json defines three explicit states:

• implemented_tested — supported runtime behavior with automated contract coverage
• implemented_local_runtime — implemented but dependent on the local Linux/network environment or optional credentials
• experimental_legacy — preserved research code outside the supported operator path

That file is the boundary between what LANimals does, what requires the local appliance, and what remains research lineage.

See CONTRIBUTING.md for contribution scope, safety requirements, validation commands, and capability-contract rules.

Independent fresh-install and scope-contract replication is tracked in Issue #21. A successful external report strengthens confidence in the documented supported path without being treated as proof of compatibility with every environment.

LANimals // badBANANA research // GnomeMan4201