Checks and Checklists

Distributive checks are written in an extraordinarily simple JSON structure. Samples are aviailible in the samples/ folder.

General structure

A checklist is a single JSON file. It contains a list of logically grouped checks (according to the software they examine, for instance). Checklists have the following fields:

• "Name" : string : Descriptive, human readable name (optional, but recommended)
• "Notes" : string : Human-readable description of this checklist (optional, not used by Distributive).
• "Checklist" : [check] : List of checks to be run, with a structure as outlined below

A truncated example:

{
    "Name": "My first checklist",
    "Notes": "A checklist that has checks, really!",
    "Checklist": [
          ...
    ]
}

The Details

This section contains an outline of every single check that Distributive provides. For information on how to create new checks, please see THIS PAGE.

Every entry in a checklist has the following fields:

• "Check" : string : Type of check to be run
• "Parameters" : [string] : Parameters to pass to the check

Every check can also have a "Name" and "Notes", as described above.

An example:

{
    "Name": "Git installation check",
    "Notes": "If I don't have git, I don't know what I'll do.",
    "Check": "Installed",
    "Parameters": ["git"]
}

Filesystem

"file"

• Description: Is there a file at this path?
• Inputs:
  • Path to file

"directory"

• Description: Is there a directory at this path?
• Inputs:
  • Path to directory

"symlink

• Description: Is there a symbolic link at this path?
• Inputs:
  • Path to symlink

"checksum"

• Description: Does this file's checksum match the expected value?
• Inputs:
  • Algorithm: SHA1 | SHA224 | SHA256 | SHA384 | SHA512 | MD5
  • Expected value (original, valid checksum)
  • Path to file

Packages

Supported package managers for checks "installed", and "repoExistsURI" are yum, apt, and pacman. Only pacman and yum are supported for "repoExists".

"installed"

• Description: Is this package installed on the server?
• Inputs:
  • Name of package
• Dependencies: yum | dpkg | pacman

"repoExists"

• Description: Does the configuration file for this package manager specify this repo? This check reads configuration files depending on the package manager specified.
• Inputs:
  • Name of package manager: yum | dpkg | pacman
  • Name of repo
• Dependencies: yum | dpkg | pacman

"repoExistsURI"

• Description: Does the configuration file for this package manager specify this repo?
• Inputs:
  • Name of package manager: yum | dpkg | pacman
  • URI of repo. Either in the form of a URL or a path.
• Dependencies: yum | dpkg | pacman

"pacmanIgnore"

• Description: Is this package listed in pacman's configuration's IgnorePkg field?
• Inputs:
  • Name of package
• Dependencies: pacman

Network

"port"

• Description: Is this port in an open state? Reads from /proc/net/tcp
• Inputs:
  • Port number (must be parseable as base 10 integer, of <64 bit width)

"interface"

• Description: Does this network interface exist?
• Inputs:
  • Interface name

"up"

• Description: Is this network interface up?
• Inputs:
  • Interface name

"ip4"

• Description: Does this interface have the specified IP address (two parameters)?

"ip6" : Does this interface have the specified IP address (two parameters)?

"gateway" : Does the default gateway have the specified IP address? "gatewayInterface" : Is the default gateway operating on this interface? "TCP" : Can this host be reached via a TCP connection? "UDP" : Can this host be reached via a UDP connection? "tcpTimeout" : Can this host be reached via a TCP connection before a set timeout? "udpTimeout" : Can this host be reached via a UDP connection before a set timeout?

Users and Groups

For all of the following checks, the user can either be specified by their username or by their UID. Except "userInGroup", which requires a username.

• "groupExists" : Does a group by this name exist on the host?
• "groupId" : Does a group by this name have this group id?
• "userInGroup" : Is this user a member of this group?
• "userExists" : Does this user exist?
• "userHasUID" : Does this user have this UID?
• "userHasGID" : Does this user have this primary GID?
• "userHasUsername" : Does this user have this username?
• "userHasName" : Does this user have this name?
• "userHasHomeDir" : Is this the path of this user's home directory?

Systemctl

• "systemctlLoaded" : Is this service loaded?
• "systemctlActive" : Is this service active?
• "systemctlSockPath" : Is the sock at this path registered with systemd?
• "systemctlSockUnit" : Is the sock with this unit registered with systemd?
• "systemctlTimer" : Is this timer active?
• "systemctlTimerLoaded" : Is this timer loaded?
• "systemctlUnitFileStatus" : Does this unit file have this status?

Miscellaneous

• "command" : Run a shell command.
• "running" : Is this service running on the server?
• "temp" : Does the CPU temp exceed this integer (Celcius)?
• "module" : Is this kernel module activated?
• "kernelParameter" : Is this kernel parameter specified?
• "dockerImage" : Does this Docker image exist on the host?
• "dockerRunning" : Is this Docker container running (must include version, e.g. user/container:latest)?