# Kubesec for Kubernetes Security Risk Analysis

> Kubesec is a Go-based static analyzer for Kubernetes resources that assigns security scores and explains rule matches. It fits developers, platform teams, and security engineers who need local manifest scans, Helm output checks, admission-controller integration, or API-backed scanning.

**controlplaneio/kubesec** — Security risk analysis for Kubernetes resources

- Repository: https://github.com/controlplaneio/kubesec
- Website: https://kubesec.io
- Stars: 1,490 · Forks: 110
- Language: Go
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/controlplaneio-kubesec

## Kubesec's Kubernetes Manifest Scoring Boundary

Kubesec addresses a specific stage in Kubernetes security work: evaluating resource definitions before they are applied. Its README describes it as "Security risk analysis for Kubernetes resources," and the command-line interface can scan local YAML or JSON files, standard input, multiple YAML documents, and rendered Helm output. The audience includes developers checking a Deployment during development, platform engineers reviewing manifests in delivery workflows, and security engineers who need a repeatable local scan.

The analyzer reports a score and the rules responsible for that result. That makes it more useful than a syntax-only Kubernetes validator for teams looking for security configuration checks, although it is still a static tool. It cannot observe what happens inside a running cluster after admission. The README does not claim runtime monitoring, image vulnerability scanning, admission-time enforcement, or cluster-wide audit analysis.

Kubesec is therefore best understood as a policy-oriented manifest check. A high or low score should prompt a closer review rather than act as a complete statement about an application's exposure. The available output includes the object name, whether the resource is considered valid, a score, and categorized rule results. Teams can print the rule catalog first when they need to know what the tool actually checks.

## How Kubesec Reads YAML, JSON, and Helm Input

The documented data path is file or stream input, manifest validation through kubeconform, rule evaluation, and formatted reporting. A file can contain several correctly formatted documents separated by `---`, and a single input file is not limited to one resource. The README also shows scanning rendered Helm output by piping the result of `helm template` into Kubesec. Standard input uses `-` as the scan target.

The `--format` flag selects `json`, `table`, or `template`. JSON is the default, table is intended for human inspection, and template mode requires a template file. Kubesec can also restrict a scan to named rules with `--rules`, using one rule name or a comma-separated list. This is useful when a workflow needs a focused check, but it also means a restricted scan should not be mistaken for a complete report.

Schema handling is delegated to kubeconform. By default, the README describes fetching the latest upstream schema. The `--kubernetes-version` option selects a specific version such as `1.25.3`. The Dockerfile embeds schemas for Pod, DaemonSet, Deployment, and StatefulSet, while the Makefile sets `K8S_SCHEMA_VER = 1.31.0` for its build workflow. That split creates an operational distinction: local installation may depend on the configured schema source, while the container carries schema files.

## Installing Kubesec and Running the First Manifest Scan

The README offers release binaries, a Docker image, a Kubernetes admission-controller project, and a kubectl plugin. For a Go installation, it documents these commands. The first command is presented for Go 1.16 and newer, while the second is the older module workflow.

```bash
go install github.com/controlplaneio/kubesec/v2@latest
```

```bash
GO111MODULE="on" go get github.com/controlplaneio/kubesec/v2
```

The repository's current `go.mod` declares `go 1.27.0`, so the README's historical Go 1.16 wording should be checked against the Go toolchain available in the target environment. The release binaries are linked from the repository, and the official image is named `docker.io/kubesec/kubesec:v2` in the README.

For the first scan, create the documented Pod manifest:

```bash
cat <<EOF > kubesec-test.yaml
apiVersion: v1
kind: Pod
metadata:
  name: kubesec-demo
spec:
  containers:
  - name: kubesec-demo
    image: gcr.io/google-samples/node-hello:1.0
    securityContext:
      readOnlyRootFilesystem: true
EOF
```

Then scan it with the local binary or the image:

```bash
kubesec scan kubesec-test.yaml
```

```bash
docker run -i kubesec/kubesec:v2 scan /dev/stdin < kubesec-test.yaml
```

The expected result, according to the README, is a security score and detailed analysis. For a human-readable view, use the documented format flag:

```bash
kubesec scan kubesec-test.yaml --format table
```

For a rendered chart, the documented pipeline is:

```bash
helm template -f values.yaml ./chart | kubesec scan /dev/stdin
```

That workflow checks the rendered result rather than the chart templates directly.

## Rule Selection, Output Formats, and Reproducible Checks

Kubesec can expose its scoring catalog through `print-rules`. The JSON form includes a rule ID, selector, reason, supported kinds, points, and an advise value. The table form is intended for readers who do not need the machine-readable structure. Printing the rules is useful when a team must explain why a manifest received a particular score or when a rule name needs to be passed to `--rules`.

The documented JSON report is an array. Each result identifies an object such as `Pod/security-context-demo.default`, includes `valid`, `message`, and `score`, and groups scoring details under `critical` and `advise`. The example includes a critical rule for adding `SYS_ADMIN`, with a penalty of -30 points, and an advise rule for `runAsNonRoot`. The exact result for a manifest depends on its fields and the rules that apply to its resource kind.

For automation, JSON is the most direct format. For local review, table output reduces the need to parse nested data. Template output can adapt the report, but the user must supply `--template report-template.tmpl`. The repository includes a `templates/` directory, although the README does not document a complete template authoring guide. A team adopting a custom report format should verify that its template remains compatible with the selected Kubesec release.

## Where Kubesec Can Mislead or Fall Short

The first limitation is scope. A static score does not establish that a container is safe at runtime. A manifest may receive a favorable result while its image contains vulnerable software, its application exposes unexpected traffic, or its secrets are handled insecurely outside the resource definition. Those are separate concerns, and the README does not say that Kubesec performs them.

The second limitation is rule coverage. Kubesec supports named rules and resource kinds such as Pod, Deployment, StatefulSet, and DaemonSet, but the README does not present the catalog as a complete Kubernetes security standard. A scan using `--rules CapSysAdmin` deliberately omits other rules. Teams should not turn a focused scan into a release gate without recording that limitation.

Schema access can also constrain use. The README links schema-location behavior to the kubeconform documentation and describes fetching schemas from an upstream GitHub location when scanning against a particular version. The Dockerfile includes selected schemas and uses `SCHEMA_LOCATION=/schemas`. In an air-gapped environment, operators must account for the schema source and ensure that the required definitions are available. The README does not document a complete offline workflow beyond referencing kubeconform's schema-location rules.

Finally, enforcement is separate. The README links to a Kubernetes Admission Controller and a kubectl plugin as separate projects. Kubesec's local CLI can produce findings, but the repository documentation does not establish that the CLI itself blocks deployments.

## Kubesec Compared With Admission Enforcement and General Validation

Kubesec is a local scoring tool. Its main difference from a general Kubernetes schema validator is the security rule layer and the numeric result attached to selected configuration properties. A schema validator can reject a malformed or unsupported resource. Kubesec can evaluate fields such as capabilities, privilege escalation, and non-root execution, then explain the score.

The README links to a separate Kubernetes admission-controller project, but its implementation and behavior are not documented here. The linked project is separate from this repository, so its installation, availability, policy behavior, and operational requirements must be assessed in their own documentation.

A generic SAST system may inspect application source, infrastructure code, dependencies, or container images as part of a wider analysis. Kubesec focuses on Kubernetes resource definitions and exposes Kubernetes-specific selectors and point values. That narrower focus makes it easy to add to a manifest review, but it also means it does not replace a broader static analysis program. The choice depends on whether the required evidence concerns Kubernetes configuration, source code, images, or admission behavior.

## Maintenance, Release Cadence, and Apache-2.0 Use

Kubesec is not archived, and the last push was on 2026-10-08. The recent release history includes v2.15.0 on 2026-10-08, v2.14.2 on 2024-11-22, and v2.14.1 on 2024-08-20. The presence of a newer release after the earlier 2024 releases indicates that upgrade planning should include checking the current release's rule changes, schema behavior, and Go requirements rather than assuming the older installation guidance is unchanged.

The project is licensed under Apache-2.0. That identifier indicates the stated licensing model, but organizations still need to review the license text, notices, dependency terms, and distribution obligations for their own use. The repository contains `LICENSE`, `CHANGELOG.md`, and release documentation references, which are the relevant starting points for compliance and upgrade review.

The repository layout separates command handling under `cmd/`, implementation packages under `pkg/`, templates under `templates/`, and tests under `test/`. The Go module path is `github.com/controlplaneio/kubesec/v2`, while the Dockerfile builds a static binary with `CGO_ENABLED=0 GOOS=linux`. These details matter when organizations rebuild images, vendor dependencies, or maintain an internal mirror.

## Conclusion

Adopt Kubesec when your team needs an explicit Kubernetes manifest security score and inspectable rule results before deployment. Do not treat its score as runtime assurance or a complete cluster security review. Verify rule coverage, schema availability, selected output format, and whether the linked admission-controller or kubectl-plugin integration fits your enforcement path before making it a release gate.

## FAQ

### How do I install Kubesec?

The README documents `go install github.com/controlplaneio/kubesec/v2@latest` for newer Go versions and `GO111MODULE="on" go get github.com/controlplaneio/kubesec/v2` for older Go versions. It also links release binaries and the `docker.io/kubesec/kubesec:v2` image.

### How do I scan a Kubernetes YAML file with Kubesec?

Run `kubesec scan kubesec-test.yaml`, replacing the filename with the path to the manifest. Kubesec accepts local files, standard input, JSON or YAML, and multiple documents separated by `---`.

### Can Kubesec scan a rendered Helm chart?

The README shows rendering the chart with Helm and piping the result to Kubesec: `helm template -f values.yaml ./chart | kubesec scan /dev/stdin`. This scans the rendered manifests rather than the chart templates directly.

### Which output formats does Kubesec support?

The `--format` flag supports `json`, `table`, and `template`. JSON is the default, while template output requires a template file supplied with `--template`.

### Does Kubesec block unsafe Kubernetes resources?

The README describes local scanning and links a separate Kubernetes Admission Controller project. It does not say that the Kubesec CLI itself rejects or blocks resources during admission.

## Sources

- [controlplaneio/kubesec on GitHub](https://github.com/controlplaneio/kubesec)
- [License: Apache-2.0](https://github.com/controlplaneio/kubesec/blob/master/LICENSE)
- [Project website](https://kubesec.io)
- [README](https://github.com/controlplaneio/kubesec/blob/master/README.md)
- [Releases](https://github.com/controlplaneio/kubesec/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/controlplaneio-kubesec