Mirrors/inspec
2
0
Fork 0
mirror of https://github.com/inspec/inspec synced 2024-09-20 14:31:58 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #3890 from inspec/cw/fix-glossary-links

Browse source 
Repair anchor links to use dashes instead of underscores
This commit is contained in:
Clinton Wolfe 2019-03-20 11:06:51 -04:00 committed by GitHub
commit 2d40181f35
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 36 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

72
docs/glossary.md
View file

@ -4,8 +4,8 @@ This document should help you become familiar with some of the terminology used
There are two ways to use it:
* A [text glossary](#text_glossary). Learn the meaning of a word you have encountered.
* A [visual glossary](#visual_glossary). Look at examples and see how the parts are labelled. You can then use the text glossary to read details of each concept.
* A [text glossary](#text-glossary). Learn the meaning of a word you have encountered.
* A [visual glossary](#visual-glossary). Look at examples and see how the parts are labelled. You can then use the text glossary to read details of each concept.
## Visual Glossary
@ -30,31 +30,31 @@ end
#### describe car(owner: 'Tony Clifton') do
_car_ is a [resource](#resource). Since we are talking about only one car, it is a [singular resource](#singular_resource).
_car_ is a [resource](#resource). Since we are talking about only one car, it is a [singular resource](#singular-resource).
#### describe car(_owner: 'Tony Clifton'_)
_owner_ is a [resource parameter](#resource_parameter) and _'Tony Clifton'_ is a resource parameter value.
_owner_ is a [resource parameter](#resource-parameter) and _'Tony Clifton'_ is a resource parameter value.
#### _it { should exist }_
Each line within the resource block beginning with `it` or `its` is a [test](#test). Use [it](#it) to access [resource-specific matchers](#resource_specific_matcher), and use [its](#its) to access [properties](#property) of the [resource](#resource), which are in turn used with [universal matchers](#universal_matcher).
Each line within the resource block beginning with `it` or `its` is a [test](#test). Use [it](#it) to access [resource-specific matchers](#resource-specific-matcher), and use [its](#its) to access [properties](#property) of the [resource](#resource), which are in turn used with [universal matchers](#universal-matcher).
#### its('_license\_plate_') { should cmp 'MOONMAN' }
_license\_plate_ is a [property](#property) belonging to the [resource](#resource). 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 [universal matchers](#universal_matcher).
_license\_plate_ is a [property](#property) belonging to the [resource](#resource). 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 [universal matchers](#universal-matcher).
#### its('license\_plate') { should _cmp_ 'MOONMAN' }
_cmp_ is a [universal matcher](#universal_matcher). `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 [Universal Matcher page](https://www.inspec.io/docs/reference/matchers/).
_cmp_ is a [universal matcher](#universal-matcher). `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 [Universal Matcher page](https://www.inspec.io/docs/reference/matchers/).
#### its('license\_plate') { should cmp _'MOONMAN'_ }
_'MOONMAN'_ is an [expected result](#expected_result). Some matchers take an expected result; others do not.
_'MOONMAN'_ is an [expected result](#expected-result). Some matchers take an expected result; others do not.
#### it { should _be\_classy_ }
_be\_classy_ is a [resource-specific matcher](#resource_specific_matcher). It returns a yes-or-no value, based on whether Tony's car is classy or not. (It is. Tony is a classy guy.)
_be\_classy_ is a [resource-specific matcher](#resource-specific-matcher). It returns a yes-or-no value, based on whether Tony's car is classy or not. (It is. Tony is a classy guy.)
#### it { _should\_not_ have\_check\_engine\_light\_on }
@ -72,19 +72,19 @@ _should\_not_ indicates this is a negated test. So, this test passes if the matc
#### describe _cars_.where(color: /^b/) do
_cars_ is a [resource](#resource). Since we are potentially talking about many cars, it is a [plural resource](#plural_resource).
_cars_ is a [resource](#resource). Since we are potentially talking about many cars, it is a [plural resource](#plural-resource).
#### describe cars._where(color: /^b/)_ do
_where(color: /^b/)_ is a [filter statement](#filter_statement). Without a filter statement, `cars` simply selects all the cars in the world.
_where(color: /^b/)_ is a [filter statement](#filter-statement). Without a filter statement, `cars` simply selects all the cars in the world.
#### describe cars.where(_color: /^b/_) do
_color_ is a [filter criterion](#filter_criteria) 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.
_color_ is a [filter criterion](#filter-criteria) 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.
#### _it { should exist }_
Each line within the resource block beginning with `it` or `its` is a [test](#test). Use [it](#it) to access [resource-specific matchers](#resource_specific_matcher), and use [its](#its) to access [properties](#property) of the [resource](#resource), which are in turn used with [universal matchers](#universal_matcher).
Each line within the resource block beginning with `it` or `its` is a [test](#test). Use [it](#it) to access [resource-specific matchers](#resource-specific-matcher), and use [its](#its) to access [properties](#property) of the [resource](#resource), which are in turn used with [universal matchers](#universal-matcher).
With plural resources, `exist` has a special meaning: did the filter match anything?
@ -94,11 +94,11 @@ _manufacturers_ is a [property](#property) of the [resource](#resource). Propert
#### its('manufacturers') { should _include_ 'Cadillac' }
_include_ is a [universal matcher](#universal_matcher). `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 [Universal Matcher page](https://www.inspec.io/docs/reference/matchers/).
_include_ is a [universal matcher](#universal-matcher). `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 [Universal Matcher page](https://www.inspec.io/docs/reference/matchers/).
#### its('manufacturers') { should include '_Cadillac_' }
_'Cadillac'_ is an [expected result](#expected_result). Some matchers take an expected result; others do not.
_'Cadillac'_ is an [expected result](#expected-result). Some matchers take an expected result; others do not.
#### its('count') { should _be >=_ 10 }
@ -118,7 +118,7 @@ The syntax for accessing attributes within a profile is documented in the [profi
### control block
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 [describe blocks](#describe_block) to implement the checks.
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 [describe blocks](#describe-block) to implement the checks.
### core resource
@ -147,7 +147,7 @@ end
_DSL_ is an acronym for _Domain Specific Language_. It refers to the language extensions InSpec provides to make authoring resources and controls easier. While 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 [describe](#describe), [control](#control), [it](#it) and [its](#its). See the [InSpec DSL page](https://www.inspec.io/docs/reference/dsl_inspec/) for details about keywords available to control authors.
For [custom resource](#custom_resource) authors, an additional DSL is available - see the [Resource DSL page](https://www.inspec.io/docs/reference/dsl_resource/).
For [custom resource](#custom-resource) authors, an additional DSL is available - see the [Resource DSL page](https://www.inspec.io/docs/reference/dsl_resource/).
### expected result
@ -163,7 +163,7 @@ end
### filter statement
When using a [plural resource](#plural_resource), a _`filter statement`_ is used to select individual test subjects using [filter criteria](#filter_criteria). A filter statement almost always is indicated by the keyword `where`, and may be repeated using method chaining.
When using a [plural resource](#plural-resource), a _`filter statement`_ is used to select individual test subjects using [filter criteria](#filter-criteria). A filter statement almost always is indicated by the keyword `where`, and may be repeated using method chaining.
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).
@ -180,7 +180,7 @@ end
### filter criteria
When using a [plural resource](#plural_resource), a _`filter criterion`_ is used to select individual test subjects within a [filter statement](#filter_statement). You may use multiple _`filter criteria`_ in a single filter statement.
When using a [plural resource](#plural-resource), a _`filter criterion`_ is used to select individual test subjects within a [filter statement](#filter-statement). 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.
@ -206,7 +206,7 @@ end
### it
Within a [describe block](#describe), _`it`_ declares an individual [test](#test) directly against the [resource](#resource) (as opposed to testing against one of the resource's [properties](#property), as [its](#its) does). Though it is possible to use [universal matchers](#universal_matcher) with `it`, it is much more typical to use [resource-specific matchers](#resource_specific_matchers).
Within a [describe block](#describe), _`it`_ declares an individual [test](#test) directly against the [resource](#resource) (as opposed to testing against one of the resource's [properties](#property), as [its](#its) does). Though it is possible to use [universal matchers](#universal-matcher) with `it`, it is much more typical to use [resource-specific matchers](#resource-specific-matchers).
`it` may be used with `should`, or negated using `should_not`.
@ -220,7 +220,7 @@ end
### its
Within a [describe block](#describe), _`its`_ declares an individual [test](#test) against a property of the [resource](#resource) (as opposed to testing directly against the resource itself, as [it](#it) does). You must use [universal matchers](#universal_matcher) with `its`; you cannot use [resource-specific matchers](#resource_specific_matchers).
Within a [describe block](#describe), _`its`_ declares an individual [test](#test) against a property of the [resource](#resource) (as opposed to testing directly against the resource itself, as [it](#it) does). You must use [universal matchers](#universal-matcher) with `its`; you cannot use [resource-specific matchers](#resource-specific-matchers).
`its` may be used with `should`, or negated using `should_not`.
@ -240,10 +240,10 @@ end
A _`matcher`_ performs the actual assertions against [resources](#resource) or the [properties](#property) of resources. Matchers always return a true/false value. Matchers fall into two camps:
* [resource-specific matchers](#resource_specific_matchers), which operate directly on the resource, are used with [it](#it), and tend to be highly customized to the auditing needs of the resource
* [universal matchers](#universal_matchers), which operate on the properties of the resource, are used with [its](#its), and tend to be very generic, operating on text, numbers, and lists
* [resource-specific matchers](#resource-specific-matchers), which operate directly on the resource, are used with [it](#it), and tend to be highly customized to the auditing needs of the resource
* [universal matchers](#universal-matchers), which operate on the properties of the resource, are used with [its](#its), and tend to be very generic, operating on text, numbers, and lists
Some matchers accept parameters, called [expected results](#expected_results).
Some matchers accept parameters, called [expected results](#expected-results).
For information on how RSpec matchers are related o InSpec matchers, see [InSpec and RSpec](https://www.inspec.io/docs/reference/inspec_and_friends/#rspec).
@ -258,11 +258,11 @@ end
### plural resource
A _`plural resource`_ is a [resource](#resource) that specializes in performing searches and represents multiple occurrences of the resource on the [target](#target) 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 [singular resources](#singular_resource) for that.
A _`plural resource`_ is a [resource](#resource) that specializes in performing searches and represents multiple occurrences of the resource on the [target](#target) 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 [singular resources](#singular-resource) for that.
Plural resources nearly always have a name that ends in 's': `processes`, `aws_security_groups`, `cars`. Plural resources generally do not have [resource-specific matchers](#resource_specific_matcher). 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 nearly always have a name that ends in 's': `processes`, `aws_security_groups`, `cars`. Plural resources generally do not have [resource-specific matchers](#resource-specific-matcher). 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 [filter statements](#filter_statement). See the [resource documentation](https://www.inspec.io/docs/reference/resources/) for details regarding which [filter criteria](#filter_criteria) are supported on each resource.
Plural resources support [filter statements](#filter-statement). See the [resource documentation](https://www.inspec.io/docs/reference/resources/) for details regarding which [filter criteria](#filter-criteria) are supported on each resource.
Here, `cars` is a plural resource.
@ -286,11 +286,11 @@ A _`profile`_ is a set of related [controls](#control) in a distributable form.
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 [custom resources](#custom_resource). If the profile contains only custom resources and no controls, we call it a [resource pack](#resource_pack).
Aside from controls, profiles can also contain [custom resources](#custom-resource). If the profile contains only custom resources and no controls, we call it a [resource pack](#resource-pack).
### property
A fact about a [resource](#resource). Typically, you use the [its](#its) keyword to access the property and write a [test](#test) within a [describe block](#describe_block), and then use a [universal matcher](#universal_matcher) to make assertions about the value of the property.
A fact about a [resource](#resource). Typically, you use the [its](#its) keyword to access the property and write a [test](#test) within a [describe block](#describe-block), and then use a [universal matcher](#universal-matcher) to make assertions about the value of the property.
Each resource has different properties. See the [resource documentation](https://www.inspec.io/docs/reference/resources/) for details.
@ -310,9 +310,9 @@ An output format for the `inspec exec` command line. Several reporters are avail
A _`resource`_ represents a category of things on the [target](#target) you wish to examine. For example, to check for the existence and permissions of a file, you would use the [`file`](https://www.inspec.io/docs/reference/resources/file/) resource. InSpec offers dozens of different resources, from the highly specialized (such as `aws_security_group`, 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 [singular](#singular_resource) or [plural](#plural_resource), though there are some irregular resources that cannot be cleanly considered one or the other.
Resources are generally categorized as either [singular](#singular-resource) or [plural](#plural-resource), though there are some irregular resources that cannot be cleanly considered one or the other.
Resources are used within a [describe block](#describe_block) to perform [tests](#test).
Resources are used within a [describe block](#describe-block) to perform [tests](#test).
Here, `car` is a resource.
@ -324,11 +324,11 @@ end
### resource pack
A _resource pack_ is a type of [profile](#profile) that is used to distribute [custom resources](#custom_resource). This specialized type of profile contains no [controls](#control), but it does contain a `libraries` directory within which Ruby files define custom resources.
A _resource pack_ is a type of [profile](#profile) that is used to distribute [custom resources](#custom-resource). This specialized type of profile contains no [controls](#control), but it does contain a `libraries` directory within which Ruby files define custom resources.
### resource parameter
_`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 [filter statement](#filter_statement).
_`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 [filter statement](#filter-statement).
Resource parameters vary from resource to resource; refer to the [resource documentation](https://www.inspec.io/docs/reference/resources/) for details.
@ -356,7 +356,7 @@ end
### singular resource
A [resource](#resource) intended to uniquely identify a single object on the [target](#target). Singular resources specialize in providing richer auditing capabilities via resource-specific matchers. Compare to [plural resources](#plural_resource).
A [resource](#resource) intended to uniquely identify a single object on the [target](#target). Singular resources specialize in providing richer auditing capabilities via resource-specific matchers. Compare to [plural resources](#plural-resource).
### target
@ -364,7 +364,7 @@ The _`target`_ is the OS or API on which InSpec is performing audits. In InSpec
### test
A _`test`_ is an individual assertion about the state of the [resource](#resource) or one of its [properties](#property). All tests begin with the keyword [it](#it) or [its](#its). Tests are grouped within a [describe block](#describe_block).
A _`test`_ is an individual assertion about the state of the [resource](#resource) or one of its [properties](#property). All tests begin with the keyword [it](#it) or [its](#its). Tests are grouped within a [describe block](#describe-block).
### universal matcher
@ -372,7 +372,7 @@ A _universal matcher_ is a [matcher](#matcher) that can be used on the [properti
Universal matchers are documented on the [Universal Matchers](https://www.inspec.io/docs/reference/matchers/) page.
Here, we access the 'color' property, then use the `cmp` universal matcher to compare the property to the 'black' [expected result](#expected_result).
Here, we access the 'color' property, then use the `cmp` universal matcher to compare the property to the 'black' [expected result](#expected-result).
```Ruby
describe car(owner: 'Bruce Wayne') do