train-k8s-container-mitre 2.0.0

data/DEVELOPMENT.md

@@ -0,0 +1,315 @@
+# Development Guide
+
+This guide covers local development and testing for train-k8s-container.
+
+## Prerequisites
+
+- Ruby 3.1+ (3.3 recommended)
+- Bundler
+- Docker (for integration testing)
+- [kind](https://kind.sigs.k8s.io/) (Kubernetes IN Docker)
+- kubectl
+
+## Quick Start
+
+```bash
+# Clone the repository
+git clone https://github.com/mitre/train-k8s-container.git
+cd train-k8s-container
+
+# Install dependencies
+bundle install
+
+# Run unit tests (no Kubernetes required)
+bundle exec rspec spec/train-k8s-container
+
+# Run linting
+bundle exec rake style
+```
+
+## Project Structure
+
+```
+train-k8s-container/
+├── lib/
+│   └── train-k8s-container/
+│       ├── connection.rb        # Main connection class
+│       ├── kubectl_exec_client.rb  # kubectl command execution
+│       ├── platform.rb          # Platform detection (Detect+Context)
+│       ├── retry_handler.rb     # Retry logic for transient failures
+│       ├── transport.rb         # Train transport plugin registration
+│       └── version.rb           # Version info
+├── spec/
+│   ├── train-k8s-container/     # Unit tests (mocked)
+│   └── integration/             # Integration tests (real kubectl)
+├── test/
+│   ├── scripts/                 # Manual test scripts
+│   ├── setup-kind.sh            # Kind cluster setup
+│   └── cleanup-kind.sh          # Kind cluster teardown
+└── .github/workflows/           # CI/CD pipelines
+```
+
+## Running Tests
+
+### Unit Tests
+
+Unit tests mock all external dependencies and run quickly:
+
+```bash
+# Run all unit tests
+bundle exec rspec spec/train-k8s-container
+
+# Run specific test file
+bundle exec rspec spec/train-k8s-container/connection_spec.rb
+
+# Run specific test by line number
+bundle exec rspec spec/train-k8s-container/connection_spec.rb:42
+
+# Run with verbose output
+bundle exec rspec --format documentation
+```
+
+### Integration Tests
+
+Integration tests require a real Kubernetes cluster:
+
+```bash
+# Setup kind cluster with test pods
+./test/setup-kind.sh
+
+# Run integration tests
+bundle exec rspec spec/integration
+
+# Cleanup when done
+./test/cleanup-kind.sh
+```
+
+### Full Test Suite
+
+```bash
+# Run all tests (unit + integration)
+bundle exec rspec
+
+# With coverage report
+bundle exec rspec
+open coverage/index.html
+```
+
+## Setting Up Local Kind Cluster
+
+### Automated Setup
+
+```bash
+# Creates cluster and deploys test pods
+./test/setup-kind.sh
+```
+
+This script:
+1. Creates a kind cluster named `test-cluster`
+2. Deploys `test-ubuntu` pod (Ubuntu 22.04 with bash)
+3. Deploys `test-alpine` pod (Alpine 3.18 with ash/sh)
+4. Deploys `test-distroless` pod (no shell, for edge case testing)
+5. Waits for all pods to be ready
+
+### Manual Setup
+
+```bash
+# Create kind cluster
+kind create cluster --name test-cluster
+
+# Deploy test pods
+kubectl run test-ubuntu --image=ubuntu:22.04 --restart=Never -- sleep infinity
+kubectl run test-alpine --image=alpine:3.18 --restart=Never -- sleep infinity
+
+# Wait for pods
+kubectl wait --for=condition=Ready pod/test-ubuntu --timeout=120s
+kubectl wait --for=condition=Ready pod/test-alpine --timeout=120s
+
+# Verify
+kubectl get pods
+kubectl exec test-ubuntu -- echo "ready"
+```
+
+### Cleanup
+
+```bash
+# Delete cluster
+kind delete cluster --name test-cluster
+
+# Or use the cleanup script
+./test/cleanup-kind.sh
+```
+
+## Testing with InSpec/Cinc Auditor
+
+### Install Plugin Locally
+
+```bash
+# Build gem
+gem build train-k8s-container.gemspec
+
+# Install in Cinc Auditor
+cinc-auditor plugin install train-k8s-container-*.gem
+
+# Verify installation
+cinc-auditor plugin list
+```
+
+### Manual Testing
+
+```bash
+# Detect platform
+cinc-auditor detect -t k8s-container:///test-ubuntu/test-ubuntu
+
+# Interactive shell
+cinc-auditor shell -t k8s-container:///test-ubuntu/test-ubuntu
+
+# Run a profile
+cinc-auditor exec my-profile -t k8s-container:///test-ubuntu/test-ubuntu
+```
+
+### Using test_live.rb
+
+```bash
+# Requires kind cluster with test pods
+bundle exec ruby test/scripts/test_live.rb
+```
+
+## Code Quality
+
+### Linting
+
+```bash
+# Run Cookstyle/RuboCop
+bundle exec rake style
+
+# Auto-fix issues
+bundle exec rubocop -a
+```
+
+### Security Audit
+
+```bash
+# Check for vulnerable dependencies
+bundle audit check --update
+```
+
+### Full Quality Check
+
+```bash
+# Runs style + tests + security
+bundle exec rake quality
+```
+
+## Debugging
+
+### Enable Debug Logging
+
+```bash
+# With InSpec/Cinc
+cinc-auditor detect -t k8s-container:///pod/container -l debug
+
+# In tests
+TRAIN_K8S_DEBUG=1 bundle exec rspec
+```
+
+### Common Issues
+
+#### "No such file or directory - kubectl"
+
+kubectl is not in PATH. Install kubectl or specify the path:
+```bash
+export PATH=$PATH:/usr/local/bin
+```
+
+#### "error: unable to forward port"
+
+The kind cluster may not be running:
+```bash
+kind get clusters
+kind create cluster --name test-cluster
+```
+
+#### "container not found"
+
+Pod or container name doesn't exist:
+```bash
+kubectl get pods -A
+kubectl describe pod <pod-name>
+```
+
+### Inspecting kubectl Commands
+
+The plugin builds kubectl commands like:
+```bash
+kubectl exec --stdin <pod> -n <namespace> -c <container> -- /bin/sh -c "<command>"
+```
+
+To debug, run the command manually:
+```bash
+kubectl exec --stdin test-ubuntu -n default -c test-ubuntu -- /bin/sh -c "whoami"
+```
+
+## Architecture Notes
+
+### Platform Detection (Detect + Context Pattern)
+
+This plugin uses Train's built-in `Detect.scan(self)` to detect the actual OS inside containers, then adds Kubernetes context families:
+
+```ruby
+# lib/train-k8s-container/platform.rb
+@platform = Train::Platforms::Detect.scan(self)
+add_k8s_families(@platform)  # Adds 'kubernetes', 'container' families
+```
+
+This allows InSpec resources to work correctly (`os.linux?` = true) while still providing transport context (`platform.kubernetes?` = true).
+
+### Connection Flow
+
+1. **URI Parsing**: `k8s-container://namespace/pod/container`
+2. **Validation**: Pod/container names validated against RFC 1123
+3. **Shell Detection**: Probes for available shells (bash, sh, ash, zsh)
+4. **Command Execution**: Routes through `KubectlExecClient`
+5. **Platform Detection**: Runs `Detect.scan()` on first access
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `transport.rb` | Plugin registration with Train |
+| `connection.rb` | Main connection class, URI parsing |
+| `kubectl_exec_client.rb` | Builds and executes kubectl commands |
+| `platform.rb` | Platform detection using Detect+Context |
+| `retry_handler.rb` | Retry logic for transient failures |
+
+## CI/CD
+
+GitHub Actions runs on every push/PR:
+
+- **Unit tests**: Ruby 3.1, 3.2, 3.3
+- **Integration tests**: Kubernetes 1.29, 1.30, 1.31
+- **Security scans**: TruffleHog, bundler-audit, SBOM
+- **Pod-to-pod tests**: InSpec running inside cluster
+
+See `.github/workflows/ci.yml` for details.
+
+## Releasing
+
+Releases are automated via GitHub Actions when a tag is pushed:
+
+```bash
+# Update VERSION file
+echo "2.1.0" > VERSION
+
+# Commit and tag
+git add VERSION CHANGELOG.md
+git commit -m "Release v2.1.0"
+git tag v2.1.0
+git push origin main --tags
+```
+
+The `release-tag.yml` workflow will:
+1. Run tests
+2. Build gem
+3. Publish to RubyGems.org
+4. Create GitHub release

data/Gemfile

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# train-core is needed for development/testing but NOT declared in gemspec
+# Train plugins are loaded within InSpec's environment which provides train
+gem 'train-core', ['>= 1.7.5', '< 4.0']
+
+# Specify your gem's dependencies in train-k8s-container.gemspec
+gemspec
+
+group :development do
+  gem 'bundler-audit', '~> 0.9'
+  gem 'cookstyle', '~> 8.1'
+  gem 'rake', '~> 13.0', '>= 13.0.6'
+  gem 'rspec', '~> 3.11'
+end
+
+group :test do
+  gem 'byebug'
+  gem 'pry'
+  gem 'simplecov', require: false
+end

data/LICENSE.md

@@ -0,0 +1,9 @@
+Licensed under the Apache-2.0 license, except as noted below.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright/digital rights legend, this list of conditions and the following Notice.
+
+* Redistributions in binary form must reproduce the above copyright/digital rights legend, this list of conditions and the following Notice in the documentation and/or other materials provided with the distribution.
+
+* Neither the name of The MITRE Corporation nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

data/NOTICE.md

@@ -0,0 +1,9 @@
+MITRE hereby grants express written permission to use, reproduce, distribute, modify, and otherwise leverage this software to the extent permitted by the licensed terms provided in the LICENSE.md file included with this project.
+
+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.
+
+No other use other than that granted to the U. S. Government, or to those acting on behalf of the U. S. Government under that Clause is authorized without the express written permission of The MITRE Corporation.
+
+For further information, please contact The MITRE Corporation, Contracts Management Office, 7515 Colshire Drive, McLean, VA 22102-7539, (703) 983-6000.
+
+(c) 2025 The MITRE Corporation.

data/README.md

@@ -0,0 +1,237 @@
+# 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.
+
+[![CI](https://github.com/mitre/train-k8s-container/actions/workflows/ci.yml/badge.svg)](https://github.com/mitre/train-k8s-container/actions/workflows/ci.yml)
+[![Security](https://github.com/mitre/train-k8s-container/actions/workflows/security.yml/badge.svg)](https://github.com/mitre/train-k8s-container/actions/workflows/security.yml)
+
+## Overview
+
+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
+
+## Features
+
+- **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
+
+## Installation
+
+### From RubyGems (Recommended)
+
+```bash
+# Using Cinc Auditor (recommended - open source, license-free)
+cinc-auditor plugin install train-k8s-container
+
+# Or using Chef InSpec
+inspec plugin install train-k8s-container
+```
+
+### From Source
+
+```bash
+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-*.gem
+```
+
+## Prerequisites
+
+- **kubectl** installed and in PATH
+- **kubeconfig** configured with cluster access (default: `~/.kube/config`)
+- **RBAC permissions** to exec into target pods
+
+## Usage
+
+### URI Format
+
+```
+k8s-container://<namespace>/<pod>/<container>
+```
+
+- `namespace` - Kubernetes namespace (use empty for `default`)
+- `pod` - Pod name
+- `container` - Container name within the pod
+
+### Examples
+
+```bash
+# 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
+```
+
+### Platform Detection Output
+
+```bash
+$ cinc-auditor detect -t k8s-container:///test-ubuntu/test-ubuntu
+
+Name:      ubuntu
+Families:  debian, linux, unix, os, kubernetes, container
+Release:   22.04
+Arch:      aarch64
+```
+
+### Running Compliance Checks
+
+```ruby
+# 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
+```
+
+## Kubernetes RBAC Setup
+
+For pod-to-pod scanning, the scanner pod needs exec permissions:
+
+```yaml
+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
+```
+
+## Supported Container Types
+
+### Linux Containers
+
+| Distribution | Shell | Status |
+|-------------|-------|--------|
+| Ubuntu/Debian | bash | Full support |
+| Alpine/BusyBox | ash/sh | Full support |
+| RHEL/CentOS | bash | Full support |
+| Distroless | N/A | Limited (direct binary only) |
+
+### Not Yet Supported
+
+- Windows containers (planned)
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `KUBECONFIG` | Path to kubeconfig file | `~/.kube/config` |
+| `TRAIN_K8S_DEBUG` | Enable debug logging | `false` |
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for local development setup and testing.
+
+### Quick Start
+
+```bash
+# 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
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](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
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for security policy and reporting vulnerabilities.
+
+- Report vulnerabilities to [saf-security@mitre.org](mailto:saf-security@mitre.org)
+- Do NOT open public issues for security vulnerabilities
+
+## License
+
+Licensed under Apache-2.0. See [LICENSE.md](LICENSE.md) and [NOTICE.md](NOTICE.md).
+
+## Maintainers
+
+This project is maintained by the MITRE SAF (Security Automation Framework) team.
+
+- **Email**: [saf@mitre.org](mailto:saf@mitre.org)
+- **Website**: [saf.mitre.org](https://saf.mitre.org)
+
+## Acknowledgments
+
+This project is a fork of [inspec/train-k8s-container](https://github.com/inspec/train-k8s-container), significantly enhanced with:
+
+- Train v2 plugin architecture
+- Detect+Context platform detection pattern
+- Comprehensive CI/CD with pod-to-pod testing
+- Security hardening and SBOM generation
+- MITRE SAF ecosystem integration
+
+---
+
+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.

data/Rakefile

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+begin
+  require 'cookstyle'
+  require 'rubocop/rake_task'
+  desc 'Run Cookstyle tests'
+  RuboCop::RakeTask.new(:style) do |task|
+    task.options += %w[--display-cop-names --no-color --parallel]
+  end
+rescue LoadError
+  puts 'cookstyle gem is not installed. bundle install first to make sure all dependencies are installed.'
+end
+
+desc 'Run security scans (bundler-audit)'
+task :security do
+  require 'bundler/audit/task'
+  Bundler::Audit::Task.new
+
+  puts '=== Running Security Scans ==='
+  puts '--- Bundler Audit (Dependency Vulnerabilities) ---'
+
+  Rake::Task['bundle:audit:update'].invoke
+  Rake::Task['bundle:audit'].invoke
+
+  puts
+  puts '✅ Security scans complete'
+end
+
+desc 'Run all quality checks (style + spec + security)'
+task quality: %i[style spec security]
+
+task default: :spec