Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

🧹 update readme to have better developer instructions #135

Merged
merged 1 commit into from
Oct 18, 2023
Merged

🧹 update readme to have better developer instructions #135

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/actions/spelling/expect.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
tions
pkrvars
pkr
linux
37 changes: 22 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,20 @@ Packer plugin [cnspec](https://github.com/mondoohq/cnspec) by [Mondoo](https://m

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.
- **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.



## 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/)
- [Building secure VM images in Google Cloud with cnspec and HashiCorp Packer](https://mondoo.com/docs/cnspec/cnspec-gcp/cnspec-gcp-packer/)

# Installation

## Using the packer init command

Starting from version 1.7, Packer supports a new `packer init` command allowing automatic installation of Packer plugins. Read the [Packer documentation](https://www.packer.io/docs/commands/init) for more information.

To install this plugin, copy and paste this code into your Packer configuration . Then, run `packer init`.
Expand Down Expand Up @@ -51,17 +50,25 @@ If you prefer to build the plugin from source, clone the GitHub repository local

By using `make dev`, the binary is copied into `~/.packer.d/plugins/` after the build.

## Configuration
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. Comment out the `packer {}` block to force Packer use the development binary installed in the previous step.

To use the developer plugin set the packer plugin environment variable:

| **Name** | **Description** | **Type** | **Default** | **Required** |
|---|---|------------------|-------------|--------------|
| `annotations` | Custom annotations can be applied to Packer build assets to provide additional metadata for asset tracking. | `map of strings` | None | No |
| `asset_name` | Overwrite the asset name in Mondoo Platform. | `string` | None | No |
| `on_failure` | Set `on_failure = "continue"` to ignore build failures that do not meet any set `score_threshold`.| `string` | None | No |
| `score_threshold` | Set a score threshold for Packer builds `[0-100]`. Any scans that fall below the `score_threshold` will fail unless `on_failure = "continue"`. To learn more, read [How Mondoo scores policies](https://mondoo.com/docs/platform/console/monitor/#how-mondoo-scores-policies) in the Mondoo documentation. | `int` | None | No |
| `sudo` | Use sudo to elevate permissions when running Mondoo scans. | `bool` | None | No |
| `mondoo_config_path` | The path to the configuration to be used when running Mondoo scans. | `string` | None | No |
```bash
export PACKER_PLUGIN_PATH=~/.packer.d/plugins
packer build amazon-linux-2.pkr.hcl
```

## Configuration

| **Name** | **Description** | **Type** | **Default** | **Required** |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ----------- | ------------ |
| `annotations` | Custom annotations can be applied to Packer build assets to provide additional metadata for asset tracking. | `map of strings` | None | No |
| `asset_name` | Overwrite the asset name in Mondoo Platform. | `string` | None | No |
| `on_failure` | Set `on_failure = "continue"` to ignore build failures that do not meet any set `score_threshold`. | `string` | None | No |
| `score_threshold` | Set a score threshold for Packer builds `[0-100]`. Any scans that fall below the `score_threshold` will fail unless `on_failure = "continue"`. To learn more, read [How Mondoo scores policies](https://mondoo.com/docs/platform/console/monitor/#how-mondoo-scores-policies) in the Mondoo documentation. | `int` | None | No |
| `sudo` | Use sudo to elevate permissions when running Mondoo scans. | `bool` | None | No |
| `mondoo_config_path` | The path to the configuration to be used when running Mondoo scans. | `string` | None | No |

### Example: Complete Configuration

Expand All @@ -85,10 +92,10 @@ If you want to use cnspec outside of packer, you can [get started](https://mondo

## Contributing

* If you think you've found a bug in the code or you have a question regarding
- If you think you've found a bug in the code or you have a question regarding
the usage of 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 add a feature or a
- Contributions to this project are welcome: if you want to add a feature or a
fix a bug, please do so by opening a Pull Request in this GitHub repository.
In case of feature contribution, we kindly ask you to open an issue to
discuss it beforehand.
Expand Down