Skip to content

Commit

Permalink
🧹 update readme to have better developer instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
@chris-rock
chris-rock committed Oct 18, 2023
1 parent 7883f00 commit 673090d
Showing 1 changed file with 22 additions and 15 deletions.
37 changes: 22 additions & 15 deletions README.md
View file
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=/Users/yourusername/.packer.d/plugins
packer build amazon-linux-2.pkr.hcl

Check failure on line 59 in README.md

View workflow job for this annotation

GitHub Actions / Run spell check 

`linux` is not a recognized word. (unrecognized-spelling)
```

## 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

0 comments on commit 673090d

Please sign in to comment.