fix(security): bind Grafana to loopback and gate wide exposure on an admin password

RenderMonitoringCompose emitted the Grafana service with an unconditional
host port publication and no environment block at all - no
GF_SECURITY_ADMIN_PASSWORD, no auth hardening - so the deployed container
kept grafana-oss's built-in admin/admin while docker published it on
0.0.0.0. On a cloud VM with a permissive security group that is the public
internet: full node metrics, the ability to lock the operator out, and -
because a Grafana admin can add arbitrary datasources and query them
through the backend proxy - a server-side request primitive into the
host's internal network and cloud metadata endpoints.

Grafana is now bound to 127.0.0.1 by default. A new
monitoring.grafana.expose restores the wide bind, but is rejected unless
monitoring.grafana.admin_password_env is also set, so the escape hatch
cannot recreate the finding; the renderer independently falls back to
loopback for an unvalidated intent. The password is rendered as a required
compose variable reference, so the secret never enters the 0644 compose
file and an unset or empty value fails at interpolation before any
container is created.

Verified against real Docker: the default resolves to host_ip 127.0.0.1,
and expose without a password falls back to loopback.

Breaking: Grafana is no longer reachable off-host by default. Use an SSH
tunnel, a reverse proxy, or the new expose opt-in.

Author: barbatos2011

CHANGELOG.md

@@ -254,6 +254,13 @@ The agent-ergonomics arc lands across four sequenced PRs:
   absent) is the only way to skip the check; results carry
   `verification_skipped` so `md5_verified: false` can no longer be read
   as "the mirror had no sidecar". Schema 1.12.2 → 1.12.3
+- **Breaking:** the rendered monitoring stack binds Grafana's host port
+  to `127.0.0.1` instead of `0.0.0.0`; it previously published the
+  grafana-oss default `admin/admin` login to every network that could
+  reach the deployment host. Use an SSH tunnel, or opt back in with
+  `monitoring.grafana.expose: true`, which now requires
+  `monitoring.grafana.admin_password_env` (the NAME of an env var
+  feeding `GF_SECURITY_ADMIN_PASSWORD`)
 
 ## [0.1.0-alpha] — 2026-XX-XX
 

README.md

@@ -370,7 +370,20 @@ trond network status
 | `trond status` / `trond inspect <node> -o json` | Expose the stack's `prometheus_port` / `grafana_port` so agents can discover it |
 | `trond remove <node>` / `trond network destroy` | Automatically cleans up the monitoring stack |
 
-After deployment, Grafana is available at http://localhost:3000 (admin/admin) with 5 dashboards: java-tron-server, java-tron-api, java-tron-api-statistic, java-tron-mechanism, and node-exporter-full. Prometheus is at http://localhost:9090.
+After deployment, Grafana is available at http://localhost:3000 — **on the deployment host's loopback interface only** — with 5 dashboards: java-tron-server, java-tron-api, java-tron-api-statistic, java-tron-mechanism, and node-exporter-full. Prometheus is at http://localhost:9090.
+
+Grafana keeps the image's default `admin/admin` login until you give it a password, so it is bound to `127.0.0.1`: reach it from your workstation over an SSH tunnel (`ssh -L 3000:127.0.0.1:3000 user@host`) or a reverse proxy you control. To publish it on all interfaces instead, opt in explicitly — which requires an admin password:
+
+```yaml
+monitoring:
+  enabled: true
+  grafana:
+    port: 3000
+    expose: true                              # bind 0.0.0.0 instead of 127.0.0.1
+    admin_password_env: GRAFANA_ADMIN_PASSWORD  # NAME of an env var, not the password
+```
+
+`GRAFANA_ADMIN_PASSWORD` must be set in the environment that runs `trond apply` (compose refuses to start the stack otherwise). Grafana applies it when it first initialises its database, so rotate the password in Grafana itself for a stack that is already running.
 
 **Limitations**: The single Prometheus instance loses visibility into nodes isolated by `trond partition`; metrics resume after `trond heal`. Monitoring is Docker-only (Prometheus and Grafana run as containers), so jar-runtime targets need Docker on the trond machine for the monitoring stack.
 

examples/monitoring.yaml

@@ -3,7 +3,11 @@
 #       trond apply --intent examples/monitoring.yaml --no-monitor  (skip monitoring)
 #
 # Default behaviour:
-#   - Grafana is exposed on port 3000.
+#   - Grafana is published on port 3000 of the deployment host's loopback
+#     interface (127.0.0.1) only, because the image ships with the
+#     well-known admin/admin login.  Reach it over an SSH tunnel, or set
+#     grafana.expose (which requires grafana.admin_password_env) to
+#     publish it on all interfaces.
 #   - Prometheus is NOT exposed on the host by default; it is reachable
 #     inside the Docker network by Grafana.  To expose Prometheus add
 #     monitoring.prometheus.port explicitly.
@@ -25,6 +29,10 @@ monitoring:
     retention: 7d
   grafana:
     port: 3000
+    # Uncomment BOTH lines to publish Grafana on every interface with an
+    # admin password taken from the named environment variable:
+    # expose: true
+    # admin_password_env: GRAFANA_ADMIN_PASSWORD
 
 nodes:
   - type: fullnode

internal/intent/fields_test.go

@@ -960,6 +960,70 @@ nodes:
 	}
 }
 
+func TestMonitoring_GrafanaExposeAndAdminPassword(t *testing.T) {
+	monitoringYAML := func(grafana string) []byte {
+		return []byte(fmt.Sprintf(`
+name: mon
+network: mainnet
+target: {type: local}
+monitoring:
+  enabled: true
+  grafana:
+%s
+nodes:
+  - type: fullnode
+`, grafana))
+	}
+
+	t.Run("defaults to not exposed", func(t *testing.T) {
+		i, err := Parse(monitoringYAML("    port: 3000"))
+		if err != nil {
+			t.Fatal(err)
+		}
+		if i.Monitoring.Grafana.Expose {
+			t.Error("grafana.expose should default to false")
+		}
+		if i.Monitoring.Grafana.AdminPasswordEnv != "" {
+			t.Errorf("grafana.admin_password_env = %q, want empty",
+				i.Monitoring.Grafana.AdminPasswordEnv)
+		}
+	})
+
+	t.Run("expose with admin_password_env parses", func(t *testing.T) {
+		i, err := Parse(monitoringYAML("    expose: true\n    admin_password_env: GRAFANA_ADMIN_PASSWORD"))
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !i.Monitoring.Grafana.Expose {
+			t.Error("grafana.expose not parsed")
+		}
+		if i.Monitoring.Grafana.AdminPasswordEnv != "GRAFANA_ADMIN_PASSWORD" {
+			t.Errorf("grafana.admin_password_env = %q, want GRAFANA_ADMIN_PASSWORD",
+				i.Monitoring.Grafana.AdminPasswordEnv)
+		}
+	})
+
+	// Exposing Grafana on every interface with the image's default
+	// admin login is the combination this rejects.
+	t.Run("expose without admin_password_env rejected", func(t *testing.T) {
+		_, err := Parse(monitoringYAML("    expose: true"))
+		if err == nil {
+			t.Fatal("expected error for expose without admin_password_env")
+		}
+		if !strings.Contains(err.Error(), "admin_password_env") {
+			t.Errorf("error %q should name the missing field", err)
+		}
+	})
+
+	// The intent carries the env var NAME, never the password.
+	t.Run("literal password rejected", func(t *testing.T) {
+		_, err := Parse(monitoringYAML(`    admin_password_env: "hunter2 !"`))
+		if err == nil {
+			t.Fatal("expected error for a non-env-name admin_password_env")
+		}
+	})
+}
+
 func TestMonitoring_InvalidRetention(t *testing.T) {
 	cases := []string{"7", "days", "1.5d", "week"}
 	for _, val := range cases {

internal/intent/loader.go

@@ -439,6 +439,22 @@ func validateMonitoring(m *Monitoring) error {
 			return fmt.Errorf("monitoring.prometheus.retention must match ^\\d+[dwh]$ (e.g. \"7d\", \"2w\"), got %q", m.Prometheus.Retention)
 		}
 	}
+	if m.Grafana.AdminPasswordEnv != "" {
+		// Same contract as witness_key.private_key_env: the intent holds
+		// the NAME of an env var, never the secret. The name is also
+		// interpolated into the rendered compose file, so restricting it
+		// to env-name characters keeps it from breaking out of ${...}.
+		envVarPattern := regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)
+		if !envVarPattern.MatchString(m.Grafana.AdminPasswordEnv) {
+			return fmt.Errorf("monitoring.grafana.admin_password_env %q is not a valid environment variable name; it must be the NAME of an env var holding the Grafana admin password (e.g., GRAFANA_ADMIN_PASSWORD), not the password itself", m.Grafana.AdminPasswordEnv)
+		}
+	}
+	if m.Grafana.Expose && m.Grafana.AdminPasswordEnv == "" {
+		// Publishing Grafana beyond loopback with the image's default
+		// admin/admin login hands the dashboards and the datasource proxy
+		// to anyone who can reach the port.
+		return fmt.Errorf("monitoring.grafana.expose publishes Grafana on all host interfaces and therefore requires monitoring.grafana.admin_password_env: set it to the NAME of an environment variable holding the admin password (e.g., admin_password_env: GRAFANA_ADMIN_PASSWORD), or drop expose to keep Grafana bound to 127.0.0.1")
+	}
 	return nil
 }
 

internal/intent/schema.go

@@ -437,6 +437,27 @@ type PromConfig struct {
 // GrafConfig configures the Grafana visualizer.
 type GrafConfig struct {
 	Port int `yaml:"port,omitempty" json:"port,omitempty"`
+
+	// Expose publishes Grafana's host port on every interface (0.0.0.0)
+	// instead of loopback only. Off by default: the grafana-oss image
+	// ships a well-known default admin login, so a host-wide bind hands
+	// the dashboards — and Grafana's datasource proxy, which can be
+	// pointed at anything the host can reach — to whoever can reach the
+	// port. Requires AdminPasswordEnv (see validateMonitoring).
+	Expose bool `yaml:"expose,omitempty" json:"expose,omitempty"`
+
+	// AdminPasswordEnv is the NAME of an environment variable holding the
+	// Grafana admin password — never the password itself. The rendered
+	// compose references it as ${NAME:?...}, so the variable must be set
+	// in the environment that runs `docker compose up` (trond's own
+	// environment for local targets); compose refuses to start the stack
+	// when it is unset or empty.
+	//
+	// Grafana applies GF_SECURITY_ADMIN_PASSWORD when it initialises its
+	// database, i.e. on the first start of a fresh grafana_data volume.
+	// Setting it for an already-initialised stack does not rotate an
+	// existing admin password.
+	AdminPasswordEnv string `yaml:"admin_password_env,omitempty" json:"admin_password_env,omitempty"`
 }
 
 // BoolPtr is a helper for creating *bool values in intent construction.

internal/render/monitoring.go

@@ -57,7 +57,11 @@ const monitoringComposeTmpl = `services:
         limits:
           memory: 2g
     ports:
-      - "{{.GrafanaPort}}:3000"
+      - "{{.GrafanaPortMapping}}"
+{{- if .GrafanaAdminPasswordRef }}
+    environment:
+      - GF_SECURITY_ADMIN_PASSWORD={{.GrafanaAdminPasswordRef}}
+{{- end }}
     volumes:
       - ./grafana_data:/var/lib/grafana
       - ./grafana/provisioning:/etc/grafana/provisioning
@@ -81,26 +85,70 @@ var composeTmpl = template.Must(template.New("monitoring").Parse(monitoringCompo
 type monitoringComposeData struct {
 	Name           string
 	PrometheusPort int
-	GrafanaPort    int
-	Retention      string
-	NetworkName    string
+	// GrafanaPortMapping is the full compose "ports" entry for Grafana,
+	// including the host bind address — see grafanaPortMapping.
+	GrafanaPortMapping string
+	// GrafanaAdminPasswordRef is the compose interpolation reference that
+	// supplies GF_SECURITY_ADMIN_PASSWORD, or "" when the operator did
+	// not configure one.
+	GrafanaAdminPasswordRef string
+	Retention               string
+	NetworkName             string
 }
 
 // RenderMonitoringCompose generates a docker-compose.yaml for the
 // Prometheus + Grafana monitoring stack.
 func RenderMonitoringCompose(name string, i *intent.Intent, targets []MonitoringTarget, networkName string) string {
 	var buf bytes.Buffer
+	g := i.Monitoring.Grafana
 	data := monitoringComposeData{
-		Name:           name,
-		PrometheusPort: i.Monitoring.Prometheus.Port,
-		GrafanaPort:    i.Monitoring.Grafana.Port,
-		Retention:      i.Monitoring.Prometheus.Retention,
-		NetworkName:    networkName,
+		Name:                    name,
+		PrometheusPort:          i.Monitoring.Prometheus.Port,
+		GrafanaPortMapping:      grafanaPortMapping(g),
+		GrafanaAdminPasswordRef: grafanaAdminPasswordRef(g),
+		Retention:               i.Monitoring.Prometheus.Retention,
+		NetworkName:             networkName,
 	}
 	_ = composeTmpl.Execute(&buf, data)
 	return buf.String()
 }
 
+// grafanaPortMapping builds Grafana's compose "ports" entry.
+//
+// A bare "<port>:3000" publishes on 0.0.0.0, which on any host with a
+// permissive firewall exposes the dashboard — and Grafana's datasource
+// proxy — to the network with the grafana-oss image's default admin
+// login. Bind to loopback instead; reaching it from elsewhere is then an
+// SSH tunnel (or a reverse proxy the operator controls) away.
+//
+// monitoring.grafana.expose opts back into the host-wide bind, and is
+// only honoured together with an admin password: intent validation
+// rejects that combination up front, and this stays fail-closed for any
+// caller that renders an unvalidated intent.
+func grafanaPortMapping(g intent.GrafConfig) string {
+	if g.Expose && g.AdminPasswordEnv != "" {
+		return fmt.Sprintf("%d:3000", g.Port)
+	}
+	return fmt.Sprintf("127.0.0.1:%d:3000", g.Port)
+}
+
+// grafanaAdminPasswordRef returns the compose interpolation that feeds
+// GF_SECURITY_ADMIN_PASSWORD from the operator's environment, keeping the
+// secret out of the rendered file (the same shape composeEnvLines uses
+// for the witness keystore password).
+//
+// The ":?" form makes `docker compose up` fail loudly when the variable
+// is unset or empty rather than silently starting Grafana with an empty
+// or default admin password. The name is constrained to env-name
+// characters by intent validation.
+func grafanaAdminPasswordRef(g intent.GrafConfig) string {
+	if g.AdminPasswordEnv == "" {
+		return ""
+	}
+	return fmt.Sprintf("${%s:?set %s to the Grafana admin password (monitoring.grafana.admin_password_env)}",
+		g.AdminPasswordEnv, g.AdminPasswordEnv)
+}
+
 // RenderPrometheusConfig generates prometheus.yml content.
 //
 // The retention parameter is currently unused: Prometheus TSDB retention is