sunshine

README

sunshine: file permission security analyzer

ABOUT

sunshine is the best disinfectant

sunshine reveals paths with anomalous file permissions.

File permissions play a critical role in software applications, from security to basic functionality. For example, SSH may reject authentication attempts when the keys have incorrect permissions.

Unfortunately, many software systems have neither the correct file permissions applied, nor useful error handling code to help users quickly diagnose the issue. That's where sunshine comes up.

sunshine is an automated program for recursively scanning files and directories for unidiomatic permission settings.

EXAMPLE

$ cd examples

$ sunshine
.ssh/id_test: expected chmod 0600, got 0644

See -help for more detail.

DOCUMENTATION

https://pkg.go.dev/github.com/mcandre/sunshine

DOWNLOAD

https://github.com/mcandre/sunshine/releases

INSTALL FROM SOURCE

$ go install github.com/mcandre/sunshine/cmd/sunshine@latest

LICENSE

BSD-2-Clause

RUNTIME REQUIREMENTS

(None)

CONTRIBUTING

For more information on developing tug itself, see DEVELOPMENT.md.

USAGE

sunshine follows classical UNIX CLI conventions: Basic exit codes, and no output except in case of an issue.

By default, sunshine analyzes the current working directory tree. To analyze specific paths, list some files and/or directories explicitly.

To scan the example SSH keys:

$ sunshine .ssh/id_test .ssh/id_test.pub
.ssh/id_test: expected chmod 0600, got 0644

To scan your live SSH directory tree:

$ sunshine ~/.ssh

Some paths may not be fully visible to the user account running sunshine. To check for paths missing chmod u+r or u+x (directories) or paths missing chmod u+r (files), run sunshine with root privileges:

$ sudo sunshine

BEST PRACTICES

sunshine is most effective for analyzing local file systems, dynamic applications, traditional network file storage directory trees such as rsync / FTP, and server / VM environments. Maxmimum security is achieved by deploying only the bare minimum files necessary for service, using chmod 0500 for directories and chmod 0400 for files, on read-only file system mounts. When access is needed by multiple users, apply the a UNIX group policy. Keep credentials and other sensitive data out of base application directory trees.

For safety and security, we recommend static assets rather than dynamic applications, such as deploying Web packs to a CDN. CDN bucket-wide permissions are ideally managed via reusable, scalable role policies, which are easier to apply and validate than individual file/object permissions. And don't make a CDN bucket world-readable without cause.

Dynamic applications can be compiled as static executables (chmod 0500) and installed into FROM scratch Docker containers, with immutable file systems. sunshine may prove useful for underlying hypervisor and Kubernetes node environments, where traditional server security must still be maintained.

Classical SSH access can be disabled entirely in favor of cloud console access (VM's), or in favor of kubectl exec access (Kubernetes pods).

SEE ALSO

• brew package manager provides a self permission check with the brew doctor command
• chmod alters file permissions
• file analyzes file types
• find can identify files and directories with specific permission matches
• linters provides an exhaustive collection of linters
• ls can describe many file and directory metadata entries
• stank analyzes executable and library shell scripts

Documentation

Index

• Constants
• Variables
• type Scanner
  • func Illuminate(roots []string, debug bool) (*Scanner, error)
  • func NewScanner(debug bool) (*Scanner, error)
  • func (o Scanner) CheckFileExists(pth string, info os.FileInfo) error
  • func (o Scanner) ScanEtcSSH(pth string, info os.FileInfo)
  • func (o Scanner) ScanHome(pth string, info os.FileInfo)
  • func (o Scanner) ScanInvisible(pth string, info os.FileInfo)
  • func (o Scanner) ScanSSHAuthorizedKeys(pth string, info os.FileInfo)
  • func (o Scanner) ScanSSHConfig(pth string, info os.FileInfo)
  • func (o Scanner) ScanSSHKeys(pth string, info os.FileInfo)
  • func (o Scanner) ScanSSHKnownHosts(pth string, info os.FileInfo)
  • func (o Scanner) ScanUserSSH(pth string, info os.FileInfo)
  • func (o *Scanner) ValidateChmod(pth string, info os.FileInfo, expectedMode os.FileMode)
  • func (o *Scanner) ValidateChmodMask(pth string, info os.FileInfo, expectedMask os.FileMode)
  • func (o *Scanner) ValidateDirectory(pth string, info os.FileInfo)
  • func (o *Scanner) ValidateFile(pth string, info os.FileInfo)
  • func (o *Scanner) Walk(pth string, info os.FileInfo, err error) error

Constants

const Version = "0.0.10"

Version is semver.

Variables

var SSHKeyPattern = regexp.MustCompile("^id_.+$")

SSHKeyPattern matches SSH key filenames.

var SSHPublicKeyPattern = regexp.MustCompile(`^id_.+\.pub$`)

SSHPublicKeyPattern matches SSH public key filenames.

Types

type Scanner

type Scanner struct {
	// Debug enables additional messages.
	Debug bool

	// DebugCh signals low level events.
	DebugCh chan string

	// WarnCh signals permission discrepancies.
	WarnCh chan string

	// ErrCh signals errors experienced during scan attempts.
	ErrCh chan error

	// DoneChn signals the end of a bulk scan.
	DoneCh chan struct{}

	// Home denotes the current user's home directory.
	Home string
}

Scanner collects warnings.

func Illuminate

func Illuminate(roots []string, debug bool) (*Scanner, error)

Illuminate pours through the given file paths recursively for known permission discrepancies.

func NewScanner

func NewScanner(debug bool) (*Scanner, error)

NewScanner constructs a scanner.

func (Scanner) CheckFileExists

func (o Scanner) CheckFileExists(pth string, info os.FileInfo) error

CheckFileExists checks paths for existence.

func (Scanner) ScanEtcSSH

func (o Scanner) ScanEtcSSH(pth string, info os.FileInfo)

ScanEtcSSH analyzes /etc or /etc/ssh.

func (Scanner) ScanHome

func (o Scanner) ScanHome(pth string, info os.FileInfo)

ScanHome analyzes home directories.

func (Scanner) ScanInvisible

func (o Scanner) ScanInvisible(pth string, info os.FileInfo)

ScanInvisible analyzes paths for missing u+x (directories) or u+r (files) bits.

func (Scanner) ScanSSHAuthorizedKeys

func (o Scanner) ScanSSHAuthorizedKeys(pth string, info os.FileInfo)

ScanSSHAuthorizedKeys analyzes authorized_keys files.

func (Scanner) ScanSSHConfig

func (o Scanner) ScanSSHConfig(pth string, info os.FileInfo)

ScanSSHConfig analyzes .ssh/config files.

func (Scanner) ScanSSHKeys

func (o Scanner) ScanSSHKeys(pth string, info os.FileInfo)

ScanSSHKeys analyzes .ssh/id_.+(\.pub)? files.

func (Scanner) ScanSSHKnownHosts

func (o Scanner) ScanSSHKnownHosts(pth string, info os.FileInfo)

ScanSSHKnownHosts analyzes known_hosts files.

func (Scanner) ScanUserSSH

func (o Scanner) ScanUserSSH(pth string, info os.FileInfo)

ScanUserSSH analyzes .ssh directories.

func (*Scanner) ValidateChmod

func (o *Scanner) ValidateChmod(pth string, info os.FileInfo, expectedMode os.FileMode)

ValidateChmod enforces the given chmod policy.

func (*Scanner) ValidateChmodMask

func (o *Scanner) ValidateChmodMask(pth string, info os.FileInfo, expectedMask os.FileMode)

ValidateChmodMask enforces the given chmod mask policy.

func (*Scanner) ValidateDirectory

func (o *Scanner) ValidateDirectory(pth string, info os.FileInfo)

ValidateDirectory enforces the given directory policy.

func (*Scanner) ValidateFile

func (o *Scanner) ValidateFile(pth string, info os.FileInfo)

ValidateFile enforces the given file policy.

func (*Scanner) Walk

func (o *Scanner) Walk(pth string, info os.FileInfo, err error) error

Walk traverses a file path recursively, collecting known permission discrepancies.