inspec 2.3.10 → 2.3.23

Sign up to get free protection for your applications and to get access to all the features.
Files changed (271) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +34 -13
  3. data/etc/plugin_filters.json +25 -0
  4. data/inspec.gemspec +3 -3
  5. data/lib/bundles/inspec-compliance/api.rb +3 -0
  6. data/lib/bundles/inspec-compliance/configuration.rb +3 -0
  7. data/lib/bundles/inspec-compliance/http.rb +3 -0
  8. data/lib/bundles/inspec-compliance/support.rb +3 -0
  9. data/lib/bundles/inspec-compliance/target.rb +3 -0
  10. data/lib/inspec/objects/attribute.rb +3 -0
  11. data/lib/inspec/plugin/v2.rb +3 -0
  12. data/lib/inspec/plugin/v2/filter.rb +62 -0
  13. data/lib/inspec/plugin/v2/installer.rb +21 -1
  14. data/lib/inspec/plugin/v2/loader.rb +4 -0
  15. data/lib/inspec/profile.rb +3 -1
  16. data/lib/inspec/version.rb +1 -1
  17. data/lib/plugins/inspec-plugin-manager-cli/lib/inspec-plugin-manager-cli/cli_command.rb +25 -3
  18. data/lib/plugins/inspec-plugin-manager-cli/test/functional/inspec-plugin_test.rb +65 -11
  19. data/lib/plugins/inspec-plugin-manager-cli/test/unit/cli_args_test.rb +5 -1
  20. data/lib/resources/package.rb +1 -1
  21. metadata +5 -253
  22. data/MAINTAINERS.toml +0 -52
  23. data/docs/.gitignore +0 -2
  24. data/docs/README.md +0 -41
  25. data/docs/dev/control-eval.md +0 -62
  26. data/docs/dev/filtertable-internals.md +0 -353
  27. data/docs/dev/filtertable-usage.md +0 -533
  28. data/docs/dev/integration-testing.md +0 -31
  29. data/docs/dev/plugins.md +0 -323
  30. data/docs/dsl_inspec.md +0 -354
  31. data/docs/dsl_resource.md +0 -100
  32. data/docs/glossary.md +0 -381
  33. data/docs/habitat.md +0 -193
  34. data/docs/inspec_and_friends.md +0 -114
  35. data/docs/matchers.md +0 -161
  36. data/docs/migration.md +0 -293
  37. data/docs/platforms.md +0 -119
  38. data/docs/plugin_kitchen_inspec.md +0 -60
  39. data/docs/plugins.md +0 -57
  40. data/docs/profiles.md +0 -576
  41. data/docs/reporters.md +0 -170
  42. data/docs/resources/aide_conf.md.erb +0 -86
  43. data/docs/resources/apache.md.erb +0 -77
  44. data/docs/resources/apache_conf.md.erb +0 -78
  45. data/docs/resources/apt.md.erb +0 -81
  46. data/docs/resources/audit_policy.md.erb +0 -57
  47. data/docs/resources/auditd.md.erb +0 -89
  48. data/docs/resources/auditd_conf.md.erb +0 -78
  49. data/docs/resources/aws_cloudtrail_trail.md.erb +0 -165
  50. data/docs/resources/aws_cloudtrail_trails.md.erb +0 -96
  51. data/docs/resources/aws_cloudwatch_alarm.md.erb +0 -101
  52. data/docs/resources/aws_cloudwatch_log_metric_filter.md.erb +0 -164
  53. data/docs/resources/aws_config_delivery_channel.md.erb +0 -111
  54. data/docs/resources/aws_config_recorder.md.erb +0 -96
  55. data/docs/resources/aws_ebs_volume.md.erb +0 -76
  56. data/docs/resources/aws_ebs_volumes.md.erb +0 -86
  57. data/docs/resources/aws_ec2_instance.md.erb +0 -122
  58. data/docs/resources/aws_ec2_instances.md.erb +0 -89
  59. data/docs/resources/aws_elb.md.erb +0 -154
  60. data/docs/resources/aws_elbs.md.erb +0 -252
  61. data/docs/resources/aws_flow_log.md.erb +0 -128
  62. data/docs/resources/aws_iam_access_key.md.erb +0 -139
  63. data/docs/resources/aws_iam_access_keys.md.erb +0 -214
  64. data/docs/resources/aws_iam_group.md.erb +0 -74
  65. data/docs/resources/aws_iam_groups.md.erb +0 -92
  66. data/docs/resources/aws_iam_password_policy.md.erb +0 -92
  67. data/docs/resources/aws_iam_policies.md.erb +0 -97
  68. data/docs/resources/aws_iam_policy.md.erb +0 -264
  69. data/docs/resources/aws_iam_role.md.erb +0 -79
  70. data/docs/resources/aws_iam_root_user.md.erb +0 -86
  71. data/docs/resources/aws_iam_user.md.erb +0 -130
  72. data/docs/resources/aws_iam_users.md.erb +0 -289
  73. data/docs/resources/aws_kms_key.md.erb +0 -187
  74. data/docs/resources/aws_kms_keys.md.erb +0 -99
  75. data/docs/resources/aws_rds_instance.md.erb +0 -76
  76. data/docs/resources/aws_route_table.md.erb +0 -63
  77. data/docs/resources/aws_route_tables.md.erb +0 -65
  78. data/docs/resources/aws_s3_bucket.md.erb +0 -156
  79. data/docs/resources/aws_s3_bucket_object.md.erb +0 -99
  80. data/docs/resources/aws_s3_buckets.md.erb +0 -69
  81. data/docs/resources/aws_security_group.md.erb +0 -323
  82. data/docs/resources/aws_security_groups.md.erb +0 -107
  83. data/docs/resources/aws_sns_subscription.md.erb +0 -140
  84. data/docs/resources/aws_sns_topic.md.erb +0 -79
  85. data/docs/resources/aws_sns_topics.md.erb +0 -68
  86. data/docs/resources/aws_subnet.md.erb +0 -150
  87. data/docs/resources/aws_subnets.md.erb +0 -142
  88. data/docs/resources/aws_vpc.md.erb +0 -135
  89. data/docs/resources/aws_vpcs.md.erb +0 -135
  90. data/docs/resources/azure_generic_resource.md.erb +0 -183
  91. data/docs/resources/azure_resource_group.md.erb +0 -294
  92. data/docs/resources/azure_virtual_machine.md.erb +0 -357
  93. data/docs/resources/azure_virtual_machine_data_disk.md.erb +0 -234
  94. data/docs/resources/bash.md.erb +0 -85
  95. data/docs/resources/bond.md.erb +0 -100
  96. data/docs/resources/bridge.md.erb +0 -67
  97. data/docs/resources/bsd_service.md.erb +0 -77
  98. data/docs/resources/chocolatey_package.md.erb +0 -68
  99. data/docs/resources/command.md.erb +0 -176
  100. data/docs/resources/cpan.md.erb +0 -89
  101. data/docs/resources/cran.md.erb +0 -74
  102. data/docs/resources/crontab.md.erb +0 -103
  103. data/docs/resources/csv.md.erb +0 -64
  104. data/docs/resources/dh_params.md.erb +0 -221
  105. data/docs/resources/directory.md.erb +0 -40
  106. data/docs/resources/docker.md.erb +0 -240
  107. data/docs/resources/docker_container.md.erb +0 -113
  108. data/docs/resources/docker_image.md.erb +0 -104
  109. data/docs/resources/docker_plugin.md.erb +0 -80
  110. data/docs/resources/docker_service.md.erb +0 -124
  111. data/docs/resources/elasticsearch.md.erb +0 -252
  112. data/docs/resources/etc_fstab.md.erb +0 -135
  113. data/docs/resources/etc_group.md.erb +0 -85
  114. data/docs/resources/etc_hosts.md.erb +0 -88
  115. data/docs/resources/etc_hosts_allow.md.erb +0 -84
  116. data/docs/resources/etc_hosts_deny.md.erb +0 -84
  117. data/docs/resources/file.md.erb +0 -543
  118. data/docs/resources/filesystem.md.erb +0 -51
  119. data/docs/resources/firewalld.md.erb +0 -117
  120. data/docs/resources/gem.md.erb +0 -108
  121. data/docs/resources/group.md.erb +0 -71
  122. data/docs/resources/grub_conf.md.erb +0 -111
  123. data/docs/resources/host.md.erb +0 -96
  124. data/docs/resources/http.md.erb +0 -207
  125. data/docs/resources/iis_app.md.erb +0 -132
  126. data/docs/resources/iis_site.md.erb +0 -145
  127. data/docs/resources/inetd_conf.md.erb +0 -104
  128. data/docs/resources/ini.md.erb +0 -86
  129. data/docs/resources/interface.md.erb +0 -68
  130. data/docs/resources/iptables.md.erb +0 -74
  131. data/docs/resources/json.md.erb +0 -73
  132. data/docs/resources/kernel_module.md.erb +0 -130
  133. data/docs/resources/kernel_parameter.md.erb +0 -63
  134. data/docs/resources/key_rsa.md.erb +0 -95
  135. data/docs/resources/launchd_service.md.erb +0 -67
  136. data/docs/resources/limits_conf.md.erb +0 -85
  137. data/docs/resources/login_defs.md.erb +0 -81
  138. data/docs/resources/mount.md.erb +0 -79
  139. data/docs/resources/mssql_session.md.erb +0 -78
  140. data/docs/resources/mysql_conf.md.erb +0 -109
  141. data/docs/resources/mysql_session.md.erb +0 -84
  142. data/docs/resources/nginx.md.erb +0 -89
  143. data/docs/resources/nginx_conf.md.erb +0 -148
  144. data/docs/resources/npm.md.erb +0 -78
  145. data/docs/resources/ntp_conf.md.erb +0 -70
  146. data/docs/resources/oneget.md.erb +0 -63
  147. data/docs/resources/oracledb_session.md.erb +0 -103
  148. data/docs/resources/os.md.erb +0 -153
  149. data/docs/resources/os_env.md.erb +0 -101
  150. data/docs/resources/package.md.erb +0 -130
  151. data/docs/resources/packages.md.erb +0 -77
  152. data/docs/resources/parse_config.md.erb +0 -113
  153. data/docs/resources/parse_config_file.md.erb +0 -148
  154. data/docs/resources/passwd.md.erb +0 -151
  155. data/docs/resources/pip.md.erb +0 -77
  156. data/docs/resources/port.md.erb +0 -147
  157. data/docs/resources/postgres_conf.md.erb +0 -89
  158. data/docs/resources/postgres_hba_conf.md.erb +0 -103
  159. data/docs/resources/postgres_ident_conf.md.erb +0 -86
  160. data/docs/resources/postgres_session.md.erb +0 -79
  161. data/docs/resources/powershell.md.erb +0 -112
  162. data/docs/resources/processes.md.erb +0 -119
  163. data/docs/resources/rabbitmq_config.md.erb +0 -51
  164. data/docs/resources/registry_key.md.erb +0 -197
  165. data/docs/resources/runit_service.md.erb +0 -67
  166. data/docs/resources/security_policy.md.erb +0 -57
  167. data/docs/resources/service.md.erb +0 -131
  168. data/docs/resources/shadow.md.erb +0 -267
  169. data/docs/resources/ssh_config.md.erb +0 -83
  170. data/docs/resources/sshd_config.md.erb +0 -93
  171. data/docs/resources/ssl.md.erb +0 -129
  172. data/docs/resources/sys_info.md.erb +0 -52
  173. data/docs/resources/systemd_service.md.erb +0 -67
  174. data/docs/resources/sysv_service.md.erb +0 -67
  175. data/docs/resources/upstart_service.md.erb +0 -67
  176. data/docs/resources/user.md.erb +0 -150
  177. data/docs/resources/users.md.erb +0 -137
  178. data/docs/resources/vbscript.md.erb +0 -65
  179. data/docs/resources/virtualization.md.erb +0 -67
  180. data/docs/resources/windows_feature.md.erb +0 -69
  181. data/docs/resources/windows_hotfix.md.erb +0 -63
  182. data/docs/resources/windows_task.md.erb +0 -95
  183. data/docs/resources/wmi.md.erb +0 -91
  184. data/docs/resources/x509_certificate.md.erb +0 -161
  185. data/docs/resources/xinetd_conf.md.erb +0 -166
  186. data/docs/resources/xml.md.erb +0 -95
  187. data/docs/resources/yaml.md.erb +0 -79
  188. data/docs/resources/yum.md.erb +0 -108
  189. data/docs/resources/zfs_dataset.md.erb +0 -63
  190. data/docs/resources/zfs_pool.md.erb +0 -57
  191. data/docs/shared/matcher_be.md.erb +0 -1
  192. data/docs/shared/matcher_cmp.md.erb +0 -43
  193. data/docs/shared/matcher_eq.md.erb +0 -3
  194. data/docs/shared/matcher_include.md.erb +0 -1
  195. data/docs/shared/matcher_match.md.erb +0 -1
  196. data/docs/shell.md +0 -217
  197. data/docs/style.md +0 -178
  198. data/examples/README.md +0 -8
  199. data/examples/custom-resource/README.md +0 -3
  200. data/examples/custom-resource/controls/example.rb +0 -7
  201. data/examples/custom-resource/inspec.yml +0 -8
  202. data/examples/custom-resource/libraries/batsignal.rb +0 -20
  203. data/examples/custom-resource/libraries/gordon.rb +0 -21
  204. data/examples/inheritance/README.md +0 -65
  205. data/examples/inheritance/controls/example.rb +0 -14
  206. data/examples/inheritance/inspec.yml +0 -16
  207. data/examples/kitchen-ansible/.kitchen.yml +0 -25
  208. data/examples/kitchen-ansible/Gemfile +0 -19
  209. data/examples/kitchen-ansible/README.md +0 -53
  210. data/examples/kitchen-ansible/files/nginx.repo +0 -6
  211. data/examples/kitchen-ansible/tasks/main.yml +0 -16
  212. data/examples/kitchen-ansible/test/integration/default/default.yml +0 -5
  213. data/examples/kitchen-ansible/test/integration/default/web_spec.rb +0 -28
  214. data/examples/kitchen-chef/.kitchen.yml +0 -20
  215. data/examples/kitchen-chef/Berksfile +0 -3
  216. data/examples/kitchen-chef/Gemfile +0 -19
  217. data/examples/kitchen-chef/README.md +0 -27
  218. data/examples/kitchen-chef/metadata.rb +0 -7
  219. data/examples/kitchen-chef/recipes/default.rb +0 -6
  220. data/examples/kitchen-chef/recipes/nginx.rb +0 -30
  221. data/examples/kitchen-chef/test/integration/default/web_spec.rb +0 -28
  222. data/examples/kitchen-puppet/.kitchen.yml +0 -23
  223. data/examples/kitchen-puppet/Gemfile +0 -20
  224. data/examples/kitchen-puppet/Puppetfile +0 -25
  225. data/examples/kitchen-puppet/README.md +0 -53
  226. data/examples/kitchen-puppet/manifests/site.pp +0 -33
  227. data/examples/kitchen-puppet/metadata.json +0 -11
  228. data/examples/kitchen-puppet/modules/.gitkeep +0 -0
  229. data/examples/kitchen-puppet/test/integration/default/web_spec.rb +0 -28
  230. data/examples/meta-profile/README.md +0 -37
  231. data/examples/meta-profile/controls/example.rb +0 -13
  232. data/examples/meta-profile/inspec.yml +0 -13
  233. data/examples/plugins/inspec-resource-lister/Gemfile +0 -12
  234. data/examples/plugins/inspec-resource-lister/LICENSE +0 -13
  235. data/examples/plugins/inspec-resource-lister/README.md +0 -62
  236. data/examples/plugins/inspec-resource-lister/Rakefile +0 -40
  237. data/examples/plugins/inspec-resource-lister/inspec-resource-lister.gemspec +0 -45
  238. data/examples/plugins/inspec-resource-lister/lib/inspec-resource-lister.rb +0 -16
  239. data/examples/plugins/inspec-resource-lister/lib/inspec-resource-lister/cli_command.rb +0 -70
  240. data/examples/plugins/inspec-resource-lister/lib/inspec-resource-lister/plugin.rb +0 -55
  241. data/examples/plugins/inspec-resource-lister/lib/inspec-resource-lister/version.rb +0 -10
  242. data/examples/plugins/inspec-resource-lister/test/fixtures/README.md +0 -24
  243. data/examples/plugins/inspec-resource-lister/test/functional/README.md +0 -18
  244. data/examples/plugins/inspec-resource-lister/test/functional/inspec_resource_lister_test.rb +0 -110
  245. data/examples/plugins/inspec-resource-lister/test/helper.rb +0 -26
  246. data/examples/plugins/inspec-resource-lister/test/unit/README.md +0 -17
  247. data/examples/plugins/inspec-resource-lister/test/unit/cli_args_test.rb +0 -64
  248. data/examples/plugins/inspec-resource-lister/test/unit/plugin_def_test.rb +0 -51
  249. data/examples/profile-attribute.yml +0 -2
  250. data/examples/profile-attribute/README.md +0 -14
  251. data/examples/profile-attribute/controls/example.rb +0 -11
  252. data/examples/profile-attribute/inspec.yml +0 -8
  253. data/examples/profile-aws/controls/iam_password_policy_expiration.rb +0 -8
  254. data/examples/profile-aws/controls/iam_password_policy_max_age.rb +0 -8
  255. data/examples/profile-aws/controls/iam_root_user_mfa.rb +0 -8
  256. data/examples/profile-aws/controls/iam_users_access_key_age.rb +0 -8
  257. data/examples/profile-aws/controls/iam_users_console_users_mfa.rb +0 -8
  258. data/examples/profile-aws/inspec.yml +0 -11
  259. data/examples/profile-azure/controls/azure_resource_group_example.rb +0 -24
  260. data/examples/profile-azure/controls/azure_vm_example.rb +0 -29
  261. data/examples/profile-azure/inspec.yml +0 -11
  262. data/examples/profile-sensitive/README.md +0 -29
  263. data/examples/profile-sensitive/controls/sensitive-failures.rb +0 -9
  264. data/examples/profile-sensitive/controls/sensitive.rb +0 -9
  265. data/examples/profile-sensitive/inspec.yml +0 -8
  266. data/examples/profile/README.md +0 -48
  267. data/examples/profile/controls/example.rb +0 -24
  268. data/examples/profile/controls/gordon.rb +0 -36
  269. data/examples/profile/controls/meta.rb +0 -36
  270. data/examples/profile/inspec.yml +0 -11
  271. data/examples/profile/libraries/gordon_config.rb +0 -59
@@ -1,99 +0,0 @@
1
- ---
2
- title: About the aws_s3_bucket_object Resource
3
- ---
4
-
5
- # aws\_s3\_bucket\_object
6
-
7
- Use the `aws_s3_bucket_object` InSpec audit resource to test properties of a single AWS bucket object.
8
-
9
- Each S3 Object has a 'key' which can be thought of as the name of the S3 Object which uniquely identifies it.
10
-
11
-
12
- <br>
13
-
14
- ## Limitations
15
-
16
- S3 object security is a complex matter. For details on how AWS evaluates requests for access, please see [the AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/dev/how-s3-evaluates-access-control.html). S3 buckets and the objects they contain support three different types of access control: bucket ACLs, bucket policies, and object ACLs.
17
-
18
- As of January 2018, this resource supports evaluating S3 Object ACLs. In particular, users of the `be_public` matcher should carefully examine the conditions under which the matcher will detect an insecure bucket. See the `be_public` section under the Matchers section below.
19
-
20
- ## Availability
21
-
22
- ### Installation
23
-
24
- This resource is distributed along with InSpec itself. You can use it automatically.
25
-
26
- ### Version
27
-
28
- This resource first became available in v2.1.10 of InSpec.
29
-
30
- ## Syntax
31
-
32
- An `aws_s3_bucket_object` resource block declares a bucket and an object key by name, and then lists tests to be performed.
33
-
34
- describe aws_s3_bucket_object(bucket_name: 'test_bucket', key: 'test_object_key') do
35
- it { should exist }
36
- it { should_not be_public }
37
- end
38
-
39
- <br>
40
-
41
- ## Examples
42
-
43
- The following examples show how to use this InSpec audit resource.
44
-
45
- ### Test a object's object-level ACL
46
-
47
- describe aws_s3_bucket_object(bucket_name: 'test_bucket', key: 'test_key') do
48
- its('object_acl.count') { should eq 1 }
49
- end
50
-
51
- ### Check to see if a object appears to be exposed to the public
52
-
53
- # See Limitations section above
54
- describe aws_s3_bucket_object(bucket_name: 'test_bucket', key: 'test_key') do
55
- it { should_not be_public }
56
- end
57
- <br>
58
-
59
- ## Unsupported Properties
60
-
61
- ### object\_acl
62
-
63
- The `object_acl` property is a low-level property that lists the individual Object ACL grants that are in effect on the object. Other higher-level properties, such as be\_public, are more concise and easier to use. You can use the `object_acl` property to investigate which grants are in effect, causing be\_public to fail.
64
-
65
- The value of object_acl is an Array of simple objects. Each object has a `permission` property and a `grantee` property. The `permission` property will be a string such as 'READ', 'WRITE' etc (See the [AWS documentation](https://docs.aws.amazon.com/sdkforruby/api/Aws/S3/Client.html#get_bucket_acl-instance_method) for a full list). The `grantee` property contains sub-properties, such as `type` and `uri`.
66
-
67
-
68
- object_acl = aws_s3_bucket_object(bucket_name: 'my_bucket', key: 'object_key')
69
-
70
- # Look for grants to "AllUsers" (that is, the public)
71
- all_users_grants = object_acl.select do |g|
72
- g.grantee.type == 'Group' && g.grantee.uri =~ /AllUsers/
73
- end
74
-
75
- # Look for grants to "AuthenticatedUsers" (that is, any authenticated AWS user - nearly public)
76
- auth_grants = object_acl.select do |g|
77
- g.grantee.type == 'Group' && g.grantee.uri =~ /AuthenticatedUsers/
78
- end
79
-
80
- ## Matchers
81
-
82
- This InSpec audit resource has the following special matchers. For a full list of available matchers (such as `exist`) please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
83
-
84
- ### be\_public
85
-
86
- The `be_public` matcher tests if the object has potentially insecure access controls. This high-level matcher detects several insecure conditions, which may be enhanced in the future. Currently, the matcher reports an insecure object if any of the following conditions are met:
87
-
88
- 1. A object ACL grant exists for the 'AllUsers' group
89
- 2. A object ACL grant exists for the 'AuthenticatedUsers' group
90
-
91
- Note: This resource does not detect insecure bucket ACLs.
92
-
93
- it { should_not be_public }
94
-
95
- ## AWS Permissions
96
-
97
- Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `s3:GetObject`, and `s3:GetObjectAcl` actions set to allow.
98
-
99
- You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon S3](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazons3.html).
@@ -1,69 +0,0 @@
1
- ---
2
- title: About the aws_s3_buckets Resource
3
- ---
4
-
5
- # aws\_s3\_buckets
6
-
7
- Use the `aws_s3_buckets` InSpec audit resource to list all buckets in a single account.
8
-
9
- Use the `aws_s3_bucket` InSpec audit resource to perform in-depth auditing of a single S3 bucket.
10
-
11
- <br>
12
-
13
- ## Availability
14
-
15
- ### Installation
16
-
17
- This resource is distributed along with InSpec itself. You can use it automatically.
18
-
19
- ### Version
20
-
21
- This resource first became available in v2.1.30 of InSpec.
22
-
23
- ## Syntax
24
-
25
- An `aws_s3_buckets` resource block takes no arguments
26
-
27
- describe aws_s3_buckets do
28
- it { should exist }
29
- end
30
-
31
- <br>
32
-
33
- ## Examples
34
-
35
- The following examples show how to use this InSpec audit resource.
36
-
37
- As this is the initial release of `aws_s3_buckets`, its limited functionality precludes examples.
38
-
39
- <br>
40
-
41
- ## Matchers
42
-
43
- ### exists
44
-
45
- The control will pass if the resource contains at least one bucket.
46
-
47
- # Test if there are any buckets
48
- describe aws_s3_buckets
49
- it { should exist }
50
- end
51
-
52
- ## Properties
53
-
54
- ### bucket\_names
55
-
56
- Provides an array of strings containing the names of the buckets.
57
-
58
- # Examine what buckets have been created.
59
- describe aws_s3_buckets do
60
- its('bucket_names') { should eq ['my_bucket'] }
61
- # OR
62
- its('bucket_names') { should include 'my_bucket' }
63
- end
64
-
65
- ## AWS Permissions
66
-
67
- Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `s3:ListAllMyBuckets` action with Effect set to Allow.
68
-
69
- You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon S3](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazons3.html).
@@ -1,323 +0,0 @@
1
- ---
2
- title: About the aws_security_group Resource
3
- ---
4
-
5
- # aws\_security\_group
6
-
7
- Use the `aws_security_group` InSpec audit resource to test detailed properties of an individual Security Group (SG).
8
-
9
- SGs are a networking construct which contain ingress and egress rules for network communications. SGs may be attached to EC2 instances, as well as certain other AWS resources. Along with Network Access Control Lists, SGs are one of the two main mechanisms of enforcing network-level security.
10
-
11
- ## Limitations
12
-
13
- While this resource provides facilities for searching inbound and outbound rules on a variety of criteria, there is currently no support for performing matches based on:
14
-
15
- * References to other Security Groups
16
- * References to VPC peers or other AWS services (that is, no support for searches based on 'prefix lists').
17
-
18
- <br>
19
-
20
- ## Availability
21
-
22
- ### Installation
23
-
24
- This resource is distributed along with InSpec itself. You can use it automatically.
25
-
26
- ### Version
27
-
28
- This resource first became available in v2.0.16 of InSpec.
29
-
30
- ## Syntax
31
-
32
- Resource parameters: group_id, group_name, id, vpc_id
33
-
34
- An `aws_security_group` resource block uses resource parameters to search for and then test a Security Group. If no SGs match, no error is raised, but the `exists` matcher returns `false`, and all scalar properties are `nil`. List properties returned under these conditions are empty lists. If more than one SG matches (due to vague search parameters), an error is raised.
35
-
36
- # Ensure you have a Security Group with a specific ID
37
- # This is "safe" - SG IDs are unique within an account
38
- describe aws_security_group('sg-12345678') do
39
- it { should exist }
40
- end
41
-
42
- # Ensure you have a Security Group with a specific ID
43
- # This uses hash syntax
44
- describe aws_security_group(id: 'sg-12345678') do
45
- it { should exist }
46
- end
47
-
48
- # Ensure you have a Security Group with a specific name. Names are
49
- # unique within a VPC but not across VPCs.
50
- # Using only Group returns an error if multiple SGs match.
51
- describe aws_security_group(group_name: 'my-group') do
52
- it { should exist }
53
- end
54
- # Add vpc_id to ensure uniqueness.
55
- describe aws_security_group(group_name: 'my-group', vpc_id: 'vpc-12345678') do
56
- it { should exist }
57
- end
58
-
59
- <br>
60
-
61
- ## Examples
62
-
63
- The following examples show how to use this InSpec audit resource.
64
-
65
- # Ensure that the linux_servers Security Group permits
66
- # SSH from the 10.5.0.0/16 range, but not the world.
67
- describe aws_security_group(group_name: linux_servers) do
68
- # This passes if any inbound rule exists that specifies
69
- # port 22 and the given IP range, regardless of protocol, etc.
70
- it { should allow_in(port: 22, ipv4_range: '10.5.0.0/16') }
71
-
72
- # This passes so long as no inbound rule that specifies port 22 exists
73
- # with a source IP range of 0.0.0.0/0. Other properties are ignored.
74
- it { should_not allow_in(port: 22, ipv4_range: '0.0.0.0/0') }
75
-
76
- end
77
-
78
- # Ensure that the careful_updates Security Group may only initiate contact with specific IPs.
79
- describe aws_security_group(group_name: 'careful_updates') do
80
-
81
- # If you have two rules, with one CIDR each:
82
- [ '10.7.23.12/32', '10.8.23.12/32' ].each do |allowed_destination|
83
- # This doesn't care about which ports are enabled
84
- it { should allow_out(ipv4_range: allowed_destination) }
85
- end
86
-
87
- # If you have one rule with two CIDRs:
88
- it { should allow_out(ipv4_range: [ '10.7.23.12/32', '10.8.23.12/32' ] }
89
-
90
- # Expect exactly three rules.
91
- its('outbound_rules.count') { should cmp 3 }
92
- end
93
-
94
- <br>
95
-
96
- ## Resource Parameters
97
-
98
- This InSpec resource accepts the following parameters, which are used to search for the Security Group.
99
-
100
- ### id, group\_id
101
-
102
- The Security Group ID of the Security Group. This is of the format `sg-` followed by 8 hexadecimal characters. The ID is unique within your AWS account; using ID ensures a match of only one SG. The ID is also the default resource parameter, so you may omit the hash syntax.
103
-
104
- # Using Hash syntax
105
- describe aws_security_group(id: 'sg-12345678') do
106
- it { should exist }
107
- end
108
-
109
- # group_id is an alias for id
110
- describe aws_security_group(group_id: 'sg-12345678') do
111
- it { should exist }
112
- end
113
-
114
- # Or omit hash syntax, rely on it being the default parameter
115
- describe aws_security_group('sg-12345678') do
116
- it { should exist }
117
- end
118
-
119
- ### group\_name
120
-
121
- The string name of the Security Group. Every VPC has a Security Group named 'default'. Names are unique within a VPC, but not within an AWS account.
122
-
123
- # Get default Security Group for a specific VPC
124
- describe aws_security_group(group_name: 'default', vpc_id: vpc_id: 'vpc-12345678') do
125
- it { should exist }
126
- end
127
-
128
- # This throws an error if more than one VPC has a 'backend' SG.
129
- describe aws_security_group(group_name: 'backend') do
130
- it { should exist }
131
- end
132
-
133
- ### vpc\_id
134
-
135
- A string identifying the VPC that contains the Security Group. Since VPCs commonly contain many SGs, you should add additional parameters to ensure you find exactly one SG.
136
-
137
- # This throws an error if more than the default SG exists
138
- describe aws_security_group(vpc_id: 'vpc-12345678') do
139
- it { should exist }
140
- end
141
-
142
- <br>
143
- ## Properties
144
-
145
- * [`description`](#description), [`group_id`](#group_id), [`group_name`](#group_name), [`inbound_rules`](#inbound_rules), [`inbound_rules_count`](#inbound_rules_count), [`outbound_rules`](#outbound_rules), [`outbound_rules_count`](#outbound_rules_count), [`vpc_id`](#vpc_id)
146
-
147
- <br>
148
-
149
- ## Property Examples
150
-
151
- ### description
152
-
153
- A String reflecting the human-meaningful description that was given to the SG at creation time.
154
-
155
- # Require a description of a particular Security Group
156
- describe aws_security_group('sg-12345678') do
157
- its('description') { should_not be_empty }
158
- end
159
-
160
- ### group\_id
161
-
162
- Provides the Security Group ID.
163
-
164
- # Inspect the Security group ID of the default Group
165
- describe aws_security_group(group_name: 'default', vpc_id: vpc_id: 'vpc-12345678') do
166
- its('group_id') { should cmp 'sg-12345678' }
167
- end
168
-
169
- # Store the Group ID in a Ruby variable for use elsewhere
170
- sg_id = aws_security_group(group_name: 'default', vpc_id: vpc_id: 'vpc-12345678').group_id
171
-
172
- ### group\_name
173
-
174
- A String reflecting the name that was given to the SG at creation time.
175
-
176
- # Inspect the Group name of a particular Group
177
- describe aws_security_group('sg-12345678') do
178
- its('group_name') { should cmp 'my_group' }
179
- end
180
-
181
- ### inbound\_rules
182
-
183
- A list of the rules that the Security Group applies to incoming network traffic. This is a low-level property that is used by the [`allow_in`](#allow_in) and [`allow_in_only`](#allow_in_only) matchers; see them for detailed examples. `inbound_rules` is provided here for those wishing to use Ruby code to inspect the rules directly, instead of using higher-level matchers.
184
-
185
- Order is critical in these rules, as the sequentially first rule to match is applied to network traffic. By default, AWS includes a reject-all rule as the last inbound rule. This implicit rule does not appear in the inbound_rules list.
186
-
187
- If the Security Group could not be found (that is, `exists` is false), `inbound_rules` returns an empty list.
188
-
189
- describe aws_security_group(group_name: linux_servers) do
190
- its('inbound_rules.first') { should include(from_port: '22', ip_ranges: ['10.2.17.0/24']) }
191
- end
192
-
193
- ### inbound\_rules\_count
194
-
195
- A Number totalling the number of individual rules defined - It is a sum of the combinations of port, protocol, ipv4 rules, ipv6 rules and security group rules.
196
-
197
- describe aws_security_group(group_name: linux_servers) do
198
- its('inbound_rules_count'){ should eq 10 }
199
- end
200
-
201
- ### outbound\_rules
202
-
203
- A list of the rules that the Security Group applies to outgoing network traffic initiated by the AWS resource in the Security Group. This is a low-level property that is used by the [`allow_out`](#allow_out) matcher; see it for detailed examples. `outbound_rules` is provided here for those wishing to use Ruby code to inspect the rules directly, instead of using higher-level matchers.
204
-
205
- Order is critical in these rules, as the sequentially first rule to match is applied to network traffic. Outbound rules are typically used when it is desirable to restrict which portions of the internet, if any, a resource may access. By default, AWS includes an allow-all rule as the last outbound rule; note that Terraform removes this implicit rule.
206
-
207
- If the Security Group could not be found (that is, `exists` is false), `outbound_rules` returns an empty list.
208
-
209
- describe aws_security_group(group_name: isolated_servers) do
210
- its('outbound_rules.last') { should_not include(ip_ranges:['0.0.0.0/0']) }
211
- end
212
-
213
- ### outbound\_rules\_count
214
-
215
- A Number totalling the number of individual rules defined - It is a sum of the combinations of port, protocol, ipv4 rules, ipv6 rules and security group rules.
216
-
217
- describe aws_security_group(group_name: linux_servers) do
218
- its('outbound_rules_count'){ should eq 2 }
219
- end
220
-
221
- ### vpc\_id
222
-
223
- A String in the format 'vpc-' followed by 8 hexadecimal characters reflecting VPC that contains the Security Group.
224
-
225
- # Inspec the VPC ID of a particular Group
226
- describe aws_security_group('sg-12345678') do
227
- its('vpc_id') { should cmp 'vpc-12345678' }
228
- end
229
-
230
- <br>
231
-
232
- ## Matchers
233
-
234
- This InSpec audit resource has the following special matchers. For a full list of additional available matchers, please visit our [Universal Matchers page](https://www.inspec.io/docs/reference/matchers/).
235
-
236
- * [`allow_in`](#allow_in), [`allow_in_only`](#allow_in_only), [`allow_out`](#allow_out), [`allow_out_only`](#allow_out_only)
237
-
238
- ### allow\_in
239
-
240
- ### allow\_out
241
-
242
- ### allow\_in\_only
243
-
244
- ### allow\_out\_only
245
-
246
- The `allow` series of matchers enable you to perform queries about what network traffic would be permitted through the Security Group rule set.
247
-
248
- `allow_in` and `allow_in_exactly` examine inbound rules, and `allow_out` and `allow_out_exactly` examine outbound rules.
249
-
250
- `allow_in` and `allow_out` examine if at least one rule that matches the criteria exists. `allow_in` and `allow_out` also perform inexact (ie, range-based or subset-based) matching on ports and IP addresses ranges, allowing you to specify a candidate port or IP address and determine if it is covered by a rule.
251
-
252
- `allow_in_only` and `allow_out_only` examines if exactly one rule exists (but see `position`, below), and if it matches the criteria (this is useful for ensuring no unexpected rules have been added). Additionally, `allow_in_only` and `allow_out_only` do _not_ perform inexact matching; you must specify exactly the port range or IP address(es) you wish to match.
253
-
254
- The matchers accept a key-value list of search criteria. For a rule to match, it must match all provided criteria.
255
-
256
- * from_port - Determines if a rule exists whose port range begins at the specified number. The word 'from_' does *not* relate to inbound/outbound directionality; it relates to the port range ("counting _from_"). `from_port` is an exact criterion; so if the rule allows 1000-2000 and you specify a `from_port` of 1001, it does not match.
257
- * ipv4_range - Specifies an IPv4 address or subnet as a CIDR, or a list of them, to be checked as a permissible origin (for `allow_in`) or destination (for `allow_out`) for traffic. Each AWS Security Group rule may have multiple allowed source IP ranges.
258
- * ipv6_range - Specifies an IPv6 address or subnet as a CIDR, or a list of them, to be checked as a permissible origin (for `allow_in`) or destination (for `allow_out`) for traffic. Each AWS Security Group rule may have multiple allowed source IP ranges.
259
- * port - Determines if a particular TCP/IP port is reachable. allow_in and allow_out examine whether the specified port is included in the port range of a rule, while allow_in. You may specify the port as a string (`'22'`) or as a number.
260
- * position - A one-based index into the list of rules. If provided, this restricts the evaluation to the rule at that position. You may also use the special values `:first` and `:last`. `position` may also be used to enable `allow_in_only` and `allow_out_only` to work with multi-rule Security Groups.
261
- * protocol - Specifies the IP protocol. 'tcp', 'udp', and 'icmp' are some typical values. The string "-1" or 'any' is used to indicate any protocol.
262
- * to_port - Determines if a rule exists whose port range ends at the specified number. The word 'to_' does *not* relate to inbound/outbound directionality; it relates to the port range ("counting _to_"). `to_port` is an exact criterion; so if the rule allows 1000-2000 and you specify a `to_port` of 1999, it does not match.
263
-
264
- describe aws_security_group(group_name: 'mixed-functionality-group') do
265
- # Allow RDP from defined range
266
- it { should allow_in(port: 3389, ipv4_range: '10.5.0.0/16') }
267
- it { should allow_in(port: 3389, ipv6_range: '2001:db8::/122') }
268
-
269
- # Allow SSH from two ranges
270
- it { should allow_in(port: 22, ipv4_range: ['10.5.0.0/16', '10.2.3.0/24']) }
271
-
272
- # Check Bacula port range
273
- it { should allow_in(from_port: 9101, to_port: 9103, ipv4_range: '10.6.7.0/24') }
274
-
275
- # Assuming the AWS SG allows 9001-9003, use inexact matching to check 9002
276
- it { should allow_in(port: 9002) }
277
-
278
- # Assuming the AWS SG allows 10.2.1.0/24, use inexact matching to check 10.2.1.33/32
279
- it { should allow_in(ipv4_range: '10.2.1.33/32') }
280
-
281
- # Ensure the 3rd outbound rule is TCP-based
282
- it { should allow_in(protocol: 'tcp', position: 3') }
283
-
284
- # Do not allow unrestricted IPv4 access.
285
- it { should_not allow_in(ipv4_range: '0.0.0.0/0') }
286
- end
287
-
288
- # Suppose you have a Group that should allow SSH and RDP from
289
- # the admin network, 10.5.0.0/16. The resource has 2 rules to
290
- # allow this, and you want to ensure no others have been added.
291
- describe aws_security_group(group_name: 'admin-group') do
292
- # Allow RDP from a defined range and nothing else
293
- # The SG must have this rule in position 1 and it must match this exactly
294
- it { should allow_in_only(port: 3389, ipv4_range: '10.5.0.0/16', position: 1) }
295
-
296
- # Specify position 2 for the SSH rule. Without `position`,
297
- # allow_in_only only allows one rule, total.
298
- it { should allow_in_only(port: 22, ipv4_range: '10.5.0.0/16', position: 2) }
299
-
300
- # Because this is an _only matcher, this fails - _only matchers
301
- # use exact IP matching.
302
- it { should allow_in_only(port: 3389, ipv4_range: '10.5.1.34/32', position: 1) }
303
- end
304
-
305
- ### exists
306
-
307
- The control passes if the specified Security Group was found. Use `should_not` if you want to verify that the specified SG does not exist.
308
-
309
- # You always have at least one SG, the VPC default SG
310
- describe aws_security_group(group_name: 'default')
311
- it { should exist }
312
- end
313
-
314
- # Make sure we don't have any Security Groups with the name 'nogood'
315
- describe aws_security_group(group_name: 'nogood')
316
- it { should_not exist }
317
- end
318
-
319
- ## AWS Permissions
320
-
321
- Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ec2:DescribeSecurityGroups` action with Effect set to Allow.
322
-
323
- You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon EC2](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonec2.html).