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

Note: For some Docker/Kubernetes healtcheck, 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 suits are near instantaneous, see benchmarks
• Goss is SMALL! - <10MB single self-contained binary

Installation

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.3 version to ~/bin
curl -fsSL https://goss.rocks/install | GOSS_VER=v0.3.3 GOSS_DST=~/bin sh

Manual installation

# See https://github.com/aelsabbahy/goss/releases for release versions
curl -L https://github.com/aelsabbahy/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)
curl -L https://raw.githubusercontent.com/aelsabbahy/goss/_VERSION_/extras/dgoss/dgoss -o /usr/local/bin/dgoss
chmod +rx /usr/local/bin/dgoss

Full Documentation

Documentation is available here: https://github.com/aelsabbahy/goss/blob/master/docs/manual.md

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

Manually editing Goss files

Goss files can be manually edited 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}}

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
• goss - add new goss file, it will be imported from this one

Supported output formats

• rspecish (default) - Similar to rspec output
• documentation - Verbose test results
• JSON - Detailed test result
• TAP
• JUnit
• nagios - Nagios/Sensu compatible output /w exit code 2 for failures.
• 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.

Limitations

Currently goss only runs on Linux.

The following tests have limitations.

Package:

• rpm
• deb
• Alpine apk
• pacman

Service:

• systemd
• sysV init
• OpenRC init
• Upstart

Documentation

Index

• Constants
• Variables
• func AddResource(fileName string, gossConfig GossConfig, resourceName, key string, ...) error
• func AddResources(fileName, resourceName string, keys []string, c *cli.Context) error
• func AutoAddResource(fileName string, gossConfig GossConfig, key string, c *cli.Context, ...) error
• func AutoAddResources(fileName string, keys []string, c *cli.Context) error
• func NewTemplateFilter(varsFile string) func([]byte) []byte
• func RenderJSON(c *cli.Context) string
• func Serve(c *cli.Context)
• func Validate(c *cli.Context, startTime time.Time)
• func WriteJSON(filePath string, gossConfig GossConfig) error
• type GossConfig
  • func NewGossConfig() *GossConfig
  • func ReadJSON(filePath string) GossConfig
  • func ReadJSONData(data []byte, detectFormat bool) GossConfig
  • func (c *GossConfig) Resources() []resource.Resource
• type TmplVars
  • func (t *TmplVars) Env() map[string]string

Constants

const (
	UNSET = iota
	JSON
	YAML
)

Variables

var OutStoreFormat = UNSET

var TemplateFilter func(data []byte) []byte

Functions

func AddResource

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

func AddResources

func AddResources(fileName, resourceName string, keys []string, c *cli.Context) error

Simple wrapper to add multiple resources

func AutoAddResource

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

func AutoAddResources

func AutoAddResources(fileName string, keys []string, c *cli.Context) error

Simple wrapper to add multiple resources

func NewTemplateFilter

func NewTemplateFilter(varsFile string) func([]byte) []byte

func RenderJSON

func RenderJSON(c *cli.Context) string

Reads json file recursively returning string

func Serve

func Serve(c *cli.Context)

func Validate

func Validate(c *cli.Context, startTime time.Time)

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

Reads json file returning GossConfig

func ReadJSONData

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

Reads json byte array returning GossConfig

func (*GossConfig) Resources

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

type TmplVars

type TmplVars struct {
	Vars map[string]interface{}
}

func (*TmplVars) Env

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