mirror of
https://github.com/inspec/inspec
synced 2024-11-30 08:30:39 +00:00
fefa6c2ecd
This PR adds 5 closely related plugin types, which allow a plugin to implement new DSL methods / keywords. The mechanism to activate the plugins are all very similar - basically, in a particular location in the code, `method_missing` is implemented, and is used to activate the particular type of DSL being requested. 4 of the DSL plugin types relate to code that could appear in a profile control file. * outer_profile_dsl plugins allow you to extend the code in profile Ruby files that appear outside `control` or `describe` blocks. * control_dsl plugins allow you to extend the code within `control` blocks. * describe_dsl plugins allow you to extend the code within `describe` blocks. * test_dsl plugins allow you to extend the code within `it`/`its` blocks. Finally, the `resource_dsl` plugin allows you to extend the code used within custom resources. Basic unit tests are provided to prove that the plugin types are properly defined. A simple plugin fixture defining DSL hooks (based on favorite foods) is included, and is exercised through a set of functional tests. The plugin developer docs are updated to describe the 5 DSLs. *Note*: Implementing a plugin using any of the DSL plugin types is experimental. The contexts that are exposed to the DSL methods are private and poorly documented. The InSpec project does not claim the APIs used by these plugin types are covered by SemVer. Plugin authors are encouraged to pin tightly to the `inspec` gem in their gemspecs. Motivation for this plugin comes from the desire to allow passionate community members to implement things like "2 out of 3" tests, example groups, improved serverspec compatibility, "they/their" and other "fluency" changes, as well as make it possible for future work by the InSpec team to be implemented as a core plugin, rather than a direct change to the main codebase.
58 lines
2.4 KiB
Markdown
58 lines
2.4 KiB
Markdown
---
|
|
title: About InSpec and Train Plugins
|
|
---
|
|
|
|
# InSpec and Train Plugins
|
|
|
|
## What are InSpec Plugins?
|
|
|
|
InSpec Plugins are optional software components that extend the capabilities of InSpec. For example, [`inspec-iggy`](https://github.com/inspec/inspec-iggy) is a Plugin project that aims to generate InSpec controls from infrastructure-as-code files. Plugins are distributed as RubyGems, and InSpec manages their installation. InSpec Plugins always begin with the prefix 'inspec-'.
|
|
|
|
## What are Train Plugins?
|
|
|
|
Train Plugins allow InSpec to speak to new kinds of targets (typically new remote targets or APIs, but you could treat the local system in a new way if you wished to). For example, if you wanted to audit a Kubernetes cluster, you might want a transport that can talk to the supervisor API. You would develop a Train Plugin for that, and install it using the InSpec command line. Train Plugins always begin with the prefix 'train-'.
|
|
|
|
## What can plugins do?
|
|
|
|
Currently, each plugin can offer one or more of these capabilities:
|
|
|
|
* define a new command-line-interface (CLI) command suite (`inspec` plugins)
|
|
* connectivity to new types of hosts or cloud providers (`train` plugins)
|
|
* DSL extensions at the file, control, describe block, or test level
|
|
* DSL extensions for custom resources
|
|
|
|
Future work might include new capability types, such as:
|
|
|
|
* reporters (output generators)
|
|
* attribute fetchers to allow reading InSpec attributes from new sources (for example, a remote encrypted key-value store)
|
|
|
|
## How do I find out which plugins are available?
|
|
|
|
The InSpec CLI can tell you which plugins are available:
|
|
|
|
```bash
|
|
$ inspec plugin search inspec-
|
|
```
|
|
|
|
## How do I install and manage plugins?
|
|
|
|
The InSpec command line now offers a new subcommand just for managing plugins.
|
|
|
|
You can install a plugin by running:
|
|
|
|
```bash
|
|
$ inspec plugin install inspec-some-plugin
|
|
$ inspec plugin install train-some-plugin
|
|
```
|
|
|
|
For more details on what the `plugin` command can do, see the [online help](https://www.inspec.io/docs/reference/cli/#plugin), or run `inspec plugin help`.
|
|
|
|
## How do I write a plugin?
|
|
|
|
### InSpec Plugins
|
|
|
|
For details on how to author an InSpec Plugin, see the [developer documentation](https://github.com/inspec/inspec/blob/master/docs/dev/plugins.md)
|
|
|
|
### Train Plugins
|
|
|
|
For details on how to author a Train Plugin, see the [developer documentation](https://github.com/inspec/train/blob/master/docs/plugins.md)
|