Siot Security Audit

Proving a finding

Write a test file named zz_audit_poc_test.go in client/ (package client_test, which has the sync helpers) or server/, run it, and delete it in the same command so it cannot be left behind.

Use your own ports and data directory. server.TestServerOptions and TestServerOptions2 use ports 8900 to 8914 and store data in /tmp/siot-test-<ID>, which a clean start deletes. Another session or a running test loop on the same checkout will collide with both. A development instance usually holds 4222, 4223, and 4224.

optsU := server.Options{NatsPort: 8950, HTTPPort: "8951", NatsMonitorPort: 8952,
	NatsWSPort: 8953, NatsServer: "nats://localhost:8950", ID: "auditU",
	AuthToken: "upstream-token", DataDir: "<scratchpad>/auditU"}
nc, root, stop, err := server.TestServerOpts(optsU)

nc is the server's full-access connection: use it to build the tree and to check results as the operator would see them. Connect separately as the principal under test.

// build a tree
client.SendNodeType(nc, client.Group{ID: "G", Parent: root.ID}, "test")
client.SendNodeType(nc, client.User{ID: "U", Parent: "G", Email: "u", Pass: "pw"}, "test")

// browser user: sign in the way the UI does, then connect with the JWT
nodes, _ := client.UserCheck(nc, "u", "pw") // the node of type data.NodeTypeJWT holds the token
user, _ := nats.Connect(uri, nats.UserInfo("U", jwt),
	nats.CustomInboxPrefix(client.InboxPrefix("U")), nats.NoReconnect())

// credentialed device, or an enrolling key
kp, _ := nkeys.FromSeed([]byte(seed))
dev, _ := nats.Connect(uri, nats.Nkey(pub, kp.Sign),
	nats.CustomInboxPrefix(client.InboxPrefix(pub)), nats.NoReconnect())

// points are built with constructors; data.Point has no exported Value or Text
pts := data.Points{
	data.NewPointFloat(data.PointTypeTombstone, "", 0),
	data.NewPointString(data.PointTypeNodeType, "", data.NodeTypeVariable),
}
// a write: an empty reply is success, anything else is the error text
reply, err := user.Request("u.G.U.ep.<child>.<parent>", pts.Encode(), 2*time.Second)

// a read: the reply is a node frame, and a refusal arrives as its error
reply, err = user.Request("u.G.U.nodes.all.<id>", nil, 2*time.Second)
nodes, err := data.DecodeNodes(reply.Data)

Helpers already in client/*_test.go: credUpstream, enrollDevice, startDeviceSync, makeEnrollToken, devicePubKey, waitFor. They use the shared test ports, so copy what they do with your own options when another test run may be active.

• A permission violation on publish is asynchronous. Collect it with nats.ErrorHandler and wait a second; no error means the publish was allowed.
• To test a loopback rule, connect to a non-loopback address of the same machine (ip -4 -o addr show scope global). Every listener binds all interfaces.
• For HTTP, POST /v1/auth with form fields email and password returns the JWT; send it as Authorization: Bearer <jwt>.
• Send the test output to a file in the scratchpad and grep it. The server log is long, and a crashed test process loses whatever was only on screen.
• A proof that the process stops belongs in its own test, since it takes the other assertions down with it.

Check pgrep -af 'go test|\.test' and git status before starting. If another session is editing the tree, leave its files alone and say so in the report.

Tooling

go run golang.org/x/vuln/cmd/govulncheck@latest ./...          # source: only called symbols count
govulncheck -mode binary <release binary>                      # what actually shipped, and with which Go
go version <release binary>
cd frontend && npm audit --omit=dev                            # what reaches the browser
cd frontend/lib && npm audit --omit=dev
rg -n 'recover\(\)|InsecureSkipVerify|math/rand|exec\.Command|sh -c' --glob '*.go'
git ls-files | xargs rg -l 'BEGIN .*PRIVATE KEY|\bS[UA][A-Z2-7]{56}\b'

Release binaries are built with the Go version go.mod names, which can differ from the one CI tests with; check both workflows in .github/workflows/.

Never read or print device.nkey or local.sh. They are local secrets and are gitignored.

Splitting the work

A full audit is too wide for one context. Reviewers that worked, run in parallel, each told to give file:line, the principal required, a concrete scenario, and what was checked and found sound:

• store/, data/, and the user, auth, and admin clients: scope checks, binary decoding, sign-in, replication trust.
• The rest of client/ plus modbus/, msg/, file/, network/: every place a point or a peer's bytes reach os/exec, a path, a URL, an allocation, a ticker, or a log line.
• Frontend, dependencies, packaging, CI, repository hygiene, and the user docs compared with server/args.go.

Keep the HTTP API, the authorizer, and enrollment for yourself, and verify every reported finding in the code, and with a test where it matters, before it goes into a document. Reviewers are sometimes wrong about severity and about what is reachable.

Recording results

• The plan gets each finding as a numbered item with Problem, Change, and Verify, marked proven when a test reproduced it, and a suggested order. Mark items complete there as they close.
• docs/ref/security.md gets corrections to any statement a test contradicted, and a row in Known limitations pointing at the plan item. Keep the deployment checklist to what an operator can do today.
• docs/user/ gets corrected where a documented default or guarantee does not match the code.
• CHANGELOG.md gets one entry when the guidance to operators changes.
• Write in the project's documentation tone: neutral, precise, no dramatic wording. Describe what a principal can do, and the change that closes it.
• Do not add a vulnerability reporting contact or policy unless asked. Note its absence in the report instead.
• A broader design review lives outside this repository at ../security.md. Mention where it has gone out of date; do not edit it without being asked.

Findings do not belong in this skill. If the harness, the principals, or the enforcement points change, update the sections above.