# Table of Contents
1. [About](#org69c4ee5)
2. [Installation methods](#org0de282f)
1. [Via deb/rpm](#org99f1862)
2. [MaOS binaries](#org47f1002)
3. [Via cargo](#org1d0629f)
4. [Guix manifest](#org422efc7)
3. [Usage](#org03891a1)
1. [Correctness of YAML files](#org5e1b701)
2. [Validity of Hiera YAML files](#orge989d6f)
3. [Linter of Puppet manifest files](#org533deba)
4. [Pretty printing manifest file](#orgbb610ea)
5. [Config file generator](#orgd106844)
6. [Hiera explorer](#org824a981)
7. [\*.pp AST dumper](#orgb8ef884)
4. [Available lints for \*.pp](#orgb030ef1)
1. [ArgumentLooksSensitive](#org18746a9)
2. [ArgumentTyped](#org49fe89c)
3. [ConstantExpressionInCondition](#orgc0f08a1)
4. [DefaultCaseIsNotLast](#org26462c5)
5. [DoNotUseUnless](#org649528e)
6. [DoubleNegation](#org0b09277)
7. [EmptyCasesList](#org78da798)
8. [EnsureAttributeIsNotTheFirst](#org1dc599c)
9. [ErbReferencesToUnknownVariable](#org6390d4c)
10. [ExecAttributes](#orgcd3755f)
11. [ExpressionInSingleQuotes](#orgdea08c8)
12. [FileModeAttributeIsString](#org1de4f41)
13. [InvalidResourceCollectionInvocation](#org99aa6c0)
14. [InvalidResourceSetInvocation](#org9baa7c1)
15. [InvalidStringEscape](#org31c4451)
16. [InvalidVariableAssignment](#org5da3c5d)
17. [LowerCaseArgumentName](#orgc014a22)
18. [LowerCaseVariable](#org7861a05)
19. [MultipleDefaultCase](#orgc437d51)
20. [MultipleResourcesWithoutDefault](#org844dda2)
21. [NegationOfEquation](#org50aeb09)
22. [NoDefaultCase](#org5750d1a)
23. [OptionalArgumentsGoesFirst](#orgf25c7e3)
24. [PerExpressionResourceDefaults](#orgff01509)
25. [ReadableArgumentsName](#orgd55110c)
26. [ReferenceToUndefinedValue](#org8cba3d6)
27. [RelationToTheLeft](#orgd97bab9)
28. [SelectorInAttributeValue](#orga58d957)
29. [SensitiveArgumentWithDefault](#org52367d2)
30. [StatementWithNoEffect](#orgde1e58a)
31. [UnconditionalExec](#orgf46ee37)
32. [UniqueArgumentsNames](#orgaaa65b7)
33. [UniqueAttributeName](#org83855a4)
34. [UnusedVariables](#org6c6fa54)
35. [UpperCaseName](#org687dd29)
36. [UselessDoubleQuotes](#orgb5a08c4)
37. [UselessParens](#orgd85a9a5)
5. [Linter for YAML files](#orgba846f3)
6. [Linter for Hiera YAML files](#org53c14e2)
1. [Reference to a module which has syntax errors](#org5e31778)
2. [Reference to class which is not found in modules/](#orgc745c51)
3. [Reference in undefined class argument](#orgc38e4a2)
4. [Single column in the name of key of root map](#org22bf944)
<a id="org69c4ee5"></a>
# About
Shadowplay is a utility for checking puppet syntax, a puppet manifest linter, a pretty printer, and a utility for exploring the Hiera.
<a id="org0de282f"></a>
# Installation methods
<a id="org99f1862"></a>
## Via deb/rpm
Latest releases can be downloaded here: <https://github.com/mailru/shadowplay/releases>
<a id="org47f1002"></a>
## MaOS binaries
Lastest binaries for MacOS can be downloaded here: <https://github.com/mailru/shadowplay/releases>
<a id="org1d0629f"></a>
## Via cargo
cargo install shadowplay
<a id="org422efc7"></a>
## Guix manifest
Guix manifest is not merged into main repository yet. One can use etc/guix.scm from Shadowplay repo. All missing dependencies are also
included into manifest file.
<a id="org03891a1"></a>
# Usage
<a id="org5e1b701"></a>
## Correctness of YAML files
shadowplay check yaml hieradata/default.yaml [hieradata/another.yaml] ...
In addition to the correctness of the syntax, the uniqueness of the keys in maps will be checked, as well as the correctness of the links
(anchors).
<a id="orge989d6f"></a>
## Validity of Hiera YAML files
shadowplay check hiera hieradata/default.yaml ...
For the specified files, YAML correctness will be checked, as well as the correctness of references to Puppet classes and class arguments.
For example, there will be an error generated if an unknown class argument is used.
As a side effect, it also checks the correctness of syntax of pappet manifests referenced by values ​​in Hiera.
<a id="org533deba"></a>
## Linter of Puppet manifest files
shadowplay --repo-path ./ check pp modules/hammer/manifests/config.pp ...
The specified files will be processed by the parser, then linter checks will be applied to the resulting AST (if parsing is successful).
<a id="orgbb610ea"></a>
## Pretty printing manifest file
shadowplay pretty-print-pp < /path/to/file.pp
<a id="orgd106844"></a>
## Config file generator
Use may want to disable some lints or customize it. She can generate default config and edit it later with the command:
shadowplay generate-config >/etc/shadowplay.yaml
<a id="org824a981"></a>
## Hiera explorer
Hiera is hierarchy of yaml files. In huge configurations it may be difficult to determine value of specific key for some host. Shadowplay
provides easy solution.
shadowplay get host123 sshd::install::version
Command prints as much information as possible:
Value: "present"
Found in "./hieradata/default_CentOS7.yaml" at lines 63:63
Value lookup path was: network/host123.yaml -> host123.yaml -> host.yaml -> default_CentOS7.yaml
===================================
Git information:
deadbeef1234 (Evgenii Lepikhin 2022-03-29 15:06:51 +0300 63) sshd::install::version: 'present'
<a id="orgb8ef884"></a>
## \*.pp AST dumper
shadowplay dump modules/sshd/manifests/install.pp
Outputs AST in JSON format. Mainly for internal purposes.
<a id="orgb030ef1"></a>
# Available lints for \*.pp
<a id="org18746a9"></a>
## ArgumentLooksSensitive
Warns if argument name looks like sensitive, but argument is not typed with type Sensitive
Bad:
class some::class (
$secret_token,
) { }
Good:
class some::class (
Sensitive $secret_token,
) { }
<a id="org49fe89c"></a>
## ArgumentTyped
Warns if argument is not typed
Bad:
class some::class (
$config_path,
) { }
Good:
class some::class (
Stdlib::Absolutepath $config_path,
) { }
<a id="orgc0f08a1"></a>
## ConstantExpressionInCondition
Warns if constant expression is used in condition
Bad:
if 1 == 2 - 1 { notify('1=2-1') }
Such type of conditions always evaluated into constant false or true, thus can be safely removed. Good:
notify('1=2-1')
<a id="org26462c5"></a>
## DefaultCaseIsNotLast
Warns if 'default' case is not the last
Bad:
case $value {
'a': { }
default: { }
'b': { }
}
Good:
case $value {
'a': { }
'b': { }
default: { }
}
<a id="org649528e"></a>
## DoNotUseUnless
Warns if 'unless' conditional statement is used
Bad:
unless $value { }
Good:
if !$value { }
<a id="org0b09277"></a>
## DoubleNegation
Warns if double negation is used
Bad:
if !(!$value) { }
if !($value != 1) { }
Good:
if $value { }
if $value == 1 { }
<a id="org78da798"></a>
## EmptyCasesList
Warns if case { … } has no cases
Bad:
case $value { }
<a id="org1dc599c"></a>
## EnsureAttributeIsNotTheFirst
Warns if 'ensure' argument of resource is not the first
Bad:
file { '/etc/passwd':
user => root,
ensure => file,
}
Good:
file { '/etc/passwd':
ensure => file,
user => root,
}
<a id="org6390d4c"></a>
## ErbReferencesToUnknownVariable
Checks ERB templates specified in template() for undefined variables
Bad:
class some::class () {
# here template_file.erb contains: <% @some_undefined_variable %>
$value = template('some/template_file.erb')
}
<a id="orgcd3755f"></a>
## ExecAttributes
Checks exec { …} arguments
Bad:
# implicit 'command' attribute
exec { 'echo Hello' : }
exec {
unknown_attribute => 1,
}
# invalid provider
exec {
provider => 'unknown provider value'
}
# 'path' is not set, 'provider' is not 'shell', thus 'command' attribute of exec {} must start with absolute path
exec {
command => 'echo Hello'
}
<a id="orgdea08c8"></a>
## ExpressionInSingleQuotes
Warns if interpolated expression found single-qouted string
Bad:
$value = 'Hello $world'
$value = '2 + 2 = ${2+2}'
<a id="org1de4f41"></a>
## FileModeAttributeIsString
Warns if argument 'mode' of 'file' resource is not in 4-digit string form
Bad:
file { '/some/file':
mode => '644',
}
file { '/some/file':
mode => 644,
}
Good:
file { '/some/file':
mode => '0644',
}
<a id="org99aa6c0"></a>
## InvalidResourceCollectionInvocation
Checks if existing resource set is used and all arguments are known in it's class
Bad:
# relation to unknown resource
Class['unknown_class'] -> Class['known_class']
<a id="org9baa7c1"></a>
## InvalidResourceSetInvocation
Checks if existing resource is used and all arguments are known in it's class
Bad:
class class1 (
$known_arg,
) { }
class class2 {
# Call to unknown class
class { 'unknown_class': }
# Call to known class with invalid argument
class { 'class1':
unknown_arg => 1
}
# Call to known class with invalid argument
class1 { 'title':
unknown_arg => 1,
}
# Call to internal resource with invalid argument
file { '/some/file':
uknown_arg => 1,
}
}
<a id="org31c4451"></a>
## InvalidStringEscape
Checks if only allowed characters are escaped in strings
Bad:
$value = '\s*\.'
$value = "\s*\."
Good:
$value = '\\s*\\.'
$value = "\\s*\\."
<a id="org5da3c5d"></a>
## InvalidVariableAssignment
Warns if left part of assignment is not a variable or array of variables
Bad:
lookup('some::value') = 1
<a id="orgc014a22"></a>
## LowerCaseArgumentName
Warns if argument name is not lowercase, as suggested by Puppet's style guide
Bad:
class some::class (
$ArgumentInCamelCase
) {}
<a id="org7861a05"></a>
## LowerCaseVariable
Warns if variable name is not lowercase
Bad:
class some::class () {
$VariableIsNOTInLowercase = 1
<a id="orgc437d51"></a>
## MultipleDefaultCase
Warns if case statement has multiple 'default' cases
Bad:
case $val {
1: {}
default: {}
default: {}
}
<a id="org844dda2"></a>
## MultipleResourcesWithoutDefault
Warns if resource set contains multiple resources and no defaults specified
Bad:
file {
'/etc/passwd':
ensure => file,
user => root,
'/etc/group':
ensure => file,
user => root,
group => wheel,
}
Good:
file {
default:
ensure => file,
user => root,
'/etc/passwd':
'/etc/group':
group => wheel,
}
<a id="org50aeb09"></a>
## NegationOfEquation
Warns on negation of equation
Bad:
if !($a == 1) { }
if !($a =~ /./) { }
Good:
if $a != 1 { }
if $a !~ /./ { }
<a id="org5750d1a"></a>
## NoDefaultCase
Warns if case statement has no default case
Bad:
case $val {
1, 2: { }
3: { }
}
Good:
case $val {
1, 2: { }
3: { }
default: { }
}
<a id="orgf25c7e3"></a>
## OptionalArgumentsGoesFirst
Warns if optional argument specified before required
class some::class (
$optional_arg = 1,
$required_arg,
) { }
Good:
class some::class (
$required_arg,
$optional_arg = 1,
) { }
<a id="orgff01509"></a>
## PerExpressionResourceDefaults
Warns if local resource defaults are used
Bad:
Exec {
provider => shell,
}
exec { 'run command':
command => 'echo Hello',
}
<a id="orgd55110c"></a>
## ReadableArgumentsName
Warns if argument name is not readable enough
Bad:
class some::class (
String $c = '/etc/config',
) { }
Good:
class some::class (
String $config = '/etc/config',
) { }
<a id="org8cba3d6"></a>
## ReferenceToUndefinedValue
Warns if variable is not defined in current context
Bad:
if $some_undefined_variable { }
<a id="orgd97bab9"></a>
## RelationToTheLeft
Checks for left-directed relations
Bad:
Class['c'] <- Class['b'] <~ Class['a']
Good:
Class['a'] ~> Class['b'] -> Class['c']
<a id="orga58d957"></a>
## SelectorInAttributeValue
Warns if selector (… ? … : …) used in resource attribute
Bad:
file { '/etc/shadow':
mode => $is_secure ? '0600' : '0644',
}
Good:
$file_mode = $is_secure ? '0600' : '0644'
file { '/etc/shadow':
mode => $file_mode,
}
<a id="org52367d2"></a>
## SensitiveArgumentWithDefault
Warns if argument typed with Sensitive contains default value
Bad:
class some::class (
Sensitive $password = 'admin',
)
Public available default value for sensitive data is nonsense. Good:
class some::class (
Sensitive $password,
)
<a id="orgde1e58a"></a>
## StatementWithNoEffect
Checks for statements without side effects
Bad:
if $a {
if $b {
2 + 2
}
}
<a id="orgf46ee37"></a>
## UnconditionalExec
Warns if exec { … } is specified without unless, onlyif, creates or refreshonly attributes
Bad:
exec { 'run command':
command => '/bin/rm -rf /var/cache/myapp',
}
Good:
exec { 'run command':
command => '/bin/rm -rf /var/cache/myapp',
onlyif => 'test -e /var/cache/myapp',
}
<a id="orgaaa65b7"></a>
## UniqueArgumentsNames
Checks for class/definition/plan arguments uniqueness
Bad:
class some::class (
$arg,
$arg,
$arg,
) { }
<a id="org83855a4"></a>
## UniqueAttributeName
Resource attributes must be unique
Bad:
service { 'sshd':
ensure => running,
ensure => stopped,
}
<a id="org6c6fa54"></a>
## UnusedVariables
Checks for unused variables. Experimental lint false-positives are possible.
Bad:
class some::class (
$unused_argument,
) {
service { 'sshd':
ensure => running,
}
}
<a id="org687dd29"></a>
## UpperCaseName
Warns if resource set used with uppercase letters
Bad:
Service { 'sshd':
ensure => running,
}
Good:
service { 'sshd':
ensure => running,
}
<a id="orgb5a08c4"></a>
## UselessDoubleQuotes
Warns if double quoted string has no interpolated expressions and no escaped single quotes
Bad:
$var = "simple literal"
Good:
$var = 'simple literal'
<a id="orgd85a9a5"></a>
## UselessParens
Checks for extra parens
Bad:
if (($var1) or ($var2)) { }
Good:
if $var1 or $var2 { }
<a id="orgba846f3"></a>
# Linter for YAML files
Some basic checks are implemented:
- File is not executable
- File is empty (no root value available)
- File parsed without syntax errors
- Maps does not contain duplicate keys
- Attempt to merge anchor which type is not array nor map
<a id="org53c14e2"></a>
# Linter for Hiera YAML files
All lints of YAML files plus:
<a id="org5e31778"></a>
## Reference to a module which has syntax errors
Linter will fail if some<sub>class</sub> was unable to parse:
some_class::argument: 1
<a id="orgc745c51"></a>
## Reference to class which is not found in modules/
Linter will fail if modules/some<sub>class</sub>/init.pp does not exists:
some_class::argument: 1
<a id="orgc38e4a2"></a>
## Reference in undefined class argument
Linter will fail if some<sub>class</sub> does not accept argument $argument<sub>name</sub>:
some_class::argument_name: 1
<a id="org22bf944"></a>
## Single column in the name of key of root map
Linter protects agains typos like:
some_class:argument_name: 1