train-k8s-container-mitre 2.0.3 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6aef3c36a97fd15eb144078a356e94c15711cad2ce7f267fd76a68d2d96043ef
-  data.tar.gz: fb7929665b4f7cac1d057f6277ca86defa5f28511a040fac38aff31b4adf762c
+  metadata.gz: 6255dfedd08c1ccc04f6c69fdd56f530f927ece9876c248813ceabe38ab93134
+  data.tar.gz: 4976598e8fec6ae7274a468be4aedda447251dc66c59acf10c0af924b47b1be2
 SHA512:
-  metadata.gz: 1625625532721a6da204352a46e4ee65168c21b68a9ef03bb660613fa78a03acded5d370ad1ac6ab63f6fb5faad79d3c6db7fd1cc915715c5e503b16f6b611cb
-  data.tar.gz: fea6a3be4230ee420687fd5d116145eba00b8693d9706dfed4581253ee56cb0410b45ee8359090b7c1daba67964155a388999f817425b145ff9db369737e2ddd
+  metadata.gz: '0959c3bbc96a96c717f0f4129ef6612ac874e599920bfd399179423e7884745accee2d9415473fa0e0dc7d50061aae01db81343be7dd4883e55465019716d9bc'
+  data.tar.gz: 3085e763b733098b172a3c73e9eb06698dd54f1632d65a0fe6b2545c7ea4dd5056a5ad49bc38cf37e469d19beb3a88dd7629b7243a8d9d848fc57a0e106153d8

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "2.0.3"
+  ".": "2.1.1"
 }

data/ARCHITECTURE.md

@@ -0,0 +1,546 @@
+# Architecture Overview
+
+This document provides a technical overview of the train-k8s-container plugin architecture.
+
+## High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           InSpec / Cinc Auditor                             │
+│                                                                             │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
+│  │   Profile   │───▶│  Resources  │───▶│    Train    │───▶│  Transport  │  │
+│  │  Controls   │    │ (file, user │    │  Framework  │    │   Plugin    │  │
+│  └─────────────┘    │  package..) │    └─────────────┘    └──────┬──────┘  │
+└──────────────────────────────────────────────────────────────────┼─────────┘
+                                                                   │
+                              ┌────────────────────────────────────┘
+                              ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        train-k8s-container Plugin                           │
+│                                                                             │
+│  ┌───────────────────────────────────────────────────────────────────────┐  │
+│  │                           Connection                                   │  │
+│  │  • URI parsing (k8s-container://namespace/pod/container)              │  │
+│  │  • Parameter validation                                                │  │
+│  │  • File operations via Train::File::Remote::Linux                     │  │
+│  └───────────────────────────────────┬───────────────────────────────────┘  │
+│                                      │                                      │
+│         ┌────────────────────────────┼────────────────────────────┐        │
+│         ▼                            ▼                            ▼        │
+│  ┌─────────────────┐    ┌─────────────────────┐    ┌─────────────────┐    │
+│  │  ShellDetector  │    │  KubectlExecClient  │    │    Platform     │    │
+│  │                 │    │                     │    │                 │    │
+│  │ • OS detection  │    │ • Command execution │    │ • Detect+Context│    │
+│  │ • Shell probing │    │ • PTY sessions      │    │ • OS families   │    │
+│  │ • Linux family  │    │ • Retry handling    │    │ • Kubernetes    │    │
+│  └────────┬────────┘    └──────────┬──────────┘    │   context       │    │
+│           │                        │               └─────────────────┘    │
+│           │             ┌──────────┴──────────┐                           │
+│           │             ▼                     ▼                           │
+│           │    ┌─────────────────┐   ┌─────────────────┐                 │
+│           │    │ SessionManager  │   │ ResultProcessor │                 │
+│           │    │   (Singleton)   │   │                 │                 │
+│           │    │                 │   │ • ANSI cleanup  │                 │
+│           │    │ • Connection    │   │ • Exit codes    │                 │
+│           │    │   pooling       │   │ • Error detect  │                 │
+│           │    │ • Thread-safe   │   └─────────────────┘                 │
+│           │    └────────┬────────┘                                       │
+│           │             │                                                 │
+│           │             ▼                                                 │
+│           │    ┌─────────────────┐                                       │
+│           │    │   PtySession    │                                       │
+│           │    │                 │                                       │
+│           │    │ • Persistent    │                                       │
+│           │    │   shell session │                                       │
+│           │    │ • Command queue │                                       │
+│           │    └─────────────────┘                                       │
+│           │                                                               │
+│  ┌────────┴──────────────────────────────────────────────────────────┐   │
+│  │                        Support Modules                             │   │
+│  │                                                                    │   │
+│  │  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐ │   │
+│  │  │ KubectlCommand   │  │ KubernetesName   │  │  AnsiSanitizer   │ │   │
+│  │  │    Builder       │  │   Validator      │  │                  │ │   │
+│  │  │                  │  │                  │  │ • CVE-2021-25743 │ │   │
+│  │  │ • Shell escaping │  │ • RFC 1123       │  │   mitigation     │ │   │
+│  │  │ • Windows/Unix   │  │ • Injection      │  │ • ANSI stripping │ │   │
+│  │  └──────────────────┘  │   prevention     │  └──────────────────┘ │   │
+│  │                        └──────────────────┘                        │   │
+│  └────────────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              kubectl exec                                   │
+│                                                                             │
+│     kubectl exec --stdin <pod> -n <namespace> -c <container> -- <cmd>      │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          Kubernetes Cluster                                 │
+│                                                                             │
+│    ┌─────────────────────────────────────────────────────────────────┐     │
+│    │                           Target Pod                             │     │
+│    │  ┌─────────────────────────────────────────────────────────┐    │     │
+│    │  │                     Target Container                     │    │     │
+│    │  │                                                          │    │     │
+│    │  │   /bin/bash, /bin/sh, /bin/ash  ──or──  distroless      │    │     │
+│    │  │                                                          │    │     │
+│    │  └─────────────────────────────────────────────────────────┘    │     │
+│    └─────────────────────────────────────────────────────────────────┘     │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Command Execution Flow
+
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│                          Command Execution Flow                              │
+└──────────────────────────────────────────────────────────────────────────────┘
+
+   InSpec Control                    Plugin Components                   kubectl
+   ─────────────                     ─────────────────                   ───────
+        │
+        │  command('whoami')
+        ▼
+   ┌─────────┐
+   │ Control │
+   └────┬────┘
+        │
+        ▼
+   ┌─────────────────┐
+   │   Connection    │ ─── parse URI, validate params
+   └────────┬────────┘
+            │
+            ▼
+   ┌─────────────────┐
+   │ KubectlExec     │
+   │    Client       │
+   └────────┬────────┘
+            │
+            │  Check for existing session
+            ▼
+   ┌─────────────────┐     ┌─────────────────┐
+   │ SessionManager  │────▶│   PtySession    │  (if pooled session exists)
+   │   (Singleton)   │     │  (persistent)   │
+   └────────┬────────┘     └────────┬────────┘
+            │                       │
+            │  No session?          │ Has session?
+            │  Create new           │ Reuse
+            ▼                       ▼
+   ┌─────────────────┐     ┌─────────────────┐
+   │ KubectlCommand  │     │  Send command   │
+   │    Builder      │     │  via PTY pipe   │
+   └────────┬────────┘     └────────┬────────┘
+            │                       │
+            ▼                       ▼
+   ┌─────────────────┐     ┌─────────────────┐
+   │  Mixlib::       │     │  Read response  │
+   │  ShellOut       │     │  until marker   │
+   └────────┬────────┘     └────────┬────────┘
+            │                       │
+            ▼                       ▼
+        ┌───────────────────────────────┐
+        │        kubectl exec           │ ───▶  Container
+        └───────────────┬───────────────┘
+                        │
+                        ▼
+               ┌─────────────────┐
+               │ ResultProcessor │
+               │                 │
+               │ • Parse exit    │
+               │   code          │
+               │ • Strip ANSI    │
+               │ • Detect errors │
+               └────────┬────────┘
+                        │
+                        ▼
+               ┌─────────────────┐
+               │  RetryHandler   │ ─── Retry on transient errors
+               │                 │     (exponential backoff)
+               └────────┬────────┘
+                        │
+                        ▼
+               Train::Extras::CommandResult
+                  (stdout, stderr, exit_code)
+```
+
+## File Structure
+
+```
+lib/train-k8s-container/
+├── transport.rb              # Train plugin registration
+├── connection.rb             # Main connection class
+├── kubectl_exec_client.rb    # Command execution engine
+├── platform.rb               # OS detection (Detect+Context)
+├── version.rb                # Version constant
+│
+├── session_manager.rb        # Connection pool (Singleton)
+├── pty_session.rb            # Persistent PTY shell session
+│
+├── shell_detector.rb         # Shell/OS detection
+├── kubectl_command_builder.rb # Command string building
+├── result_processor.rb       # Output parsing & validation
+├── retry_handler.rb          # Exponential backoff retry
+│
+├── ansi_sanitizer.rb         # ANSI escape removal (CVE fix)
+├── kubernetes_name_validator.rb  # RFC 1123 validation
+└── errors.rb                 # Custom error classes
+```
+
+## Component Details
+
+### Core Components
+
+#### Transport (`transport.rb`)
+
+Registers the `k8s-container` transport with Train:
+
+```ruby
+module TrainPlugins::K8sContainer
+  class Transport < Train.plugin(1)
+    name 'k8s-container'
+    # ...
+  end
+end
+```
+
+Connection options:
+- `pod` - Target pod name (required)
+- `container_name` - Target container (required)
+- `namespace` - Kubernetes namespace (default: `default`)
+- `kubeconfig` - Path to kubeconfig file
+
+#### Connection (`connection.rb`)
+
+Main connection handler:
+- Parses URI format: `k8s-container://<namespace>/<pod>/<container>`
+- Validates required parameters (pod, container)
+- Provides `run_command()` for command execution
+- Provides file access via `Train::File::Remote::Linux`
+
+#### KubectlExecClient (`kubectl_exec_client.rb`)
+
+Command execution engine:
+- Detects available shell via `ShellDetector`
+- Routes commands through `SessionManager` for pooling
+- Falls back to direct execution for distroless containers
+- Integrates `RetryHandler` for transient errors
+
+#### Platform (`platform.rb`)
+
+OS detection using **Detect+Context** pattern:
+
+```ruby
+def platform
+  # 1. Use Train's scanner to detect actual OS
+  @platform = Train::Platforms::Detect.scan(self)
+
+  # 2. Add Kubernetes context families
+  add_k8s_families(@platform)
+
+  @platform
+end
+```
+
+Result: `os.linux?` returns `true` while `platform.families` includes `kubernetes`, `container`.
+
+### Session Management (Connection Pooling)
+
+#### SessionManager (`session_manager.rb`)
+
+Thread-safe singleton that pools PTY sessions:
+
+```ruby
+class SessionManager
+  include Singleton
+
+  # One session per namespace/pod/container
+  def get_session(session_key, kubectl_cmd:, shell:, timeout:, logger:)
+    @mutex.synchronize do
+      unless @sessions[session_key]&.healthy?
+        @sessions[session_key] = PtySession.new(...)
+        @sessions[session_key].connect
+      end
+      @sessions[session_key]
+    end
+  end
+end
+```
+
+Benefits:
+- Reuses kubectl exec connections across multiple commands
+- Significantly faster for profiles with many controls
+- Automatic cleanup on session failure or process exit
+
+#### PtySession (`pty_session.rb`)
+
+Persistent PTY-based shell session:
+
+```ruby
+# Instead of spawning kubectl for each command:
+kubectl exec pod -c container -- /bin/sh -c "command1"
+kubectl exec pod -c container -- /bin/sh -c "command2"
+kubectl exec pod -c container -- /bin/sh -c "command3"
+
+# Maintains one persistent session:
+kubectl exec pod -c container -- /bin/bash
+> command1
+> command2
+> command3
+```
+
+Features:
+- Uses Ruby's `PTY.spawn` for interactive session
+- Sends commands with exit code markers
+- Parses output and extracts real exit codes
+- Health checking via process status
+
+### Shell & OS Detection
+
+#### ShellDetector (`shell_detector.rb`)
+
+Detects available shell in container:
+
+```
+Detection Order (Unix):
+  1. /bin/bash   - Ubuntu, Debian, RHEL
+  2. /bin/sh     - POSIX standard
+  3. /bin/ash    - Alpine, BusyBox
+  4. /bin/zsh    - Less common
+
+Detection Order (Windows):
+  1. cmd.exe         - Command prompt
+  2. powershell.exe  - PowerShell 5.1
+  3. pwsh.exe        - PowerShell Core
+```
+
+Also detects Linux distribution family from `/etc/os-release`:
+- Debian family: ubuntu, debian, linuxmint, kali
+- RedHat family: rhel, centos, fedora, rocky, almalinux
+- Alpine, Arch, SUSE, Gentoo
+
+### Command Building & Processing
+
+#### KubectlCommandBuilder (`kubectl_command_builder.rb`)
+
+Builds properly escaped kubectl commands:
+
+```ruby
+builder = KubectlCommandBuilder.new(
+  kubectl_path: '/usr/bin/kubectl',
+  pod: 'my-pod',
+  namespace: 'default',
+  container_name: 'app'
+)
+
+# Unix shell
+builder.with_shell('/bin/bash', 'cat /etc/passwd')
+# => "kubectl exec --stdin my-pod -n default -c app -- /bin/bash -c 'cat /etc/passwd'"
+
+# Windows shell
+builder.with_windows_shell('cmd.exe', 'dir')
+# => "kubectl exec --stdin my-pod -n default -c app -- cmd.exe /c 'dir'"
+
+# Direct binary (distroless)
+builder.direct_binary('cat /etc/os-release')
+# => "kubectl exec --stdin my-pod -n default -c app -- cat /etc/os-release"
+```
+
+#### ResultProcessor (`result_processor.rb`)
+
+Processes command output:
+
+1. **Validation**: Detects connection errors and silent failures
+2. **Sanitization**: Strips ANSI sequences, normalizes line endings
+3. **Exit code parsing**: Extracts real exit code from kubectl messages
+
+Connection error patterns detected:
+- `error dialing backend`
+- `connection refused`
+- `pods "name" not found`
+- `Error from server`
+
+### Security Components
+
+#### AnsiSanitizer (`ansi_sanitizer.rb`)
+
+Addresses **CVE-2021-25743** (terminal escape sequence injection):
+
+```ruby
+module AnsiSanitizer
+  CSI_REGEX = /\e\[([;\d]+)?[A-Za-z]/  # Colors, cursor
+  OSC_REGEX = /\e\][^\a]*\a/            # Terminal title
+  CURSOR_REGEX = /\e\[A|\e\[C|\e\[K/    # Movement
+
+  def self.sanitize(text)
+    # Remove all ANSI escape sequences
+  end
+end
+```
+
+#### KubernetesNameValidator (`kubernetes_name_validator.rb`)
+
+Validates names per **RFC 1123** DNS subdomain rules:
+
+```ruby
+VALID_NAME_REGEX = /\A[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)?\z/
+MAX_NAME_LENGTH = 253
+
+def self.validate!(name, resource_type:)
+  # Prevents command injection via malformed names
+end
+```
+
+### Error Handling
+
+#### RetryHandler (`retry_handler.rb`)
+
+Exponential backoff for transient errors:
+
+```ruby
+RetryHandler.with_retry(max_retries: 3, logger: logger) do
+  # Network operation
+end
+
+# Retry delays: 1s, 2s, 4s (exponential backoff)
+```
+
+Retryable errors:
+- `NetworkError` - Silent failures, timeouts
+- `ConnectionError` - kubectl connection issues
+
+#### Custom Errors (`errors.rb`)
+
+```ruby
+K8sContainerError < Train::TransportError  # Base class
+KubectlNotFoundError    # kubectl binary not in PATH
+ContainerNotFoundError  # Container doesn't exist in pod
+PodNotFoundError        # Pod doesn't exist in namespace
+ShellNotAvailableError  # Distroless container, no shell
+```
+
+## Platform Detection Deep Dive
+
+### Why "Detect + Context" Pattern?
+
+When connecting to an **operating system** (container, VM, bare metal), Train must detect the actual OS for InSpec resources to work correctly.
+
+**Wrong approach** - `force_platform!('k8s-container')`:
+- Platform name becomes `k8s-container` instead of `ubuntu`
+- `os.linux?` returns `false`
+- Resources like `user`, `package`, `service` fail
+
+**Correct approach** - Detect + Context:
+- Detect actual OS: `ubuntu`, `alpine`, `centos`
+- Add context families: `kubernetes`, `container`
+- `os.linux?` returns `true` ✓
+- Resources work correctly ✓
+
+### Detection Commands
+
+Train's scanner executes these to identify the OS:
+
+```bash
+uname -s                    # "Linux"
+uname -m                    # Architecture
+cat /etc/os-release         # OS identification
+cat /etc/debian_version     # Debian family
+cat /etc/alpine-release     # Alpine
+cat /etc/redhat-release     # RHEL family
+```
+
+### Result
+
+```bash
+$ cinc-auditor detect -t k8s-container:///my-pod/my-container
+
+Name:      ubuntu
+Families:  debian, linux, unix, os, kubernetes, container
+Release:   22.04
+Arch:      aarch64
+```
+
+## URI Format
+
+```
+k8s-container://<namespace>/<pod>/<container>
+```
+
+| Component | Required | Default | Example |
+|-----------|----------|---------|---------|
+| namespace | No | `default` | `production` |
+| pod | Yes | - | `web-app-7d4b8c9f-x2k4m` |
+| container | Yes | - | `nginx` |
+
+**Examples:**
+```bash
+# Full URI
+k8s-container://production/web-app/nginx
+
+# Default namespace
+k8s-container:///my-pod/my-container
+```
+
+## Testing Architecture
+
+### Test Structure
+
+```
+spec/
+├── train-k8s-container/     # Unit tests (mocked)
+│   ├── connection_spec.rb
+│   ├── kubectl_exec_client_spec.rb
+│   ├── platform_spec.rb
+│   ├── shell_detector_spec.rb
+│   ├── session_manager_spec.rb
+│   └── ...
+│
+└── integration/             # Integration tests (real cluster)
+    ├── platform_detection_spec.rb
+    ├── command_execution_spec.rb
+    └── ...
+```
+
+### CI Matrix
+
+| Test Type | Ruby | Kubernetes | Description |
+|-----------|------|------------|-------------|
+| Unit | 3.1, 3.2, 3.3 | N/A | Mocked, fast |
+| Integration | 3.1, 3.2, 3.3 | 1.29, 1.30, 1.31 | Real kind cluster |
+| Pod-to-Pod | 3.3 | 1.30 | Scanner inside cluster |
+
+## Key Design Decisions
+
+1. **kubectl over Kubernetes Ruby client**
+   - Simpler dependency management
+   - Leverages user's existing kubeconfig and auth
+   - Works with any kubectl-compatible cluster
+
+2. **Connection pooling via PTY sessions**
+   - Dramatically improves performance for multi-control profiles
+   - Single kubectl process instead of one per command
+   - Thread-safe singleton pattern
+
+3. **Detect+Context over force_platform**
+   - Ensures InSpec resources work correctly
+   - Provides Kubernetes awareness via family tags
+   - Compatible with existing profiles
+
+4. **RFC 1123 validation**
+   - Prevents command injection via malformed names
+   - Enforces Kubernetes naming standards
+
+5. **ANSI sanitization (CVE-2021-25743)**
+   - Strips terminal escape sequences
+   - Prevents injection attacks via kubectl output
+
+6. **Cinc Auditor in CI**
+   - Open-source, license-free InSpec distribution
+   - No Chef license required for testing
+
+7. **OIDC trusted publishing**
+   - Secure gem publishing without API keys
+   - Leverages GitHub Actions identity

data/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.1](https://github.com/mitre/train-k8s-container/compare/v2.1.0...v2.1.1) (2025-12-12)
+
+
+### Bug Fixes
+
+* Parse PR number from JSON in auto-merge step ([09a3667](https://github.com/mitre/train-k8s-container/commit/09a3667cb67010c58837d3ff1ddcf5b197dc3d0d))
+
+
+### Documentation
+
+* Add ARCHITECTURE.md with technical overview ([acfe73a](https://github.com/mitre/train-k8s-container/commit/acfe73a5ad16faa9b481d0c7802d2a8f6f64efb9))
+* Enhance ARCHITECTURE.md with comprehensive technical details ([519675d](https://github.com/mitre/train-k8s-container/commit/519675db04d3766ac3d00575989e748da738a7ea))
+* Fix inaccurate claims in README acknowledgments ([fa2e53c](https://github.com/mitre/train-k8s-container/commit/fa2e53c0eee41638edfa04a583bdcea4fd7eb272))
+* Update release process documentation for automated workflow ([23d1fcf](https://github.com/mitre/train-k8s-container/commit/23d1fcfb38b1415c12029564b92dbcb9df34715d))
+
+## [2.1.0](https://github.com/mitre/train-k8s-container/compare/v2.0.3...v2.1.0) (2025-12-12)
+
+
+### Features
+
+* Enable auto-merge for release-please PRs ([f098f5a](https://github.com/mitre/train-k8s-container/commit/f098f5a150d5532b4def7702e9427448d65764bb))
+
+
+### Bug Fixes
+
+* Remove duplicate push trigger from release workflow ([f1b4c87](https://github.com/mitre/train-k8s-container/commit/f1b4c872f8e1617c38149bc0172ba20e49ba3dc8))
+
 ## [2.0.3](https://github.com/mitre/train-k8s-container/compare/v2.0.2...v2.0.3) (2025-12-12)
 
 

data/CONTRIBUTING.md

@@ -135,60 +135,149 @@ open coverage/index.html
 5. **CI Passing**: All GitHub Actions checks must pass
 6. **Merge**: Maintainers will merge approved PRs
 
-## Release Process
+## Versioning and Commit Messages
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/) and [Semantic Versioning](https://semver.org/). Your commit message prefix determines how the version number changes.
+
+**Official References:**
+- [Conventional Commits Specification](https://www.conventionalcommits.org/en/v1.0.0/)
+- [Angular Commit Message Guidelines](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-commit-message-format) (original source)
+- [Semantic Versioning](https://semver.org/)
+
+### Commit Prefix → Version Bump
+
+| Commit Prefix | Version Change | When to Use |
+|---------------|----------------|-------------|
+| `feat:` | **Minor** (2.0.0 → 2.1.0) | New features, capabilities, or enhancements |
+| `fix:` | **Patch** (2.0.0 → 2.0.1) | Bug fixes, corrections, error handling |
+| `docs:` | **Patch** | Documentation changes only |
+| `style:` | **Patch** | Code style, formatting (no logic change) |
+| `refactor:` | **Patch** | Code restructuring (no behavior change) |
+| `perf:` | **Patch** | Performance improvements |
+| `test:` | **Patch** | Adding or updating tests |
+| `chore:` | **Patch** | Maintenance, dependencies, tooling |
+| `ci:` | **Patch** | CI/CD pipeline changes |
+| `build:` | **Patch** | Build system changes |
+| `revert:` | **Patch** | Reverting a previous commit |
+| `feat!:` | **Major** (2.0.0 → 3.0.0) | Breaking changes (note the `!`) |
+| `fix!:` | **Major** | Breaking bug fix |
+| `BREAKING CHANGE:` | **Major** | In commit body, forces major bump |
+
+### Type Descriptions
+
+- **feat**: A new feature for the user (not a build script feature)
+- **fix**: A bug fix for the user (not a build script fix)
+- **docs**: Documentation only changes (README, CONTRIBUTING, inline docs)
+- **style**: Changes that don't affect code meaning (whitespace, formatting, semicolons)
+- **refactor**: Code change that neither fixes a bug nor adds a feature
+- **perf**: Code change that improves performance
+- **test**: Adding missing tests or correcting existing tests
+- **chore**: Changes to build process, auxiliary tools, libraries
+- **ci**: Changes to CI configuration files and scripts
+- **build**: Changes that affect the build system or external dependencies
+- **revert**: Reverts a previous commit (include reverted commit SHA in body)
+
+### Examples
 
-Releases are automated using [release-please](https://github.com/googleapis/release-please) and managed by project maintainers.
+```bash
+# Patch version bump (2.1.0 → 2.1.1)
+git commit -m "fix: handle nil response in platform detection"
+git commit -m "docs: update installation instructions"
+git commit -m "chore: update rubocop dependency"
+git commit -m "test: add integration tests for Alpine containers"
 
-### How It Works
+# Minor version bump (2.1.0 → 2.2.0)
+git commit -m "feat: add support for Windows containers"
+git commit -m "feat: add retry logic for transient kubectl failures"
 
-1. **Commit with Conventional Commits**: Use prefixes like `feat:`, `fix:`, `docs:`, `chore:`
-   - `feat:` triggers a minor version bump (e.g., 2.0.0 → 2.1.0)
-   - `fix:` triggers a patch version bump (e.g., 2.0.0 → 2.0.1)
-   - `feat!:` or `BREAKING CHANGE:` triggers a major version bump
+# Major version bump (2.1.0 → 3.0.0)
+git commit -m "feat!: change URI format to k8s://namespace/pod/container"
+git commit -m "fix!: remove deprecated connection options"
+```
 
-2. **Release PR Created Automatically**: When commits are pushed to `main`, release-please creates/updates a Release PR that:
-   - Bumps the version in `VERSION` file
-   - Updates `CHANGELOG.md` with commit messages
-   - Shows the proposed version change
+### Commit Message Format
 
-3. **Merge to Release**: When maintainers merge the Release PR:
-   - A git tag is created (e.g., `v2.1.0`)
-   - GitHub Actions builds and publishes the gem to RubyGems.org
-   - A GitHub Release is created with auto-generated notes
+```
+<type>(<optional scope>): <description>
 
-### Example Workflow
+[optional body]
 
+[optional footer(s)]
+```
+
+**Examples:**
 ```bash
-# Make changes with conventional commit messages
-git commit -m "feat: add support for Windows containers"
-git push origin main
+# Simple
+git commit -m "fix: handle empty shell response"
 
-# release-please automatically creates a PR like:
-# "chore(main): release 2.1.0"
+# With scope
+git commit -m "feat(platform): add FreeBSD detection"
 
-# After review, maintainer merges the PR
-# → Tag v2.1.0 is created
-# → Gem is published to RubyGems.org
+# With body
+git commit -m "feat: add Windows container support
+
+This adds support for Windows containers running in Kubernetes.
+Tested with Windows Server 2022 and Windows Server Core images."
+
+# Breaking change with body
+git commit -m "feat!: require Ruby 3.1+
+
+BREAKING CHANGE: Ruby 2.7 and 3.0 are no longer supported.
+This allows us to use pattern matching and other Ruby 3.1 features."
 ```
 
-### Manual Releases (Emergency Only)
+## Release Process
 
-For hotfixes that need immediate release without waiting for release-please:
+Releases are **fully automated** using [release-please](https://github.com/googleapis/release-please) with auto-merge enabled.
 
-```bash
-# Update VERSION manually
-echo "2.0.2" > VERSION
+### How It Works
+
+1. **Release PR Created Automatically**: When commits are pushed to `main`, release-please creates/updates a Release PR with auto-merge enabled that:
+   - Bumps the version in `lib/train-k8s-container/version.rb`
+   - Updates `CHANGELOG.md` with commit messages
+   - Shows the proposed version change
+
+2. **Auto-Merge When CI Passes**: The Release PR automatically merges once all CI checks pass:
+   - Unit tests (Ruby 3.1, 3.2, 3.3)
+   - Integration tests (Kubernetes 1.29, 1.30, 1.31)
+   - Security audit
+   - Branch protection enforces all checks must pass
+
+3. **Automatic Publishing**: After merge, release-please creates a GitHub Release which triggers:
+   - Gem build
+   - Publish to RubyGems.org (via OIDC trusted publishing)
+   - Gem artifact attached to GitHub Release
+
+### Complete Automated Flow
 
-# Update CHANGELOG.md manually
+```
+Push commit → CI runs → Release PR created (auto-merge enabled)
+                                    ↓
+                            CI passes on PR
+                                    ↓
+                            PR auto-merges
+                                    ↓
+                        GitHub Release created
+                                    ↓
+                        Gem published to RubyGems
+```
+
+### Example
+
+```bash
+# Make changes with conventional commit messages
+git commit -m "feat: add support for Windows containers"
+git push origin main
 
-# Commit, tag, and push
-git add VERSION CHANGELOG.md
-git commit -m "chore: release v2.0.2"
-git tag v2.0.2
-git push origin main --tags
+# Everything else is automatic:
+# 1. release-please creates PR: "chore(main): release 2.2.0"
+# 2. CI runs on the PR
+# 3. PR auto-merges when CI passes
+# 4. Tag v2.2.0 is created
+# 5. Gem is published to RubyGems.org
 ```
 
-**Note:** Manual releases should be rare. Prefer the automated release-please flow.
+No manual intervention required for releases.
 
 ## Getting Help
 

data/DEVELOPMENT.md

@@ -295,29 +295,24 @@ See `.github/workflows/ci.yml` for details.
 
 ## Releasing
 
-Releases are automated using [release-please](https://github.com/googleapis/release-please).
+Releases are **fully automated** using [release-please](https://github.com/googleapis/release-please) with auto-merge enabled. No manual intervention required.
 
-### Automated Release Process (Recommended)
+### How It Works
 
-1. **Make commits using Conventional Commits format**:
+1. **Push commits with Conventional Commits format**:
    ```bash
    git commit -m "feat: add Windows container support"
    git commit -m "fix: handle empty shell response"
-   git commit -m "docs: update installation instructions"
-   ```
-
-2. **Push to main** - release-please will automatically create a Release PR:
-   ```bash
    git push origin main
-   # release-please creates PR: "chore(main): release 2.1.0"
    ```
 
-3. **Review and merge the Release PR** - this triggers:
-   - Version bump in `VERSION` file
-   - `CHANGELOG.md` update
-   - Git tag creation (e.g., `v2.1.0`)
-   - Gem build and publish to RubyGems.org
-   - GitHub Release creation
+2. **Automatic flow**:
+   - Release-please creates/updates a Release PR with auto-merge enabled
+   - CI runs on the PR (unit tests, integration tests, security audit)
+   - Branch protection requires all checks to pass
+   - PR auto-merges when CI is green
+   - Release-please creates a GitHub Release
+   - `release-tag.yml` triggers and publishes gem to RubyGems.org
 
 ### Conventional Commits Cheat Sheet
 
@@ -329,25 +324,28 @@ Releases are automated using [release-please](https://github.com/googleapis/rele
 | `chore:` | Patch | `chore: update dependencies` |
 | `feat!:` | Major (2.0.0 → 3.0.0) | `feat!: change URI format` |
 
-### Manual Release (Emergency Only)
-
-For hotfixes that can't wait for the release-please flow:
-
-```bash
-# Update VERSION file
-echo "2.0.2" > VERSION
-
-# Update CHANGELOG.md manually
+### Complete Flow Diagram
 
-# Commit and tag
-git add VERSION CHANGELOG.md
-git commit -m "chore: release v2.0.2"
-git tag v2.0.2
-git push origin main --tags
 ```
+Push commit → CI runs on main → Release-please creates PR (auto-merge on)
+                                              ↓
+                                     CI runs on PR
+                                              ↓
+                                   PR auto-merges when green
+                                              ↓
+                                 GitHub Release created (v2.x.x)
+                                              ↓
+                               release-tag.yml triggers
+                                              ↓
+                              Gem published to RubyGems.org
+```
+
+### Key Files
 
-The `release-tag.yml` workflow triggers on tag push and will:
-1. Run tests
-2. Build gem
-3. Publish to RubyGems.org (via OIDC trusted publishing)
-4. Create GitHub release
+| File | Purpose |
+|------|---------|
+| `lib/train-k8s-container/version.rb` | VERSION constant (updated by release-please) |
+| `release-please-config.json` | Release-please configuration |
+| `.release-please-manifest.json` | Current version tracking |
+| `.github/workflows/release-please.yml` | Creates PRs with auto-merge |
+| `.github/workflows/release-tag.yml` | Publishes gem on release |

data/README.md

@@ -2,6 +2,7 @@
 
 A Train transport plugin that enables Chef InSpec and Cinc Auditor to execute compliance checks against containers running in Kubernetes clusters via kubectl exec.
 
+[![Gem Version](https://badge.fury.io/rb/train-k8s-container-mitre.svg)](https://badge.fury.io/rb/train-k8s-container-mitre)
 [![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)
 
@@ -29,7 +30,7 @@ This plugin allows InSpec/Cinc Auditor to scan containers running in Kubernetes
 **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.
 
 ```bash
-# Using Cinc Auditor (recommended - open source, license-free)
+# Using Cinc Auditor (open source, license-free)
 cinc-auditor plugin install train-k8s-container-mitre
 
 # Or using Chef InSpec
@@ -204,6 +205,18 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 4. Run `bundle exec rspec && bundle exec rake style`
 5. Submit a pull request
 
+### Versioning
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/) for automated releases:
+
+| Commit Prefix | Version Bump | Example |
+|---------------|--------------|---------|
+| `feat:` | Minor (2.1.0) | New features |
+| `fix:` | Patch (2.0.1) | Bug fixes |
+| `feat!:` | Major (3.0.0) | Breaking changes |
+
+See [CONTRIBUTING.md](CONTRIBUTING.md#versioning-and-commit-messages) for full details.
+
 ## Security
 
 See [SECURITY.md](SECURITY.md) for security policy and reporting vulnerabilities.
@@ -224,13 +237,12 @@ This project is maintained by the MITRE SAF (Security Automation Framework) team
 
 ## Acknowledgments
 
-This project is a fork of [inspec/train-k8s-container](https://github.com/inspec/train-k8s-container), significantly enhanced with:
+This project is a fork of [inspec/train-k8s-container](https://github.com/inspec/train-k8s-container), 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
+- Automated releases via release-please
 
 ---
 

data/lib/train-k8s-container/version.rb

@@ -2,6 +2,6 @@
 
 module TrainPlugins
   module K8sContainer
-    VERSION = '2.0.3'
+    VERSION = '2.1.1'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: train-k8s-container-mitre
 version: !ruby/object:Gem::Version
-  version: 2.0.3
+  version: 2.1.1
 platform: ruby
 authors:
 - MITRE SAF Team
@@ -49,6 +49,7 @@ files:
 - ".release-please-manifest.json"
 - ".rspec"
 - ".rubocop.yml"
+- ARCHITECTURE.md
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md