goss

README

Goss - Quick and Easy server validation

**

Goss in 45 seconds

Note: For an even faster way of doing this, see: autoadd

Note: For testing docker containers see the dgoss wrapper. Also, user submitted wrapper scripts for Kubernetes kgoss and Docker Compose dcgoss.

Note: For some Docker/Kubernetes healthcheck, health endpoint, and container ordering examples, see my blog post here.

Introduction

What is Goss?

Goss is a YAML based serverspec alternative tool for validating a server’s configuration. It eases the process of writing tests by allowing the user to generate tests from the current system state. Once the test suite is written they can be executed, waited-on, or served as a health endpoint.

Why use Goss?

• Goss is EASY! - Goss in 45 seconds
• Goss is FAST! - small-medium test suites are near instantaneous, see benchmarks
• Goss is SMALL! - <10MB single self-contained binary

Installation

Note: For macOS and Windows, see: platform-feature-parity.

This will install goss and dgoss.

Note: Using curl | sh is not recommended for production systems, use manual installation below.

# Install latest version to /usr/local/bin
curl -fsSL https://goss.rocks/install | sh

# Install v0.3.16 version to ~/bin
curl -fsSL https://goss.rocks/install | GOSS_VER=v0.3.16 GOSS_DST=~/bin sh

Manual installation

Latest

curl -L https://github.com/goss-org/goss/releases/latest/download/goss-linux-amd64 -o /usr/local/bin/goss
chmod +rx /usr/local/bin/goss

curl -L https://github.com/goss-org/goss/releases/latest/download/dgoss -o /usr/local/bin/dgoss
# Alternatively, using the latest master
# curl -L https://raw.githubusercontent.com/goss-org/goss/master/extras/dgoss/dgoss -o /usr/local/bin/dgoss
chmod +rx /usr/local/bin/dgoss

Specific Version

# See https://github.com/goss-org/goss/releases for release versions
VERSION=v0.3.10
curl -L "https://github.com/goss-org/goss/releases/download/${VERSION}/goss-linux-amd64" -o /usr/local/bin/goss
chmod +rx /usr/local/bin/goss

# (optional) dgoss docker wrapper (use 'master' for latest version)
VERSION=v0.3.10
curl -L "https://github.com/goss-org/goss/releases/download/${VERSION}/dgoss" -o /usr/local/bin/dgoss
chmod +rx /usr/local/bin/dgoss

Build it yourself

make build

Full Documentation

Documentation is available here: manual

Quick start

Writing a simple sshd test

An initial set of tests can be derived from the system state by using the add or autoadd commands.

Let's write a simple sshd test using autoadd.

# Running it as root will allow it to also detect ports
$ sudo goss autoadd sshd

Generated goss.yaml:

$ cat goss.yaml
port:
  tcp:22:
    listening: true
    ip:
    - 0.0.0.0
  tcp6:22:
    listening: true
    ip:
    - '::'
service:
  sshd:
    enabled: true
    running: true
user:
  sshd:
    exists: true
    uid: 74
    gid: 74
    groups:
    - sshd
    home: /var/empty/sshd
    shell: /sbin/nologin
group:
  sshd:
    exists: true
    gid: 74
process:
  sshd:
    running: true

Now that we have a test suite, we can:

• Run it once

goss validate
...............

Total Duration: 0.021s # <- yeah, it's that fast..
Count: 15, Failed: 0

• Edit it to use templates, and run with a vars file

goss --vars vars.yaml validate

• keep running it until the system enters a valid state or we timeout

goss validate --retry-timeout 30s --sleep 1s

• serve the tests as a health endpoint

goss serve &
curl localhost:8080/healthz

# JSON endpoint
goss serve --format json &
curl localhost:8080/healthz

# rspecish response via content negotiation
goss serve --format json &
curl -H "Accept: application/vnd.goss-rspecish" localhost:8080/healthz

Manually editing Goss files

Goss files can be manually edited to improve readability and expressiveness of tests.

A Json draft 7 schema available in docs/goss-json-schema.yaml makes it easier to edit simple goss.yaml files in IDEs, providing usual coding assistance such as inline documentation, completion and static analysis. See PR 793 for screenshots.

For example, to configure the Json schema in JetBrains intellij IDEA, follow documented instructions, with arguments such as schema url=https://raw.githubusercontent.com/goss-org/goss/master/docs/goss-json-schema.yaml, schema version=Json schema version 7, file path pattern=*/goss.yaml

In addition, Goss files can also be further manually edited (without yet full json support) to use:

• Patterns
• Advanced Matchers
• Templates
• title and meta (arbitrary data) attributes are persisted when adding other resources with goss add

Some examples:

user:
  sshd:
    title: UID must be between 50-100, GID doesn't matter. home is flexible
    meta:
      desc: Ensure sshd is enabled and running since it's needed for system management
      sev: 5
    exists: true
    uid:
      # Validate that UID is between 50 and 100
      and:
        gt: 50
        lt: 100
    home:
      # Home can be any of the following
      or:
      - /var/empty/sshd
      - /var/run/sshd

package:
  kernel:
    installed: true
    versions:
      # Must have 3 kernels and none of them can be 4.4.0
      and:
      - have-len: 3
      - not:
          contain-element: 4.4.0

  # Loaded from --vars YAML/JSON file
  {{.Vars.package}}:
    installed: true

{{if eq .Env.OS "centos"}}
  # This test is only when $OS environment variable is set to "centos"
  libselinux:
    installed: true
{{end}}

Goss.yaml files with templates can still be validated through the Json schema after being rendered using the goss render command. See example below

cd docs
goss --vars ./vars.yaml render > rendered_goss.yaml 
# proceed with json schema validation of rendered_goss.yaml in your favorite IDE 
# or in one of the Json schema validator listed in https://json-schema.org/implementations.html
# The following example is for a Linux AMD64 host 
curl -LO https://github.com/neilpa/yajsv/releases/download/v1.4.1/yajsv.linux.amd64
chmod a+x yajsv.linux.amd64 
sudo mv yajsv.linux.amd64 /usr/sbin/yajsv

yajsv -s goss-json-schema.yaml rendered_goss.yaml

rendered_goss.yaml: fail: process.chrome: skip is required
rendered_goss.yaml: fail: service.sshd: skip is required
1 of 1 failed validation
rendered_goss.yaml: fail: process.chrome: skip is required
rendered_goss.yaml: fail: service.sshd: skip is required

Full list of available Json schema validators can be found in https://json-schema.org/implementations.html#validator-command%20line

Supported resources

• package - add new package
• file - add new file
• addr - add new remote address:port - ex: google.com:80
• port - add new listening [protocol]:port - ex: 80 or udp:123
• service - add new service
• user - add new user
• group - add new group
• command - add new command
• dns - add new dns
• process - add new process name
• kernel-param - add new kernel-param
• mount - add new mount
• interface - add new network interface
• http - add new network http url with proxy support
• goss - add new goss file, it will be imported from this one
• matching - test for matches in supplied content

Supported output formats

• rspecish - (default) Similar to rspec output
• documentation - Verbose test results
• json - JSON, detailed test result
• tap - TAP style
• junit - JUnit style
• nagios - Nagios/Sensu compatible output /w exit code 2 for failures.
• prometheus - Prometheus compatible output.
• silent - No output. Avoids exposing system information (e.g. when serving tests as a healthcheck endpoint).

Community Contributions

• goss-ansible - Ansible module for Goss.
• degoss - Ansible role for installing, running, and removing Goss in a single go.
• kitchen-goss - A test-kitchen verifier plugin for Goss.
• goss-fpm-files - Might be useful for building goss system packages.
• molecule - Automated testing for Ansible roles, with native Goss support.
• packer-provisioner-goss - A packer plugin to run Goss as a provision step.
• gossboss - Collect and view aggregated Goss test results from multiple remote Goss servers.

Limitations

goss works well on Linux, but support on Windows & macOS is alpha. See platform-feature-parity.

The following tests have limitations.

Package:

• rpm
• deb
• Alpine apk
• pacman

Service:

• systemd
• sysV init
• OpenRC init
• Upstart

Documentation

Index

• Constants
• func AddResource(fileName string, gossConfig GossConfig, resourceName, key string, ...) error
• func AddResources(fileName, resourceName string, keys []string, c *util.Config) error
• func AutoAddResource(fileName string, gossConfig GossConfig, key string, c *util.Config, ...) error
• func AutoAddResources(fileName string, keys []string, c *util.Config) error
• func NewTemplateFilter(varsFile string, varsInline string) (func([]byte) ([]byte, error), error)
• func RenderJSON(c *util.Config) (string, error)
• func Serve(c *util.Config) error
• func Validate(c *util.Config, startTime time.Time) (code int, err error)
• func ValidateResults(c *util.Config) (results <-chan []resource.TestResult, err error)
• func WriteJSON(filePath string, gossConfig GossConfig) error
• type GossConfig
  • func NewGossConfig() *GossConfig
  • func ReadJSON(filePath string) (GossConfig, error)
  • func ReadJSONData(data []byte, detectFormat bool) (GossConfig, error)
  • func (c *GossConfig) Merge(g2 GossConfig)
  • func (c *GossConfig) Resources() []resource.Resource
• type TemplateFilter
• type TmplVars
  • func (t *TmplVars) Env() map[string]string

Constants

const (
	UNSET = iota
	JSON
	YAML
)

Functions

func AddResource

func AddResource(fileName string, gossConfig GossConfig, resourceName, key string, config util.Config, sys *system.System) error

AddResource adds a single resource to fileName

func AddResources

func AddResources(fileName, resourceName string, keys []string, c *util.Config) error

AddResources is a simple wrapper to add multiple resources

func AutoAddResource

func AutoAddResource(fileName string, gossConfig GossConfig, key string, c *util.Config, sys *system.System) error

AutoAddResource adds a single resource to fileName with automatic detection of the type of resource

func AutoAddResources

func AutoAddResources(fileName string, keys []string, c *util.Config) error

AutoAddResources is a simple wrapper to add multiple resources

func NewTemplateFilter

func NewTemplateFilter(varsFile string, varsInline string) (func([]byte) ([]byte, error), error)

NewTemplateFilter creates a new Template Filter based in the file and inline variables.

func RenderJSON

func RenderJSON(c *util.Config) (string, error)

RenderJSON reads json file recursively returning string

func Serve

func Serve(c *util.Config) error

func Validate

func Validate(c *util.Config, startTime time.Time) (code int, err error)

Validate performs validation, writes formatted output to stdout by default and supports retries and more, this is the full featured Validate used by the typical CLI invocation and will produce output to StdOut. Use ValidateResults for programmatic access

func ValidateResults

func ValidateResults(c *util.Config) (results <-chan []resource.TestResult, err error)

ValidateResults performs validation and provides programmatic access to validation results no retries or outputs are supported

func WriteJSON

func WriteJSON(filePath string, gossConfig GossConfig) error

Types

type GossConfig

type GossConfig struct {
	Files        resource.FileMap        `json:"file,omitempty" yaml:"file,omitempty"`
	Packages     resource.PackageMap     `json:"package,omitempty" yaml:"package,omitempty"`
	Addrs        resource.AddrMap        `json:"addr,omitempty" yaml:"addr,omitempty"`
	Ports        resource.PortMap        `json:"port,omitempty" yaml:"port,omitempty"`
	Services     resource.ServiceMap     `json:"service,omitempty" yaml:"service,omitempty"`
	Users        resource.UserMap        `json:"user,omitempty" yaml:"user,omitempty"`
	Groups       resource.GroupMap       `json:"group,omitempty" yaml:"group,omitempty"`
	Commands     resource.CommandMap     `json:"command,omitempty" yaml:"command,omitempty"`
	DNS          resource.DNSMap         `json:"dns,omitempty" yaml:"dns,omitempty"`
	Processes    resource.ProcessMap     `json:"process,omitempty" yaml:"process,omitempty"`
	Gossfiles    resource.GossfileMap    `json:"gossfile,omitempty" yaml:"gossfile,omitempty"`
	KernelParams resource.KernelParamMap `json:"kernel-param,omitempty" yaml:"kernel-param,omitempty"`
	Mounts       resource.MountMap       `json:"mount,omitempty" yaml:"mount,omitempty"`
	Interfaces   resource.InterfaceMap   `json:"interface,omitempty" yaml:"interface,omitempty"`
	HTTPs        resource.HTTPMap        `json:"http,omitempty" yaml:"http,omitempty"`
	Matchings    resource.MatchingMap    `json:"matching,omitempty" yaml:"matching,omitempty"`
}

func NewGossConfig

func NewGossConfig() *GossConfig

func ReadJSON

func ReadJSON(filePath string) (GossConfig, error)

ReadJSON Reads json file returning GossConfig

func ReadJSONData

func ReadJSONData(data []byte, detectFormat bool) (GossConfig, error)

ReadJSONData Reads json byte array returning GossConfig

func (*GossConfig) Merge

func (c *GossConfig) Merge(g2 GossConfig)

Merge consumes all the resources in g2 into c, duplicate resources will be overwritten with the ones in g2

func (*GossConfig) Resources

func (c *GossConfig) Resources() []resource.Resource

type TemplateFilter

type TemplateFilter func([]byte) ([]byte, error)

TemplateFilter is the type of the Goss Template Filter which include custom variables and functions.

type TmplVars

type TmplVars struct {
	Vars map[string]any
}

func (*TmplVars) Env

func (t *TmplVars) Env() map[string]string