Update docs and add exitcode flag (#299)

.goreleaser.yml

@@ -5,19 +5,16 @@ release:
     name: kubeaudit
   draft: true
   name_template: "{{.ProjectName}}-v{{.Version}}"
-brews:
-- github:
-    owner: Shopify
-    name: homebrew-shopify
-  install: bin.install "kubeaudit"
-  homepage: "https://github.com/Shopify/kubeaudit"
-  description: "kubeaudit audits Kubernetes clusters for common security controls"
 dockers:
 - dockerfile: goreleaser.Dockerfile
+  goos: linux
+  goarch: amd64
+  goarm: ''
   image_templates:
   - "shopify/kubeaudit:latest"
   - "shopify/kubeaudit:{{ .Tag }}"
   - "shopify/kubeaudit:v{{ .Major }}"
+  - "shopify/kubeaudit:v{{ .Major }}.{{ .Minor }}"
 builds:
 - goos:
   - linux

Dockerfile

@@ -45,7 +45,7 @@ COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
 COPY --from=builder --chown=app /go/bin/kubeaudit /kubeaudit
 
 # from now on, run as the unprivileged user
-USER app
+USER 1000
 
 # entrypoint
 ENTRYPOINT ["/kubeaudit"]

README.md

@@ -30,10 +30,15 @@ The rest of this README will focus on how to use kubeaudit as a command line too
 * [Commands](#commands)
 * [Configuration File](#configuration-file)
 * [Override Errors](#override-errors)
-* [CI/CD Usage](#cicd-usage)
 * [Contributing](#contributing)
 
 ## Installation
+
+### Brew
+
+```
+brew install kubeaudit
+```
 
 ### Download a binary
 
@@ -73,6 +78,10 @@ or
 
 - renaming the binary to `kubectl-audit` and having it available in your path.
 
+### Docker
+
+We also release a [Docker image](https://hub.docker.com/r/shopify/kubeaudit): `shopify/kubeaudit`. To run kubeaudit as a job in your cluster see [Running kubeaudit in a cluster](docs/cluster.md).
+
 ## Quick Start
 
 kubeaudit has three modes:
@@ -135,23 +144,22 @@ To write the fixed manifest to a new file instead of modifying the source file,
 kubeaudit autofix -f "/path/to/manifest.yml" -o "/path/to/fixed"
 ```
 
-### Local Mode
-
-If a kubeconfig file is provided using the `-c/--kubeconfig` flag, kubeaudit will audit the resources specified in the kubeconfig file. If no kubeconfig file is specified, `$HOME/.kube/config` is used by default:
+### Cluster Mode
 
+Kubeaudit can detect if it is running within a container in a cluster. If so, it will try to audit all Kubernetes resources in that cluster:
 ```
-kubeaudit all -c "/path/to/config"
+kubeaudit all
 ```
 
-For more information on kubernetes config files, see https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/
-
-### Cluster Mode
+### Local Mode
 
-Kubeaudit can detect if it is running within a container in a cluster. If so, it will try to audit all Kubernetes resources in that cluster:
+Kubeaudit will try to connect to a cluster using the local kubeconfig file (`$HOME/.kube/config`). A different kubeconfig location can be specified using the `-c/--kubeconfig` flag.
 ```
-kubeaudit all
+kubeaudit all -c "/path/to/config"
 ```
 
+For more information on kubernetes config files, see https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/
+
 ## Audit Results
 
 Kubeaudit produces results with three levels of severity:
@@ -160,7 +168,13 @@ Kubeaudit produces results with three levels of severity:
 `Warning`: A best practice recommendation
 `Info`: Informational, no action required. This includes results that are [overridden](#override-errors)
 
-The minimum severity level can be set using the `--minSeverity/-m` flag. See [Global Flags](#global-flags) for a more detailed description.
+The minimum severity level can be set using the `--minSeverity/-m` flag.
+
+By default kubeaudit will output results in a human-readable way. If the output is intended to be further processed, it can be set to output JSON using the `--format json` flag. To output results as logs (the previous default) use `--format logrus`.
+
+If there are results of severity level `error`, kubeaudit will exit with exit code 2. This can be changed using the `--exitcode/-e` flag.
+
+For all the ways kubeaudit can be customized, see [Global Flags](#global-flags).
 
 ## Commands
 
@@ -196,8 +210,9 @@ Auditors can also be run individually.
 |         | --format       | The output format to use (one of "pretty", "logrus", "json") (default is "pretty")                  |
 | -c      | --kubeconfig   | Path to local Kubernetes config file. Only used in local mode (default is `$HOME/.kube/config`)     |
 | -f      | --manifest     | Path to the yaml configuration to audit. Only used in manifest mode.                                |
-| -n      | --namespace    | Only audit resources in the specified namespace. Not currently supported in manifest mode.                         |
-| -m      | --minseverity  | Set the lowest severity level to report (one of "error", "warning", "info") (default "info")           |
+| -n      | --namespace    | Only audit resources in the specified namespace. Not currently supported in manifest mode.          |
+| -m      | --minseverity  | Set the lowest severity level to report (one of "error", "warning", "info") (default "info")        |
+| -e      | --exitcode     | Exit code to use if there are results with severity of "error". Conventionally, 0 is used for success and all non-zero codes for an error. (default 2) |
 
 ## Configuration File
 
@@ -248,11 +263,6 @@ See the specific [auditor docs](#auditors) for the auditor you wish to override
 
 To learn more about labels, see https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/
 
-## CI/CD usage
-
-kubeaudit will return exit code `2` whenever any errors are being found, so it can stop your pipeline.
-If you do not want this to happen, run it as `kubeaudit all || true`
-
 ## Contributing
 
 If you'd like to fix a bug, contribute a feature or just correct a typo, please feel free to do so as long as you follow our [Code of Conduct](https://github.com/Shopify/kubeaudit/blob/master/CODE_OF_CONDUCT.md).

cmd/commands/root.go

@@ -22,21 +22,19 @@ type rootFlags struct {
 	manifest    string
 	namespace   string
 	minSeverity string
+	exitCode    int
 }
 
 // RootCmd defines the shell command usage for kubeaudit.
 var RootCmd = &cobra.Command{
 	Use:   "kubeaudit",
 	Short: "A Kubernetes security auditor",
-	Long: `kubeaudit is a program that makes sure all your containers are secure #patcheswelcome
+	Long: `Kubeaudit audits Kubernetes clusters for common security controls.
 
 kubeaudit has three modes:
-1. Manifest mode: If a Kubernetes manifest file is provided using the -f/--manifest flag, kubeaudit will audit the manifest file.
-	 Kubeaudit also supports autofixing in manifest mode using the 'autofix' command. This will fix the manifest in-place.
-	 The fixed manfiest can be written to a different file using the -o/--out flag.
-2. Cluster mode: If kubeaudit detects it is running within a container, it will try to audit the cluster it is contained in.
-3. Local mode: kubeaudit will audit the resources specified by the local kubeconfig file ($HOME/.kube/config). A different
-     kubeaconfig location can be specified using the -c/--kubeconfig flag
+  1. Manifest mode: If a Kubernetes manifest file is provided using the -f/--manifest flag, kubeaudit will audit the manifest file. Kubeaudit also supports autofixing in manifest mode using the 'autofix' command. This will fix the manifest in-place. The fixed manifest can be written to a different file using the -o/--out flag.
+  2. Cluster mode: If kubeaudit detects it is running in a cluster, it will audit the other resources in the cluster.
+  3. Local mode: kubeaudit will try to connect to a cluster using the local kubeconfig file ($HOME/.kube/config). A different kubeconfig location can be specified using the -c/--kubeconfig flag
 `,
 }
 
@@ -53,6 +51,7 @@ func init() {
 	RootCmd.PersistentFlags().StringVarP(&rootConfig.format, "format", "p", "pretty", "The output format to use (one of \"pretty\", \"logrus\", \"json\")")
 	RootCmd.PersistentFlags().StringVarP(&rootConfig.namespace, "namespace", "n", apiv1.NamespaceAll, "Only audit resources in the specified namespace. Not currently supported in manifest mode.")
 	RootCmd.PersistentFlags().StringVarP(&rootConfig.manifest, "manifest", "f", "", "Path to the yaml configuration to audit. Only used in manifest mode.")
+	RootCmd.PersistentFlags().IntVarP(&rootConfig.exitCode, "exitcode", "e", 2, "Exit code to use if there are results with severity of \"error\". Conventionally, 0 is used for success and all non-zero codes for an error.")
 }
 
 // KubeauditLogLevels represents an enum for the supported log levels.
@@ -81,7 +80,7 @@ func runAudit(auditable ...kubeaudit.Auditable) func(cmd *cobra.Command, args []
 		report.PrintResults(printOptions...)
 
 		if report.HasErrors() {
-			os.Exit(2)
+			os.Exit(rootConfig.exitCode)
 		}
 	}
 }