goss

README

Goss - Quick and Easy server validation

Goss in 45 seconds

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

Introduction

What is goss?

Goss is a serverspec-like tool for validating a server's configuration. It eases the process of generating tests by assuming the user already has a properly configured machine from which they can derive system state. Once the test suite is generated they can be executed on any other host for the full TDD experience.

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! - single self-contained ~2MB binary
• Goss is UNIXY! - does one thing and does it well, chainable through pipes

Installation

curl -L https://github.com/aelsabbahy/goss/releases/download/v0.1.2/goss-linux-amd64 > /usr/local/bin/goss && chmod +rx /usr/local/bin/goss

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.

$ goss autoadd sshd
Adding Group to 'goss.yaml':

sshd:
  exists: true
  gid: 74


Adding Process to 'goss.yaml':

sshd:
  running: true


Adding Service to 'goss.yaml':

sshd:
  enabled: true
  running: true


Adding User to 'goss.yaml':

sshd:
  exists: true
  uid: 74
  gid: 74
  groups:
  - sshd
  home: /var/empty/sshd

We can now run our test by using goss validate:

$ goss validate
..........

Total Duration: 0.016s
Count: 10, Failed: 0

As you can see goss tests are extremely fast, we were able to validate our system state in 16ms!

Patterns, matchers and descriptions

Goss files can be manually edited to match:

• Patterns
• Advanced Matchers.
• desc is a comment that is persisted when adding other resources with goss add

Some examples:

user:
  sshd:
    desc: UID must be between 50-100, GID doesn't matter. home is flexible
    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

Supported resources

• addr - addr is reachable
• command - command, exist status and outputs
• dns - dns is resolvable
• file - file exists, owner/perm, conent
• group - group, uid
• package - package is installed, versions
• port - port is listening, listening ip
• process - process is running
• user - uid, home, etc..

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.

Limitations

Currently goss only runs on Linux.

The following tests have limitations.

Package:

• rpm
• deb
• Alpine apk

Service:

• systemd
• sysV init
• OpenRC init
• Upstart

Documentation

Index

• Constants
• Variables
• func AddResource(fileName, resourceName, key string, c *cli.Context) error
• func AutoAddResource(fileName, key string, c *cli.Context) error
• func RenderJSON(filePath string) string
• 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) GossConfig
  • func (c *GossConfig) Resources() []resource.Resource

Constants

const (
	JSON = iota
	YAML
	UNSET
)

Variables

var StoreFormat = UNSET

Functions

func AddResource

func AddResource(fileName, resourceName, key string, c *cli.Context) error

func AutoAddResource

func AutoAddResource(fileName, key string, c *cli.Context) error

func RenderJSON

func RenderJSON(filePath string) string

Reads json file recursively returning string

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"`
}

func NewGossConfig

func NewGossConfig() *GossConfig

func ReadJSON

func ReadJSON(filePath string) GossConfig

Reads json file returning GossConfig

func ReadJSONData

func ReadJSONData(data []byte) GossConfig

Reads json byte array returning GossConfig

func (*GossConfig) Resources

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