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
6 changes: 6 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,12 @@ jobs:
- name: Tests (race, shuffled)
run: go test -race -shuffle=on -count=1 ./...

- name: Fuzz (short run per target; a crasher fails the job)
shell: bash
run: |
scripts/fuzz.sh --selftest
scripts/fuzz.sh

- name: Scrub tracked files
shell: bash
run: scripts/scrub.sh
Expand Down
5 changes: 4 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ Contributions are licensed under Apache-2.0, the license of this repository.

## Build and check

Go 1.27.3 is pinned in `go.mod`. Run these before you push; CI runs the same on Linux and macOS.
Go 1.27.4 is pinned in `go.mod`. Run these before you push; CI runs the same on Linux and macOS.

```
go vet ./...
Expand All @@ -64,6 +64,8 @@ go test -race -shuffle=on -count=1 ./...
scripts/scrub.sh
scripts/scrub.sh --selftest
scripts/depguard-selftest.sh
scripts/fuzz.sh --selftest
scripts/fuzz.sh
```

Use golangci-lint v2 and a current govulncheck. All checks are blocking.
Expand All @@ -72,6 +74,7 @@ Use golangci-lint v2 and a current govulncheck. All checks are blocking.

- **No URL input.** No flag, route, config value or document field makes Vigil fetch a URL, take a selector, or send free-form PromQL.
- **No `os/exec`** in non-test code, and no schema validator in the binary. The linter enforces both.
- **One HTTP client.** Every call to a backend goes through `internal/httpx`: GET only, no redirect, no proxy, a body cap, a deadline, two calls in flight per backend. The linter rejects `net/http` anywhere else in non-test code.
- **Severity comes from authorities.** Vigil combines verdicts and applies the stale and missing-authority caps. It does not compute severity from raw data.
- **Slugs only.** Use the public host slugs (`castle`, `tower`, `citadel`, `apiary`, `lathe`, `box`) in code, docs, fixtures and examples. No IP addresses, hostnames or secrets. Placeholders use reserved documentation values. Real addresses live in an untracked overlay.
- **Schemas are the contract.** JSON Schemas under `schema/` are written by hand. A change that adds a field is additive within `v0`; anything that removes or renames one needs a new major.
Expand Down
31 changes: 31 additions & 0 deletions cmd/vigil/echo_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
package main

import (
"strings"
"testing"
)

// TestHelpAndErrorsDoNotEchoArguments puts a marker in every argument slot and
// checks it never comes back on stdout or stderr, in help, in a usage error or
// in version output.
func TestHelpAndErrorsDoNotEchoArguments(t *testing.T) {
const m = "leakmarker"
for _, args := range [][]string{
{"--help", m + ".example.invalid"},
{"help", "http://" + m + ".example.invalid/x"},
{"prom", "--help", m},
{"-hh", "\"" + m},
{"version", m},
{m},
{"prom", m},
{"prom", "query", "http://" + m + ".example.invalid"},
{"sources", "--nope=" + m},
{"sources", "--config=https://" + m + ".example.invalid"},
{"--now", m, "sources"},
} {
_, out, errs := call(t, defaultHandlers(), args...)
if strings.Contains(out, m) || strings.Contains(errs, m) {
t.Errorf("%q echoed the marker: stdout=%q stderr=%q", args, out, errs)
}
}
}
125 changes: 125 additions & 0 deletions cmd/vigil/fuzz_cli_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
package main

import (
"bytes"
"context"
"encoding/json"
"strings"
"testing"

"github.com/Hedronite/vigil/internal/exitcode"
)

// usageMessages is every message the command layer prints for a usage error.
// It is fixed text: a message outside this set means text from the input, a
// backend or an error reached stderr.
var usageMessages = map[string]bool{
"a command is required": true,
"a subcommand is required": true,
"a query name is required": true,
"the query name is not a configured name": true,
"--host must be a host slug": true,
"a path is required here, not a URL": true,
"--now must be an RFC 3339 time": true,
"unknown command; see vigil --help": true,
"unknown flag; see vigil --help": true,
"a flag is missing its value": true,
"a flag value is invalid": true,
"unexpected arguments; no command takes a URL, selector or PromQL": true,
"usage error; see vigil --help": true,
}

// FuzzCLIArgs feeds arbitrary argument lists to the command tree with handlers
// that record what they were given and always succeed. Whatever the arguments,
// the parser never panics and exits 0 or 3 only. A failure is one fixed-text
// vigil.error/v0 line with empty stdout whose text is chosen from the
// fixed set above, so it cannot repeat an argument. A success hands the handler only values of the right shape: a
// query name, a host slug, and file names that are not URLs. Checking what the
// handler received, and not the raw arguments, is the property that matters:
// flags may repeat and the last value wins, so an earlier bad value that was
// overridden never reaches anything.
func FuzzCLIArgs(f *testing.F) {
for _, s := range []string{
"version", "prom targets", "prom query up_all", "prom query up_by_host --host castle",
"sources --json", "grafana health --now 2026-11-14T09:00:00Z", "--help", "prom --help",
"sources http://leak.example.invalid/x", "prom query up{job=\"x\"}", "--config https://leak.example.invalid sources",
"--overlay //leak/x sources", "prom query rate(x[5m]) --host 192.0.2.7:9090", "--now yesterday sources",
"--nope", "-x", "", "prom", "grafana", "help", "completion bash", "sources --config", "--json=maybe sources",
"prom query a b", "version extra", "sources --host castle", "--now 2026-11-14T09:00:00Z --json prom targets",
"prom query http://leak.example.invalid/x", "prom query up_all --host http://leak.example.invalid",
"prom query up(x)", "prom query up_all --host a{b}",
"prom query a --host \" --host ", "-hh \"", "\"000000 -h", "--overlay \" sources",
"prom query up_all --config ? --overlay #", "prom query up_all --host Castle", "prom query UP",
} {
f.Add(s)
}

f.Fuzz(func(t *testing.T, line string) {
args := strings.Split(line, " ")
var got *Invocation
rec := func(_ context.Context, i Invocation) error {
i.Stdout = nil
got = &i
return nil
}
h := Handlers{PromTargets: rec, PromQuery: rec, GrafanaHealth: rec, Sources: rec}

var out, errb bytes.Buffer
code := run(context.Background(), args, &out, &errb, h)
switch code {
case exitcode.Green:
if errb.Len() != 0 {
t.Fatalf("exit 0 with stderr %q", errb.String())
}
if got == nil {
// Help or version: static text, which cannot hold an
// argument. TestHelpAndErrorsDoNotEchoArguments pins that
// with a marker; a substring check here would trip on
// words the help text really contains.
return
}
if got.Name != "" && !queryNamePattern.MatchString(got.Name) {
t.Fatalf("handler got the query name %q", got.Name)
}
if got.Host != "" && !hostSlugPattern.MatchString(got.Host) {
t.Fatalf("handler got the host %q", got.Host)
}
for _, p := range []string{got.ConfigPath, got.OverlayPath} {
if !plainPath(p) {
t.Fatalf("handler got the path %q", p)
}
}
case exitcode.Usage:
if out.Len() != 0 {
t.Fatalf("usage error with stdout %q", out.String())
}
if got != nil {
t.Fatal("a handler ran for a usage error")
}
s := errb.String()
if !strings.HasSuffix(s, "\n") || strings.Count(s, "\n") != 1 {
t.Fatalf("stderr is not one line: %q", s)
}
var doc struct {
APIVersion string `json:"apiVersion"`
Error struct {
Code string `json:"code"`
Message string `json:"message"`
} `json:"error"`
}
dec := json.NewDecoder(strings.NewReader(s))
dec.DisallowUnknownFields()
if err := dec.Decode(&doc); err != nil {
t.Fatalf("stderr is not an error document: %v (%q)", err, s)
}
if doc.APIVersion != "vigil.error/v0" || doc.Error.Code != "usage" {
t.Fatalf("document = %+v", doc)
}
if !usageMessages[doc.Error.Message] {
t.Fatalf("message is not fixed text: %q", doc.Error.Message)
}
default:
t.Fatalf("exit %d: handlers that succeed leave only 0 and 3", code)
}
})
}
2 changes: 2 additions & 0 deletions cmd/vigil/testdata/fuzz/FuzzCLIArgs/2accfe88474a2571
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
go test fuzz v1
string("lp\"")
2 changes: 2 additions & 0 deletions cmd/vigil/testdata/fuzz/FuzzCLIArgs/52678d88f23b88fa
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
go test fuzz v1
string("-hh \"")
2 changes: 2 additions & 0 deletions cmd/vigil/testdata/fuzz/FuzzCLIArgs/949f7a65805732d7
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
go test fuzz v1
string("--overlay \" sources")
2 changes: 2 additions & 0 deletions cmd/vigil/testdata/fuzz/FuzzCLIArgs/9635a12fbf9e6bbc
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
go test fuzz v1
string("\"000000 -h")
2 changes: 2 additions & 0 deletions cmd/vigil/testdata/fuzz/FuzzCLIArgs/a259869c65214bce
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
go test fuzz v1
string("prom query a --host \" --host ")
100 changes: 100 additions & 0 deletions internal/httpx/fuzz_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
package httpx

import (
"context"
"net"
"net/url"
"strings"
"testing"
)

// FuzzBase: a base address is either refused with an error, or it is an http
// or https URL with a host and nothing else that could redirect a request: no
// userinfo, query, fragment, whitespace or dot segment.
func FuzzBase(f *testing.F) {
for _, s := range []string{
"http://example.test", "https://example.test:8443/p", "http://[::1]:9090", "http://192.0.2.7:9090/a/b",
"", "localhost:9090", "ftp://example.test", "http://user:pw@example.test", "http://example.test?x=1",
"http://example.test#f", "http://example.test/a/../b", "http://example.test/./a", "http://exa mple.test",
"//example.test", "http:example.test", "http://example.test\\@evil.test", "http://example.test/%2e%2e/x",
"http://example.test/a%2fb", "HTTP://EXAMPLE.TEST", "http://\x00example.test",
} {
f.Add(s)
}
f.Fuzz(func(t *testing.T, s string) {
c, err := New(Config{Base: s})
if err != nil {
if Code(err) == "" {
t.Fatalf("untyped error: %v", err)
}
return
}
u := c.base
if u.Scheme != "http" && u.Scheme != "https" {
t.Fatalf("scheme %q accepted from %q", u.Scheme, s)
}
if u.Hostname() == "" || u.User != nil || u.RawQuery != "" || u.Fragment != "" || u.Opaque != "" {
t.Fatalf("unsafe base accepted from %q: %+v", s, u)
}
if hasDotSegment(u.Path) || strings.ContainsAny(s, " \t\r\n\\") {
t.Fatalf("base %q accepted with a dot segment or whitespace", s)
}
})
}

// FuzzPath: an accepted path is a plain absolute path that survives a parse
// unchanged, and a refused path never reaches the dialer.
func FuzzPath(f *testing.F) {
for _, s := range []string{
"/api/v1/targets", "/-/ready", "/api/health", "", "/", "api/v1", "//evil.test/x", "/a/../b", "/a/./b",
"/a?x=1", "/a#f", "/a b", "/a%2e%2e/b", "/a\\b", "/a\nb", "http://example.test/x", "/a//b", "/%2e%2e", "/é",
// One reserved character each, so a rule that lets any of them
// through is caught by the seed run and not only by luck.
"/a?b", "/a#b", "/a%2e", "/a;b", "/a:b", "/a@b", "/a*b", "/a+b", "/a=b", "/a&b", "/a,b", "/a!b", "/a~b", "/a\"b",
} {
f.Add(s)
}
var dialed bool
c, err := newClient(Config{Base: "http://example.test"}, func(context.Context, string, string) (net.Conn, error) {
dialed = true
return nil, &net.OpError{Op: "dial", Err: net.ErrClosed}
})
if err != nil {
f.Fatal(err)
}
f.Fuzz(func(t *testing.T, p string) {
dialed = false
_, err := c.Get(context.Background(), Request{Path: p})
if err == nil {
t.Fatal("the dialer always fails, so Get cannot succeed")
}
if !validPath(p) {
if dialed {
t.Fatalf("a request went out for the refused path %q", p)
}
return
}
u, perr := url.Parse("http://example.test" + p)
if perr != nil || u.Path != p || u.RawQuery != "" || u.Fragment != "" || u.Host != "example.test" {
t.Fatalf("accepted path %q does not survive a parse: %+v (%v)", p, u, perr)
}
if strings.Contains(p, "//") || hasDotSegment(p) || p[0] != '/' {
t.Fatalf("accepted path %q has a doubled slash, a dot segment or no root", p)
}
for i := 0; i < len(p); i++ {
if c := p[i]; !plainPathChar(c) {
t.Fatalf("accepted path %q holds %q", p, c)
}
}
})
}

// plainPathChar is the set a fixed path may use, written out here and not
// borrowed from the code under test.
func plainPathChar(c byte) bool {
switch {
case c >= 'a' && c <= 'z', c >= 'A' && c <= 'Z', c >= '0' && c <= '9':
return true
}
return c == '/' || c == '-' || c == '_' || c == '.'
}
Loading
Loading