If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/goss-org/goss shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 27+ active contributors
• Distributed ownership (top contributor 34% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live goss-org/goss repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/goss-org/goss.

What it runs against: a local clone of goss-org/goss — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in goss-org/goss | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 401 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of goss-org/goss. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/goss-org/goss.git
#   cd goss
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of goss-org/goss and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "goss-org/goss(\\.git)?\\b" \\
  && ok "origin remote is goss-org/goss" \\
  || miss "origin remote is not goss-org/goss (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "cmd/goss/goss.go" \\
  && ok "cmd/goss/goss.go" \\
  || miss "missing critical file: cmd/goss/goss.go"
test -f "goss_config.go" \\
  && ok "goss_config.go" \\
  || miss "missing critical file: goss_config.go"
test -f "add.go" \\
  && ok "add.go" \\
  || miss "missing critical file: add.go"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 401 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~371d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/goss-org/goss"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Goss is a YAML-based server validation tool written in Go that generates and executes test suites to verify server configuration state. It reads test specs from gossfile.yaml and can run them as one-off tests, watch loops, or HTTP health endpoints—offering an alternative to ServerSpec with a focus on simplicity and speed (sub-10MB single binary, near-instantaneous execution on medium test suites). Monolithic CLI tool: cmd/goss/goss.go is the entry point, add.go handles test generation from live systems, main package logic infers types from the system state and serializes to YAML. Complementary extras/ folder contains wrapper scripts (dgoss for Docker, kgoss for Kubernetes, dcgoss for Docker Compose) that are shell-based adapters around the core goss binary.

DevOps engineers, SREs, and infrastructure developers who need to validate server configuration (packages installed, services running, ports listening, user accounts present, files with correct permissions) across Linux/Unix environments—particularly those running containers (Docker, Kubernetes) or managing infrastructure as code.

Production-ready and actively maintained. The project has substantial GitHub release history, organized CI/CD pipelines (GitHub Actions for linting, testing, building Docker images), and comprehensive documentation at goss.rocks. The codebase is 321KB of Go with supporting shell scripts, indicating a mature, focused tool. Last activity visible through maintained GitHub workflows and regular dependency updates (dependabot.yml present).

Low risk for typical use. Single-language implementation (Go) reduces dependency complexity. The tool is read-only (doesn't modify system state), limiting blast radius of bugs. Minor risk: wrapper scripts (dgoss, kgoss, dcgoss) for containers live in extras/ and may have different maintenance cycles than the core binary. No obvious sign of critical backlog from file structure.

Active maintenance visible through GitHub Actions workflows (docker-goss.yaml, release.yaml, golangci.yaml, trivy-schedule.yaml) and dependabot.yml indicating regular dependency scanning. Documentation is actively maintained in docs/ with changelog.md tracking releases. .travis.yml suggests legacy CI; modern workflow is GitHub Actions–based.

git clone https://github.com/goss-org/goss.git
cd goss
make
# or: go build -o goss ./cmd/goss/goss.go
./goss generate
./goss validate

The Makefile orchestrates build, test, and install targets. For quick install: curl -fsSL https://goss.rocks/install | sh

Daily commands:

make build          # Compile goss binary
make test           # Run test suite (ci/go-test.sh)
make fmt            # Run gofmt checks (ci/go-fmt.sh)

Or directly: go run ./cmd/goss/goss.go validate (if goss.yaml exists in cwd).

• cmd/goss/goss.go — Entry point for the CLI application; all command-line interactions flow through this file.
• goss_config.go — Core configuration parsing and validation logic; defines how gossfiles are read and interpreted.
• add.go — Implements the 'goss add' command for discovering and adding system resources to gossfiles.
• go.mod — Declares all Go dependencies; critical for understanding external library versions and compatibility.
• Makefile — Build and test orchestration; shows how to compile, test, and package goss for all platforms.
• docs/gossfile.md — Primary reference for gossfile syntax and structure; essential for understanding the validation DSL.
• .github/workflows/release.yaml — Automated release pipeline; defines how binaries are built and published for multiple OS/arch.

• CLI Handler (cmd/goss/goss.go) (Go flag/cobra-like parsing, os.Stderr/Stdout) — Parses command-line flags, routes subcommands, handles I/O
  • Failure mode: Invalid flags cause exit 1; invalid subcommand shows usage
• Gossfile Parser (goss_config.go) (gopkg.in/yaml, Go text/template) — Loads YAML/JSON, applies variable templating, validates schema
  • Failure mode: Parse error halts validation immediately with diagnostic output
• Validation Engine (goss_test.go) (Go goroutines, os/exec, filesystem APIs) — Executes all resources in parallel, collects results, applies matchers
  • Failure mode: Individual resource failure recorded; engine continues to completion
• System Probes (os, os/exec, net, regexp packages) — Direct inspection: files, packages, services, ports, kernel state
  • Failure mode: Permission denied or missing system command results in resource failure
• Container Wrappers (dgoss/kgoss/dcgoss) (Shell scripts, docker/kubectl CLI invocation) — Injects gossfile into container, executes goss, streams output
  • Failure mode: Container not running or inaccessible causes wrapper failure

• User shell → goss CLI binary — Command-line args and flags (subcommand, gossfile path, output format)
• goss CLI → Gossfile (YAML/JSON) — Reads resource definitions and assertions
• Gossfile Parser → Validation Engine — Parsed resource list with matchers and assertions
• Validation → undefined — undefined

Add a new resource type validation

1. Define the resource struct and parsing logic in a new file (e.g., resource_newtype.go) (goss_config.go)
2. Implement the Validate() method for your resource type (goss_test.go)
3. Register the resource in the gossfile schema (docs/schema.yaml)
4. Add integration test cases for the new resource (integration-tests/goss/alpine3/goss.yaml)
5. Document usage in gossfile reference (docs/gossfile.md)

Add a new CLI subcommand

1. Create handler function in cmd/goss/goss.go or separate file (cmd/goss/goss.go)
2. Register the command with CLI argument parsing (cmd/goss/goss.go)
3. Document the command in CLI reference (docs/cli.md)
4. Add test cases in integration tests (integration-tests/goss)

Add support for a new container platform

1. Create wrapper script following dgoss/kgoss pattern (extras/dgoss/dgoss)
2. Implement platform detection and gossfile injection (extras/dgoss/dgoss)
3. Document the wrapper with usage examples (extras/dgoss/README.md)
4. Add integration tests for the platform (integration-tests/goss)

• Go — Single static binary deployment; fast execution; minimal resource footprint for server validation
• YAML gossfiles — Human-readable declarative syntax; familiar to DevOps practitioners; easy version control integration
• Docker/Kubernetes wrappers — Extends goss to container ecosystems without modifying core; wrapper pattern allows independent evolution
• GitHub Actions workflows — Automated multi-platform cross-compilation and release distribution (Linux, macOS, Windows)

• Wrapper scripts (dgoss/kgoss) instead of native container integration

  • Why: Keeps core goss simple and platform-agnostic; wrappers can be updated independently
  • Consequence: Requires separate shell scripts; adds slight operational complexity but increases modularity

• Stateless validation (no state persistence between runs)

  • Why: Simplifies testing model; each run is idempotent and reproducible
  • Consequence: Cannot track changes over time without external tooling; each invocation is independent

• Direct system probe approach (no agent/daemon)

  • Why: Minimal operational overhead; works in ephemeral containers and CI/CD pipelines
  • Consequence: Must have direct OS/API access; cannot validate systems remotely without wrappers

• Real-time monitoring (not a daemon; validates at point-in-time)
• Distributed tracing or telemetry aggregation
• Windows Server native support (focus on Linux containers and cloud-native)
• Remediation/self-healing (validation and reporting only; no auto-fix)
• Complex orchestration (composable with external tools like Ansible, not a replacement)

No global ~/.goss config file: All configuration is per-invocation via flags or gossfile.yaml in current directory. File ownership validation requires root or matching UID: Some validation modes may fail unprivileged; dgoss/kgoss bypass this by running inside containers. YAML indentation is strict: malformed gossfile.yaml fails silently with generic parse errors. Service/package validation backend-dependent: 'dpkg' vs 'rpm' vs 'apk' auto-detected from system; cross-platform gossfiles may not be portable. Serve mode listens on all interfaces by default: Security consideration if goss serve is exposed to untrusted networks.

• State Snapshot Generation & Validation — Goss's core innovation: goss add reads live system state and generates tests from it (file permissions, installed packages, running processes), turning infrastructure inspection into test definition—this reverses traditional TDD workflow for ops.
• YAML-based DSL for Infrastructure Testing — Goss uses YAML (not code) for test specs, lowering the barrier for operators without programming experience to write and maintain tests; understanding YAML structure and validation rules is central to using goss effectively.
• Container-aware Testing (dgoss/kgoss) — Goss extends beyond bare-metal via wrapper scripts that inject tests into running containers (Docker, Kubernetes); understanding container execution context, namespace isolation, and mount propagation is key for container validation.
• Health Check Serving (HTTP Endpoint) — Goss can run in serve mode, exposing a /health endpoint that returns live validation results—this enables Kubernetes liveness/readiness probes and load balancer health checks without external agents.
• Idempotent Test Re-execution (watch mode) — Goss supports watch mode for continuous validation polling; understanding polling intervals, backoff, and transient failure handling is important for monitoring and debugging flaky infrastructure.
• Cross-platform Package Manager Detection — Goss automatically detects whether to use dpkg, rpm, apk, or other package managers; writing portable gossfiles requires understanding this auto-detection and when it may fail on mixed-OS environments.
• TAP / JUnit Test Output Formats — Goss can serialize results in TAP (Test Anything Protocol) and JUnit XML for CI/CD integration; understanding these formats is critical for integrating goss into Jenkins, GitLab CI, GitHub Actions, etc.

• aelsabbahy/goss — Original author's namespace; contains the canonical goss implementation
• serverspec/serverspec — Direct predecessor and inspiration: Ruby-based server spec testing tool that goss was designed as a simpler, faster YAML alternative to
• cilium/cilium — Major user of goss: Cilium uses goss (via dgoss/kgoss) for container networking policy validation in Kubernetes test suites
• bats-core/bats-core — Complementary testing approach: BATS is bash-based unit testing that often runs alongside goss for script validation vs. state validation
• inspec/inspec — Alternative compliance/validation framework (Ruby-based): offers similar server state testing but with more policy/compliance focus; users often compare goss vs. InSpec for simplicity/speed tradeoff

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for dgoss wrapper functionality

The extras/dgoss directory exists but there's no dedicated CI workflow testing the dgoss wrapper against actual Docker containers. Currently, docker-integration-tests.yaml likely tests goss itself, but dgoss (the Docker wrapper mentioned in the README) lacks explicit test coverage. This is high-value because dgoss is a primary use case mentioned in the README and needs reliability for container testing workflows.

• [ ] Create ci/dgoss-test.sh to test dgoss wrapper against sample Docker containers
• [ ] Add a new GitHub workflow at .github/workflows/dgoss-integration-tests.yaml that runs on pull requests
• [ ] Test dgoss with docker-compose files in examples/ and extras/dcgoss/ directories
• [ ] Verify dgoss works with various image types and validates goss.yaml test files correctly

Create schema validation tests for goss.yaml gossfile format

The repo has docs/schema.yaml and docs/gossfile.md documenting the gossfile format, but there are no automated tests validating that example gossfiles conform to the schema. This is valuable because it prevents documentation drift and ensures examples (in examples/ and docs/) are always valid templates for users.

• [ ] Add a CI test in ci/ that uses a schema validator (e.g., yamllint or json-schema validator) against docs/schema.yaml
• [ ] Create ci/gossfile-validate.sh to validate all example gossfiles: examples/goss.yaml, examples/goss_awesome_gomega.yaml, docs/goss.yaml, docs/rendered_goss.yaml
• [ ] Integrate this validation into .github/workflows/yamllint.yaml or create a dedicated workflow
• [ ] Document the validation process in .github/CONTRIBUTING.md so contributors validate their gossfile examples

Add Go benchmarks for core validation functions in add.go and main goss.go

The repo has ci/go-test.sh for unit tests but no performance benchmarks. Since goss is a validation tool that users run repeatedly in CI/CD pipelines, performance regressions are critical to catch. This is specific because add.go likely handles resource validation operations that could regress.

• [ ] Create benchmarks in cmd/goss/goss_bench_test.go to measure performance of core validation operations
• [ ] Add benchmarks for add.go operations (if add.go contains validation logic) to catch performance regressions
• [ ] Integrate Go benchmark comparisons into .github/workflows/golangci.yaml or a new performance workflow
• [ ] Document benchmark results in docs/contributing.md so contributors understand performance expectations

• Add integration test coverage for port validation on uncommon protocols: docs/gossfile.md documents port resource type, but .github/workflows/docker-integration-tests.yaml may lack tests for UDP, SCTP, or IPv6 ports—contributing a new test case and documenting in test suite improves reliability.
• Document goss output format (JSON, TAP, JUnit) with examples in docs/: README and docs/cli.md mention output flags but lack example output blocks; adding markdown snippets showing --output-format json output would help users integrate goss into CI pipelines.
• Add Windows/PowerShell support validation tests in CI: .github/workflows/ are Linux-only; the file structure includes PowerShell (443 bytes), suggesting Windows is planned or partially supported but untested—adding a CI job or documenting Windows limitations would clarify scope.
• Create shell linting for extras/ wrapper scripts in CI: .github/workflows/golangci.yaml lints Go, but .github/workflows/ lacks shellcheck integration for extras/dgoss, extras/kgoss, extras/dcgoss despite them being user-facing entry points.
• Expand development/README.md with Vagrant setup instructions: development/debian/Vagrantfile exists but development/README.md is sparse; documenting how to spin up a test VM for local goss development would lower barrier for contributors.

The Goss project demonstrates a generally secure posture with multi-stage Docker builds, minimal attack surface (Alpine base), and proper use of CGO_ENABLED=0 for static compilation. The main recommendations focus on maintaining up-to-date dependencies and implementing automated security scanning. No critical vulnerabilities or hardcoded secrets were detected in the analyzed files. The codebase follows good practices with proper CI/CD workflows including golangci, Trivy scanning, and Dependabot integration. Primary areas for improvement include regular dependency updates, explicit security policies, and health checks in container images.

• Medium · Outdated Go Version in Dockerfile — Dockerfile (line: ARG GO_VERSION=1.22). The Dockerfile uses Go 1.22 as the base image for compilation. While this is relatively recent, it's important to ensure the Go version is kept up-to-date with security patches. The build process should regularly update to the latest stable Go version to receive security fixes. Fix: Implement a process to regularly update the GO_VERSION argument to the latest stable Go release. Consider using automated dependency checking tools like Dependabot for the Dockerfile as well.
• Medium · Alpine Base Image Without Explicit Version Pin — Dockerfile (line: FROM alpine:3.19). The Dockerfile uses 'alpine:3.19' which, while pinned to a specific version, could still receive security updates. However, the production image should ensure that security patches are regularly applied and the image is rebuilt periodically. Fix: Keep the Alpine base image updated regularly. Consider using Alpine with a specific patch version (e.g., 'alpine:3.19.1') for better reproducibility, and implement automated image rebuilds to receive OS-level security patches.
• Low · Potential Information Disclosure via Build Arguments — Dockerfile (line: ARG GOSS_VERSION=v0.0.0). The GOSS_VERSION is exposed as a build argument and embedded in the binary via ldflags. While this is typically acceptable for version information, ensure that no sensitive data is passed through build arguments that could be exposed in image history. Fix: Ensure that only non-sensitive information is passed through build arguments. Implement build argument validation and document which arguments are safe to expose.
• Low · Missing HEALTHCHECK in Production Docker Image — Dockerfile. The Dockerfile does not include a HEALTHCHECK instruction for the production container, which could make it difficult to detect if the goss service becomes unresponsive in orchestrated environments. Fix: Consider adding a HEALTHCHECK instruction to the production Alpine image to enable container orchestration platforms to automatically detect unhealthy containers.
• Low · Unspecified Python Dependency Versions in Documentation — docs/requirements.txt (dependencies: mkdocs-material==9.5.23, pygments==2.18.0, etc.). The docs/requirements.txt file contains Python dependencies with pinned versions, but the security analysis shows relatively recent versions. However, some dependencies may have known vulnerabilities that should be monitored. Fix: Implement regular dependency scanning using tools like Safety or Bandit for Python dependencies. Keep dependencies updated and monitor security advisories for known vulnerabilities in mkdocs and related packages.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.