cem_acpt 0.10.10 → 0.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b957ec32b61b81b89e9fdf3961a0dcdf80030835434a6a9be34c9d57c94e761f
-  data.tar.gz: f73b5bff3f0cbedeca09bc50b607a368a9e4f9bb31dfedde2377782ef73d23e5
+  metadata.gz: df61aa1c290a076e460b4c790babb19d0e0729e7d543feb96a9fb40e1589e50a
+  data.tar.gz: 800a652e59491e42f0e3fdd43db93e397956309e2b575d33e0f2c1497ebd8311
 SHA512:
-  metadata.gz: 60a7e8efb5e618f05bee99a9ce88db85ccc98e5b35ed35272ee8dae0ff8824ef8c83470e854e4d1ccccac65453a37e58bc29da57dbc61e357176f7dd4dd45e38
-  data.tar.gz: fd4c65392b90be5d35194ba990d8ada0f222721382a4fd6ee40b2f3c346f1f475dedbb9896495e70a2b2e07dcfa7890a3535c5fc34b5ea5c369b256cb65d06a2
+  metadata.gz: a4a93419e474a066291ead08cbb28222f635f218b3df394b92f8c23d2fc1d63d55b9c5e240229c86db22a7b98e0e8673a5f13c7d02bd0d3633976942cc22be08
+  data.tar.gz: 614ecdad289b17a01ffcaea724aa928372cf578a4270f641e592549a6f2d017235646fe5ab8b3274e23801755935b6d7e17cdd39072aee28cbc7692b86e5b663

data/.gitignore

@@ -16,3 +16,11 @@ profile.txt
 
 # local dev
 run_script.rb
+
+# Ignore .env files which may contain sensitive information
+.env
+.env.*.local
+
+# Local Claude configuration
+.claude/settings.local.json
+.claude/worktrees/

data/.worktreeinclude

@@ -0,0 +1 @@
+.env

data/CLAUDE.md

@@ -0,0 +1,126 @@
+# CLAUDE.md
+
+## What This Project Is
+
+`cem_acpt` is a Ruby gem providing an acceptance testing CLI for Puppet SCE (Security Compliance Enforcement, formerly Puppet CEM / Compliance Enforcement Modules). It provisions cloud nodes via Terraform, applies a Puppet manifest, runs infrastructure tests via Goss (and optionally Bolt task/plan tests), then tears everything down. Both Linux nodes (over SSH) and Windows nodes (over WinRM) are supported.
+
+A second binary, `cem_acpt_image`, builds the base VM images used by the test runner.
+
+The gem name is intentionally unchanged after the CEM → SCE rename. The consuming Puppet modules were renamed to `sce_linux` / `sce_windows`, but this gem stays `cem_acpt`.
+
+## Where to Read More
+
+Before diving into the summary below, skim:
+- `docs/ARCHITECTURE.md` — fuller architecture writeup
+- `docs/rfcs/` — design decisions (Windows image builder, OS dispatch, platform namespacing, logging behavior, etc.). Check here before proposing structural changes.
+
+## Commands
+
+```bash
+bundle install          # Install dependencies
+
+bundle exec rake spec                                  # Run all spec tests
+bundle exec rake spec SPEC=spec/path/to/file_spec.rb   # Run a single spec file
+
+rubocop                 # Lint
+rubocop -a              # Auto-fix lint issues
+
+bundle exec rake build                           # Build the gem (saves to pkg/cem_acpt-<semver>.gem)
+bundle exec gem install pkg/cem_acpt-X.X.X.gem   # Install built gem
+
+bundle exec exe/cem_acpt -h       # CLI help
+bundle exec exe/cem_acpt -Y       # Print merged config as YAML
+bundle exec exe/cem_acpt -X       # Explain config merge sources
+```
+
+CI runs `bundle exec rake spec` on PRs against `main` (see `.github/workflows/spec.yml`). Lint is not currently gated in CI, but RuboCop should be clean before merging.
+
+RuboCop targets Ruby 3.2 with a 200-char line limit. The config in `.rubocop.yml` is intentionally permissive — many cops (complexity, layout, style) are disabled. Check `.rubocop.yml` before assuming a rule is enforced.
+
+## Architecture
+
+### Entry Points
+
+- `exe/cem_acpt` and `exe/cem_acpt_image` both call into `CemAcpt.run` in `lib/cem_acpt.rb`, which dispatches on the command:
+  - `:cem_acpt` → `TestRunner::Runner`
+  - `:cem_acpt_image` → `ImageBuilder::TerraformBuilder`
+  - `:print_yaml_config` / `:print_explain_config` → handle the `-Y` / `-X` debugging flags
+  - `:version` → prints gem version
+- CLI parsing lives in `lib/cem_acpt/cli.rb` (Ruby `OptionParser`).
+
+### Configuration System (`lib/cem_acpt/config/`)
+
+Config is built by merging four sources, with each later source overriding earlier ones:
+
+1. Environment variables (`CEM_ACPT_` prefix; nested keys use `__`)
+2. User config at `~/.cem_acpt/config.yaml`
+3. `--config FILE` option
+4. Other CLI flags
+
+`Config::Base` handles the merge via `deep_merge`. `Config::CemAcpt` and `Config::CemAcptImage` define the schema for each command. Use `-Y` to print the merged result and `-X` to see which source contributed each value.
+
+### Test Runner Lifecycle (`lib/cem_acpt/test_runner.rb`)
+
+1. **Pre-provision** — Build the Puppet module tarball (`Utils::Puppet`).
+2. **Provision** — Spin up nodes via the configured platform (currently only GCP) using Terraform (`Provision::Terraform`), generate ephemeral SSH keys (or set up WinRM for Windows), and install the module.
+3. **Execute** — Run action groups: `:goss` (async, HTTP) and `:bolt` (sync, Puppet tasks). Filter with `--only-actions` / `--except-actions`.
+4. **Cleanup** — `terraform destroy` unless `--no-destroy-nodes`.
+
+### Platform Abstraction (`lib/cem_acpt/platform/`)
+
+`Platform::Base` defines the interface; `Platform::TestBase` extends it for test-node platforms. `Platform::Gcp` is the only concrete implementation today, but platforms are loaded dynamically by name from config — so adding e.g. AWS means a new file here plus a Terraform tree under `lib/terraform/`.
+
+### Actions (`lib/cem_acpt/actions.rb`)
+
+The `Actions` class orchestrates test execution. Actions register themselves via `register_action`/`register_group` and run in `order` order. Goss actions run asynchronously via `async-http`; Bolt actions run synchronously.
+
+### Transports
+
+- **SSH** (`lib/cem_acpt/utils/ssh.rb`) — Linux nodes
+- **WinRM** (`lib/cem_acpt/utils/winrm_runner.rb`) — Windows nodes
+- **Goss HTTP API** (`lib/cem_acpt/goss/api.rb`) — assertions, on a port exposed by the provisioned node
+
+### Terraform Templates (`lib/terraform/`)
+
+Terraform HCL ships inside the gem:
+- `lib/terraform/gcp/linux/` and `lib/terraform/gcp/windows/` — test-node provisioning
+- `lib/terraform/image/gcp/linux/` and `lib/terraform/image/gcp/windows/` — image-building provisioning
+
+### Logging (`lib/cem_acpt/logging/`)
+
+Supports simultaneous STDOUT + file logging. `-I` / `--CI` enables GitHub Actions–formatted output. `--trace` enables Ruby `TracePoint` debugging. Most subsystems include `CemAcpt::Logging` to get a `logger` method.
+
+## Where to Add Things
+
+| Adding…                       | Touch                                                                                          |
+| ----------------------------- | ---------------------------------------------------------------------------------------------- |
+| A new platform (e.g. AWS)     | `lib/cem_acpt/platform/<name>.rb` (subclass `Platform::TestBase`) + `lib/terraform/<name>/...` |
+| A new action group            | Register in `lib/cem_acpt/actions.rb`; add a subdir under `lib/cem_acpt/<group>/`              |
+| A new config option           | Add to `lib/cem_acpt/config/cem_acpt.rb` (or `cem_acpt_image.rb`) and wire into `cli.rb`       |
+| A new Bolt helper             | `lib/cem_acpt/bolt/` — see `inventory.rb`, `tasks.rb`, `tests.rb` for the existing pattern     |
+| A new utility (SSH/WinRM/etc) | `lib/cem_acpt/utils/`                                                                          |
+
+## Test Structure
+
+### Unit tests (this repo)
+
+Specs live under `spec/`, mirroring the layout of `lib/`. Fixtures live in `spec/fixtures/`. Run with `bundle exec rake spec`.
+
+### Acceptance tests (consuming module)
+
+Acceptance test cases live in the **consuming module** (e.g. `sce_linux`, `sce_windows`), not in this gem. They follow this layout:
+
+```
+spec/acceptance/<framework>_<os>-<version>_<firewall>_<profile>_<level>/
+  manifest.pp   # Puppet manifest to apply
+  goss.yaml     # Goss assertions
+  bolt.yaml     # (optional) Bolt task assertions
+```
+
+## Conventions
+
+- Document Ruby code with YARD comments.
+- All changes should have tests.
+- Subsystem-specific error classes live alongside the subsystem (e.g. `lib/cem_acpt/bolt/errors.rb`); follow that pattern rather than reusing generic `StandardError`.
+- Use `CemAcpt::Utils::FinalizerQueue` for ordered cleanup of provisioned resources rather than ad-hoc `ensure` blocks.
+- Mix in `CemAcpt::Logging` to get a logger; don't instantiate one directly.

data/Gemfile.lock

@@ -1,10 +1,11 @@
 PATH
   remote: .
   specs:
-    cem_acpt (0.10.10)
+    cem_acpt (0.11.1)
       async-http (>= 0.60, < 0.70)
       bcrypt_pbkdf (>= 1.0, < 2.0)
       deep_merge (>= 1.2, < 2.0)
+      dotenv (>= 3.2, < 4.0)
       ed25519 (>= 1.0, < 2.0)
       puppet-modulebuilder (>= 0.0.1)
       winrm (>= 2.3, < 3.0)
@@ -44,6 +45,7 @@ GEM
     deep_merge (1.2.2)
     diff-lcs (1.6.1)
     docile (1.4.1)
+    dotenv (3.2.0)
     ed25519 (1.3.0)
     erubi (1.13.1)
     ffi (1.17.1)

data/README.md

@@ -16,7 +16,7 @@ gem install cem_acpt
 
 ### Quickstart
 
-Make sure Terraform and the gcloud CLI are installed and in your PATH. Instructions for installing Terraform can be found [here](https://learn.hashicorp.com/tutorials/terraform/install-cli) and instructions for installing the gcloud CLI can be found [here](https://cloud.google.com/sdk/docs/install).Then, navigate to the root of the `cem_linux` module and run the following command:
+Make sure Terraform and the gcloud CLI are installed and in your PATH. Instructions for installing Terraform can be found [here](https://learn.hashicorp.com/tutorials/terraform/install-cli) and instructions for installing the gcloud CLI can be found [here](https://cloud.google.com/sdk/docs/install).Then, navigate to the root of the `sce_linux` module and run the following command:
 
 ```bash
 cem_acpt --config ./cem_acpt_config.yaml
@@ -140,7 +140,7 @@ All Bolt tasks are ran with the `--format json` flag, which returns a JSON docum
 
 Example:
 
-In this example, we will go over how a Bolt task's output would be evaluated by a Bolt test hash. This example assumes one Bolt task named `cem_linux::audit_sssd_certmap` that takes no parameters was ran successfully against two nodes.
+In this example, we will go over how a Bolt task's output would be evaluated by a Bolt test hash. This example assumes one Bolt task named `sce_linux::audit_sssd_certmap` that takes no parameters was ran successfully against two nodes.
 
 Bolt task JSON output:
 
@@ -150,7 +150,7 @@ Bolt task JSON output:
     {
       "target":"35.212.146.14",
       "action":"task",
-      "object":"cem_linux::audit_sssd_certmap",
+      "object":"sce_linux::audit_sssd_certmap",
       "status":"success",
       "value":{
         "sssd_certmap_exists":false
@@ -159,7 +159,7 @@ Bolt task JSON output:
     {
       "target":"35.212.197.53",
       "action":"task",
-      "object":"cem_linux::audit_sssd_certmap",
+      "object":"sce_linux::audit_sssd_certmap",
       "status":"success",
       "value":{
         "sssd_certmap_exists":false
@@ -174,7 +174,7 @@ Bolt task JSON output:
 Bolt test hash in `bolt.yaml`:
 
 ```yaml
-'cem_linux::audit_sssd_certmap':
+'sce_linux::audit_sssd_certmap':
   status: 'success'
   value:
     match: 'false'
@@ -335,6 +335,19 @@ images:
 
 See [sample_config.yaml](sample_config.yaml) for a more complete example.
 
-### Testing with cem_windows
+### Testing with sce_windows
 
-While testing with cem_windows follows pretty much the same outline as cem_linux, there are a few extra step that we have to do when bootstrapping the generated node. Two of the most prominents steps are enabling long path and using NSSM to start the goss service. When we enable long path on Windows, it allows the command `puppet module install` to install dependencies correctly (specifically the dsc modules). As for [NSSM](https://nssm.cc/), stands for Non-sucking service manager, it is necessary for us to use this tool because without it, we will not be able to create services for Goss. Windows services cannot run from an executable but rather through a Windows service project that can be build with Visual Studio. NSSM allows us to bypass having to create Windows service project for Goss and create services directly from the Goss executable.
+While testing with sce_windows follows pretty much the same outline as sce_linux, there are a few extra step that we have to do when bootstrapping the generated node. Two of the most prominents steps are enabling long path and using NSSM to start the goss service. When we enable long path on Windows, it allows the command `puppet module install` to install dependencies correctly (specifically the dsc modules). As for [NSSM](https://nssm.cc/), stands for Non-sucking service manager, it is necessary for us to use this tool because without it, we will not be able to create services for Goss. Windows services cannot run from an executable but rather through a Windows service project that can be build with Visual Studio. NSSM allows us to bypass having to create Windows service project for Goss and create services directly from the Goss executable.
+
+#### Configuring the GCS bucket
+
+The Windows test path uploads the Puppet module tarball to a GCS bucket so the test instance can `gcloud storage cp` it back down. The bucket name is configurable via `platform.gcp.windows_bucket` (default: `win_cem_acpt`):
+
+```yaml
+platform:
+  name: gcp
+  gcp:
+    windows_bucket: my-org-cem-acpt
+```
+
+Alternatively, pass `--windows-bucket BUCKET` on the CLI or set `CEM_ACPT_PLATFORM__GCP__WINDOWS_BUCKET` in the environment. The bucket must exist and be writable by the account running `cem_acpt`; it must also be readable by the service account attached to the Windows test instance.

data/cem_acpt.gemspec

@@ -30,6 +30,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'async-http', '>= 0.60', '< 0.70'
   spec.add_runtime_dependency 'bcrypt_pbkdf', '>= 1.0', '< 2.0'
   spec.add_runtime_dependency 'deep_merge', '>= 1.2', '< 2.0'
+  spec.add_runtime_dependency 'dotenv', '>= 3.2', '< 4.0'
   spec.add_runtime_dependency 'ed25519', '>= 1.0', '< 2.0'
   spec.add_runtime_dependency 'puppet-modulebuilder', '>= 0.0.1'
   spec.add_runtime_dependency 'winrm', '>= 2.3', '< 3.0'