Project: Chef InSpec (Provisioning / Security & Compliance)
File: glossary.md

+++ title = "Chef InSpec Glossary" draft = false gh_repo = "inspec" [menu] [menu.inspec] title = "Chef InSpec Glossary" identifier = "inspec/reference/Chef InSpec Glossary" parent = "inspec/reference" weight = 50 +++ This document should help you become familiar with some of the terminology used by the Chef InSpec project. There are two ways to use it: A . Learn the meaning of a word you have encountered. A . Look at examples and see how the parts are labelled. You can then use the text glossary to read details of each concept. Suppose we are interested in auditing cars. Let's suppose we have two Chef InSpec resources for auditing: `cars`, which searches for and filters groups of cars, and `car`, which performs detailed auditing of a single car. Let's look at some simple examples. ```ruby describe car(owner: 'Tony Clifton') do it { should exist } its('license_plate') { should cmp 'MOONMAN' } it { should be_classy } it { shouldnot havecheckenginelight_on } end ``` car is a . Since we are talking about only one car, it is a . owner is a and 'Tony Clifton' is a resource parameter value. Each line within the resource block beginning with `it` or `its` is a . Use to access , and use to access of the , which are in turn used with . license\plate_ is a belonging to the . Properties expose testable information about the resource. Some properties are numbers, some (like this one) are text, some are lists, and some are more complex objects. Properties are always used with . cmp is a . `cmp` is a very flexible, loosely typed equality operator; here it checks to see if the license plate text is the same as the text 'MOONMAN'. Notice that the test operates on the license plate text (the property value) and not on the resource. You can find the full list of supported universal matchers on the . 'MOONMAN' is an . Some matchers take an expected result; others do not. be\classy_ is a . It returns a yes-or-no value, based on whether Tony's car is classy or not. (It is. Tony is a classy guy.) should\not_ indicates this is a negated test. So, this test passes if the matcher says "no". ```ruby describe cars.where(color: /^b/) do it { should exist } its('manufacturers') { should include 'Cadillac' } its('count') { should be >= 10 } end ``` cars is a . Since we are potentially talking about many cars, it is a . where(color: /^b/) is a . Without a filter statement, `cars` simply selects all the cars in the world. color is a along with its filter value, /^b/. Here, the criterion expresses that we want to select all cars whose colors begin with the letter 'b' - blue, brown, burgundy, etc. Each line within the resource block beginning with `it` or `its` is a . Use to access , and use to access of the , which are in turn used with . With plural resources, `exist` has a special meaning: did the filter match anything? manufacturers is a of the . Properties expose testable information about the

On plural resources, properties are almost always names in the plural, and almost always return a list of values. Here, the test returns a list of the car manufacturer names. Some list properties are de-duplicated; for example, you might have 10 cars, but if they are all Subarus and Cadillacs, it returns only two entries in the `manufacturers` property. Be sure to check the documentation for your resource. include is a . `include` works with lists, and checks to see if an expected result is present. Here, it checks to see if the list of manufacturers contains an entry with the text 'Cadillac'. Notice it operates on the manufacturers list (the property value) and not on the resource. You can find the full list of supported universal matchers on the . 'Cadillac' is an . Some matchers take an expected result; others do not. be >= is an . It allows you to perform numeric comparisons. All plural resources have a `count` property. Deprecated name for . The `control` keyword is used to declare a `control block`. Here, the word 'control' means a 'regulatory control, recommendation, or requirement' - not a software engineering construct. A `control block` has a name (which usually refers to the assigned ID of the regulatory recommendation it implements), metadata such as descriptions, references, and tags, and finally groups together related to implement the checks. A that is included with InSpec; you are not required to install additional or depend on a to use the resource. A that is not included with InSpec. It may be a resource of your own creation, or one you obtain by depending on a . The `describe` keyword is used with a `describe block` to refer to a Chef InSpec resource. You use the `describe` keyword along with the name of a to enclose related that apply to the resource. Multiple describe blocks are usually grouped together in a , but you can also use them outside of a control. ```ruby control 'Rule 1.1 - Color restrictions' do describe cars.where(color: 'blue') do its('count') { should eq 20 } end end ``` DSL is an acronym for Domain Specific Language. It refers to the language extensions Chef InSpec provides to make authoring resources and controls easier. While Chef InSpec control files are use Ruby, the Control DSL makes it easy to write controls without knowledge of Ruby by providing DSL keywords such as , , and . See the for details about keywords available to control authors. For authors, an additional DSL is available - see the . When using a , the `expected result` is the value the matcher will compare against the being accessed. In this example, the matcher is being used to compare the `color` property to the expected result 'black'. ```ruby describe car(owner: 'Bruce Wayne') do its('color') { should cmp 'black' } end ``` When using a , a `filter statement` is used to select individual test subjects using . A filter statement almost always is indicated by the keyword `where`, and may be repeated using method

A filter statement may use method call syntax (which allows basic criteria operations, such as equality, regex matching, and Ruby `===` comparison) or block syntax (which allows arbitrary code). In this example, `where(...)` is the filter statement. ```ruby describe cars.where(color: 'blue') do its('count') { should eq 20 } end ``` When using a , a `filter criterion` is used to select individual test subjects within a . You may use multiple `filter criteria` in a single filter statement. When method-call syntax is used with the filter statement, you provide filter criteria as a Hash, with filter criteria names as keys, and conditions as the Hash values. You may provide test, true/false, or numbers, in which case the comparison is equality; or you may provide a regular expression, in which case a match is performed. Here, `(color: blue)` is a single filter criterion being used with a filter statement in method-call syntax. ```ruby describe cars.where(color: 'blue') do its('count') { should eq 20 } end ``` When block-method syntax is used with the filter statement, you provide a block. The block may contain arbitrary code, and each filter criteria will be available as an accessor. The block will be evaluated once per row, and each block that evaluates to a truthy value will pass the filter. Here, `{ engine_cylinders >= 6 }` is a block-syntax filter statement referring to one filter criterion. ```ruby describe cars.where { engine_cylinders >= 6 } do its('citympgratings') { should_not include '4-star' } end ``` An `input` is a value that Chef InSpec can source from a number of providers, including from the command line, profile metadata, or within the control file DSL itself. You can use this feature either to change a behavior by passing different attribute files or to store secrets that should not be directly present in a profile. Inputs were formerly known as `attributes`. Chef InSpec inputs are unrelated to Chef Infra attributes. The CLI syntax for inputs is documented under the command. Inputs are documented in detail in the . Within a , `it` declares an individual directly against the (as opposed to testing against one of the resource's , as does). Though it is possible to use with `it`, it is much more typical to use . `it` may be used with `should`, or negated using `should_not`. Here, `it { should ... }` declares a test, calling the `classy?` matcher on Tony Clifton's car. ```ruby describe car(owner: 'Tony Clifton') do it { should be_classy } end ``` Within a , `its` declares an individual against a property of the (as opposed to testing directly against the resource itself, as does). You must use with `its`; you cannot use . `its` may be used with `should`, or negated using `should_not`. The property to access is passed as a single string argument to `its`. As an advanced usage, if the property has methods you are interested in, you can call them using '`.`' within the string; even more advanced calling patterns are possible - see . Here, `its('fuzzydice') { should ... }` declares a test, testing against the `fuzzydice` property of Tony Clifton's car. Let's assume - Tony being Tony - that `fuzzy_dice` will return an Array. ```ruby describe car(owner: 'Tony Clifton') do its('fuzzydice') { shouldnot be_empty } its('fuzzy_dice.count') { should be >= 2 }

{ should cmp 'outlandishly so' } end ``` A `matcher` performs the actual assertions against or the of resources. Matchers always return a true/false value. Matchers fall into two camps: , which operate directly on the resource, are used with , and tend to be highly customized to the auditing needs of the resource , which operate on the properties of the resource, are used with , and tend to be very generic, operating on text, numbers, and lists Some matchers accept parameters, called . For information on how RSpec matchers are related o Chef InSpec matchers, see . Here, `be_classy` is a resource-specific matcher operating directly on the `car`, while `cmp` is a universal matcher operating on the `manufacturer` property. ```ruby describe car(owner: 'Tony Clifton') do it { should be_classy } its('manufacturer') { should cmp 'Cadillac' } end ``` An operator matcher allows you to use operators to compare numerical against a . All plural resources have a `count` property. For example: ```ruby describe cars do its('count') { should be >= 10 } end ``` Operators include: `==` `>=` `<=` `>` `<` A `plural resource` is a that specializes in performing searches and represents multiple occurrences of the resource on the platform. Plural resources are used to audit counts, inspect group properties, and have the unique ability to enforce negative tests ("nothing like this should exist") often required by compliance standards. Plural resources are not intended to perform in-depth auditing of an individual; use for that. Plural resources nearly always have a name that ends in 's': `processes`, `awssecuritygroups`, `cars`. Plural resources generally do not have . If they have properties, they are almost always list properties, meaning that they return a list of values, which may or may not be de-duplicated. Plural resources support . See the for details regarding which are supported on each resource. Here, `cars` is a plural resource. ```ruby describe cars.where(color: 'blue') do its('count') { should eq 20 } its('license_plates') { should include 'AUTOAZUL' } its('license_plates.count') { should cmp 20 } its('manufacturers') { should include 'Subaru' } its('manufacturers.count') { should be < 10 } end ``` A `profile` is a set of related in a distributable form. You might have a locally-developed profile that your organization uses to define baseline security on all machines, or you might use a pre-defined profile that implements the requirements of a specific compliance standard. For full details about the capabilities of a profile, see the . Profiles may be distributed locally as a directory tree, as a tarball or zipfile at a URL, as a git repo, and several other ways. Profiles contain metadata, including versioning, and can setup dependency relationships with other profiles. Aside from controls, profiles can also contain . If the profile contains only custom resources and no controls, we call it a . A fact about a . Typically, you use the keyword to access the property and write a within a , and then use a to make assertions about the value of the property. Each resource has different properties. See the for details. Here, `manufacturer` is a property of the `car`

```ruby describe car(owner: 'Tony Clifton') do its('manufacturer') { should cmp 'Cadillac' } end ``` An output format for the `inspec exec` command line. Several reporters are available, including JSON and JUnit; see the . A `resource` represents a category of things on the you wish to examine. For example, to check for the existence and permissions of a file, you would use the resource. Chef InSpec offers dozens of different resources, from the highly specialized (such as `awssecuritygroup`, which examines firewall rules in AWS) to the very general (such as `command`, which runs a command and lets you examine its output). Resources are generally categorized as either or , though there are some irregular resources that cannot be cleanly considered one or the other. Resources are used within a to perform . Here, `car` is a resource. ```ruby describe car(owner: 'Tony Clifton') do it { should be_classy } end ``` A resource pack is a type of that is used to distribute . This specialized type of profile contains no , but it does contain a `libraries` directory within which Ruby files define custom resources. `resource parameters` are information passed to the resource when they are declared. Typically, resource parameters provide identifying information or connectivity information. Resource parameters are not the same as a . Resource parameters vary from resource to resource; refer to the for details. Here, `owner: 'Tony Clifton'` is a resource parameter. ```ruby describe car(owner: 'Tony Clifton') do it { should be_classy } end ``` A that operates directly on the , as opposed to operating on a property as a does. Resource-specific matchers often provide highly customized behavior. Check the to discover which resource-specific matchers are available for your resource. For example, the hypothetical `car` resource defines a `classy?` method, which is exposed as the `be_classy` matcher in Chef InSpec tests. ```ruby describe car(owner: 'Tony Clifton') do it { should be_classy } end ``` A intended to uniquely identify a single object on the . Singular resources specialize in providing richer auditing capabilities via resource-specific matchers. Compare to . The `target` is the OS or API on which Chef InSpec is performing audits. In Chef InSpec 1.x, this was always an operating system target (a bare metal machine, VM, or container). In Chef InSpec 2.x and later, this can be an OS target, or an API target, including cloud providers such as AWS. Chef InSpec is agentless, meaning that the Chef InSpec code and profiles remain on your workstation, and the target is remotely interrogated without installing anything. A `test` is an individual assertion about the state of the or one of its . All tests begin with the keyword or . Tests are grouped within a . A universal matcher is a that can be used on the of any type of . For example, you can use the `cmp` matcher to check the value of properties without having to worry about Ruby type-casting. Universal matchers are almost always used with the keyword. Universal matchers are documented on the page. Here, we access the 'color' property, then use the `cmp` universal matcher to compare the property to the 'black' . ```ruby describe car(owner: 'Bruce Wayne') do its('color') { should cmp 'black' } end ```