kubeaudit

Example shows how to audit and fix a Kubernetes manifest file

package main

import (
	"fmt"
	"os"
	"strings"

	"github.com/Shopify/kubeaudit"
	"github.com/Shopify/kubeaudit/auditors/all"
	"github.com/Shopify/kubeaudit/config"

	log "github.com/sirupsen/logrus"
)

func main() {
	// A sample Kubernetes manifest file
	manifest := `
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myAuditor 
  spec:
    template:
      spec:
        containers:
        - name: myContainer
`

	// Initialize all the security auditors using default configuration
	allAuditors, err := all.Auditors(config.KubeauditConfig{})
	if err != nil {
		log.Fatal(err)
	}

	// Initialize kubeaudit
	auditor, err := kubeaudit.New(allAuditors)
	if err != nil {
		log.Fatal(err)
	}

	// Run the audit in manifest mode
	report, err := auditor.AuditManifest(strings.NewReader(manifest))
	if err != nil {
		log.Fatal(err)
	}

	// Print the audit results to screen
	report.PrintResults(os.Stdout, kubeaudit.Error, nil)

	// Print the plan to screen. These are the steps that will be taken by calling "report.Fix()".
	fmt.Println("\nPlan:")
	report.PrintPlan(os.Stdout)

	// Print the fixed manifest to screen. Note that this leaves the original manifest unmodified.
	fmt.Println("\nFixed manifest:")
	err = report.Fix(os.Stdout)
	if err != nil {
		log.Fatal(err)
	}
}

ExampleAuditCluster shows how to run kubeaudit in cluster mode (only works if kubeaudit is being run from a container insdie of a cluster)

package main

import (
	"os"

	"github.com/Shopify/kubeaudit"
	"github.com/Shopify/kubeaudit/auditors/all"
	"github.com/Shopify/kubeaudit/config"
	"github.com/Shopify/kubeaudit/internal/k8s"

	log "github.com/sirupsen/logrus"
)

func main() {
	// Initialize all the security auditors using default configuration
	allAuditors, err := all.Auditors(config.KubeauditConfig{})
	if err != nil {
		log.Fatal(err)
	}

	// Initialize kubeaudit
	auditor, err := kubeaudit.New(allAuditors)
	if err != nil {
		log.Fatal(err)
	}

	// Run the audit in cluster mode. Note this will fail if kubeaudit is not running within a cluster.
	report, err := auditor.AuditCluster(k8s.ClientOptions{})
	if err != nil {
		log.Fatal(err)
	}

	// Print the audit results to screen
	report.PrintResults(os.Stdout, kubeaudit.Info, nil)
}

ExampleAuditLocal shows how to run kubeaudit in local mode

package main

import (
	"os"

	"github.com/Shopify/kubeaudit"
	"github.com/Shopify/kubeaudit/auditors/all"
	"github.com/Shopify/kubeaudit/config"
	"github.com/Shopify/kubeaudit/internal/k8s"

	log "github.com/sirupsen/logrus"
)

func main() {
	// Initialize all the security auditors using default configuration
	allAuditors, err := all.Auditors(config.KubeauditConfig{})
	if err != nil {
		log.WithError(err).Fatal("Error initializing all auditors")
	}

	// Initialize kubeaudit
	auditor, err := kubeaudit.New(allAuditors)
	if err != nil {
		log.Fatal(err)
	}

	// Run the audit in local mode
	report, err := auditor.AuditLocal("", k8s.ClientOptions{})
	if err != nil {
		log.Fatal(err)
	}

	// Print the audit results to screen
	report.PrintResults(os.Stdout, kubeaudit.Info, nil)
}

ExampleAuditorSubset shows how to run kubeaudit with a subset of auditors

// Initialize the auditors you want to use
auditor, err := kubeaudit.New([]kubeaudit.Auditable{
	apparmor.New(),
	image.New(image.Config{Image: "myimage:mytag"}),
})
if err != nil {
	log.Fatal(err)
}

// Run the audit in the mode of your choosing. Here we use manifest mode.
report, err := auditor.AuditManifest(strings.NewReader(manifest))
if err != nil {
	log.Fatal(err)
}

// Print the audit results to screen
report.PrintResults(os.Stdout, kubeaudit.Info, &log.JSONFormatter{})

ExampleConfig shows how to use a kubeaudit with a config file. A kubeaudit config can be used to specify which security auditors to run, and to specify configuration for those auditors.

configFile := "config/config.yaml"

// Open the configuration file
reader, err := os.Open(configFile)
if err != nil {
	log.WithError(err).Fatal("Unable to open config file ", configFile)
}

// Load the config
conf, err := config.New(reader)
if err != nil {
	log.WithError(err).Fatal("Error parsing config file ", configFile)
}

// Initialize security auditors using the configuration
auditors, err := all.Auditors(conf)
if err != nil {
	log.Fatal(err)
}

// Initialize kubeaudit
auditor, err := kubeaudit.New(auditors)
if err != nil {
	log.Fatal(err)
}

// Run the audit in the mode of your choosing. Here we use manifest mode.
report, err := auditor.AuditManifest(strings.NewReader(manifest))
if err != nil {
	log.Fatal(err)
}

// Print the audit results to screen
report.PrintResults(os.Stdout, kubeaudit.Error, nil)

ExampleCustomAuditor shows how to use a custom auditor

package main

import (
	"fmt"
	"os"
	"strings"

	"github.com/Shopify/kubeaudit"
	"github.com/Shopify/kubeaudit/k8stypes"

	log "github.com/sirupsen/logrus"
)

func NewCustomAuditor() kubeaudit.Auditable {
	return &myAuditor{}
}

// Your auditor must implement the Auditable interface, which requires only one method: Audit().
type myAuditor struct{}

// The Audit function takes in a resource to audit and returns audit results for that resource.
//
// Params
//
//	resource: Read-only. The resource to audit.
//	resources: Read-only. A reference to all resources. Can be used for context.
//
// Return
//
//	auditResults: The results for the audit. Each result can optionally include a PendingFix object to
//	  define autofix behaviour (see below).
func (a *myAuditor) Audit(resource k8stypes.Resource, _ []k8stypes.Resource) ([]*kubeaudit.AuditResult, error) {
	return []*kubeaudit.AuditResult{
		{
			Name:     "MyAudit",
			Severity: kubeaudit.Error,
			Message:  "My custom error",
			PendingFix: &myAuditorFix{
				newVal: "bye",
			},
		},
	}, nil
}

// To provide autofix behaviour for an audit result, implement the PendingFix interface. The PendingFix interface
// has two methods: Plan() and Apply().
type myAuditorFix struct {
	newVal string
}

// The Plan method explains what fix will be applied by Apply().
//
// Return
//
//	plan: A human-friendly explanation of what Apply() will do
func (f *myAuditorFix) Plan() string {
	return fmt.Sprintf("Set label 'hi' to '%s'", f.newVal)
}

// The Apply method applies a fix to a resource.
//
// Params
//
//	resource: A reference to the resource that should be fixed.
//
// Return
//
//	newResources: New resources created as part of the fix. Generally, it should not be necessary to create
//	  new resources, only modify the passed in resource.
func (f *myAuditorFix) Apply(resource k8stypes.Resource) []k8stypes.Resource {
	setLabel(resource, "hi", f.newVal)
	return nil
}

// This is just a helper function
func setLabel(resource k8stypes.Resource, key, value string) {
	switch kubeType := resource.(type) {
	case *k8stypes.PodV1:
		kubeType.Labels[key] = value
	case *k8stypes.DeploymentV1:
		kubeType.Labels[key] = value
	}
}

// A sample Kubernetes manifest file
var manifest = `
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myAuditor 
spec:
  template:
    spec:
      containers:
      - name: myContainer
`

// ExampleCustomAuditor shows how to use a custom auditor
func main() {
	// Initialize kubeaudit with your custom auditor
	auditor, err := kubeaudit.New([]kubeaudit.Auditable{NewCustomAuditor()})
	if err != nil {
		log.Fatal(err)
	}

	// Run the audit in the mode of your choosing. Here we use manifest mode.
	report, err := auditor.AuditManifest(strings.NewReader(manifest))
	if err != nil {
		log.Fatal(err)
	}

	// Print the results to screen
	report.PrintResults(os.Stdout, kubeaudit.Info, nil)
}