train-k8s-container

A Train transport plugin that enables Chef InSpec and Cinc Auditor to execute compliance checks against containers running in Kubernetes clusters via kubectl exec.

This plugin allows InSpec/Cinc Auditor to scan containers running in Kubernetes clusters, enabling compliance-as-code for containerized workloads. It supports:

• Pod-to-Pod Scanning: Scanner pod connects to target containers in other pods
• Same-Pod Scanning: Scanner sidecar scans sibling containers within the same pod
• External Scanning: Run scans from outside the cluster using kubeconfig

• Train v2 Compliance - Modern TrainPlugins namespace and structure
• Multi-Platform Support - Linux containers (Ubuntu, Alpine, RHEL, distroless)
• Shell Detection - Automatic detection of available shells (bash, sh, ash, zsh)
• Platform Detection - Uses Train's Detect+Context pattern for accurate OS detection
• Security Hardening - CVE-2021-25743 mitigation, RFC 1123 validation, command injection prevention
• Comprehensive Testing - 95%+ code coverage with unit and integration tests

Important: Always install Train plugins using inspec plugin install or cinc-auditor plugin install. Do NOT use gem install directly, as this can cause issues with plugin discovery and management.

# Using Cinc Auditor (open source, license-free)
cinc-auditor plugin install train-k8s-container-mitre

# Or using Chef InSpec
inspec plugin install train-k8s-container-mitre

git clone https://github.com/mitre/train-k8s-container.git
cd train-k8s-container
gem build train-k8s-container.gemspec
cinc-auditor plugin install train-k8s-container-mitre-*.gem

• kubectl installed and in PATH
• kubeconfig configured with cluster access (default: ~/.kube/config)
• RBAC permissions to exec into target pods

k8s-container://<namespace>/<pod>/<container>

• namespace - Kubernetes namespace (use empty for default)
• pod - Pod name
• container - Container name within the pod

# Detect container platform
cinc-auditor detect -t k8s-container://production/web-app/nginx

# Using default namespace
cinc-auditor detect -t k8s-container:///my-pod/my-container

# Interactive shell
cinc-auditor shell -t k8s-container:///my-pod/my-container

# Run a compliance profile
cinc-auditor exec my-profile -t k8s-container://prod/app-pod/app

# Run STIG baseline
cinc-auditor exec https://github.com/mitre/canonical-ubuntu-22.04-lts-stig-baseline \
  -t k8s-container:///target-pod/target-container

$ cinc-auditor detect -t k8s-container:///test-ubuntu/test-ubuntu

Name:      ubuntu
Families:  debian, linux, unix, os, kubernetes, container
Release:   22.04
Arch:      aarch64

# Example InSpec control
control 'container-security-1' do
  impact 1.0
  title 'Verify container user'

  describe user('root') do
    it { should exist }
  end

  describe file('/etc/passwd') do
    it { should exist }
    its('owner') { should eq 'root' }
  end
end

For pod-to-pod scanning, the scanner pod needs exec permissions:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: inspec-scanner
  namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: inspec-scanner-role
rules:
- apiGroups: [""]
  resources: ["pods", "pods/exec"]
  verbs: ["get", "list", "create"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: inspec-scanner-binding
subjects:
- kind: ServiceAccount
  name: inspec-scanner
  namespace: default
roleRef:
  kind: ClusterRole
  name: inspec-scanner-role
  apiGroup: rbac.authorization.k8s.io

• Windows containers (planned)

See DEVELOPMENT.md for local development setup and testing.

# Install dependencies
bundle install

# Run unit tests
bundle exec rspec spec/train-k8s-container

# Run linting
bundle exec rake style

# Setup kind cluster for integration tests
./test/setup-kind.sh

# Run integration tests
bundle exec rspec spec/integration

See CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Run bundle exec rspec && bundle exec rake style
5. Submit a pull request

This project uses Conventional Commits for automated releases:

See CONTRIBUTING.md for full details.

See SECURITY.md for security policy and reporting vulnerabilities.

• Report vulnerabilities to saf-security@mitre.org
• Do NOT open public issues for security vulnerabilities

Licensed under Apache-2.0. See LICENSE.md and NOTICE.md.

This project is maintained by the MITRE SAF (Security Automation Framework) team.

• Email: saf@mitre.org
• Website: saf.mitre.org

This project is a fork of inspec/train-k8s-container, enhanced with:

• Train v2 plugin architecture
• Detect+Context platform detection pattern
• Comprehensive CI/CD with pod-to-pod testing
• Automated releases via release-please

NOTICE: This software was produced for the U.S. Government under Contract Number HHSM-500-2012-00008I, and is subject to Federal Acquisition Regulation Clause 52.227-14, Rights in Data-General.

(c) 2025 The MITRE Corporation.