From 1c16a8aa012b589165286bedc4099bffa8903317 Mon Sep 17 00:00:00 2001 From: Manuel de Brito Fontes Date: Thu, 19 Nov 2026 01:51:06 -0300 Subject: [PATCH] planguard: whether a plan may be applied unread - nothing, apply, or person spinbox.dev follows the edge channel and its module's main, and every release and module commit was a plan somebody read and an apply somebody ran, for a change nobody chose (spin-terraform-aws#130: 29 merges in 15 days, 7 of them a release). planguard reads `tofu show -json` and says whether the plan only adds and updates in place - applied on a schedule - or takes something away: a delete, a replacement, a forget, an action it does not know, which a person reads. The plan cannot say which resources hold data, so none is assumed not to; a type named as made to be replaced may be, never deleted alone. Co-Authored-By: Claude Opus 5.5 --- README.md | 1 + cmd/planguard/main.go | 73 +++++++++++++++++++ cmd/planguard/main_test.go | 70 ++++++++++++++++++ internal/planguard/planguard.go | 104 +++++++++++++++++++++++++++ internal/planguard/planguard_test.go | 68 ++++++++++++++++++ site/src/content/docs/planguard.md | 38 ++++++++++ site/src/lib/nav.mjs | 1 + 7 files changed, 355 insertions(+) create mode 100644 cmd/planguard/main.go create mode 100644 cmd/planguard/main_test.go create mode 100644 internal/planguard/planguard.go create mode 100644 internal/planguard/planguard_test.go create mode 100644 site/src/content/docs/planguard.md diff --git a/README.md b/README.md index 9604957..bb363e7 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,7 @@ their `go.mod`; each fails CI with a specific finding and says how to resolve it | [`linkweight`](https://spin-stack.github.io/go-tools/linkweight/) | what each binary links and why: the bytes every module puts in it, the function that stops the linker dropping unused methods, the import whose cut drops the most, and a capability - exec, listen, mount, setuid - no line of the allowlist explains | | [`proven`](https://spin-stack.github.io/go-tools/proven/) | what CI already proved about a commit, by its tree: the run that answers for it, what a run on main is of, whether it may be released, each test's time, which failed tests are flaky | | [`exposure`](https://spin-stack.github.io/go-tools/exposure/) | what a repository would show if made public: secrets and private values in every ref's commits, pull request heads included, and in its issues, comments and releases | +| [`planguard`](https://spin-stack.github.io/go-tools/planguard/) | an OpenTofu plan that takes something away - a delete, a replacement, a forget - which an installation applying on a schedule leaves to a person, and applies the rest | | [`task`](https://spin-stack.github.io/go-tools/start/) | not a check: Task at the version `versions.yaml` pins, with every other go-tools command on its `PATH`, the tools at their latest release - both downloaded as binaries; the one command a repository's `go.mod` takes, so neither Task's modules nor the tools' are compiled or cached | | [`gencache`](https://spin-stack.github.io/go-tools/gencache/) | not a check: `go generate` with each mockgen directive answered from a cache when nothing its mock is made from has changed | | [`ghatrace`](https://spin-stack.github.io/go-tools/ghatrace/) | not a check: where a GitHub Actions run's time went - the critical path, each job's wait for a runner, its steps and the spans inside them - as the run's summary, an HTML page and a Perfetto trace, with nothing hosted | diff --git a/cmd/planguard/main.go b/cmd/planguard/main.go new file mode 100644 index 0000000..eda207a --- /dev/null +++ b/cmd/planguard/main.go @@ -0,0 +1,73 @@ +// Command planguard says whether an OpenTofu plan may be applied without a person reading it +// (internal/planguard): nothing, apply - creates and in-place updates alone - or person, with each +// change that took something away. An installation applying on a schedule applies what says apply +// and opens a pull request for what says person. +// +// tofu plan -out=plan.bin && tofu show -json plan.bin > plan.json +// go tool planguard [-replaceable aws_launch_template,...] plan.json +// +// The verdict is the first line on stdout, the changes held after it; in a workflow it is also +// verdict= in $GITHUB_OUTPUT. The exit status is 0 for any verdict and 2 for no answer, so a +// person's plan is not a failed step: what follows it is the workflow's choice. +package main + +import ( + "flag" + "fmt" + "io" + "os" + "strings" + + "github.com/spin-stack/go-tools/internal/planguard" +) + +func main() { + os.Exit(run(os.Args[1:], os.Stdout, os.Stderr)) // mutate-exempt: the process's own arguments; run is what the tests drive +} + +func run(args []string, stdout, stderr io.Writer) int { + fs := flag.NewFlagSet("planguard", flag.ContinueOnError) + fs.SetOutput(stderr) + replaceable := fs.String("replaceable", "", "resource types that may be replaced unread, comma-separated") + if err := fs.Parse(args); err != nil { + return 2 + } + if fs.NArg() != 1 { + say(stderr, "planguard: usage: planguard [-replaceable type,...] ") + return 2 + } + raw, err := os.ReadFile(fs.Arg(0)) + if err != nil { + say(stderr, "planguard:", err) + return 2 + } + var types []string + if *replaceable != "" { + types = strings.Split(*replaceable, ",") + } + d, err := planguard.Decide(raw, types) + if err != nil { + say(stderr, err) + return 2 + } + say(stdout, d.Verdict) + for _, h := range d.Held { + say(stdout, " "+h) + } + if path := os.Getenv("GITHUB_OUTPUT"); path != "" { + f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644) //nolint:gosec // the path the runner gives + if err != nil { + say(stderr, "planguard:", err) + return 2 + } + _, werr := fmt.Fprintf(f, "verdict=%s\n", d.Verdict) + if err := f.Close(); werr != nil || err != nil { + say(stderr, "planguard: $GITHUB_OUTPUT:", werr, err) + return 2 + } + } + return 0 +} + +// say writes one line. A line that cannot be written changes no exit status, which is the answer. +func say(w io.Writer, a ...any) { _, _ = fmt.Fprintln(w, a...) } diff --git a/cmd/planguard/main_test.go b/cmd/planguard/main_test.go new file mode 100644 index 0000000..2572b35 --- /dev/null +++ b/cmd/planguard/main_test.go @@ -0,0 +1,70 @@ +package main + +import ( + "bytes" + "os" + "path/filepath" + "testing" +) + +func write(t *testing.T, content string) string { + t.Helper() + p := filepath.Join(t.TempDir(), "plan.json") + if err := os.WriteFile(p, []byte(content), 0o600); err != nil { + t.Fatal(err) + } + return p +} + +const ( + applied = `{"format_version":"1.2","resource_changes":[{"address":"aws_launch_template.cp","type":"aws_launch_template","change":{"actions":["delete","create"]}}]}` + held = `{"format_version":"1.2","resource_changes":[{"address":"aws_s3_bucket.logs","type":"aws_s3_bucket","change":{"actions":["delete"]}}]}` +) + +// The verdict is the first line, the changes held after it, and verdict= in $GITHUB_OUTPUT; +// any verdict exits 0. A type named replaceable is replaced unread. +func TestTheVerdictIsSaidAndWrittenForTheWorkflow(t *testing.T) { + out := filepath.Join(t.TempDir(), "output") + t.Setenv("GITHUB_OUTPUT", out) + for _, tc := range []struct { + args []string + said, kept string + }{ + {[]string{write(t, held)}, "person\n aws_s3_bucket.logs: delete\n", "verdict=person\n"}, + {[]string{"-replaceable", "aws_instance,aws_launch_template", write(t, applied)}, "apply\n", "verdict=person\nverdict=apply\n"}, + {[]string{write(t, applied)}, "person\n aws_launch_template.cp: delete, create\n", "verdict=person\nverdict=apply\nverdict=person\n"}, + } { + var stdout, stderr bytes.Buffer + if code := run(tc.args, &stdout, &stderr); code != 0 || stdout.String() != tc.said { + t.Errorf("%v: %d, said %q (%s), want %q", tc.args, code, stdout.String(), stderr.String(), tc.said) + } + if got, err := os.ReadFile(out); err != nil || string(got) != tc.kept { + t.Errorf("%v: $GITHUB_OUTPUT has %q, %v; want %q", tc.args, got, err, tc.kept) + } + } +} + +// No plan, two, one that cannot be read or is not a plan, an unknown flag, and a $GITHUB_OUTPUT that +// cannot be written are no answer: exit 2, nothing on stdout. +func TestWhatGivesNoAnswerExitsTwo(t *testing.T) { + t.Setenv("GITHUB_OUTPUT", "") + for name, args := range map[string][]string{ + "no plan": nil, + "two": {write(t, held), write(t, held)}, + "none there": {filepath.Join(t.TempDir(), "none.json")}, + "not a plan": {write(t, "{}")}, + "a flag not": {"-x", write(t, held)}, + } { + var stdout, stderr bytes.Buffer + if code := run(args, &stdout, &stderr); code != 2 || stdout.Len() != 0 { + t.Errorf("%s: %d, said %q", name, code, stdout.String()) + } + } + for what, path := range map[string]string{"a directory": t.TempDir(), "a file that takes no write": "/dev/full"} { + t.Setenv("GITHUB_OUTPUT", path) + var stdout, stderr bytes.Buffer + if code := run([]string{write(t, held)}, &stdout, &stderr); code != 2 { + t.Errorf("a $GITHUB_OUTPUT that is %s: %d", what, code) + } + } +} diff --git a/internal/planguard/planguard.go b/internal/planguard/planguard.go new file mode 100644 index 0000000..f1ebb00 --- /dev/null +++ b/internal/planguard/planguard.go @@ -0,0 +1,104 @@ +// Package planguard decides whether an OpenTofu or Terraform plan may be applied without a person +// reading it: what an installation that follows a channel or its module's main applies on a +// schedule, and what it opens a pull request for instead. +// +// A plan is applied unread only when nothing in it is taken away: every change creates a resource +// or updates one in place. A delete, a replacement - delete and create, either order - and a +// forget (state that stops tracking a resource it does not delete) are a person's, whatever the +// resource: the plan cannot say which resources hold data, and a replaced database, bucket or key +// is the kind of change no schedule should make. A resource type a caller names as made to be +// replaced - a launch template's version, an instance an autoscaling group refreshes anyway - may +// be replaced, never deleted alone. +package planguard + +import ( + "encoding/json" + "fmt" + "slices" + "strings" +) + +// Verdict is what a plan asks for. +type Verdict string + +const ( + // Nothing is a plan with no change to a resource: nothing to apply. + Nothing Verdict = "nothing" + // Apply is a plan of creates and in-place updates alone, which may be applied unread. + Apply Verdict = "apply" + // Person is a plan that takes something away, which a person reads before it is applied. + Person Verdict = "person" +) + +// Decision is a plan's verdict, and each change that made it a person's. +type Decision struct { + Verdict Verdict + // Held are the changes a person has to read, "
: ", in the plan's order. + Held []string + // Changes is how many resources the plan changes. + Changes int +} + +// plan is what `tofu show -json ` says that this reads. +type plan struct { + FormatVersion string `json:"format_version"` + ResourceChanges []struct { + Address string `json:"address"` + Type string `json:"type"` + Mode string `json:"mode"` + Change struct { + Actions []string `json:"actions"` + } `json:"change"` + } `json:"resource_changes"` +} + +// Decide reads a plan as `tofu show -json` writes it. replaceable are the resource types that +// may be replaced unread. +func Decide(raw []byte, replaceable []string) (Decision, error) { + var p plan + if err := json.Unmarshal(raw, &p); err != nil { + return Decision{}, fmt.Errorf("planguard: not a plan's JSON: %w", err) + } + // A file with no format is not a plan: an empty object would read as nothing to do. + if p.FormatVersion == "" { + return Decision{}, fmt.Errorf("planguard: no format_version: not what `tofu show -json ` writes") + } + d := Decision{Verdict: Nothing} + for _, rc := range p.ResourceChanges { + actions := rc.Change.Actions + if len(actions) == 0 { + return Decision{}, fmt.Errorf("planguard: %s has no actions", rc.Address) + } + if changesNothing(actions) { + continue + } + d.Changes++ + if !held(rc.Type, actions, replaceable) { + continue + } + d.Held = append(d.Held, rc.Address+": "+strings.Join(actions, ", ")) + } + switch { + case len(d.Held) > 0: + d.Verdict = Person + case d.Changes > 0: + d.Verdict = Apply + } + return d, nil +} + +// changesNothing is a change that touches no resource: none, or a data source read. +func changesNothing(actions []string) bool { + return slices.Equal(actions, []string{"no-op"}) || slices.Equal(actions, []string{"read"}) +} + +// held is a change a person reads: anything but a create or an in-place update - a delete, a +// forget, or an action this does not know - unless it is a replacement of a type made to be +// replaced. +func held(typ string, actions []string, replaceable []string) bool { + if slices.Equal(actions, []string{"create"}) || slices.Equal(actions, []string{"update"}) { + return false + } + replace := len(actions) == 2 && slices.Contains(actions, "create") && slices.Contains(actions, "delete") + return !replace || !slices.Contains(replaceable, typ) +} diff --git a/internal/planguard/planguard_test.go b/internal/planguard/planguard_test.go new file mode 100644 index 0000000..2494311 --- /dev/null +++ b/internal/planguard/planguard_test.go @@ -0,0 +1,68 @@ +package planguard + +import ( + "strings" + "testing" +) + +// planOf is a plan's JSON with one resource change for each of changes, ". ,...". +func planOf(changes ...string) []byte { + var rcs []string + for _, c := range changes { + addr, acts, _ := strings.Cut(c, " ") + typ, _, _ := strings.Cut(addr, ".") + quoted := `"` + strings.ReplaceAll(acts, ",", `","`) + `"` + rcs = append(rcs, `{"address":"module.spin.`+addr+`","type":"`+typ+`","mode":"managed","change":{"actions":[`+quoted+`]}}`) + } + return []byte(`{"format_version":"1.2","resource_changes":[` + strings.Join(rcs, ",") + `]}`) +} + +// A plan is nothing with no change to a resource, applied with creates and in-place updates alone, +// and a person's with anything taken away - a delete, a replacement, a forget, an action not known - +// unless it replaces a type named as made to be replaced; never a delete alone. +func TestAPlanIsAppliedUnreadOnlyWhenNothingIsTakenAway(t *testing.T) { + replaceable := []string{"aws_launch_template"} + for name, tc := range map[string]struct { + plan []byte + verdict Verdict + held []string + changes int + }{ + "no changes": {planOf("aws_s3_bucket.logs no-op", "aws_ami.image read"), Nothing, nil, 0}, + "none at all": {[]byte(`{"format_version":"1.2"}`), Nothing, nil, 0}, + "creates and updates": {planOf("aws_launch_template.cp update", "aws_ssm_parameter.pcrs create", "aws_kms_key.cp update"), Apply, nil, 3}, + "a delete": {planOf("aws_launch_template.cp update", "aws_s3_bucket.logs delete"), Person, []string{"module.spin.aws_s3_bucket.logs: delete"}, 2}, + "a replacement": {planOf("aws_db_instance.state delete,create"), Person, []string{"module.spin.aws_db_instance.state: delete, create"}, 1}, + "a create-first replace": {planOf("aws_kms_key.cp create,delete"), Person, []string{"module.spin.aws_kms_key.cp: create, delete"}, 1}, + "a forget": {planOf("aws_route53_zone.z forget"), Person, []string{"module.spin.aws_route53_zone.z: forget"}, 1}, + "an action not known": {planOf("aws_iam_role.r adopt"), Person, []string{"module.spin.aws_iam_role.r: adopt"}, 1}, + "a replaceable replaced": {planOf("aws_launch_template.cp delete,create", "aws_launch_template.px create,delete"), Apply, nil, 2}, + "a replaceable deleted": {planOf("aws_launch_template.cp delete"), Person, []string{"module.spin.aws_launch_template.cp: delete"}, 1}, + "three actions": {planOf("aws_launch_template.cp delete,create,update"), Person, []string{"module.spin.aws_launch_template.cp: delete, create, update"}, 1}, + } { + t.Run(name, func(t *testing.T) { + d, err := Decide(tc.plan, replaceable) + if err != nil { + t.Fatal(err) + } + if d.Verdict != tc.verdict || strings.Join(d.Held, ";") != strings.Join(tc.held, ";") || d.Changes != tc.changes { + t.Errorf("%+v, want %s held %v changes %d", d, tc.verdict, tc.held, tc.changes) + } + }) + } +} + +// What is not a plan's JSON - not JSON, an object with no format, a change with no actions - is +// an error, never nothing to do. +func TestWhatIsNotAPlanIsRefused(t *testing.T) { + for name, raw := range map[string]string{ + "not JSON": "{", + "no format": `{"resource_changes":[]}`, + "no actions": `{"format_version":"1.2","resource_changes":[{"address":"a.b","type":"a","change":{"actions":[]}}]}`, + "a plan's text": "Plan: 1 to add, 0 to change, 0 to destroy.", + } { + if d, err := Decide([]byte(raw), nil); err == nil { + t.Errorf("%s: %+v", name, d) + } + } +} diff --git a/site/src/content/docs/planguard.md b/site/src/content/docs/planguard.md new file mode 100644 index 0000000..4138e38 --- /dev/null +++ b/site/src/content/docs/planguard.md @@ -0,0 +1,38 @@ +--- +title: planguard +description: Whether an OpenTofu plan may be applied without a person reading it - nothing, apply, or person - so an installation can apply on a schedule what only adds and updates, and leave the rest to a pull request. +--- + +An installation that follows a release channel, or its module's main, changes without anybody +writing a commit: a new release moves the images its launch templates name, a new module commit +moves whatever it moves. Applying each of those by hand is a plan read and a button pressed for a +change nobody chose. Applying all of them on a schedule is how a database gets replaced on a +Tuesday night. `planguard` draws the line between the two from the plan itself. + +```sh +tofu plan -out=plan.bin +tofu show -json plan.bin > plan.json +go tool planguard [-replaceable aws_launch_template,...] plan.json +``` + +| the plan | verdict | +|---|---| +| no resource changes - nothing, or only data sources read | `nothing` | +| creates and in-place updates, and nothing else | `apply`: applied unread | +| any delete, replacement (delete and create, either order), forget, or an action it does not know | `person`: each such change is listed | + +The plan cannot say which resources hold data, so every resource is treated as one that might: +a replaced bucket, database or KMS key is a person's whatever its type. A type made to be replaced - +`-replaceable aws_launch_template` - may be replaced unread, but never deleted alone. + +The verdict is the first line on stdout and the changes held follow it; in GitHub Actions it is +also `verdict=` in `$GITHUB_OUTPUT`, for a step's `if:`. Every verdict exits 0 - a plan that is +a person's is not a failed run - and what cannot be read exits 2, never `nothing`. + +```yaml title=".github/workflows/auto.yml" +- run: go tool task plan:json # tofu plan -out, tofu show -json +- id: guard + run: go tool task guard # go tool planguard plan.json +- if: steps.guard.outputs.verdict == 'apply' + run: go tool task apply:saved # tofu apply plan.bin: what was judged is what is applied +``` diff --git a/site/src/lib/nav.mjs b/site/src/lib/nav.mjs index 02919a9..ead20d6 100644 --- a/site/src/lib/nav.mjs +++ b/site/src/lib/nav.mjs @@ -30,6 +30,7 @@ export const sidebar = [ { label: 'sfw', slug: 'sfw' }, { label: 'Provenance and SBOMs', slug: 'supply-chain' }, { label: 'exposure', slug: 'exposure' }, + { label: 'planguard', slug: 'planguard' }, ], }, { label: 'Doing less work', items: [{ label: 'gencache', slug: 'gencache' }] },