crowdsec-dashy/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Additional Instructions
- personal overrides: @~/.claude/CLAUDE.md

## Commands

```bash
# Build
go build -o crowdsec-dashy ./cmd/server

# Production build (static binary, stripped)
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o crowdsec-dashy ./cmd/server

# Run
./crowdsec-dashy

# Lint / vet
go vet ./...

# Tests (none yet — project is in early build phases)
go test ./...

# Docker
docker compose up -d
docker compose build
```

## Architecture

**Go 1.26. Zero external Go dependencies.** Stdlib only (`net/http`, `html/template`, `os/exec`, `encoding/json`).

### Data access — two parallel layers

| Layer | Package | Coverage |
|---|---|---|
| CrowdSec LAPI (REST) | `internal/crowdsec/lapi.go` | Decisions CRUD, Alerts, health |
| `cscli` exec wrapper | `internal/crowdsec/cli.go` | Bouncers, Machines, Hub, Metrics |

All shared structs (Decision, Alert, Bouncer, Machine, HubItem, MetricsSection, etc.) live in `internal/crowdsec/types.go`.

Bouncers, machines, hub, and metrics are **not** exposed via REST — they require `cscli` hitting the database directly. Features that need `cscli` check `Deps.CLIAvailable` and render an inline warning banner when the binary is absent.

### Package layout

```
cmd/server/main.go                entrypoint — loads config, authenticates LAPI, starts HTTP server
internal/config/config.go         env-var loading; CscliAvailable() stat-checks the binary path
internal/crowdsec/
  types.go                        all shared structs
  lapi.go                         REST client (JWT auth, auto-retry on 401)
  cli.go                          cscli exec wrapper (strict allow-list)
internal/handlers/
  renderer.go                     Renderer, PageData, Deps, SidebarNav
  dashboard.go / api.go / ...     one file per page + JSON API handler
internal/middleware/middleware.go  BasicAuth, Logger, SecureHeaders, Recovery
internal/router/router.go         constructs Deps, wires all routes
web/templates/layouts/base.html   sidebar shell
web/templates/pages/*.html        one file per page
web/static/css/app.css            all component styles
web/static/js/dashboard.js        live stat polling + sparklines
web/static/js/tables.js           client-side filter/sort/bulk-select
```

### Request flow

```
HTTP request
  → middleware chain (BasicAuth → Logger → SecureHeaders → Recovery)
  → router.go (stdlib mux)
  → handler struct (receives Deps: Renderer, LAPI, CLI, CLIAvailable, PollInterval)
  → handler renders to bytes.Buffer first, then writes to ResponseWriter
```

### Dependency injection

`Deps` struct (`internal/handlers/renderer.go:246`) is constructed once in `router.New()` and passed to every handler constructor. Handlers are structs, not functions.

### Template system

`Renderer` (`internal/handlers/renderer.go`) parses all page templates at startup: each page in `web/templates/pages/*.html` is combined with `web/templates/layouts/base.html` into a named `*template.Template`. Templates are keyed by filename without extension (e.g. `"dashboard"`, `"decisions"`). All render calls go through `Renderer.Render(w, name, data)` using the buffer-then-write pattern.

Template functions available: `inc`, `dec`, `dict`, `decisionBadgeClass`, `originBadgeClass`, `hubStatusClass`, `safeHTML`, `boolIcon`, `truncate`, `join`.

### LAPI authentication

On startup, `lapi.Login()` POSTs to `/v1/watchers/login` → JWT stored in memory. All subsequent requests carry `Authorization: Bearer <jwt>`. On 401, `doJSON()` auto-retries with a fresh login once before failing.

### `cscli` exec security

All args passed as a slice (never through shell). Two allow-lists enforced before `exec.CommandContext`:
- `allowedSubcommands` (first arg): bouncers, machines, collections, parsers, scenarios, postoverflows, hub, metrics, version
- `allowedActions` (second arg): list, add, delete, install, remove, update, upgrade, validate
- All other user-supplied values validated against `safeArg` regex `^[a-zA-Z0-9_./:@\-]+$`

### POST pattern

All state-changing POST handlers use PRG (Post/Redirect/Get). Flash messages are attached to `PageData` via `WithFlash(type, msg)` and displayed on the redirected GET. All POST handlers must apply `http.MaxBytesReader` before parsing the body.

### Internal JSON API

Used by frontend JS — all return JSON, protected by the same BasicAuth middleware.

| Method | Path | Description |
|---|---|---|
| GET | `/api/v1/stats` | Dashboard summary counts |
| GET | `/api/v1/health` | LAPI health + cscli availability |

### Adding a new page

1. `internal/handlers/mypage.go` — handler struct with `ServeHTTP` or named methods
2. `web/templates/pages/mypage.html` — starts with `{{template "base" .}}`
3. Add `NavItem` to `SidebarNav` in `renderer.go`
4. `router.go` — `mux.Handle("/mypage", handlers.NewMyPageHandler(deps))`

### UI design

Dark industrial aesthetic. Palette: near-black surface `#080b10`, blue-grey panels `#0f1520`, cyan accent `#00d4ff`, threat-red `#ff3b3b`, safe-green `#00e676`. Fonts: `JetBrains Mono` for data, `IBM Plex Sans` for labels. All styles in `web/static/css/app.css`. No external JS frameworks — sparklines drawn with inline SVG `<polyline>`.

Dashboard live stats poll `/api/v1/stats` via `web/static/js/dashboard.js`. Client-side table filter/sort/bulk-select in `web/static/js/tables.js`.

### Environment variables

| Variable | Default | Notes |
|---|---|---|
| `PORT` | `:8080` | Listen address |
| `CROWDSEC_API_URL` | `http://localhost:8080` | LAPI base URL |
| `CROWDSEC_API_LOGIN` | *(required)* | Machine login |
| `CROWDSEC_API_PASSWORD` | *(required)* | Machine password |
| `CSCLI_PATH` | `/usr/local/bin/cscli` | Binary path; CLI features disabled if absent |
| `UI_USERNAME` | `admin` | Basic Auth username |
| `UI_PASSWORD` | `changeme` | Basic Auth password |
| `UI_SESSION_SECRET` | *(required, ≥32 chars)* | HMAC signing key |
| `POLL_INTERVAL_SEC` | `15` | Dashboard poll interval (seconds) |