Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@ GHOSTNODE_INTELLIGENCE_DB=./data/staking_intelligence.sqlite3
GHOSTNODE_DASHBOARD_MODE=localhost
GHOSTNODE_DASHBOARD_LAN_ADDRESS=
GHOSTNODE_DASHBOARD_PORT=44678
# Required only for localhost_lan; keep the token outside the repository.
# LAN auth defaults to token_required. trusted_lan is an explicit, risky,
# unauthenticated read-only mode; administrative endpoints still need a token.
GHOSTNODE_DASHBOARD_LAN_AUTH_MODE=token_required
# Required for token_required and administrative LAN operations; keep the token outside the repository.
GHOSTNODE_DASHBOARD_TOKEN_FILE=
GHOSTNODE_NETWORK_CONFIG=~/.config/ghostnode-tools/network.json
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,19 @@
# Changelog

## 0.3.1

- Added an explicit `trusted_lan` mode for direct, unauthenticated read-only
dashboard access on a configured private LAN address.
- Preserved `token_required` as the default for new LAN configurations.
- Kept network settings and other administrative endpoints token-protected in
`trusted_lan` mode.
- Added focused regression coverage for LAN modes, persistence, rollback
compatibility, and wildcard rejection.

`trusted_lan` is intentionally opt-in: every reachable LAN client can read
the dashboard, and plain HTTP does not provide confidentiality. Use it only on
a trusted network; prefer `token_required` or an SSH tunnel otherwise.

## 0.3.0

- Version-neutral README with a latest-release link.
Expand Down
8 changes: 6 additions & 2 deletions CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,16 @@
| `GHOSTNODE_DASHBOARD_MODE` | `localhost` | `localhost` or `localhost_lan` |
| `GHOSTNODE_DASHBOARD_LAN_ADDRESS` | unset | One assigned private LAN IPv4 address; never a wildcard |
| `GHOSTNODE_DASHBOARD_PORT` | `44678` | Unprivileged dashboard TCP port |
| `GHOSTNODE_DASHBOARD_LAN_AUTH_MODE` | `token_required` | `token_required` or explicitly reviewed `trusted_lan` |
| `GHOSTNODE_DASHBOARD_TOKEN_FILE` | unset | Private file containing the LAN bearer token |
| `GHOSTNODE_NETWORK_CONFIG` | `~/.config/ghostnode-tools/network.json` | Private atomically written non-secret settings |

The dashboard always includes `127.0.0.1`. In `localhost_lan` mode it adds
exactly the configured assigned private LAN IPv4 address. LAN mode requires a
bearer token from a private file; there is no default password. Wildcard,
exactly the configured assigned private LAN IPv4 address. LAN mode defaults to
`token_required`, requiring a bearer token from a private file; there is no
default password. Explicit `trusted_lan` permits unauthenticated read-only
access for reachable LAN clients while administrative endpoints remain
token-protected. Wildcard,
multicast, public, loopback-as-LAN, and IPv6 binds are rejected. Network settings
are validated before listeners start and web proposals never apply changes.
Never put RPC passwords, cookies, bearer tokens, seeds, or wallet keys in
Expand Down
10 changes: 7 additions & 3 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,11 +60,15 @@ does not load or unlock wallets.

The dashboard is read-only and defaults to loopback. To enable the optional
dual-address mode, configure `GHOSTNODE_DASHBOARD_MODE=localhost_lan`, an
assigned private `GHOSTNODE_DASHBOARD_LAN_ADDRESS`, and a restrictive
`GHOSTNODE_DASHBOARD_TOKEN_FILE` in a private environment file. The token file
assigned private `GHOSTNODE_DASHBOARD_LAN_ADDRESS`, and
`GHOSTNODE_DASHBOARD_LAN_AUTH_MODE=token_required` (the safe default) with a
restrictive `GHOSTNODE_DASHBOARD_TOKEN_FILE` in a private environment file. The token file
must already exist; GhostNode Tools never generates or logs a default password.
Wildcard, public, multicast, loopback-as-LAN, and IPv6 addresses are rejected.
Plain HTTP on a LAN does not provide confidentiality. For remote viewing,
An explicitly reviewed `trusted_lan` mode allows unauthenticated read-only
access to every reachable LAN client; administrative endpoints still require
the private token. A specific LAN address is not authentication. Plain HTTP on
a LAN does not provide confidentiality. For remote viewing,
localhost mode with an SSH tunnel remains preferred:

```bash
Expand Down
17 changes: 12 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,8 @@ unlocks wallets, or changes node configuration.

No Ghost Core connection is required for M1.

v0.3.0 adds configurable, validated dashboard network access. The portable
v0.3.1 adds an explicitly reviewed trusted-LAN access option on top of the
configurable, validated dashboard network access introduced in v0.3.0. The portable
defaults are `ghost-cli`, `~/.ghost`, and wallet `ghostmain`; they can be
overridden with command options or environment variables.

Expand Down Expand Up @@ -69,8 +70,11 @@ python -m pip install --no-build-isolation --no-deps -e .
The dashboard is read-only and defaults to `127.0.0.1:44678`. It can optionally
bind exactly one explicitly assigned private LAN IPv4 address in addition to
localhost. Wildcard, multicast, public, loopback-as-LAN, and IPv6 addresses are
rejected. LAN mode requires a private bearer token file; there is no default
password and plain HTTP does not provide confidentiality. Keep LAN access on a
rejected. LAN mode defaults to `token_required`, using a private bearer token
file; there is no default password and plain HTTP does not provide
confidentiality. An explicitly selected `trusted_lan` mode permits
unauthenticated read-only access to every client that can reach the configured
private address. Keep LAN access on a
trusted network or use HTTPS/SSH tunneling as appropriate.

The dashboard groups diagnostics into Blockchain, Network, System, Service,
Expand Down Expand Up @@ -138,8 +142,11 @@ sudo systemctl disable ghostnode-dashboard.service

The unit runs as `etcmc`, uses the project `.venv`, and reads dashboard network
settings from its private environment file. Localhost is the default. To use
LAN mode, configure a private token file and an explicitly assigned LAN IPv4
address; never use `0.0.0.0` or expose the dashboard publicly.
For authenticated LAN mode, configure a private token file and an explicitly
assigned LAN IPv4 address; never use `0.0.0.0` or expose the dashboard publicly.
The explicit `trusted_lan` mode is an operator decision and does not protect
read-only data from reachable LAN clients; administrative endpoints remain
token-protected.

The intelligence collector unit is separate and is not enabled by default. It
requires a separate operator review, backup, and migration plan.
Expand Down
9 changes: 6 additions & 3 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,12 @@ files, and mainnet reports outside the repository.

The dashboard defaults to `127.0.0.1` and localhost mode has no authentication
because it is loopback-only. Optional LAN mode binds exactly one assigned
private IPv4 address and requires a bearer token from a private file for every
request. It rejects wildcard, multicast, public, loopback-as-LAN, and IPv6
addresses. There is no default password. Plain HTTP on a LAN does not provide
private IPv4 address. New LAN configurations use `token_required`, which
requires a bearer token from a private file for every request. An operator may
explicitly select `trusted_lan` for unauthenticated read-only access, but
administrative endpoints remain token-protected. It rejects wildcard,
multicast, public, loopback-as-LAN, and IPv6 addresses. There is no default
password. Plain HTTP on a LAN does not provide
confidentiality; use an appropriately secured HTTPS layer or SSH tunnel when
needed. This document is not a guarantee of security or legal compliance.

Expand Down
7 changes: 5 additions & 2 deletions docs/GHOST_CORE_SETUP.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,9 @@ encryption passphrase is not guaranteed recoverable.

Keep the dashboard on `127.0.0.1` and use an SSH tunnel for authorized remote
viewing by default. If `localhost_lan` is explicitly configured, use exactly
one assigned private LAN IPv4 address and a private bearer token; plain HTTP
does not provide confidentiality. Never expose Ghost Core RPC directly to the
one assigned private LAN IPv4 address. The safe default is
`GHOSTNODE_DASHBOARD_LAN_AUTH_MODE=token_required`; the explicit
`trusted_lan` mode allows unauthenticated read-only access to reachable LAN
clients while administrative endpoints remain token-protected. Plain HTTP does
not provide confidentiality. Never expose Ghost Core RPC directly to the
public Internet.
21 changes: 15 additions & 6 deletions docs/V0_3_NETWORK_ACCESS.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,31 +12,40 @@ that is not currently assigned to a local interface.

## LAN security

LAN mode requires a bearer token supplied through a private token file. There
is no default password and GhostNode Tools never generates, prints, or commits
the token. Plain HTTP does not provide confidentiality or integrity against a
hostile LAN; use an appropriately secured HTTPS layer or an SSH tunnel when
that matters.
LAN mode defaults to `token_required`, using a bearer token supplied through a
private token file. There is no default password and GhostNode Tools never
generates, prints, or commits the token. An explicitly selected `trusted_lan`
mode allows direct unauthenticated read-only dashboard/API access to every
client able to reach the configured LAN address; state-changing and
configuration endpoints remain token-protected. A specific LAN bind is not an
authentication boundary. Plain HTTP does not provide confidentiality or
integrity against a hostile LAN; use an appropriately secured HTTPS layer or
an SSH tunnel when that matters.

Example private environment settings:

```text
GHOSTNODE_DASHBOARD_MODE=localhost_lan
GHOSTNODE_DASHBOARD_LAN_ADDRESS=192.168.1.100
GHOSTNODE_DASHBOARD_PORT=44678
GHOSTNODE_DASHBOARD_LAN_AUTH_MODE=token_required
GHOSTNODE_DASHBOARD_TOKEN_FILE=/private/path/ghostnode-dashboard.token
```

The token file should be owned by the service account and mode `0600`.

## First-run review

`ghostnode init --json --network-mode localhost_lan --lan-address 192.168.1.100`
`ghostnode init --json --network-mode localhost_lan --lan-address 192.168.1.100 --lan-auth-mode token_required`
prints a proposed configuration. It does not apply it. Applying settings
requires the explicit pair `--apply-network --confirm-network` and writes only
the private non-secret configuration atomically. The dashboard's network
settings endpoint is read-only; its POST endpoint validates proposals but does
not write files or restart services.

For an explicitly reviewed trusted-LAN deployment, use
`--lan-auth-mode trusted_lan`. This does not protect read-only dashboard data
from other reachable LAN clients; keep the mode limited to a trusted network.

Always preserve the previous working configuration, test both listeners, and
keep the existing SSH tunnel or proxy until the replacement is verified.
2 changes: 1 addition & 1 deletion ghostnode/__init__.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
"""GhostNode Tools."""

__version__ = "0.3.0"
__version__ = "0.3.1"
9 changes: 6 additions & 3 deletions ghostnode/commands/init.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,23 +21,26 @@
@click.option("--network", "expected_network", default="main", show_default=True)
@click.option("--network-mode", type=click.Choice(["localhost", "localhost_lan"]), default="localhost",
show_default=True)
@click.option("--lan-auth-mode", type=click.Choice(["token_required", "trusted_lan"]), default="token_required",
show_default=True, help="Explicit LAN authentication mode.")
@click.option("--lan-address", default=None, help="Assigned private LAN IPv4 address for localhost_lan mode.")
@click.option("--dashboard-port", default=44678, show_default=True, type=int)
@click.option("--network-config", default=None, help="Private network configuration path.")
@click.option("--apply-network", is_flag=True, help="Persist the reviewed network settings atomically.")
@click.option("--confirm-network", is_flag=True, help="Confirm the explicit network configuration review.")
def init(as_json: bool, cli_path: str, datadir: str, wallet_name: str,
wallet_dir: str | None, rpc_host: str | None, rpc_port: int | None,
expected_network: str, network_mode: str, lan_address: str | None,
expected_network: str, network_mode: str, lan_auth_mode: str, lan_address: str | None,
dashboard_port: int, network_config: str | None,
apply_network: bool, confirm_network: bool) -> None:
"""Run the safe, read-only first-run readiness workflow."""
try:
network = validate_network_settings(NetworkSettings(network_mode, lan_address, dashboard_port))
network = validate_network_settings(NetworkSettings(network_mode, lan_address, dashboard_port, lan_auth_mode))
except ValueError as exc:
raise click.ClickException(str(exc)) from exc
network_plan = {**network.as_dict(), "restart_required": True, "applied": False,
"security": "token required for localhost_lan"}
"security": ("token required for localhost_lan" if network.lan_auth_mode == "token_required"
else "trusted LAN: every reachable client can read the dashboard")}
if apply_network:
if not confirm_network:
raise click.ClickException("--apply-network requires --confirm-network after reviewing the plan")
Expand Down
16 changes: 10 additions & 6 deletions ghostnode/commands/web.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,14 +21,16 @@ def validate_dashboard_host(host: str) -> str:
@click.option("--host", default="127.0.0.1", show_default=True, help="Bind address; localhost is the safe default.")
@click.option("--port", default=44678, show_default=True, type=int)
@click.option("--network-mode", type=click.Choice(["localhost", "localhost_lan"]), default=None,
help="Use localhost only or authenticated localhost plus one LAN IPv4 listener.")
help="Use localhost only or localhost plus one LAN IPv4 listener.")
@click.option("--lan-auth-mode", type=click.Choice(["token_required", "trusted_lan"]), default=None,
help="LAN authentication mode; token_required is the safe default.")
@click.option("--lan-address", default=None, help="Explicit assigned private LAN IPv4 address.")
@click.option("--token-file", default=None, help="Private file containing the LAN bearer token.")
@click.option("--cli-path", default=Config.cli_path, show_default=True)
@click.option("--datadir", default=Config.datadir, show_default=True)
@click.option("--wallet", "wallet_name", default=Config.wallet_name, show_default=True)
@click.option("--service", "service_name", default=Config.service, show_default=True)
def web(host: str, port: int, network_mode: str | None, lan_address: str | None,
def web(host: str, port: int, network_mode: str | None, lan_auth_mode: str | None, lan_address: str | None,
token_file: str | None, cli_path: str, datadir: str, wallet_name: str,
service_name: str) -> None:
"""Run the read-only dashboard with an explicit localhost or authenticated LAN mode."""
Expand All @@ -40,8 +42,10 @@ def web(host: str, port: int, network_mode: str | None, lan_address: str | None,
active_config = Config(cli_path=cli_path, datadir=datadir, wallet_name=wallet_name,
service=service_name, dashboard_mode=network_mode or Config.dashboard_mode,
dashboard_lan_address=lan_address or Config.dashboard_lan_address,
dashboard_port=port, dashboard_token_file=token_file or Config.dashboard_token_file)
settings = NetworkSettings(active_config.dashboard_mode, active_config.dashboard_lan_address, port)
dashboard_port=port, dashboard_token_file=token_file or Config.dashboard_token_file,
dashboard_lan_auth_mode=lan_auth_mode or Config.dashboard_lan_auth_mode)
settings = NetworkSettings(active_config.dashboard_mode, active_config.dashboard_lan_address, port,
active_config.dashboard_lan_auth_mode)
if network_mode is None and lan_address is None and port == 44678 \
and active_config.dashboard_mode == "localhost" \
and active_config.dashboard_lan_address is None:
Expand All @@ -52,8 +56,8 @@ def web(host: str, port: int, network_mode: str | None, lan_address: str | None,
if not ports_available(settings):
raise click.ClickException("one or more dashboard listeners are unavailable; no configuration was changed")
token = read_dashboard_token(active_config.dashboard_token_file)
if settings.mode == LAN_MODE and not token:
raise click.ClickException("LAN mode requires a private bearer token file; no listener was started")
if settings.mode == LAN_MODE and settings.lan_auth_mode == "token_required" and not token:
raise click.ClickException("token_required LAN mode requires a private bearer token file; no listener was started")
app = create_app(active_config, network_settings=settings, dashboard_token=token)
if settings.mode == "localhost":
uvicorn.run(app, host=LOCALHOST, port=settings.port)
Expand Down
1 change: 1 addition & 0 deletions ghostnode/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,5 @@ class Config:
dashboard_port: int = (int(os.environ["GHOSTNODE_DASHBOARD_PORT"])
if os.environ.get("GHOSTNODE_DASHBOARD_PORT") else 44678)
dashboard_token_file: str | None = os.environ.get("GHOSTNODE_DASHBOARD_TOKEN_FILE") or None
dashboard_lan_auth_mode: str = os.environ.get("GHOSTNODE_DASHBOARD_LAN_AUTH_MODE", "token_required")
dashboard_network_config: str | None = os.environ.get("GHOSTNODE_NETWORK_CONFIG") or None
13 changes: 10 additions & 3 deletions ghostnode/network.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@
LOCALHOST = "127.0.0.1"
LOCALHOST_MODE = "localhost"
LAN_MODE = "localhost_lan"
TOKEN_REQUIRED = "token_required"
TRUSTED_LAN = "trusted_lan"
DEFAULT_PORT = 44678


Expand All @@ -26,13 +28,15 @@ class NetworkSettings:
mode: str = LOCALHOST_MODE
lan_address: str | None = None
port: int = DEFAULT_PORT
lan_auth_mode: str = TOKEN_REQUIRED

@property
def bind_addresses(self) -> tuple[str, ...]:
return (LOCALHOST,) if self.mode == LOCALHOST_MODE else (LOCALHOST, self.lan_address or "")

def as_dict(self) -> dict[str, object]:
return {"mode": self.mode, "lan_address": self.lan_address, "port": self.port,
"lan_auth_mode": self.lan_auth_mode,
"localhost_address": LOCALHOST, "bind_addresses": list(self.bind_addresses)}


Expand Down Expand Up @@ -68,7 +72,9 @@ def validate_network_settings(settings: NetworkSettings,
if settings.mode == LOCALHOST_MODE:
if settings.lan_address not in (None, ""):
raise ValueError("localhost mode cannot configure a LAN address")
return NetworkSettings(LOCALHOST_MODE, None, settings.port)
return NetworkSettings(LOCALHOST_MODE, None, settings.port, TOKEN_REQUIRED)
if settings.lan_auth_mode not in {TOKEN_REQUIRED, TRUSTED_LAN}:
raise ValueError("unsupported LAN authentication mode")
try:
address = ipaddress.ip_address(settings.lan_address or "")
except ValueError as exc:
Expand All @@ -79,7 +85,7 @@ def validate_network_settings(settings: NetworkSettings,
assigned = set(available if available is not None else available_lan_ipv4())
if str(address) not in assigned:
raise ValueError("LAN address is not assigned to a local interface")
return NetworkSettings(LAN_MODE, str(address), settings.port)
return NetworkSettings(LAN_MODE, str(address), settings.port, settings.lan_auth_mode)


def load_network_settings(path: str | Path | None = None) -> NetworkSettings:
Expand All @@ -90,7 +96,8 @@ def load_network_settings(path: str | Path | None = None) -> NetworkSettings:
data = json.loads(target.read_text(encoding="utf-8"))
return validate_network_settings(NetworkSettings(data.get("mode", LOCALHOST_MODE),
data.get("lan_address"),
int(data.get("port", DEFAULT_PORT))))
int(data.get("port", DEFAULT_PORT)),
data.get("lan_auth_mode", data.get("auth_mode", TOKEN_REQUIRED))))
except (OSError, ValueError, TypeError, json.JSONDecodeError):
return NetworkSettings()

Expand Down
Loading
Loading