SiteNetX

SiteNetX is a Linux network appliance for connecting one commissioning computer to several isolated site networks, internet sources, and selective VPN routes. Milestone 6 adds recent password verification, authenticated exact-plan confirmation, and a deterministic non-privileged simulated preflight. Confirmation and simulation remain non-executing; effective state is not_applied.

Build and test

The pinned build toolchain is Go 1.27.1 with a Go 1.26 module compatibility floor. Node.js 20.19 or later is required for Vite.

npm --prefix web ci
make test
make build
make test-cross
make test-e2e

The application uses the pure-Go modernc.org/sqlite v1.58.0 driver, so both AMD64 and ARM64 builds retain SQLite support without a C cross-compiler.

Runtime data

The database path is mandatory, absolute, and explicitly supplied with the -database flag. Keep it outside the repository in a private directory. Runtime database, journal, WAL, shared-memory, lock, and backup files are ignored by Git.

The accepted Milestone 2 database remains preserved and must not be used by a process that could write or migrate it:

/var/lib/sitenetx-m2/sitenetx.db

The accepted Milestone 4 database is preserved unchanged at /var/lib/sitenetx-m4/sitenetx.db (schema 3, configuration revision 8). The accepted, onboarded Milestone 5 database is preserved at /var/lib/sitenetx-m5/sitenetx.db (schema 4, configuration revision 8). Its administrator remains in place and its temporary bootstrap and review-TLS files have been removed.

Milestone 6 migration and review use the separate private copy at /var/lib/sitenetx-m6/sitenetx.db. Migration 005 preserves the administrator verifier and desired revision while adding session-scoped recent authentication, exact confirmation state, and structured simulated-preflight history.

systemd creates /var/lib/sitenetx-m2 with mode 0700. The database and SQLite sidecar files use mode 0600. The intended future production path is:

/var/lib/sitenetx/sitenetx.db

For a manual laboratory process, create private database and bootstrap files. Generate the device-specific temporary credential locally and do not place its value on the command line:

install -d -m 0700 /tmp/sitenetx-dev
openssl rand -hex 32 > /tmp/sitenetx-dev/bootstrap-credential
chmod 0400 /tmp/sitenetx-dev/bootstrap-credential
./bin/sitenetx -listen 127.0.0.1:8080 -mode lab -lab-config config/lab.json -database /tmp/sitenetx-dev/sitenetx.db -bootstrap-credential-file /tmp/sitenetx-dev/bootstrap-credential -insecure-lab-cookie

The deterministic simulator is disabled by default. It can be injected only in explicit laboratory mode with -preflight-engine deterministic-fake; production rejects that selection. Production mode has no preflight engine and returns a categorical unavailable response.

Production mode has no dependency on the lab exclusion file and requires TLS. Certificate and bootstrap paths are references; no secret value is accepted as a command-line argument. A physical appliance binds management to the address owned by its configured Laptop connection:

./bin/sitenetx -listen <product-laptop-ip>:8443 -mode production -database /var/lib/sitenetx/sitenetx.db -bootstrap-credential-file /run/credentials/sitenetx.service/bootstrap -tls-cert-file /run/credentials/sitenetx.service/tls-cert -tls-key-file /run/credentials/sitenetx.service/tls-key

API and behavior

• GET /api/v1/health and GET /api/v1/auth/status are the only unauthenticated reads. POST /api/v1/auth/bootstrap performs single-use onboarding; POST /api/v1/auth/login, GET /api/v1/auth/session, and POST /api/v1/auth/logout manage the one local administrator's browser session.
• POST /api/v1/auth/reauthenticate verifies the administrator password for only the current session's five-minute recent-authentication window.
• POST /api/v1/plan-confirmations, GET /api/v1/plan-confirmations/current, GET /api/v1/plan-confirmations/history, and POST /api/v1/plan-confirmations/revoke manage acknowledgement of one exact ready-for-review plan. Confirmation expires after 15 minutes and never authorizes execution.
• POST /api/v1/simulated-preflights, GET /api/v1/simulated-preflights/current, and GET /api/v1/simulated-preflights/history run/read only the explicitly injected deterministic model simulator. simulation_passed means preflight model validated, never safe to apply.
• All adapter, role, profile, candidate-plan, and detailed diagnostic surfaces require an opaque browser session. Every mutation also requires its session-bound X-SiteNetX-CSRF value; existing expected-revision checks still apply.
• GET /api/v1/adapters returns current observations combined with saved desired roles and an explicitly not-applied effective state.
• GET /api/v1/network-plan returns schema-versioned desired, observed, proposed, and not_applied effective state, with typed future operations, blockers, warnings, explanations, safety invariants, verification, rollback intent, and deterministic fingerprints.
• GET /api/v1/connection-profiles returns the saved role-specific profiles, named health-policy catalog, configuration revision, environment, and not_applied effective state.
• POST /api/v1/connection-profiles atomically creates, updates, or explicitly clears the complete profile set using mode: "replace_all" and expectedRevision.
• POST /api/v1/connection-profiles/clear clears one adapter-owned profile; POST /api/v1/connection-profiles/firewall/clear clears forwarding intent. Both require expectedRevision.
• GET /api/v1/role-assignments returns saved assignments, quarantined records, the current configuration revision, and redacted audit entries.
• POST /api/v1/role-assignments assigns Laptop, Site network, or Internet intent.
• POST /api/v1/role-assignments/clear removes one saved role.
• POST /api/v1/role-assignments/move-laptop atomically moves the single Laptop role.

The candidate-plan endpoint is read-only. Its optional staleness check accepts expectedPlanFingerprint, expectedDesiredRevision, and expectedObservationFingerprint only when all three are present and exact. A complete saved profile set may make the candidate ready_for_review; confirmation then binds its exact schema, plan/desired/observation fingerprints, desired revision, administrator, acknowledgement version, expiry, and server-produced safety summary. No apply, execute, command, or privileged endpoint exists.

All role mutations require expectedRevision. Stale writes and a second ordinary Laptop assignment return structured conflicts. Roles bind to qualified stable identity, never Linux interface name. OOB and other excluded observations cannot receive product roles.

Local authentication, confirmation, and simulated preflight do not change profile or role intent, candidate fingerprints, interface state, addresses, DHCP, DNS, routes, firewall rules, forwarding, IPv6 policy, network-manager ownership, health state, or VPNs. Profiles entered in lab mode remain labelled lab-only rather than production defaults; Linux names remain display-only and never choose profile ownership.

Milestone 5 was closed out at commit b0abfc27d4fc5d153a015dbd4f9ad07a0f0f5dfb after successful onboarding through direct development-laboratory OOB HTTPS at:

https://10.76.20.50:8443/

The Milestone 5 and Milestone 6 transient review services are stopped, port 8443 is no longer listening, and their temporary TLS material has been removed. The schema-5 Milestone 6 database copy remains preserved. During review, the Milestone 6 service used the same direct OOB HTTPS URL and injected only the deterministic fake preflight engine in explicit lab mode.

Direct OOB access is laboratory transport only. It does not prove Laptop-side product networking and does not make ens18, its address, or its route part of SiteNetX product state. Production management remains owned by the configured Laptop connection. The current frontend remains an engineering scaffold without final product-design approval. Milestone 6 does not add privileged transport, real preflight, apply/rollback execution, network commands, health probes, DHCP/DNS, routes, forwarding, firewall, or VPN behavior.