Guardrails / commands

The build runs no command this repository forbids

commands/forbidden-invocation@v1

No command the build ran matched the executable and arguments this guardrail is configured to look for.

Id	commands/forbidden-invocation
Version	v1
Category	commands
Default severity	error
Interpreter	python3
Timeout	30 seconds
Violations tolerated	0
Collects	commands

Collectors

This guardrail doesn't gather anything itself. It relies on the collectors below, which the CLI runs once per build before any check, and reads what they found from GUARDRAIL_FACTS. If a collector collects nothing, this guardrail is skipped, not failed.

Collector	Gathers	Inputs it is given
commands	Every command the build executed, read from the session a running buildnote monitor records on the runner. This is what the job actually ran, not what a pipeline file says it would run.	none

The inputs above are this guardrail's own inputs, passed straight through to the collector. Setting one in buildnote.json changes what is collected, and two guardrails configured the same way share a single collection.

Configuration

{
  "guardrails": {
      "failOn": "error",
      "checks": [
          {
              "use": "commands/forbidden-invocation@v1",
              "severity": "error",
              "with": {
                  "command": "",
                  "arguments": "",
                  "match": "any",
                  "reason": ""
              },
              "exemptions": []
          }
      ]
  }
}

Inputs

Input	Description	Default	Environment variable
command	Comma separated executable names to look for. Any one of them counts. Each is matched against the file name of every token in the recorded line, so /usr/local/bin/terraform and npx terraform both count, and so does a line that only mentions it, such as grep terraform Makefile.	``	GUARDRAIL_INPUT_COMMAND
arguments	Comma separated arguments that make an invocation a violation. Each is matched against the tokens of the command line exactly, in its <argument>=<value> form, and as a glob, so -Dskip.tests=* matches whatever value is set. If you name none, every invocation of the command is a violation.	``	GUARDRAIL_INPUT_ARGUMENTS
match	any reports an invocation carrying any one of the arguments, and all reports one carrying all of them.	any	GUARDRAIL_INPUT_MATCH
reason	Why this repository forbids the invocation. It replaces the default wording as the violation's message.	``	GUARDRAIL_INPUT_REASON

How to fix

Configure the executable and the arguments that make an invocation a violation. From the next run, the build is held to that rule:

{
  "guardrails": {
    "checks": [
      {
        "use": "commands/forbidden-invocation@v1",
        "with": {
          "command": "terraform,tofu",
          "arguments": "apply,-auto-approve",
          "match": "all",
          "reason": "Terraform is applied from the deploy pipeline rather than from a build"
        }
      }
    ]
  }
}

Each entry is one rule. To add another rule, list the guardrail again with different inputs, and each entry reports its own verdict.

If the reported invocation is one the build is meant to make, change the rule, not the pipeline: narrow arguments to the form that is actually dangerous, or remove the entry. A rule nobody can satisfy gets turned off within a week.

The guardrail reads what the build actually ran, as recorded by buildnote monitor, not what a pipeline file says it would run. A command reached through a wrapper script or a package runner is reported the same way as one written directly into the job.

The recorded command line is the process's argument vector joined by spaces, so the original quoting is lost, and the command name is looked for in every token. As a result, an argument written inside a quoted string looks exactly like an argument of the command, and a line that mentions the command as a word of its own, such as grep curl Dockerfile, looks like an invocation of it. Both are reported instead of being guessed away. The evidence is the recorded line, so you can see which of the two happened.