Quick and Easy server testing/validation

Goss - Quick and Easy server validation

Build Status Go Report Card Test Coverage

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 healthcheck, health endpoint, and container ordering examples, see the blog post from @aelsabbahy here.

asciicast

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

Why a fork?

I forked this project because the original repository isn't under active development anymore. Due to the reason we use it heavily in production I started this fork.

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://raw.githubusercontent.com/SimonBaeumer/goss/add-coverage/install.sh | sh

# Install v0.4.0 version to ~/bin
curl -fsSL https://raw.githubusercontent.com/SimonBaeumer/goss/add-coverage/install.sh | GOSS_VER=v0.4.0 GOSS_DST=~/bin sh

Manual installation

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

Build it yourself

# Enable git-hooks for development environments
make init
# Build the source
make build

Full Documentation

Documentation is available here: https://github.com/SimonBaeumer/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:

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
  • matching - test for matches in supplied content

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

Credits

Original project: https://github.com/aelsabbahy/goss

Comments
  • Evalute if the system package could be removed

    Evalute if the system package could be removed

    Removal of the system package could be a good thing because it doesn't need to be abstracted behind an interface. It just gathers information about the system under test, which could be done by simple libraries/packages.

  • Add test https client-certificate authentication server

    Add test https client-certificate authentication server

    • Added https server for testing client certificate authentication

    Example certificate authentication:

    http:
        https://client.server:
            status: 200
            cert: /home/example/client.crt
            key: /home/example/client.key
    

    Fixes #25

  • Add support for client certificates

    Add support for client certificates

    It would be great if you could give the HTTPS request a client certificate.

    Certificate format like: -----BEGIN CERTIFICATE ----- ASDASDASDASDASDASDASD ASDASDASDASDASD .... -----END CERTIFICATE -----

  • Builds fail with latest packer - Incompatible API version

    Builds fail with latest packer - Incompatible API version

    With the latest packer (1.5.1), I started to get the following error with goss:

    Failed to initialize build 'amazon-ebs': error initializing provisioner 'goss': Incompatible API version with plugin. Plugin version: 4, Ours: 5
    

    Using goss 0.6.0

  • [WIP] Add docker resource

    [WIP] Add docker resource

    Adds the docker resource to goss.

    First draft:

    docker:
      "alpine:3.7": # Image, Title or Name as title? 
        exist: true
        running: true
        image: "alpine:3.7"
        name: "alpine_name"
        count: 1
    

    Fixes #57

    Definition of done:

    • [ ] Add documentation
    • [ ] Define api / resource definition
    • [ ] Implement add command
    • [ ] Implement auto add
    • [ ] Implement validation
    • [ ] Add integration tests
    • [ ] Add unit tests
  • Commands are not executed in the order they defined

    Commands are not executed in the order they defined

    Hi,

    I've two ideas.

    1. I'd like to define multiple commands in goss.yml and I expect they are being run in the same order as they go in the file. But they do not run in the same order, sometimes they do. It looks like they run randomly. Example of commands:
    • mount a NFS share
    • check permissions
    • unmount the share.

    It would be great if it possible to define either order of execution (maybe add an option "priority") or just follow the order the commands are defined in goss.yml.

    1. I feel a big inconvenience in running multiple commands using "command" test. It would be awesome to have a test called script where I can specify a code of a multiline script. This might look like this:
    script:
      myscript:
        body: |
          #!/bin/bash, #!/usr/bin/env python, #!/usr/bin/awk, #!/usr/bin/sed, etc
          as many as need shell/python/awk/etc commands or other script language instructions
          on many lines
       exit-status: 
       stdout: []
      ... etc ...
    

    I know I can put needed scripts on a target host/image and execute it using command but the powerfull side of Goss is a simplicity. I wouldn't like to split a simple configuration into multiple pieces.

    Thanks, Dmitrii

    Imported from https://github.com/aelsabbahy/goss/issues/455

  • add process misreads process status

    add process misreads process status

    For several processes on my RHEL 7.3 server, goss seems to misrecord the statuses of processes...

    As a test, I pipe every process in ps into a goss add process command...

    for p in $(ps -ef | grep -v '\[' | cut -b49- | cut -d" " -f1 | cut -d: -f1 | rev | cut -d/ -f1 | rev |sort -u); do 
      ../goss a process ${p}
    done
    

    Apart from the fluff (CMD from ps header, and ps, cut, rev, sort used in the command above), one would expect all these processes to be actual running processes. Yet, goss reports several of them as NOT running.

    If I take just systemd processes as an example:

    ps -ef | grep systemd
    root         1     0  0 May21 ?        00:00:51 /usr/lib/systemd/systemd --switched-root --system --deserialize 21
    root       898     1  0 May21 ?        00:01:01 /usr/lib/systemd/systemd-journald
    root       932     1  0 May21 ?        00:00:00 /usr/lib/systemd/systemd-udevd
    dbus      2353     1  0 May21 ?        00:00:23 /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation
    root      2383     1  0 May21 ?        00:00:08 /usr/lib/systemd/systemd-logind
    

    We see 4 processes all running since May 21. If we examine the goss.yaml file we see this:

    grep -A1 systemd goss.yaml
      systemd:            
        running: true     
      systemd-journald:   
        running: false    
      systemd-logind:     
        running: true     
      systemd-udevd:      
        running: true
    

    3 of the 4 are listed as running, but even though systemd-journald is running, it is reported as false...

    Whatever is happening is consistent, in the sense that validation will pass confirming "systemd-journald" is not running when goss re-executes.

    There are a few other processes (excluding ps, cut, rev, sort from the command that fed goss) from a vendor product on my system that similarly report as running false when they are actually running...

    Any idea what is happening to cause this strange behavior?

    [This is using v0.3.7 AMD64]

    Imported from https://github.com/aelsabbahy/goss/issues/451

siusiu (suite-suite harmonics) a suite used to manage the suite, designed to free penetration testing engineers from learning and using various security tools, reducing the time and effort spent by penetration testing engineers on installing tools, remembering how to use tools.
siusiu (suite-suite harmonics) a suite used to manage the suite, designed to free penetration testing engineers from learning and using various security tools, reducing the time and effort spent by penetration testing engineers on installing tools, remembering how to use tools.

siusiu (suite-suite harmonics) a suite used to manage the suite, designed to free penetration testing engineers from learning and using various security tools, reducing the time and effort spent by penetration testing engineers on installing tools, remembering how to use tools.

Dec 12, 2022
A yaml data-driven testing format together with golang testing library

Specimen Yaml-based data-driven testing Specimen is a yaml data format for data-driven testing. This enforces separation between feature being tested

Nov 24, 2022
HTTP traffic mocking and testing made easy in Go ༼ʘ̚ل͜ʘ̚༽

gock Versatile HTTP mocking made easy in Go that works with any net/http based stdlib implementation. Heavily inspired by nock. There is also its Pyth

Jan 4, 2023
Expressive end-to-end HTTP API testing made easy in Go

baloo Expressive and versatile end-to-end HTTP API testing made easy in Go (golang), built on top of gentleman HTTP client toolkit. Take a look to the

Dec 13, 2022
Database testing made easy in Go.

dbtest Database testing made easy in Go. Features Declarative Define the minimum test specification in a YAML-based DSL, then all tests can be generat

Oct 31, 2022
Quick and dirty test to compare MySQL perf between ARM64 & Rosetta MySQL on M1Pro mac

Quick and dirty test to compare MySQL perf between ARM64 & Rosetta MySQL on M1Pro mac

Nov 5, 2021
Fortio load testing library, command line tool, advanced echo server and web UI in go (golang). Allows to specify a set query-per-second load and record latency histograms and other useful stats.
Fortio load testing library, command line tool, advanced echo server and web UI in go (golang). Allows to specify a set query-per-second load and record latency histograms and other useful stats.

Fortio Fortio (Φορτίο) started as, and is, Istio's load testing tool and now graduated to be its own project. Fortio is also used by, among others, Me

Jan 2, 2023
Sample code for a quick demo of go 1.18's fuzzing

Fuzzing in Go 1.18 What is it? "Fuzzing is a type of automated testing which continuously manipulates inputs to a program to find bugs. Go fuzzing use

Feb 11, 2022
mock server to aid testing the jaguar-java client API

stripe-mock stripe-mock is a mock HTTP server that responds like the real Stripe API. It can be used instead of Stripe's test mode to make test suites

Dec 24, 2021
Client tool for testing HTTP server timeouts

HTTP timeout test client While testing Go HTTP server timeouts I wrote this little tool to help me test. It allows for slowing down header write and b

Sep 21, 2022
Testing framework for Go. Allows writing self-documenting tests/specifications, and executes them concurrently and safely isolated. [UNMAINTAINED]

GoSpec GoSpec is a BDD-style testing framework for the Go programming language. It allows writing self-documenting tests/specs, and executes them in p

Nov 28, 2022
Extremely flexible golang deep comparison, extends the go testing package and tests HTTP APIs
Extremely flexible golang deep comparison, extends the go testing package and tests HTTP APIs

go-testdeep Extremely flexible golang deep comparison, extends the go testing package. Latest news Synopsis Description Installation Functions Availab

Dec 22, 2022
Minimal and Beautiful Go testing framework
Minimal and Beautiful Go testing framework

Goblin A Mocha like BDD testing framework written in Go that requires no additional dependencies. Requires no extensive documentation nor complicated

Dec 25, 2022
A collection of packages to augment the go testing package and support common patterns.

gotest.tools A collection of packages to augment testing and support common patterns. Usage With Go modules enabled (go1.11+) $ go get gotest.tools/v3

Jan 4, 2023
End-to-end HTTP and REST API testing for Go.

httpexpect Concise, declarative, and easy to use end-to-end HTTP and REST API testing for Go (golang). Basically, httpexpect is a set of chainable bui

Jan 5, 2023
HTTP mock for Golang: record and replay HTTP/HTTPS interactions for offline testing

govcr A Word Of Warning I'm in the process of partly rewriting govcr to offer better support for cassette mutations. This is necessary because when I

Dec 28, 2022
A next-generation testing tool. Orion provides a powerful DSL to write and automate your acceptance tests

Orion is born to change the way we implement our acceptance tests. It takes advantage of HCL from Hashicorp t o provide a simple DSL to write the acceptance tests.

Aug 31, 2022
Stress testing and benchmarking tool for the NEAR EVM

evm-bully --- stress testing and benchmarking tool for the NEAR EVM

May 30, 2022
An always-on framework that performs end-to-end functional network testing for reachability, latency, and packet loss

Arachne Arachne is a packet loss detection system and an underperforming path detection system. It provides fast and easy active end-to-end functional

Dec 31, 2022