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: 4 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ This file is for agents changing the gatecheck repository. To use the gatecheck

## Layout

- `cmd/`: Cobra commands. `cmd/gatecheck` is `main`. `new<Name>Command` wires flags. Command behavior that is not flag parsing lives in `pkg/gatecheck`.
- `cmd/`: Cobra commands. `cmd/gatecheck` is `main`. `new<Name>Command` builds the command and its flags. Command behavior that is not flag parsing lives in `pkg/gatecheck`.
- `internal/fetch`: download and SHA-256 checks. `internal/bootstrap`: scanner install and passthrough. Pinned versions are the constants in `internal/bootstrap/versions.go`.
- `pkg/`: report decoding, validation, bundles, EPSS, and KEV.
- `docs/`: mdBook source for docs.gatecheck.dev. `docs/agent-guide.md` is the agent guide embedded by `docs/embed.go`.
Expand All @@ -26,5 +26,7 @@ This file is for agents changing the gatecheck repository. To use the gatecheck
- Check `gatecheck <command> --help` before describing a flag. `docs/cli-reference.md` matches the CLI on main.
- Report type is detected from file contents. A lowercase filename substring is the fallback when the contents are ambiguous. See `docs/supported-reports.md`.
- Coverage thresholds and EPSS scores are ratios from 0 to 1.
- Exit codes from `cmd/gatecheck`: 0 success, 1 threshold failure (`gatecheck.ErrValidationFailure`), 255 any other error (`os.Exit(-1)`). `grype`, `syft`, `gitleaks`, `semgrep`, `osemgrep`, `trivy`, and `osv-scanner` return the scanner's status. A missing scanner still exits 255.
- Exit codes come from `cmd.ExitCode`: 0 success, 1 threshold failure (`gatecheck.ErrValidationFailure`), 3 EPSS or KEV data failure (`gatecheck.ErrExternalData`), 2 any other error. The scanner passthrough commands return the scanner's status. A missing scanner exits 2.
- `cmd.NewGatecheckCommand` builds a new command tree on each call. Keep command state in the command's flags, not package variables. Settings are read flag, then `GATECHECK_*` environment variable, then default, through the helpers in `cmd/settings.go`.
- Tests in `cmd/cli_test.go` run the real command tree. Add a case there for a new flag or exit path.
- Do not add copyright notices.
34 changes: 34 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [UNRELEASED]

This release reworks the CLI settings layer and changes exit codes. See Changed. Fixes #73.

### Added

- OpenSSF Scorecard JSON (`scorecard --format json`) is a report type. The `scorecard` config section fails a report whose aggregate score, or a named check's score, is below a minimum. Inconclusive checks are skipped with a warning.
- trufflehog JSON (`--json`, one object per line) is a report type. `trufflehog.limitEnabled` fails on any finding, and `verifiedOnly` counts only verified secrets. `list` never prints secret values.
- `gatecheck bootstrap --tools scorecard,trufflehog,cosign` installs pinned OpenSSF Scorecard 5.6.0, trufflehog 3.99.8, and cosign 3.1.4, and `gatecheck scorecard`, `gatecheck trufflehog`, and `gatecheck cosign` run them. A failed `gatecheck cosign verify` fails the CI step with cosign's status. Fixes #105.

- `--log-level debug|info|warn|error` and `--log-format text|json` on every command, with `GATECHECK_LOG_LEVEL` and `GATECHECK_LOG_FORMAT`. Text logs are colored only on a terminal, and `NO_COLOR` turns color off.
- `validate --format table|markdown|json` prints the result to stdout. `list` and `list-all` take `--format table|markdown|json`. `list-all --format json` is one array keyed by file.
- `validate --input-type`, and `validate` reads stdin when FILE is omitted and `--input-type` is set.
- `validate --epss-url` and `--kev-url`. `list-all --epss-filename` and `--epss-url`.
- `GATECHECK_KEV_FILENAME` sets `--kev-filename`.
- `validate` warns when there is no config, and when the config has keys gatecheck does not read. `config convert` warns about those keys too.

- `gatecheck bootstrap --tools gosec,hadolint,zizmor` installs pinned gosec 2.30.0, hadolint 2.15.1, and zizmor 1.32.0. `gatecheck gosec`, `gatecheck hadolint`, and `gatecheck zizmor` run them. Their SARIF output is gated with the `sarif` config section. They are not part of the default install. zizmor publishes no checksum file, so its asset digests are pinned in gatecheck.
- `gatecheck bootstrap --list` shows every supported tool.
- The `license` config section fails Syft JSON and CycloneDX SBOMs whose package licenses match `deny` patterns, fall outside a non-empty `allow` list, or are missing when `denyUnknown` is set. SPDX `AND`, `OR`, and `WITH` expressions are evaluated. `packageRiskAcceptance` skips packages by purl or name. Fixes #103.
- `list` prints the packages and licenses in Syft JSON, and `validate` and bundles check Syft JSON with the license rules. Both used to return an error.
- `validate --vex FILE`, `GATECHECK_VEX`, and the config's `vex.files` read OpenVEX and CycloneDX VEX documents. Grype, CycloneDX, Trivy, and osv-scanner findings marked `not_affected`, `fixed`, `false_positive`, or `resolved` are skipped before the KEV, EPSS, and severity rules. A statement that names packages matches by package URL. The latest statement wins. Fixes #102.

### Changed

- Exit codes: 2 for usage errors, files that cannot be read or written, and reports, configs, or VEX files that cannot be decoded; 3 when EPSS or KEV data cannot be loaded. These used to be 255. A missing scanner for a passthrough command also exits 2.
- `--audit` only turns a threshold failure into exit 0. Unsupported reports, decode errors, and EPSS or KEV failures now fail in audit mode too.
- `--silent` keeps warnings. It used to show errors only. Use `--log-level error` for the old behavior.
- Coverage thresholds over 1 are read as percents, so `80` means `0.8`, with a warning.
- `config init` and `config convert` indent JSON and YAML by two spaces, and indent TOML tables. JSON config files write `metadata` for CVE entries instead of `Metadata`. Both spellings are read.
- `list-all` exits 2 when a file cannot be read or listed. It still lists the other files first. It loads EPSS data once per run instead of once per file.
- `bundle remove` of a label that is not in the bundle exits 2 and leaves the bundle unchanged.
- Each run builds a new command tree. configkit and Viper are gone. Settings are read flag, then environment variable, then default.

### Fixed

- `GATECHECK_VERBOSE`, `GATECHECK_SILENT`, and `GATECHECK_AUDIT` panicked on any value. They now take booleans, and a bad value is a usage error.
- `--audit=false` lost to `GATECHECK_AUDIT=true`. A flag now wins over its variable.
- The KEV file setting read `GATECHECK_EPSS_FILENAME`, so setting that variable made `validate` read the EPSS CSV as KEV.
- `bundle create` did not truncate an existing file, and `bundle add` and `bundle remove` could leave old bytes after a shorter bundle.
- The Grype KEV rule compared ids with case. It now ignores case and also checks a match's related CVE ids.
- EPSS CSV files with a `+0000` offset in the `score_date` header failed to parse.
- Config files are closed after reading. The EPSS and KEV files passed to `validate` and `list` are closed when the command ends.

## [0.10.0] - 2026-10-30

### Added
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ gatecheck validate --config gatecheck.yaml grype-report.json

`gatecheck agent-guide` (alias `llm`) prints a markdown guide for coding agents. The same text is `docs/agent-guide.md`.

`gatecheck bootstrap` installs pinned Grype, Syft, Gitleaks, semgrep's experimental osemgrep CLI, Trivy, and osv-scanner. `gatecheck grype`, `gatecheck syft`, `gatecheck gitleaks`, `gatecheck semgrep`, `gatecheck osemgrep`, `gatecheck trivy`, and `gatecheck osv-scanner` run them. `gatecheck bootstrap --tools gosec,hadolint,zizmor` adds gosec, hadolint, and zizmor, whose SARIF output `validate` reads.
`gatecheck bootstrap` installs pinned Grype, Syft, Gitleaks, semgrep's experimental osemgrep CLI, Trivy, and osv-scanner. `gatecheck grype`, `gatecheck syft`, `gatecheck gitleaks`, `gatecheck semgrep`, `gatecheck osemgrep`, `gatecheck trivy`, and `gatecheck osv-scanner` run them. `gatecheck bootstrap --tools gosec,hadolint,zizmor` adds gosec, hadolint, and zizmor, whose SARIF output `validate` reads. `--tools scorecard,trufflehog,cosign` adds OpenSSF Scorecard and trufflehog, whose JSON `validate` gates, and cosign for signature checks.

### Summarize Reports with List

Expand Down
2 changes: 1 addition & 1 deletion cmd/bootstrap.go
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ func newBootstrapCommand() *cobra.Command {
})
},
}
cmd.Flags().String("tools", "", "comma-separated scanners to install (default grype,syft,gitleaks,semgrep,trivy,osv-scanner; also gosec,hadolint,zizmor)")
cmd.Flags().String("tools", "", "comma-separated scanners to install (default grype,syft,gitleaks,semgrep,trivy,osv-scanner; also gosec,hadolint,zizmor,scorecard,trufflehog,cosign)")
cmd.Flags().Bool("force", false, "reinstall even when the pinned version is already present")
cmd.Flags().Bool("list", false, "print pinned versions, installed versions, and paths")
return cmd
Expand Down
168 changes: 79 additions & 89 deletions cmd/bundle.go
Original file line number Diff line number Diff line change
@@ -1,108 +1,98 @@
package cmd

import (
"log/slog"
"io"
"os"
"path"

"github.com/gatecheckdev/gatecheck/pkg/gatecheck"
"github.com/spf13/cobra"
)

var bundleCmd = &cobra.Command{
Use: "bundle",
Short: "create and manage a gatecheck bundle",
}

var bundleCreateCmd = &cobra.Command{
Use: "create BUNDLE_FILE TARGET_FILE",
Short: "create a new bundle with a new file",
Aliases: []string{"init"},
Args: cobra.ExactArgs(2),
PreRunE: func(cmd *cobra.Command, args []string) error {
bundleFilename := args[0]
targetFilename := args[1]

bundleFile, err := os.OpenFile(bundleFilename, os.O_CREATE|os.O_WRONLY, 0o644)
if err != nil {
return err
}
targetFile, err := os.Open(targetFilename)
if err != nil {
return err
}
func newBundleCommand() *cobra.Command {
bundleCmd := &cobra.Command{
Use: "bundle",
Short: "create and manage a gatecheck bundle",
}

RuntimeConfig.bundleFile = bundleFile
RuntimeConfig.targetFile = targetFile
RuntimeConfig.BundleTagValue = RuntimeConfig.BundleTag.Value().([]string)
return nil
},
RunE: func(cmd *cobra.Command, args []string) error {
targetFilename := args[1]
label := path.Base(targetFilename)
bf, tf := RuntimeConfig.bundleFile, RuntimeConfig.targetFile
tags := RuntimeConfig.BundleTagValue
return gatecheck.CreateBundle(bf, tf, label, tags)
},
}
createCmd := &cobra.Command{
Use: "create BUNDLE_FILE TARGET_FILE",
Short: "create a new bundle with one file, replacing BUNDLE_FILE if it exists",
Aliases: []string{"init"},
Args: cobra.ExactArgs(2),
RunE: func(cmd *cobra.Command, args []string) error {
target, err := os.Open(args[1])
if err != nil {
return err
}
defer func() { _ = target.Close() }()
bundleFile, err := os.OpenFile(args[0], os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o644)
if err != nil {
return err
}
err = gatecheck.CreateBundle(bundleFile, target, path.Base(args[1]), stringSliceSetting(cmd, "tag", "GATECHECK_BUNDLE_TAG"))
return closeAfter(bundleFile, err)
},
}

var bundleAddCmd = &cobra.Command{
Use: "add BUNDLE_FILE TARGET_FILE",
Short: "add a file to a bundle",
Args: cobra.ExactArgs(2),
PreRunE: func(cmd *cobra.Command, args []string) error {
bundleFilename := args[0]
targetFilename := args[1]
addCmd := &cobra.Command{
Use: "add BUNDLE_FILE TARGET_FILE",
Short: "add a file to a bundle",
Args: cobra.ExactArgs(2),
RunE: func(cmd *cobra.Command, args []string) error {
target, err := os.Open(args[1])
if err != nil {
return err
}
defer func() { _ = target.Close() }()
bundleFile, err := os.OpenFile(args[0], os.O_RDWR, 0o644)
if err != nil {
return err
}
err = gatecheck.AppendToBundle(bundleFile, target, path.Base(args[1]), stringSliceSetting(cmd, "tag", "GATECHECK_BUNDLE_TAG"))
return closeAfter(bundleFile, truncateAtOffset(bundleFile, err))
},
}

bundleFile, err := os.OpenFile(bundleFilename, os.O_RDWR, 0o644)
if err != nil {
return err
}
targetFile, err := os.Open(targetFilename)
if err != nil {
return err
}
removeCmd := &cobra.Command{
Use: "remove BUNDLE_FILE LABEL",
Short: "remove a file from a bundle by label",
Aliases: []string{"rm"},
Args: cobra.ExactArgs(2),
RunE: func(cmd *cobra.Command, args []string) error {
bundleFile, err := os.OpenFile(args[0], os.O_RDWR, 0o644)
if err != nil {
return err
}
err = gatecheck.RemoveFromBundle(bundleFile, args[1])
return closeAfter(bundleFile, truncateAtOffset(bundleFile, err))
},
}

RuntimeConfig.bundleFile = bundleFile
RuntimeConfig.targetFile = targetFile
RuntimeConfig.BundleTagValue = RuntimeConfig.BundleTag.Value().([]string)
return nil
},
RunE: func(cmd *cobra.Command, args []string) error {
targetFilename := args[1]
slog.Info("bundle tag", "environment", os.Getenv("GATECHECK_BUNDLE_TAG"))
label := path.Base(targetFilename)
bf, tf := RuntimeConfig.bundleFile, RuntimeConfig.targetFile
tags := RuntimeConfig.BundleTagValue
return gatecheck.AppendToBundle(bf, tf, label, tags)
},
for _, c := range []*cobra.Command{createCmd, addCmd} {
c.Flags().StringSliceP("tag", "t", nil, "tags for the added file, repeatable or comma-separated (env GATECHECK_BUNDLE_TAG)")
}
bundleCmd.AddCommand(createCmd, addCmd, removeCmd)
return bundleCmd
}

var bundleRemoveCmd = &cobra.Command{
Use: "remove BUNDLE_FILE TARGET_FILE",
Short: "remove a file from a bundle by label",
Aliases: []string{"rm"},
Args: cobra.ExactArgs(2),
PreRunE: func(cmd *cobra.Command, args []string) error {
bundleFilename := args[0]

bundleFile, err := os.OpenFile(bundleFilename, os.O_RDWR, 0o644)
if err != nil {
return err
}
RuntimeConfig.bundleFile = bundleFile
return nil
},
RunE: func(cmd *cobra.Command, args []string) error {
label := args[1]
return gatecheck.RemoveFromBundle(RuntimeConfig.bundleFile, label)
},
// truncateAtOffset drops bytes left over from a longer old bundle after it
// was rewritten in place.
func truncateAtOffset(f *os.File, err error) error {
if err != nil {
return err
}
offset, err := f.Seek(0, io.SeekCurrent)
if err != nil {
return err
}
return f.Truncate(offset)
}

func newBundleCommand() *cobra.Command {
RuntimeConfig.BundleTag.SetupCobra(bundleCreateCmd)
RuntimeConfig.BundleTag.SetupCobra(bundleAddCmd)

bundleCmd.AddCommand(bundleCreateCmd, bundleAddCmd, bundleRemoveCmd)
return bundleCmd
func closeAfter(f *os.File, err error) error {
closeErr := f.Close()
if err != nil {
return err
}
return closeErr
}
Loading
Loading