https://github.com/mondoohq/packer-plugin-cnspec
Packer plugin cnspec by Mondoo - Build machine images free of security misconfigurations and vulnerabilities!
https://github.com/mondoohq/packer-plugin-cnspec
ami cnspec mondoo packer packer-plugin security vulnerability
Last synced: 28 days ago
JSON representation
Packer plugin cnspec by Mondoo - Build machine images free of security misconfigurations and vulnerabilities!
- Host: GitHub
- URL: https://github.com/mondoohq/packer-plugin-cnspec
- Owner: mondoohq
- License: other
- Created: 2022-06-14T16:58:50.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2026-05-26T09:24:19.000Z (29 days ago)
- Last Synced: 2026-05-26T11:24:46.186Z (29 days ago)
- Topics: ami, cnspec, mondoo, packer, packer-plugin, security, vulnerability
- Language: Go
- Homepage: https://developer.hashicorp.com/packer/integrations/mondoohq/cnspec
- Size: 4.16 MB
- Stars: 27
- Watchers: 8
- Forks: 7
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Packer Plugin for Mondoo cnspec
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 that is updated daily with the latest CVEs and advisories. Additionally, cnspec runs security scans using [cnspec-policies](https://github.com/mondoohq/cnspec/blob/main/content/) to uncover common misconfigurations that open your hosts to the risk of attack. cnspec supports scanning Linux, Windows, and macOS, as well as Docker containers.
## Plugin modes
Packer Plugin cnspec is designed to work in one of two modes:
- **Unregistered** - In unregistered mode, the plugin works without being registered with Mondoo Platform, and is designed to provide baseline security scanning with minimal configuration. On Linux builds, the plugin runs the [Linux Security by Mondoo](https://github.com/mondoohq/cnspec/blob/main/content/mondoo-linux-security.mql.yaml) policy. On Windows builds, the plugin runs the [Windows Security by Mondoo](https://github.com/mondoohq/cnspec/blob/main/content/mondoo-windows-security.mql.yaml) policy. Each of these policies provides security hardening checks based on industry standards for Linux and Windows. Scan results display in STDOUT during the Packer run.
- **Registered** - In registered mode, the plugin is registered with your account in Mondoo Platform using a service account. This 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.
## Configuration Options
The `packer-plugin-cnspec` plugin supports a wide range of configuration options to customize scanning behavior, authentication, output, and policy usage. These options can be set directly in your Packer template or via environment variables where applicable.
### Plugin Configuration Fields
| Field | Type | Description |
| ----------- | ----------- | ----------- |
| `annotations` | `map[string]string` | Key/value annotations to assign to scanned assets. |
| `asset_name` | `string` | Custom asset name to display in Mondoo Platform. Defaults to instance hostname. |
| `debug` | `bool` | Enables debug logging. |
| `host_alias` | `string` | Alias by which the host should be identified in Mondoo Platform. Defaults to `default`. |
| `incognito` | `bool` | Disables sending scan results to Mondoo Platform. Defaults to automatic detection. |
| `labels` | `map[string]string` | Key/value labels to assign to scanned assets. |
| `local_port` | `uint` | Starting port to listen for SSH connections. Defaults to system-assigned port if not set. |
| `mondoo_config_path` | `string` | Path to the Mondoo service account YAML file. Defaults to `$HOME/.config/mondoo/mondoo.yml`. |
| `on_failure` | `string` | Behavior when `risk_threshold` is not met. Options: `continue` or `fail`. Default: `fail`. |
| `output` | `string` | Output format. Options: `compact`, `csv`, `full`, `json`, `junit`, `report`, `summary`, `yaml`. Default: `compact`. |
| `output_target` | `string` | Target path for saving output. Optional. |
| `policies` | `[]string` | List of policy paths or URLs to use instead of defaults. Enables incognito mode. |
| `policybundle` | `string` | Path to a local `.tar.gz` policy bundle. |
| `risk_threshold` | `int` | Integer threshold for scan score. Builds fail if the score is below this value. Default: `100`. |
| `score_threshold` | `int` | **Deprecated:** Use `risk_threshold` instead. |
| `ssh_authorized_key_file` | `string` | Path to public key of SSH user. Defaults to autogenerated one-time key. |
| `ssh_host_key_file` | `string` | Path to SSH key used for forwarding commands. Defaults to autogenerated one-time key. |
| `sudo` | `*SudoConfig` | Runs scan with `--sudo` when applicable. |
| `use_proxy` | `bool` | Use proxy to connect to the host. Falls back to Packer’s communicator proxy if needed. |
| `use_scp` | `bool` | Use SCP instead of SFTP. Not recommended on Windows 2025. Default: false. |
| `use_sftp` | `bool` | (Deprecated) Use SFTP for file transfers. Default: true. |
| `user` | `string` | The user for SSH connection. Defaults to the communicator's configured user. |
| `winrm_password` | `string` | WinRM password for Windows instances. Defaults to communicator’s password. |
| `winrm_user` | `string` | WinRM user for Windows instances. Defaults to communicator’s user. |
### Environment Variables
Some configuration options can also be set using environment variables, especially those related to authentication:
| Environment Variable | Description |
| ----------- | ----------- |
| `MONDOO_CONFIG_PATH` | Path to the Mondoo service account YAML file. Equivalent to `mondoo_config_path`. |
| `MONDOO_CONFIG_BASE64` | Base64-encoded Mondoo service account config. Used in CI/CD environments or inline secrets. |
For more information about Mondoo service accounts, refer to the official documentation:
https://mondoo.com/docs/platform/maintain/access/non-human/service_accounts/
## Tutorials
Check out the Packer tutorials on the Mondoo documentation site:
- [Build Secure AMIs with cnspec and HashiCorp Packer](https://mondoo.com/docs/cnspec/cloud/aws/packer/)
- [Build Secure VM Images in Google Cloud with cnspec and HashiCorp Packer](https://mondoo.com/docs/cnspec/cloud/gcp/packer/)
# Install Packer plugin cnspec
You can install Packer Plugin cnspec using the `packer init` command, install it manually, or build it from source.
## Install using the packer init command
As of version 1.7, Packer's `packer init` command allows automatic installation of Packer plugins. For more information, read the [Packer documentation](https://www.packer.io/docs/commands/init).
To install Packer Plugin cnspec:
1. Copy and paste this code into your Packer configuration.
```hcl
packer {
required_plugins {
cnspec = {
version = "~> 12"
source = "github.com/mondoohq/cnspec"
}
}
}
```
2. Run this command:
```bash
packer init /path/to/template.pkr.hcl
```
### Install manually
You can find pre-built binary releases of the plugin [here](https://github.com/mondoohq/packer-plugin-cnspec/releases).
Once you have downloaded the latest archive corresponding to your target OS, uncompress it to retrieve the plugin binary file corresponding to your platform. To install the plugin, follow the Packer documentation on
[installing a plugin](https://www.packer.io/docs/extending/plugins/#installing-plugins).
### Build from source
If you prefer to build the plugin from source:
1. Clone this GitHub repository locally.
2. Run this command from the root directory: `go build`
3. After you successfully compile, the `packer-plugin-cnspec` plugin binary file is in the root directory. Copy the binary into `~/.packer.d/plugins/` by running this command: `make dev`
4. To install the compiled plugin, follow the Packer documentation on [installing plugins](https://developer.hashicorp.com/packer/docs/plugins/install-plugins).
After building the cnspec plugin successfully, use the latest version of Packer to build a machine and verify your changes. In the [example folder](https://github.com/mondoohq/packer-plugin-cnspec/blob/main/examples) we provide a basic template. To force Packer to use the development binary installed in the previous step, comment out the `packer {}` block.
To use the developer plugin, set the packer plugin environment variable:
```bash
export PACKER_PLUGIN_PATH=~/.packer.d/plugins
packer build amazon-linux-2.pkr.hcl
```
## Configure Packer Plugin cnspec
For detailed instructions on configuring the Packer Plugin cnspec, please visit the official HashiCorp documentation at Packer Plugin cnspec. There you'll find comprehensive guidance on setup and configuration options.
## Sample Packer Templates
You can find example Packer templates in the [examples](/examples/) directory in this repository. You can also find a [GitHub Action workflow example](/examples/github-actions/packer-build-scan.yaml) of how to use cnspec to test builds as part of a CI/CD pipeline.
## Get Started with cnspec
cnspec's benefits extend well beyond securing Packer builds! To start exploring, [download cnspec](https://mondoo.com/docs/cnspec/).
## Contributing
If you think you've found a bug in the code or you have a question about using this software, please reach out to us by opening an issue in this GitHub repository.
Contributions to this project are welcome! If you want to fix a bug, please do so by opening a pull request in this GitHub repository. If you want to add a feature, please start by opening an issue in this GitHub repository to discuss it with us beforehand.
### Join the community!
Join the [Mondoo Community GitHub Discussions](https://github.com/orgs/mondoohq/discussions) to collaborate on policy as code and security automation.