Merge pull request #133 from jackby03/feat/125-serve

feat(serve): hardbox serve — lightweight web dashboard

Author: jackby03

docs/SERVE.md

@@ -0,0 +1,59 @@
+# hardbox serve — Web Dashboard
+
+`hardbox serve` starts a local, read-only HTTP dashboard for browsing audit reports, inspecting findings, and comparing reports side by side.
+
+## Usage
+
+```bash
+hardbox serve [flags]
+```
+
+### Flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `--reports-dir` | `.` | Directory containing JSON audit reports |
+| `--port` | `8080` | Port to listen on (ignored when `--addr` is set) |
+| `--addr` | `127.0.0.1:8080` | Full listen address — override to change host |
+| `--no-open` | `false` | Do not open the browser automatically |
+| `--basic-auth` | _(none)_ | Enable HTTP Basic Auth: `user:pass` |
+
+## Quick start
+
+```bash
+# Run an audit and save the report
+hardbox audit --format json --output /var/log/hardbox/reports/$(date +%s).json
+
+# Start the dashboard
+hardbox serve --reports-dir /var/log/hardbox/reports/
+# → hardbox dashboard → http://127.0.0.1:8080
+```
+
+## Dashboard routes
+
+| Route | Description |
+|---|---|
+| `/` | Report list — all JSON reports sorted by date |
+| `/report/<session_id>` | Single report — findings table per module |
+| `/diff/<before_id>/<after_id>` | Inline diff between two reports |
+| `/api/reports` | JSON API — report metadata list |
+
+## Security
+
+- Binds to `127.0.0.1` by default — not reachable from the network.
+- To expose on the local network (e.g. in a shared lab), set `--addr 0.0.0.0:8080` and protect with `--basic-auth`.
+- Read-only — no write operations are exposed via HTTP.
+- All assets are embedded in the binary via `go:embed` — no external CDN or internet access required.
+
+## Examples
+
+```bash
+# Custom port, no browser
+hardbox serve --port 9000 --reports-dir ./reports/ --no-open
+
+# Shared access with basic auth
+hardbox serve --addr 0.0.0.0:8080 --basic-auth ops:s3cr3t --reports-dir /var/log/hardbox/reports/
+
+# Compare two specific reports from the UI
+# Navigate to: http://127.0.0.1:8080/diff/<before_session_id>/<after_session_id>
+```

internal/cli/root.go

@@ -47,6 +47,7 @@ func newRootCmd(version string) *cobra.Command {
 		newDiffCmd(),
 		newFleetCmd(gf),
 		newPluginCmd(gf),
+		newServeCmd(),
 	)
 
 	return root

internal/cli/serve.go

@@ -0,0 +1,110 @@
+package cli
+
+import (
+	"fmt"
+	"net"
+	"os/exec"
+	"runtime"
+	"strings"
+
+	"github.com/rs/zerolog/log"
+	"github.com/spf13/cobra"
+
+	"github.com/hardbox-io/hardbox/internal/serve"
+)
+
+func newServeCmd() *cobra.Command {
+	var (
+		port       int
+		addr       string
+		reportsDir string
+		noOpen     bool
+		basicAuth  string
+	)
+
+	cmd := &cobra.Command{
+		Use:   "serve",
+		Short: "Start a local web dashboard to browse audit reports",
+		Long: `serve starts a read-only HTTP dashboard on localhost that lets you
+browse audit reports, inspect findings, and compare any two reports side by side.
+
+The server binds to 127.0.0.1 by default and never exposes to the network
+unless --addr is set explicitly.
+
+Examples:
+  # Start on default port 8080
+  hardbox serve --reports-dir /var/log/hardbox/reports/
+
+  # Custom port
+  hardbox serve --port 9000 --reports-dir ./reports/
+
+  # Bind to custom address with basic auth
+  hardbox serve --addr 0.0.0.0:8080 --basic-auth admin:secret
+
+  # Don't open browser automatically
+  hardbox serve --no-open --reports-dir ./reports/`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			listenAddr := resolveAddr(addr, port)
+
+			cfg := serve.Config{
+				Addr:       listenAddr,
+				ReportsDir: reportsDir,
+				BasicAuth:  basicAuth,
+			}
+
+			srv, err := serve.New(cfg)
+			if err != nil {
+				return fmt.Errorf("creating server: %w", err)
+			}
+
+			url := "http://" + srv.Addr()
+			fmt.Fprintf(cmd.OutOrStdout(), "hardbox dashboard → %s\n", url)
+			fmt.Fprintf(cmd.OutOrStdout(), "reports dir      → %s\n", reportsDir)
+			fmt.Fprintf(cmd.OutOrStdout(), "press Ctrl+C to stop\n\n")
+
+			if !noOpen {
+				go openBrowser(url)
+			}
+
+			log.Debug().Str("addr", listenAddr).Str("reports_dir", reportsDir).Msg("serve: starting")
+			return srv.Start(cmd.Context())
+		},
+	}
+
+	cmd.Flags().IntVar(&port, "port", 8080, "port to listen on (ignored when --addr is set)")
+	cmd.Flags().StringVar(&addr, "addr", "", "full listen address, e.g. 127.0.0.1:8080 (overrides --port)")
+	cmd.Flags().StringVar(&reportsDir, "reports-dir", ".", "directory containing JSON audit reports")
+	cmd.Flags().BoolVar(&noOpen, "no-open", false, "do not open the browser automatically")
+	cmd.Flags().StringVar(&basicAuth, "basic-auth", "", "enable HTTP basic auth, format: user:pass")
+
+	return cmd
+}
+
+// resolveAddr returns the listen address, preferring --addr over --port.
+func resolveAddr(addr string, port int) string {
+	if addr != "" {
+		// Ensure it has a host component — default to 127.0.0.1 for safety.
+		if !strings.Contains(addr, ":") {
+			return net.JoinHostPort("127.0.0.1", addr)
+		}
+		return addr
+	}
+	return net.JoinHostPort("127.0.0.1", fmt.Sprintf("%d", port))
+}
+
+// openBrowser opens url in the user's default browser.
+func openBrowser(url string) {
+	var cmd *exec.Cmd
+	switch runtime.GOOS {
+	case "darwin":
+		cmd = exec.Command("open", url)
+	case "windows":
+		cmd = exec.Command("cmd", "/c", "start", url)
+	default:
+		cmd = exec.Command("xdg-open", url)
+	}
+	if err := cmd.Start(); err != nil {
+		log.Debug().Err(err).Msg("serve: could not open browser")
+	}
+}
+