{"id":26647837,"url":"https://github.com/aelsabbahy/goss","last_synced_at":"2025-03-25T00:01:37.439Z","repository":{"id":38310540,"uuid":"43526066","full_name":"goss-org/goss","owner":"goss-org","description":"Quick and Easy server testing/validation","archived":false,"fork":false,"pushed_at":"2024-03-28T10:21:51.000Z","size":1373,"stargazers_count":5438,"open_issues_count":39,"forks_count":466,"subscribers_count":82,"default_branch":"master","last_synced_at":"2024-04-14T17:36:20.297Z","etag":null,"topics":["devops","devops-tools","docker","go","golang","goss","health-check","health-endpoint","infrastructure-as-code","linux","nagios","sensu","tap","tdd","tdd-utilities","testing","testing-tools"],"latest_commit_sha":null,"homepage":"https://goss.rocks","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goss-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2015-10-01T23:13:01.000Z","updated_at":"2024-04-19T14:42:23.935Z","dependencies_parsed_at":"2023-11-23T23:25:22.840Z","dependency_job_id":"f1900588-b9a5-42bd-8d04-9e86d3df46a8","html_url":"https://github.com/goss-org/goss","commit_stats":null,"previous_names":["aelsabbahy/goss"],"tags_count":75,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goss-org%2Fgoss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goss-org%2Fgoss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goss-org%2Fgoss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goss-org%2Fgoss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goss-org","download_url":"https://codeload.github.com/goss-org/goss/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245372376,"owners_count":20604491,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["devops","devops-tools","docker","go","golang","goss","health-check","health-endpoint","infrastructure-as-code","linux","nagios","sensu","tap","tdd","tdd-utilities","testing","testing-tools"],"created_at":"2025-03-25T00:01:04.366Z","updated_at":"2025-03-25T00:01:37.379Z","avatar_url":"https://github.com/goss-org.png","language":"Go","funding_links":[],"categories":["Endpoint validation","Go","DevOps Utilities","Testing","testing-tools","Code signing ###","Repositories","Security"],"sub_categories":["Build systems","Chess :chess_pawn:","Tools"],"readme":"# Goss - Quick and Easy server validation\n\n[![Build Status](https://travis-ci.org/goss-org/goss.svg?branch=master)](https://travis-ci.org/goss-org/goss)\n[![Github All Releases](https://img.shields.io/github/downloads/goss-org/goss/total.svg?maxAge=604800)](https://github.com/goss-org/goss/releases)\n[![Documentation Status](https://readthedocs.org/projects/goss/badge/)](https://goss.rocks/)\n**\n[![Blog](https://img.shields.io/badge/follow-blog-brightgreen.svg)](https://medium.com/@aelsabbahy)\n\n\u003c!-- --8\u003c-- [start:intro] --\u003e\n\n## Goss in 45 seconds\n\n\u003c!-- markdownlint-disable line-length no-inline-html--\u003e\n\u003ca href=\"https://asciinema.org/a/4suhr8p42qcn6r7crfzt6cc3e?autoplay=1\" target=\"_blank\"\u003e\u003cimg src=\"https://cloud.githubusercontent.com/assets/6783261/17330426/ce7ad066-5894-11e6-84ea-29fd4207af58.gif\" alt=\"asciicast\"\u003e\u003c/a\u003e\n\u003c!-- markdownlint-enable line-length no-inline-html --\u003e\n\n**Note:** For testing containers see the [dgoss](https://github.com/goss-org/goss/tree/master/extras/dgoss) wrapper.\nAlso, user submitted wrapper scripts for Kubernetes [kgoss](https://github.com/goss-org/goss/tree/master/extras/kgoss)\nand Docker Compose [dcgoss](https://github.com/goss-org/goss/tree/master/extras/dcgoss).\n\n**Note:** For some Docker/Kubernetes healthcheck, health endpoint, and\ncontainer ordering examples, see my blog post\n[here][kubernetes-simplified-health-checks].\n\n## Introduction\n\n### What is Goss?\n\nGoss is a YAML based [serverspec](http://serverspec.org/) alternative tool for validating a server's configuration.\nIt eases the process of writing tests by allowing the user to generate tests from the current system state.\nOnce the test suite is written they can be executed, waited-on, or served as a health endpoint.\n\n### Why use Goss?\n\n* Goss is EASY! - [Goss in 45 seconds](#goss-in-45-seconds)\n* Goss is FAST! - small-medium test suites are near instantaneous, see [benchmarks](https://github.com/goss-org/goss/wiki/Benchmarks)\n* Goss is SMALL! - \u003c10MB single self-contained binary\n\n## Installation\n\n**Note:** For macOS and Windows, see: [platform-feature-parity].\n\nThis will install goss and [dgoss](https://github.com/goss-org/goss/tree/master/extras/dgoss).\n\n**Note:** Using `curl | sh` is not recommended for production systems, use manual installation below.\n\n```bash\n# Install latest version to /usr/local/bin\ncurl -fsSL https://goss.rocks/install | sh\n\n# Install v0.4.8 version to ~/bin\ncurl -fsSL https://goss.rocks/install | GOSS_VER=v0.4.8 GOSS_DST=~/bin sh\n```\n\n\u003c!-- --8\u003c-- [end:intro] --\u003e\n\u003c!-- --8\u003c-- [start:install] --\u003e\n\n### Manual installation\n\n#### Latest\n\n```bash\ncurl -L https://github.com/goss-org/goss/releases/latest/download/goss-linux-amd64 -o /usr/local/bin/goss\nchmod +rx /usr/local/bin/goss\n\ncurl -L https://github.com/goss-org/goss/releases/latest/download/dgoss -o /usr/local/bin/dgoss\n# Alternatively, using the latest master\n# curl -L https://raw.githubusercontent.com/goss-org/goss/master/extras/dgoss/dgoss -o /usr/local/bin/dgoss\nchmod +rx /usr/local/bin/dgoss\n```\n\n#### Specific Version\n\n```bash\n# See https://github.com/goss-org/goss/releases for release versions\nVERSION=v0.4.8\ncurl -L \"https://github.com/goss-org/goss/releases/download/${VERSION}/goss-linux-amd64\" -o /usr/local/bin/goss\nchmod +rx /usr/local/bin/goss\n\n# (optional) dgoss docker wrapper (use 'master' for latest version)\nVERSION=v0.4.8\ncurl -L \"https://github.com/goss-org/goss/releases/download/${VERSION}/dgoss\" -o /usr/local/bin/dgoss\nchmod +rx /usr/local/bin/dgoss\n```\n\n### Build it yourself\n\n```bash\nmake build\n```\n\n\u003c!-- --8\u003c-- [end:install] --\u003e\n\n## Full Documentation\n\n[Full Documentation](https://goss.readthedocs.io/en/stable/)\n\n## Using the container image\n\n[Using the Goss container image](https://goss.readthedocs.io/en/stable/container_image/)\n\n## Quick start\n\n\u003c!-- --8\u003c-- [start:quickstart] --\u003e\n\n### Writing a simple sshd test\n\nAn initial set of tests can be derived from the system state by using the [add](https://goss.rocks/cli/#add)\nor [autoadd](https://goss.rocks/cli/#autoadd) commands.\n\nLet's write a simple sshd test using autoadd.\n\n```txt\n# Running it as root will allow it to also detect ports\n$ sudo goss autoadd sshd\n```\n\nGenerated `goss.yaml`:\n\n```yaml\nport:\n  tcp:22:\n    listening: true\n    ip:\n    - 0.0.0.0\n  tcp6:22:\n    listening: true\n    ip:\n    - '::'\nservice:\n  sshd:\n    enabled: true\n    running: true\nuser:\n  sshd:\n    exists: true\n    uid: 74\n    gid: 74\n    groups:\n    - sshd\n    home: /var/empty/sshd\n    shell: /sbin/nologin\ngroup:\n  sshd:\n    exists: true\n    gid: 74\nprocess:\n  sshd:\n    running: true\n```\n\nNow that we have a test suite, we can:\n\n* Run it once\n\n```console\n$ goss validate\n...............\n\nTotal Duration: 0.021s # \u003c- yeah, it's that fast..\nCount: 15, Failed: 0\n```\n\n* Edit it to use [templates](https://goss.rocks/gossfile/#templates), and run with a vars file\n\n```console\ngoss --vars vars.yaml validate\n```\n\n* keep running it until the system enters a valid state or we timeout\n\n```console\ngoss validate --retry-timeout 30s --sleep 1s\n```\n\n* serve the tests as a health endpoint\n\n```console\n$ goss serve \u0026\n$ curl localhost:8080/healthz\n\n# JSON endpoint\n$ goss serve --format json \u0026\n$ curl localhost:8080/healthz\n\n# rspecish response via content negotiation\n$ goss serve --format json \u0026\n$ curl -H \"Accept: application/vnd.goss-rspecish\" localhost:8080/healthz\n```\n\n### Manually editing Goss files\n\nGoss files can be manually edited to improve readability and expressiveness of tests.\n\nA [Json draft 7 schema](https://github.com/json-schema-org/json-schema-spec/blob/draft-07/schema.json) available\nat \u003chttps://goss.rocks/schema.yaml\u003e makes it easier to edit simple goss.yaml files in IDEs,\nproviding usual coding assistance such as inline documentation, completion and static analysis.\nSee #793 for screenshots.\n\nFor example, to configure the Json schema in JetBrains intellij IDEA,\nfollow [documented instructions](https://www.jetbrains.com/help/idea/json.html#ws_json_schema_add_custom),\nwith arguments such as:\n* `schema url=https://goss.rocks/schema.yaml`\n* `schema version=Json schema version 7`\n* `file path pattern=*/goss.yaml`\n\nIn addition, Goss files can also be further manually edited (without yet full json support) to use:\n\n* [Patterns](https://goss.rocks/gossfile/#patterns)\n* [Advanced Matchers](https://goss.rocks/gossfile/#advanced-matchers)\n* [Templates](https://goss.rocks/gossfile/#templates)\n* `title` and `meta` (arbitrary data) attributes are persisted when adding other resources with `goss add`\n\nSome examples:\n\n```yaml+jinja\nuser:\n  sshd:\n    title: UID must be between 50-100, GID doesn't matter. home is flexible\n    meta:\n      desc: Ensure sshd is enabled and running since it's needed for system management\n      sev: 5\n    exists: true\n    uid:\n      # Validate that UID is between 50 and 100\n      and:\n        gt: 50\n        lt: 100\n    home:\n      # Home can be any of the following\n      or:\n      - /var/empty/sshd\n      - /var/run/sshd\n\npackage:\n  kernel:\n    installed: true\n    versions:\n      # Must have 3 kernels and none of them can be 4.4.0\n      and:\n      - have-len: 3\n      - not:\n          contain-element: 4.4.0\n\n  # Loaded from --vars YAML/JSON file\n  {{.Vars.package}}:\n    installed: true\n\n{{if eq .Env.OS \"centos\"}}\n  # This test is only when $OS environment variable is set to \"centos\"\n  libselinux:\n    installed: true\n{{end}}\n```\n\nGoss.yaml files with templates can still be validated through the Json schema after being rendered\nusing the `goss render` command. See example below\n\n```console\n$ cd docs\n$ goss --vars ./vars.yaml render \u003e rendered_goss.yaml\n# proceed with json schema validation of rendered_goss.yaml in your favorite IDE\n# or in one of the Json schema validator listed in https://json-schema.org/implementations.html\n# The following example is for a Linux AMD64 host\n$ curl -LO https://github.com/neilpa/yajsv/releases/download/v1.4.1/yajsv.linux.amd64\n$ chmod a+x yajsv.linux.amd64\n$ sudo mv yajsv.linux.amd64 /usr/sbin/yajsv\n\n$ yajsv -s goss-json-schema.yaml rendered_goss.yaml\n\nrendered_goss.yaml: fail: process.chrome: skip is required\nrendered_goss.yaml: fail: service.sshd: skip is required\n1 of 1 failed validation\nrendered_goss.yaml: fail: process.chrome: skip is required\nrendered_goss.yaml: fail: service.sshd: skip is required\n```\n\nFull list of available Json schema validators can be found in \u003chttps://json-schema.org/implementations.html#validator-command%20line\u003e\n\n\u003c!-- --8\u003c-- [end:quickstart] --\u003e\n\u003c!-- --8\u003c-- [start:about] --\u003e\n\n## Supported resources\n\n* package - add new package\n* file - add new file\n* addr - add new remote address:port - ex: google.com:80\n* port - add new listening [protocol]:port - ex: 80 or udp:123\n* service - add new service\n* user - add new user\n* group - add new group\n* command - add new command\n* dns - add new dns\n* process - add new process name\n* kernel-param - add new kernel-param\n* mount - add new mount\n* interface - add new network interface\n* http - add new network http url with proxy support\n* goss - add new goss file, it will be imported from this one\n* matching - test for matches in supplied content\n\n## Supported output formats\n\n* rspecish - **(default)** Similar to rspec output\n* documentation - Verbose test results\n* json - JSON, detailed test result\n* tap - TAP style\n* junit - JUnit style\n* nagios - Nagios/Sensu compatible output /w exit code 2 for failures.\n* prometheus - Prometheus compatible output.\n* silent - No output. Avoids exposing system information (e.g. when serving tests as a healthcheck endpoint).\n\n## Community Contributions\n\n\u003c!-- markdownlint-disable line-length --\u003e\n* [goss-ansible](https://github.com/indusbox/goss-ansible) - Ansible module for Goss.\n* [degoss](https://github.com/naftulikay/ansible-role-degoss) - Ansible role for installing, running, and removing Goss in a single go.\n* [ansible-goss-install](https://github.com/marcinpraczko/ansible-goss-install) - Ansible role for installing Goss (option for install as user or root)\n* [kitchen-goss](https://github.com/ahelal/kitchen-goss) - A test-kitchen verifier plugin for Goss.\n* [goss-fpm-files](https://github.com/deanwilson/unixdaemon-fpm-cookery-recipes) - Might be useful for building goss system packages.\n* [packer-provisioner-goss](https://github.com/YaleUniversity/packer-provisioner-goss) - A packer plugin to run Goss as a provision step.\n* [gossboss](https://github.com/mdb/gossboss) - Collect and view aggregated Goss test results from multiple remote Goss servers.\n\u003c!-- markdownlint-enable line-length --\u003e\n\n## Limitations\n\n`goss` works well on Linux, but support on Windows \u0026 macOS is alpha. See [platform-feature-parity].\n\nThe following tests have limitations.\n\nPackage:\n\n* rpm\n* deb\n* Alpine apk\n* pacman\n\nService:\n\n* systemd\n* sysV init\n* OpenRC init\n* Upstart\n\n[kubernetes-simplified-health-checks]: https://medium.com/@aelsabbahy/docker-1-12-kubernetes-simplified-health-checks-and-container-ordering-with-goss-fa8debbe676c\n[platform-feature-parity]: https://goss.rocks/platforms\n\n\u003c!-- --8\u003c-- [end:about] --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faelsabbahy%2Fgoss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faelsabbahy%2Fgoss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faelsabbahy%2Fgoss/lists"}