Register plug-in as Packer integration (#153)

Co-authored-by: BrandonRomano <[email protected]> Co-authored-by: Lucas Bajolet <[email protected]> Co-authored-by: Tim Smith <[email protected]>
mondoohq · Jan 12, 2024 · 2995a24 · 2995a24
1 parent 3105bc6
commit 2995a24
Show file tree

Hide file tree

Showing 12 changed files with 604 additions and 10 deletions.
diff --git a/.github/workflows/ensure-docs-compiled.yaml b/.github/workflows/ensure-docs-compiled.yaml
@@ -0,0 +1,24 @@
+name: Ensure Docs are Compiled
+on:
+  push:
+jobs:
+  ensure-docs-compiled:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛎
+        uses: actions/checkout@v2
+      - uses: actions/setup-go@v4
+        with:
+          go-version: '1.21.x'
+      - shell: bash
+        run: make build-docs
+      - shell: bash
+        run: |
+          if [[ -z "$(git status -s)" ]]; then
+            echo "OK"
+          else
+            echo "Docs have been updated, but the compiled docs have not been committed."
+            echo "Run 'make build-docs', and commit the result to resolve this error."
+            exit 1
+          fi
+
diff --git a/.github/workflows/notify-integration-release-via-manual.yaml b/.github/workflows/notify-integration-release-via-manual.yaml
@@ -0,0 +1,50 @@
+# Manual release workflow is used for deploying documentation updates
+# on the specified branch without making an official plugin release. 
+name: Notify Integration Release (Manual)
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "The release version (semver)"
+        default: 1.0.0
+        required: false
+      branch:
+        description: "A branch or SHA"
+        default: 'main'
+        required: false
+jobs:
+  notify-release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout this repo
+        uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2
+        with:
+          ref: ${{ github.event.inputs.branch }}
+      # Ensure that Docs are Compiled
+      - uses: actions/setup-go@93397bea11091df50f3d7e59dc26a7711a8bcfbe # v4.1.0
+      - shell: bash
+        run: make generate
+      - shell: bash
+        run: |
+          if [[ -z "$(git status -s)" ]]; then
+            echo "OK"
+          else
+            echo "Docs have been updated, but the compiled docs have not been committed."
+            echo "Run 'make generate', and commit the result to resolve this error."
+            exit 1
+          fi
+      # Perform the Release
+      - name: Checkout integration-release-action
+        uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2
+        with:
+          repository: hashicorp/integration-release-action
+          path: ./integration-release-action
+      - name: Notify Release
+        uses: ./integration-release-action
+        with:
+          # The integration identifier will be used by the Packer team to register the integration
+          # the expected format is packer/<GitHub Org Name>/<plugin-name>
+          integration_identifier: "packer/mondoohq/cnspec"
+          release_version: ${{ github.event.inputs.version }}
+          release_sha: ${{ github.event.inputs.branch }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/notify-integration-release-via-tag.yaml b/.github/workflows/notify-integration-release-via-tag.yaml
@@ -0,0 +1,54 @@
+name: Notify Integration Release (Tag)
+on:
+  push:
+    tags:
+      - '*.*.*'   # Proper releases
+jobs:
+  strip-version:
+    runs-on: ubuntu-latest
+    outputs:
+      packer-version: ${{ steps.strip.outputs.packer-version }}
+    steps:
+      - name: Strip leading v from version tag
+        id: strip
+        env:
+          REF: ${{ github.ref_name }}
+        run: |
+          echo "packer-version=$(echo "$REF" | sed -E 's/v?([0-9]+\.[0-9]+\.[0-9]+)/\1/')" >> "$GITHUB_OUTPUT"
+  notify-release:
+    needs:
+      - strip-version
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout this repo
+        uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2
+        with:
+          ref: ${{ github.ref }}
+      # Ensure that Docs are Compiled
+      - uses: actions/setup-go@93397bea11091df50f3d7e59dc26a7711a8bcfbe # v4.1.0
+      - shell: bash
+        run: make generate
+      - shell: bash
+        run: |
+          if [[ -z "$(git status -s)" ]]; then
+            echo "OK"
+          else
+            echo "Docs have been updated, but the compiled docs have not been committed."
+            echo "Run 'make generate', and commit the result to resolve this error."
+            exit 1
+          fi
+      # Perform the Release
+      - name: Checkout integration-release-action
+        uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2
+        with:
+          repository: hashicorp/integration-release-action
+          path: ./integration-release-action
+      - name: Notify Release
+        uses: ./integration-release-action
+        with:
+          # The integration identifier will be used by the Packer team to register the integration
+          # the expected format is packer/<GitHub Org Name>/<plugin-name>
+          integration_identifier: "packer/mondoohq/cnspec"
+          release_version: ${{ needs.strip-version.outputs.packer-version }}
+          release_sha: ${{ github.ref }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.web-docs/README.md b/.web-docs/README.md
@@ -0,0 +1,45 @@
+Packer plugin [cnspec](https://github.com/mondoohq/cnspec) by [Mondoo](https://mondoo.com) scans Linux and Windows [HashiCorp Packer](https://www.packer.io) builds for vulnerabilities and security misconfigurations. The plugin retrieves CVE data from Mondoo, which is updated daily with the latest CVEs and advisories. Additionally, cnspec runs security scans using [cnspec-policies](https://github.com/mondoohq/cnspec-policies) to uncover common misconfigurations that open your hosts to the risk of attack. cnspec supports scanning of Linux, Windows, and macOS, as well as Docker containers.
+
+Packer plugin cnspec is designed to work in one of two modes:
+
+- **Unregistered** - In unregistered mode, the plugin works without being registered to Mondoo Platform, and is designed to provide baseline security scanning with minimal configuration. The plugin runs either the [Linux Security by Mondoo](https://github.com/mondoohq/cnspec-policies/blob/main/core/mondoo-linux-security.mql.yaml) policy on Linux builds, or the [Windows Security by Mondoo](https://github.com/mondoohq/cnspec-policies/blob/main/core/mondoo-windows-security.mql.yaml) policy on Windows builds. Each of these policies provides security hardening checks based off of industry standards for Linux and Windows. Scan results are shown in STDOUT during the Packer run.
+- **Registered** - In registered mode, the plugin is registered to your account in Mondoo Platform using a service account. Registered mode allows you to configure and customize any of the policies in Mondoo Platform including CIS benchmarks and more. Scan results are shown in STDOUT and sent back to Mondoo Platform for your records.
+
+### Installation
+
+To install this plugin, copy and paste this code into your Packer configuration, then run [`packer init`](https://www.packer.io/docs/commands/init).
+
+```hcl
+packer {
+  required_plugins {
+    cnspec = {
+      version = ">= 9.0.0"
+      source  = "github.com/mondoohq/cnspec"
+    }
+  }
+}
+```
+
+Alternatively, you can use `packer plugins install` to manage installation of this plugin.
+
+```sh
+$ packer plugins install github.com/mondoohq/cnspec
+```
+
+### Components
+
+#### Provisioners
+
+- [cnspec](/packer/integrations/mondoohq/cnspec/latest/components/provisioner/cnspec) - Packer plugin [cnspec](https://github.com/mondoohq/cnspec) by [Mondoo](https://mondoo.com) scans 
+Linux and Windows machine images for vulnerabilities and security misconfigurations. The plugin retrieves CVE data from Mondoo, which is updated daily with the latest CVEs and advisories. Additionally, cnspec runs security scans using [cnspec-policies](https://github.com/mondoohq/cnspec-policies) to uncover common misconfigurations that open your hosts to the risk of attack. 
+- [mondoo](/packer/integrations/mondoohq/cnspec/latest/components/provisioner/mondoo) - The `mondoo` provisioner scans [Packer](https://www.packer.io) builds for vulnerabilities and misconfigurations by executing security
+policies-as-code enabled in [Mondoo Platform](https://console.mondoo.com). Mondoo Platform comes stocked with an ever-increasing collection of
+certified security policies which can be easily customize to meet your needs.
+
+### Tutorials
+
+Check out the Packer tutorials on the Mondoo documentation site:
+
+- [Building secure AMIs with Mondoo and Packer](https://mondoo.com/docs/cnspec/cnspec-aws/cnspec-aws-packer/)
+- [Building secure VM images in Google Cloud with cnspec and HashiCorp Packer](https://mondoo.com/docs/cnspec/cnspec-gcp/cnspec-gcp-packer/)
+
diff --git a/.web-docs/components/provisioner/cnspec/README.md b/.web-docs/components/provisioner/cnspec/README.md
@@ -0,0 +1,110 @@
+Type: `cnspec`
+
+Packer plugin [cnspec](https://github.com/mondoohq/cnspec) by [Mondoo](https://mondoo.com) scans Linux and Windows machine images for vulnerabilities and security misconfigurations. The plugin retrieves CVE data from Mondoo, which is updated daily with the latest CVEs and advisories. Additionally, cnspec runs security scans using [cnspec-policies](https://github.com/mondoohq/cnspec-policies) to uncover common misconfigurations that open your hosts to the risk of attack. 
+
+## Basic Example
+```hcl
+provisioner "cnspec" {
+  on_failure          = "continue"
+  score_threshold     = 85
+  sudo {
+    active = true
+  }
+}
+```
+
+## Configuration Reference
+
+Optional Parameters:
+<!-- Code generated from the comments of the Config struct in provisioner/provisioner.go; DO NOT EDIT MANUALLY -->
+
+- `host_alias` (string) - The alias by which the host should be known.
+  Defaults to `default`.
+
+- `user` (string) - The `user` set for your communicator. Defaults to the `user` set
+  by packer.
+
+- `local_port` (uint) - The port on which to attempt to listen for SSH
+   connections. This value is a starting point. The provisioner will attempt
+   listen for SSH connections on the first available of ten ports, starting at
+   `local_port`. A system-chosen port is used when `local_port` is missing or
+   empty.
+
+- `ssh_host_key_file` (string) - The SSH key that will be used to run the SSH
+   server on the host machine to forward commands to the target machine.
+   packer connects to this server and will validate the identity of the
+   server using the system known_hosts. The default behavior is to generate
+   and use a onetime key.
+
+- `ssh_authorized_key_file` (string) - The SSH public key of the packer `ssh_user`.
+  The default behavior is to generate and use a onetime key.
+
+- `use_sftp` (bool) - packer's SFTP proxy is not reliable on some unix/linux systems,
+  therefore we recommend to use scp as default for packer proxy
+
+- `debug` (bool) - Sets the log level to `DEBUG`
+
+- `asset_name` (string) - The asset name passed to Mondoo Platform. Defaults to the hostname
+  of the instance.
+
+- `on_failure` (string) - Configure behavior whether packer should fail if `scan_threshold` is
+  not met. If `scan_threshold` configuration is omitted, the threshold
+  is set to `0` and builds will pass regardless of what score is
+  returned.
+  If `score_threshold` is set to a value, and `on_failure = "continue"`
+  builds will continue regardless of what score is returned.
+
+- `labels` (map[string]string) - Configure an optional map of labels for the asset data in Mondoo Platform.
+
+- `annotations` (map[string]string) - Configure an optional map of `key/val` annotations for the asset data in
+  Mondoo Platform.
+
+- `incognito` (bool) - Configures incognito mode. Defaults to `true`. When set to false, scan results
+  will not be sent to Mondoo Platform.
+
+- `policies` ([]string) - A list of policies to be executed (requires incognito mode).
+
+- `policybundle` (string) - A path to local policy bundle file.
+
+- `sudo` (\*SudoConfig) - Run mondoo scan with `--sudo`. Defaults to none.
+
+- `winrm_user` (string) - Configure WinRM user. Defaults to `user` set by the packer communicator.
+
+- `winrm_password` (string) - Configure WinRM user password. Defaults to `password` set by the packer communicator.
+
+- `use_proxy` (bool) - Use proxy to connect to host to scan. This configuration will fall-back to packer proxy
+  for cases where the provisioner cannot access the target directly
+  NOTE: we have seen cases with the vsphere builder
+
+- `output` (string) - Set output format: summary, full, yaml, json, csv, compact, report, junit (default "compact")
+
+- `score_threshold` (int) - An integer value to set the `score_threshold` of mondoo scans. Defaults to `0` which results in
+  a passing score regardless of what scan results are returned.
+
+- `mondoo_config_path` (string) - The path to the Mondoo client config. Defaults to `$HOME/.config/mondoo/mondoo.yml`
+
+<!-- End of code generated from the comments of the Config struct in provisioner/provisioner.go; -->
+
+
+### SudoConfig
+<!-- Code generated from the comments of the SudoConfig struct in provisioner/provisioner.go; DO NOT EDIT MANUALLY -->
+
+- `active` (bool) - Active
+
+<!-- End of code generated from the comments of the SudoConfig struct in provisioner/provisioner.go; -->
+
+
+## Get Started with cnspec
+
+If you are new to cnspec, check out [Get started with cnspec](https://mondoo.com/docs/cnspec/).
+
+## Packer plugin cnspec tutorial
+
+Check out the Packer tutorials on the Mondoo documentation site:
+
+- [Building secure AMIs with Mondoo and Packer](https://mondoo.com/docs/cnspec/cnspec-aws/cnspec-aws-packer/) 
+- [Building secure VM images in Google Cloud with cnspec and HashiCorp Packer](https://mondoo.com/docs/cnspec/cnspec-gcp/cnspec-gcp-packer/) 
+
+## Sample Packer Templates
+
+You can find example Packer templates in the [examples](https://github.com/mondoohq/packer-plugin-cnspec/tree/main/examples) directory in this repository.