Mirrors/inspec
2
0
Fork 0
mirror of https://github.com/inspec/inspec synced 2024-12-03 18:09:32 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #4674 from inspec/zenspider/website

Browse source 
Revamp www/doco setup
This commit is contained in:
Ryan Davis 2019-11-06 19:03:50 -08:00 committed by GitHub
commit e3402b9cc9
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
54 changed files with 82 additions and 6079 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
.expeditor/buildkite/wwwrelease.sh Executable file
View file

@ -0,0 +1,13 @@
#!/bin/bash
exit 0 # don't do this quite yet...
set -ue
echo "--- bundle install"
cd www
bundle install --jobs=7 --retry=3 --without tools maintenance deploy
echo "+++ bundle exec rake"
bundle exec rake www V=1 PUSH=1

8
.expeditor/config.yml
View file

@ -37,12 +37,6 @@ pipelines:
- CI_ENABLE_COVERAGE: true
- LANG: "C.UTF-8"
- SLOW: 1
- www/build:
description: Build website.
definition: .expeditor/wwwbuild.yml
- www/deploy:
description: Deploy website to inspec.io
definition: .expeditor/wwwdeploy.yml
- integration/resources:
description: Test core resources with test-kitchen.
definition: .expeditor/integration.resources.yml
@ -140,6 +134,8 @@ subscriptions:
- workload: artifact_published:unstable:inspec:{{version_constraint}}
actions:
- built_in:build_docker_image
- bash:.expeditor/buildkite/wwwrelease.sh:
post_commit: true
- workload: artifact_published:current:inspec:{{version_constraint}}
actions:
- built_in:tag_docker_image

0
.expeditor/wwwbuild.yml
View file

0
.expeditor/wwwdeploy.yml
View file

113
docs/resources/aws_billing_report.md.erb
View file

@ -1,113 +0,0 @@
---
title: About the aws_billing_report Resource
platform: aws
---
# aws\_billing\_report
Use the `aws_billing_report` Chef InSpec audit resource to test properties of a single AWS Cost and Billing report.
<br>
## Syntax
# Verify the time_unit used by the 'inspec1' Billing Report.
describe aws_billing_report('inspec1') do
its('time_unit') { should cmp 'daily' }
end
# Hash Syntax to verify the time_unit used by the 'inspec1' Billing Report.
describe aws_billing_report(report_name: 'inspec1') do
its('time_unit') { should cmp 'daily' }
end
## Properties
`report_name`, `time_unit`, `compression`, `s3_bucket`, `s3_prefix`, `s3_region`, `additional_artifacts`
<br>
## Propery Examples
### report_name
The report's name.
describe aws_billing_report('inspec1') do
its('report_name') { should cmp 'inspec1' }
end
### time_unit
The interval of time covered by the report. Valid values: hourly or daily.
describe aws_billing_report('inspec1') do
its('time_unit') { should cmp 'hourly' }
end
### compression
The reports compression type. Valid values: zip, or gzip.
describe aws_billing_report('inspec1') do
its('compression') { should cmp 'zip' }
end
### s3_bucket
The s3_bucket the report is stored in.
describe aws_billing_report('inspec1') do
its('s3_bucket') { should cmp 'inspec-s3-bucket' }
end
### s3_prefix
The prefix that AWS adds to the report when stored.
describe aws_billing_report('inspec1') do
its('s3_prefix') { should cmp 'inspec1' }
end
### s3_region
The AWS region of the S3 bucket.
describe aws_billing_report('inspec1') do
its('s3_region') { should cmp 'us-east-1' }
end
## Matchers
For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### be_hourly
If true, indicates that the report summarizes usage on a per-hour basis.
describe aws_billing_report('inspec1') do
it { should be_hourly }
end
### be_daily
If true, indicates that the report summarizes usage on a per-day basis.
describe aws_billing_report('inspec1') do
it { should be_daily }
end
### exist
Indicates that the Billing Report provided was found. Use `should_not` to test for Billing Reports that should not exist.
# Verify that the 'inspec1' Billing Report exists.
describe aws_billing_report('inspec1') do
it { should exist }
end
# Verify that the 'inspec2' Billing Report does not exist.
describe aws_billing_report('invalid-inspec') do
it { should_not exist }
end

93
docs/resources/aws_billing_reports.md.erb
View file

@ -1,93 +0,0 @@
---
title: About the aws_billing_reports Resource
platform: aws
---
# aws\_billing\_reports
Use the `aws_billing_reports` Chef InSpec audit resource to test properties of a some or all AWS Cost and Billing reports.
<br>
## Syntax
# Verify the number of Billing Reports in the AWS account.
describe aws_billing_reports do
its('count') { should cmp 2 }
end
# Use the .where clause to match a property to one or more rules in the available reports.
describe aws_billing_reports.where { report_name =~ /inspec.*/ } do
its('report_names') { should include 'inspec1' }
its('time_units') { should include 'DAILY' }
its('s3_buckets') { should include 'inspec1-s3-bucket' }
end
## Properties
`report_names`, `time_units`, `compressions`, `s3_buckets`, `s3_prefixs`, `s3_regions`
<br>
## Propery Examples
### report_names
A list of the names of the reports matched by the query.
describe aws_billing_reports do
its('report_names') { should include 'myreport' }
end
### time_units
A list of the time intervals of the reports matched by the query. Valid values: `hourly` or `daily`. This list is de-duplicated, so its count may not match the query count.
describe aws_billing_reports do
its('time_units') { should_not include 'hourly' }
end
### compressions
A list of the compression types of the reports matched by the query. Valid values: `zip`, or `gzip`. This list is de-duplicated, so its count may not match the query count.
describe aws_billing_reports do
its('compressions') { should_not include 'zip' }
end
### s3_buckets
A list of the S3 buckets the reports matched by the query are stored in. This list is de-duplicated, so its count may not match the query count.
describe aws_billing_reports do
its('s3_buckets') { should include 'some-s3-bucket'] }
end
### s3_prefixes
A list of the S3 prefixes (analogous to a directory on a filesystem) that the reports matched by the query are stored in. This list is de-duplicated, so its count may not match the query count.
describe aws_billing_reports do
its('s3_prefixes') { should include '/my/path/here' }
end
### s3_regions
A list of the S3 regions that reports matched by the query are stored in. This list is de-duplicated, so its count may not match the query count.
describe aws_billing_reports do
its('s3_regions') { should_not include 'us-west-1' }
end
## Matchers
For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### exist
Indicates that the query matched at least one report. Use `should_not` to test for Billing Reports that should not exist.
# Verify that at least one Billing Report exists.
describe aws_billing_reports
it { should exist }
end

165
docs/resources/aws_cloudtrail_trail.md.erb
View file

@ -1,165 +0,0 @@
---
title: About the aws_cloudtrail_trail Resource
platform: aws
---
# aws\_cloudtrail\_trail
Use the `aws_cloudtrail_trail` Chef InSpec audit resource to test properties of a single AWS Cloudtrail Trail.
AWS CloudTrail is a service that enables governance, compliance, operational auditing, and risk auditing of your AWS account. With CloudTrail, you can log, continuously monitor, and retain account activity related to actions across your AWS infrastructure. CloudTrail provides event history of your AWS account activity, including actions taken through the AWS Management Console, AWS SDKs, command line tools, and other AWS services. This event history simplifies security analysis, resource change tracking, and troubleshooting.
Each AWS Cloudtrail Trail is uniquely identified by its `trail_name` or `trail_arn`.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_cloudtrail_trail` resource block identifies a trail by `trail_name`.
# Find a trail by name
describe aws_cloudtrail_trail('trail-name') do
it { should exist }
end
# Hash syntax for trail name
describe aws_cloudtrail_trail(trail_name: 'trail-name') do
it { should exist }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test that the specified trail does exist
describe aws_cloudtrail_trail('trail-name') do
it { should exist }
end
### Test that the specified trail is encrypted using SSE-KMS
describe aws_cloudtrail_trail('trail-name') do
it { should be_encrypted }
end
### Test that the specified trail is a multi-region trail
describe aws_cloudtrail_trail('trail-name') do
it { should be_multi_region_trail }
end
<br>
## Properties
* `s3_bucket_name`, `trail_arn`, `cloud_watch_logs_role_arn`, `cloud_watch_logs_log_group_arn`, `kms_key_id`, `home_region`,
<br>
## Property Examples
### s3\_bucket\_name
Specifies the name of the Amazon S3 bucket designated for publishing log files.
describe aws_cloudtrail_trail('trail-name') do
its('s3_bucket_name') { should cmp "s3-bucket-name" }
end
### trail\_arn
The ARN identifier of the specified trail. An ARN uniquely identifies the trail within AWS.
describe aws_cloudtrail_trail('trail-name') do
its('trail_arn') { should cmp "arn:aws:cloudtrail:us-east-1:484747447281:trail/trail-name" }
end
### cloud\_watch\_logs\_role\_arn
Specifies the role for the CloudWatch Logs endpoint to assume to write to a user\'s log group.
describe aws_cloudtrail_trail('trail-name') do
its('cloud_watch_logs_role_arn') { should include "arn:aws:iam:::role/CloudTrail_CloudWatchLogs_Role" }
end
### cloud\_watch\_logs\_log\_group\_arn
Specifies a log group name using an Amazon Resource Name (ARN), a unique identifier that represents the log group to which CloudTrail logs will be delivered.
describe aws_cloudtrail_trail('trail-name') do
its('cloud_watch_logs_log_group_arn') { should include "arn:aws:logs:us-east-1::log-group:test:*" }
end
### kms\_key\_id
Specifies the KMS key ID to used to encrypt the logs delivered by CloudTrail.
describe aws_cloudtrail_trail('trail-name') do
its('kms_key_id') { should include "key-arn" }
end
### home\_region
Specifies the region in which the trail was created.
describe aws_cloudtrail_trail('trail-name') do
its('home_region') { should include "us-east-1" }
end
### delivered\_logs\_days\_ago
Specifies the number of days ago the CloudTrail delivered logs to CloudWatch Logs.
# Ensure the latest delivery time was recent
describe aws_cloudtrail_trail('trail-name') do
its('delivered_logs_days_ago') { should eq 0 }
end
<br>
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### be\_multi\_region\_trail
The test will pass if the identified trail is a multi-region trail.
describe aws_cloudtrail_trail('trail-name') do
it { should be_multi_region_trail }
end
### be\_encrypted
The test will pass if the logs delivered by the identified trail is encrypted.
describe aws_cloudtrail_trail('trail-name') do
it { should be_encrypted }
end
### be\_log\_file\_validation\_enabled
The test will pass if the identified trail has log file integrity validation is enabled.
describe aws_cloudtrail_trail('trail-name') do
it { should be_log_file_validation_enabled }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `cloudtrail:DescribeTrails` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for AWS CloudTrail](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awscloudtrail.html).

96
docs/resources/aws_cloudtrail_trails.md.erb
View file

@ -1,96 +0,0 @@
---
title: About the aws_cloudtrail_trails Resource
platform: aws
---
# aws\_cloudtrail\_trails
Use the `aws_cloudtrail_trails` Chef InSpec audit resource to test properties of some or all AWS CloudTrail Trails.
AWS CloudTrail is a service that enables governance, compliance, operational auditing, and risk auditing of your AWS account. With CloudTrail, you can log, continuously monitor, and retain account activity related to actions across your AWS infrastructure. CloudTrail provides event history of your AWS account activity, including actions taken through the AWS Management Console, AWS SDKs, command line tools, and other AWS services. This event history simplifies security analysis, resource change tracking, and troubleshooting.
Each AWS CloudTrail Trails is uniquely identified by its trail name or trail arn.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_cloudtrail_trails` resource block collects a group of CloudTrail Trails and then tests that group.
# Verify the number of CloudTrail Trails in the AWS account
describe aws_cloudtrail_trails do
its('entries.count') { should cmp 10 }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
As this is the initial release of `aws_cloudtrail_trails`, its limited functionality precludes examples.
<br>
## Properties
* `entries`, `names`, `trail_arns`
<br>
## Property Examples
### entries
Provides access to the raw results of the query. This can be useful for checking counts and other advanced operations.
# Allow at most 100 CloudTrail Trails on the account
describe aws_cloudtrail_trails do
its('entries.count') { should be <= 100}
end
### names
Provides a list of trail names for all CloudTrail Trails in the AWS account.
describe aws_cloudtrail_trails do
its('names') { should include('trail-1') }
end
### trail\_arns
Provides a list of trail arns for all CloudTrail Trails in the AWS account.
describe aws_cloudtrail_trails do
its('trail_arns') { should include('arn:aws:cloudtrail:us-east-1::trail/trail-1') }
end
<br>
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### exists
The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
# Verify that at least one CloudTrail Trail exists.
describe aws_cloudtrail_trails
it { should exist }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `cloudtrail:DescribeTrails` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for AWS CloudTrail](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awscloudtrail.html).

101
docs/resources/aws_cloudwatch_alarm.md.erb
View file

@ -1,101 +0,0 @@
---
title: About the aws_cloudwatch_alarm Resource
platform: aws
---
# aws\_cloudwatch\_alarm
Use the `aws_cloudwatch_alarm` Chef InSpec audit resource to test properties of a single Cloudwatch Alarm.
Cloudwatch Alarms are currently identified using the metric name and metric namespace. Future work may allow other approaches to identifying alarms.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_cloudwatch_alarm` resource block searches for a Cloudwatch Alarm, specified by several search options. If more than one Alarm matches, an error occurs.
# Look for a specific alarm
aws_cloudwatch_alarm(
metric_name: 'my-metric-name',
metric_namespace: 'my-metric-namespace',
) do
it { should exist }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Ensure an Alarm has at least one alarm action
describe aws_cloudwatch_alarm(
metric: 'my-metric-name',
metric_namespace: 'my-metric-namespace',
) do
its('alarm_actions') { should_not be_empty }
end
<br>
## Properties
* `alarm_actions`
## Property Examples
### alarm\_actions
`alarm_actions` returns a list of strings. Each string is the ARN of an action that will be taken should the alarm be triggered.
# Ensure that the alarm has at least one action
describe aws_cloudwatch_alarm(
metric: 'bed-metric',
metric_namespace: 'my-metric-namespace',
) do
its('alarm_actions') { should_not be_empty }
end
<br>
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### exists
The control will pass if a Cloudwatch Alarm could be found. Use `should_not` if you expect zero matches.
# Expect good metric
describe aws_cloudwatch_alarm(
metric: 'good-metric',
metric_namespace: 'my-metric-namespace',
) do
it { should exist }
end
# Disallow alarms based on bad-metric
describe aws_cloudwatch_alarm(
metric: 'bed-metric',
metric_namespace: 'my-metric-namespace',
) do
it { should_not exist }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `cloudwatch:DescribeAlarmsForMetric` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon CloudWatch](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazoncloudwatch.html).

164
docs/resources/aws_cloudwatch_log_metric_filter.md.erb
View file

@ -1,164 +0,0 @@
---
title: About the aws_cloudwatch_log_metric_filter Resource
platform: aws
---
# aws\_cloudwatch\_log\_metric\_filter
Use the `aws_cloudwatch_log_metric_filter` Chef InSpec audit resource to search for and test properties of individual AWS Cloudwatch Log Metric Filters.
A Log Metric Filter (LMF) is an AWS resource that observes log traffic, looks for a specified pattern, and then updates a metric about the number times the match occurs. The metric can also be connected to AWS Cloudwatch Alarms, so that actions can be taken when a match occurs.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_cloudwatch_log_metric_filter` resource block searches for an LMF, specified by several search options. If more than one log metric filter matches, an error occurs.
# Look for an LMF by its filter name and log group name. This combination
# will always either find at most one LMF - no duplicates.
describe aws_cloudwatch_log_metric_filter(
filter_name: 'my-filter',
log_group_name: 'my-log-group'
) do
it { should exist }
end
# Search for an LMF by pattern and log group.
# This could result in an error if the results are not unique.
describe aws_cloudwatch_log_metric_filter(
log_group_name: 'my-log-group',
pattern: 'my-filter'
) do
it { should exist }
end
<br>
## Filter Attributes
* `filter_name`, `log_group_name`, `pattern`
<br>
## Filter Examples
### filter\_name
This is the identifier of the log metric filter within its log group. To ensure you have a unique result, you must also provide the `log_group_name`.
describe aws_cloudwatch_log_metric_filter(
filter_name: 'my-filter'
) do
it { should exist }
end
### log\_group\_name
The name of the Cloudwatch Log Group that the LMF is watching. Together with `filter_name`, this uniquely identifies an LMF.
describe aws_cloudwatch_log_metric_filter(
log_group_name: 'my-log-group',
) do
it { should exist }
end
### pattern
The filter pattern used to match entries from the logs in the log group.
describe aws_cloudwatch_log_metric_filter(
pattern: '"ERROR" - "Exiting"',
) do
it { should exist }
end
<br>
## Properties
* `filter_name`, `log_group_name`,` metric_name`, `metric_namespace`, `pattern`
<br>
## Property Examples
### filter\_name
The name of the LMF within the `log_group`.
# Check the name of the LMF that has a certain pattern
describe aws_cloudwatch_log_metric_filter(
log_group_name: 'app-log-group',
pattern: 'KERBLEWIE',
) do
its('filter_name') { should cmp 'kaboom_lmf' }
end
### log\_group\_name
The name of the log group that the LMF is watching.
# Check which log group the LMF 'error-watcher' is watching
describe aws_cloudwatch_log_metric_filter(
filter_name: 'error-watcher',
) do
its('log_group_name') { should cmp 'app-log-group' }
end
### metric\_name, metric\_namespace
The name and namespace of the Cloudwatch Metric that will be updated when the LMF matches. You also need the `metric_namespace` to uniquely identify the metric.
# Ensure that the LMF has the right metric name
describe aws_cloudwatch_log_metric_filter(
filter_name: 'my-filter',
log_group_name: 'my-log-group',
) do
its('metric_name') { should cmp 'MyMetric' }
its('metric_namespace') { should cmp 'MyFantasticMetrics' }
end
### pattern
The pattern used to match entries from the logs in the log group.
# Ensure that the LMF is watching for errors
describe aws_cloudwatch_log_metric_filter(
filter_name: 'error-watcher',
log_group_name: 'app-log-group',
) do
its('pattern') { should cmp 'ERROR' }
end
<br>
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### exist
Matches (i.e., passes the test) if the resource parameters (search criteria) were able to locate exactly one LMF.
describe aws_cloudwatch_log_metric_filter(
log_group_name: 'my-log-group',
) do
it { should exist }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `cloudwatch:DescribeAlarmsForMetric` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon CloudWatch](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazoncloudwatch.html).

111
docs/resources/aws_config_delivery_channel.md.erb
View file

@ -1,111 +0,0 @@
---
title: About the aws_config_delivery_channel Resource
---
# aws\_config\_delivery\_channel
The AWS Config service can monitor and record changes to your AWS resource configurations. A Delivery Channel can record the changes
to an S3 Bucket, an SNS or both.
Use the `aws_config_delivery_channel` Chef InSpec audit resource to examine how the AWS Config service delivers those change notifications.
As of April 2018, each AWS region may have only one Delivery Channel.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.1.21 of InSpec.
## Resource Parameters
An `aws_config_delivery_channel` resource block declares the tests for a single AWS Config Delivery Channel.
You may specify the Delivery Channel name:
describe aws_config_delivery_channel('my_channel') do
it { should exist }
end
describe aws_config_delivery_channel(channel_name: 'my-channel') do
it { should exist }
end
However, since you may only have one Delivery Channel per region, and Chef InSpec connections are per-region, you may also omit the `channel_name` to obtain the one Delivery Channel (if any) that exists:
describe aws_config_delivery_channel do
it { should exist }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test how frequently the channel writes configuration changes to the s3 bucket.
describe aws_config_delivery_channel(channel_name: 'my-recorder') do
its(delivery_frequency_in_hours) { should be > 3 }
end
## Properties
### channel\_name
Returns the name of the Delivery Channel.
describe aws_config_delivery_channel do
its('channel_name') { should cmp 'my-channel' }
end
### delivery\_frequency\_in\_hours
Provides how often the AWS Config sends configuration changes to the s3 bucket in the delivery channel.
describe aws_config_delivery_channel(channel_name: 'my_channel')
its('delivery_frequency_in_hours') { should eq 24 }
its('delivery_frequency_in_hours') { should be > 24 }
end
### s3\_bucket\_name
Provides the name of the s3 bucket that the channel sends configuration changes to. This is an optional value since a Delivery Channel can also talk to an SNS.
describe aws_config_delivery_channel(channel_name: 'my_channel')
its('s3_bucket_name') { should eq 'my_bucket' }
end
### s3\_key\_prefix
Provides the s3 object key prefix (or "path") under which configuration data will be recorded.
describe aws_config_delivery_channel(channel_name: 'my_channel')
its('s3_key_prefix') { should eq 'log/' }
end
### sns\_topic\_arn
Provides the ARN of the SNS topic for which the channel sends notifications about configuration changes.
describe aws_config_delivery_channel(channel_name: 'my_channel')
its('sns_topic_arn') { should eq 'arn:aws:sns:us-east-1:721741954427:sns_topic' }
end
<br>
## Matchers
This resource provides no matchers, aside from the standard `exist` matcher.
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `config:DescribeDeliveryChannels` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for AWS Config](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awsconfig.html).

96
docs/resources/aws_config_recorder.md.erb
View file

@ -1,96 +0,0 @@
---
title: About the aws_config_recorder Resource
---
# aws\_config\_recorder
Use the `aws_config_recorder` Chef InSpec audit resource to test properties of your AWS Config Service.
The AWS Config service can monitor and record changes to your AWS resource configurations. The Aws Config Recorder is used to detect changes in resource configurations and capture these changes as configuration items.
As of April 2018, you are only permitted one configuration recorder per region.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.32 of InSpec.
## Resource Parameters
An `aws_config_recorder` resource block declares the tests for a single AWS configuration recorder.
You may specify a recorder by name:
describe aws_config_recorder('my_recorder') do
it { should exist }
end
describe aws_config_recorder(recorder_name: 'my-recorder') do
it { should exist }
end
However, since you may only have one recorder per region, and Chef InSpec connections are per-region, you may also omit the `recorder_name` to obtain the one recorder (if any) that exists:
describe aws_config_recorder do
it { should exist }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test if the recorder is active and recording.
describe aws_config_recorder(recorder_name: 'my-recorder') do
it { should be_recording }
end
## Properties
### role\_arn
Provides the IAM role arn associated with the configuration recorder. The role is used to grant permissions to S3 Buckets, SNS topics and to get configuration details for supported AWS resources.
describe aws_config_recorder(username: 'bob')
its('role_arn') { should eq 'arn:aws:iam::721741954427:role/My_Recorder' }
end
### resource\_types
Provides a list of AWS resource types for which the AWS Config records configuration will change. Note that if be_recording_all_resource_types is true than this property is meaningless and will return and empty array.
describe aws_config_recorder(username: 'bob')
its('resource_types') { should include 'AWS::EC2::CustomerGateway' }
its('resource_types') { should include 'AWS::EC2::EIP' }
end
<br>
## Matchers
### be\_recording\_all\_resource\_types
Indicates if the ConfigurationRecorder will record changes for all resources, regardless of type. If this is true, resource_types is ignored.
it { should be_recording_all_resource_types }
### be\_recording\_all\_global\_types
Indicates whether the ConfigurationRecorder will record changes for global resource types (such as [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal)s).
it { should be_recording_all_global_types }
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `config:DescribeConfigurationRecorders` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for AWS Config](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awsconfig.html).

76
docs/resources/aws_ebs_volume.md.erb
View file

@ -1,76 +0,0 @@
---
title: About the aws_ebs_volume Resource
platform: aws
---
# aws\_ebs\_volume
Use the `aws_ebs_volume` Chef InSpec audit resource to test properties of a single AWS EBS volume.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
## Syntax
An `aws_ebs_volume` resource block declares the tests for a single AWS EBS volume by either name or id.
describe aws_ebs_volume('vol-01a2349e94458a507') do
it { should exist }
end
describe aws_ebs_volume(name: 'data-vol') do
it { should be_encrypted }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test that an EBS Volume does not exist
describe aws_ebs_volume(name: 'data_vol') do
it { should_not exist }
end
### Test that an EBS Volume is encrypted
describe aws_ebs_volume(name: 'secure_data_vol') do
it { should be_encrypted }
end
### Test that an EBS Volume the correct size
describe aws_ebs_volume(name: 'data_vol') do
its('size') { should cmp 32 }
end
<br>
## Properties
* `availability_zone`, `encrypted`, `iops`, `kms_key_id`, `size`, `snapshot_id`, `state`, `volume_type`
<br>
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### be\_encrypted
The `be_encrypted` matcher tests if the described EBS Volume is encrypted.
it { should be_encrypted }
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ec2:DescribeVolumes`, and `iam:GetInstanceProfile` actions set to allow.
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), and [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

86
docs/resources/aws_ebs_volumes.md.erb
View file

@ -1,86 +0,0 @@
---
title: About the aws_ebs_volumes Resource
platform: aws
---
# aws\_ebs\_volumes
Use the `aws_ebs_volumes` Chef InSpec audit resource to test properties of some or all AWS EBS volumes. To audit a single EBS volume, use `aws_ebs_volume` (singular).
EBS volumes are persistent block storage volumes for use with Amazon EC2 instances in the AWS Cloud.
Each EBS volume is uniquely identified by its ID.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
## Syntax
An `aws_ebs_volumes` resource block collects a group of EBS volumes and then tests that group.
# Ensure you have exactly 3 volumes
describe aws_ebs_volumes do
its('volume_ids.count') { should cmp 3 }
end
# Use the Chef InSpec resource to enumerate IDs, then test in-depth using `aws_ebs_volume`.
aws_ebs_volumes.volume_ids.each do |volume_id|
describe aws_ebs_volume(volume_id) do
it { should exist }
it { should be_encrypted }
its('size') { should cmp 8 }
its('iops') { should cmp 100 }
end
end
<br>
## Examples
As this is the initial release of `aws_ebs_volumes`, its limited functionality precludes examples.
<br>
## Filter Criteria
This resource currently does not support any filter criteria; it will always fetch all volumes in the region.
## Properties
### entries
Provides access to the raw results of the query, which can be treated as an array of hashes. This can be useful for checking counts and other advanced operations.
# Allow at most 100 EBS volumes on the account
describe aws_ebs_volumes do
its('entries.count') { should be <= 100 }
end
### volume_ids
Provides a list of the volume ids that were found in the query.
describe aws_ebs_volumes do
its('volume_ids') { should include 'vol-12345678' }
its('volume_ids.count') { should cmp 3 }
end
<br>
## Matchers
For a full list of available matchers, please visit our [Universal Matchers page](https://www.inspec.io/docs/reference/matchers/).
### exist
The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
# Verify that at least one EBS volume exists
describe aws_ebs_volumes do
it { should exist }
end

122
docs/resources/aws_ec2_instance.md.erb
View file

@ -1,122 +0,0 @@
---
title: About the aws_ec2_instance Resource
platform: aws
---
# aws\_ec2\_instance
Use the `aws_ec2_instance` Chef InSpec audit resource to test properties of a single AWS EC2 instance.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_ec2_instance` resource block declares the tests for a single AWS EC2 instance by either name or id.
describe aws_ec2_instance('i-01a2349e94458a507') do
it { should exist }
end
describe aws_ec2_instance(name: 'my-instance') do
it { should be_running }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test that an EC2 instance does not exist
describe aws_ec2_instance(name: 'dev-server') do
it { should_not exist }
end
### Test that an EC2 instance is running
describe aws_ec2_instance(name: 'prod-database') do
it { should be_running }
end
### Test that an EC2 instance is using the correct image ID
describe aws_ec2_instance(name: 'my-instance') do
its('image_id') { should eq 'ami-27a58d5c' }
end
### Test that an EC2 instance has the correct tag
describe aws_ec2_instance('i-090c29e4f4c165b74') do
its('tags') { should include(key: 'Contact', value: 'Gilfoyle') }
end
<br>
## Properties
* `architecture`, `client_token`, `image_id`,`instance_type`, `key_name`, `launch_time`,`private_ip_address`, `private_dns_name`, `public_dns_name`, `public_ip_address`, `root_device_type`, `root_device_name`, `security_group_ids`, `subnet_id`, `tags`,`virtualization_type`, `vpc_id`
<br>
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### be\_pending
The `be_pending` matcher tests if the described EC2 instance state is `pending`. This indicates that an instance is provisioning. This state should be temporary.
it { should be_pending }
### be\_running
The `be_running` matcher tests if the described EC2 instance state is `running`. This indicates the instance is fully operational from AWS's perspective.
it { should be_running }
### be\_shutting\_down
The `be_shutting_down` matcher tests if the described EC2 instance state is `shutting-down`. This indicates the instance has received a termination command and is in the process of being permanently halted and de-provisioned. This state should be temporary.
it { should be_shutting_down }
### be\_stopped
The `be_stopped` matcher tests if the described EC2 instance state is `stopped`. This indicates that the instance is suspended and may be started again.
it { should be_stopped }
### be\_stopping
The `be_stopping` matcher tests if the described EC2 instance state is `stopping`. This indicates that an AWS stop command has been issued, which will suspend the instance in an OS-unaware manner. This state should be temporary.
it { should be_stopping }
### be\_terminated
The `be_terminated` matcher tests if the described EC2 instance state is `terminated`. This indicates the instance is permanently halted and will be removed from the instance listing in a short period. This state should be temporary.
it { should be_terminated }
### be\_unknown
The `be_unknown` matcher tests if the described EC2 instance state is `unknown`. This indicates an error condition in the AWS management system. This state should be temporary.
it { should be_unknown }
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ec2:DescribeInstances`, and `iam:GetInstanceProfile` actions set to allow.
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), and [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

89
docs/resources/aws_ec2_instances.md.erb
View file

@ -1,89 +0,0 @@
---
title: About the aws_ec2_instances Resource
platform: aws
---
# aws\_ec2\_instances
Use the `aws_ec2_instances` Chef InSpec audit resource to test properties of some or all AWS EC2 instances. To audit a single EC2 instance, use `aws_ec2_instance` (singular).
EC2 instances are the basic unit of computing within AWS. An instance is a virtual machine that contains a running OS, and may be created or destroyed by code.
Each EC2 instance is uniquely identified by its ID.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.1.72 of InSpec.
## Syntax
An `aws_ec2_instances` resource block collects a group of EC2 Instances and then tests that group.
# Ensure you have exactly 3 instances
describe aws_ec2_instances do
its('instance_ids.count') { should cmp 3 }
end
# Use the Chef InSpec resource to enumerate IDs, then test in-depth using `aws_ec2_instance`.
aws_ec2_instances.instance_ids.each do |instance_id|
describe aws_ec2_instance(instance_id) do
its('key_name') { should cmp 'admin-ssh-key' }
end
end
<br>
## Examples
As this is the initial release of `aws_ec2_instances`, its limited functionality precludes examples.
<br>
## Filter Criteria
This resource currently does not support any filter criteria; it will always fetch all instances in the region.
## Properties
### entries
Provides access to the raw results of the query, which can be treated as an array of hashes. This can be useful for checking counts and other advanced operations.
# Allow at most 100 EC2 Instances on the account
describe aws_ec2_instances do
its('entries.count') { should be <= 100}
end
### instance_ids
Provides a list of the instance ids that were found in the query.
describe aws_ec2_instances do
its('instance_ids') { should include('i-12345678') }
its('instance_ids.count') { should cmp 3) }
end
<br>
## Matchers
For a full list of available matchers, please visit our [Universal Matchers page](https://www.inspec.io/docs/reference/matchers/).
### exist
The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
# Verify that at least one EC2 Instance exists.
describe aws_ec2_instances
it { should exist }
end

190
docs/resources/aws_eks_cluster.md.erb
View file

@ -1,190 +0,0 @@
## Resource Parameters
An `aws_eks_cluster` resource block declares the tests for a single EKS Cluster by Cluster name.
describe aws_eks_cluster('my-eks') do
it { should exist }
end
describe aws_eks_cluster(cluster_name: 'my-eks') do
its('status') { should eq 'ACTIVE' }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test that an EKS Cluster does not exist
describe aws_eks_cluster('bad-eks') do
it { should_not exist }
end
### Test that an EKS Cluster has at least 2 subnets
describe aws_eks_cluster('my-cluster') do
its('subnets_count') { should be > 1 }
end
<br>
## Properties
### version
Returns a string identifying the version of the EKS Cluster.
# Verify the version is 1.5
describe aws_eks_cluster('my-cluster') do
its('version') { should cmp '1.5' }
end
### arn
Returns the ARN of the cluster. This is the Amazon resource name.
# Verify the arn is what we expect it to be
describe aws_eks_cluster('my-cluster') do
its('arn') { should eq 'arn:aws:eks:ab-region-1:012345678910:cluster/kangaroo' }
end
### name
The name of the EKS cluster within AWS. The EKS name is unique within the region.
# Ensure that the EKS's name is what we said it was
describe aws_eks_cluster('my-cluster') do
its('name') { should match /my-cluster/ }
end
### status
Returns a string containing the current status of the cluster, possible values are: CREATING,ACTIVE,DELETING,FAILED.
# ensure the cluster is available or being created
describe aws_eks_cluster('my-cluster') do
its('status') { should be_in %w(ACTIVE CREATING) }
end
Status can also be called with predicates.
# ensure the cluster is available
describe aws_eks_cluster('my-cluster') do
it { should be_active }
end
# ensure the cluster is being removed
describe aws_eks_cluster('my-cluster') do
it { should be_deleting }
end
### endpoint
Returns a string with the K8s API server endpoint. The endpoint is used by kubectl to control the cluster.
# Ensure that the endpoint is what we expect it to be
describe aws_eks_cluster('my-cluster') do
its('endpoint') { should eq 'https://A0DCCD80A04F01705DD065655C30CC3D.yl4.aq-south-2.eks.amazonaws.com' }
end
### security\_group\_ids
Returns an array of strings reflecting the security group IDs (firewall rule sets) assigned to the EKS Cluster VPC.
# Ensure that a specific SG ID is assigned
describe aws_eks_cluster('my-cluster') do
its('security_group_ids') { should include 'sg-12345678' }
end
### subnet\_ids
Returns an array of strings reflecting the subnet IDs on which the EKS Cluster VPC is located.
# Ensure that the EKS VPC is on a specific subnet
describe aws_eks_cluster('my-cluster') do
its('subnet_ids') { should include 'subnet-12345678' }
end
### vpc\_id
Returns a String reflecting the ID of the VPC in which the EKS Cluster is located.
# Ensure that the EKS Cluster is on a specific VPC
describe aws_eks_cluster('my-cluster') do
its('vpc_id') { should cmp 'vpc-12345678' }
end
### role\_arn
Returns a String reflecting the Amazon resource name of the Amazon EKS Service IAM role the cluster is using.
# Ensure that the EKS Cluster is using a specific IAM role
describe aws_eks_cluster('my-cluster') do
its('role_arn') { should cmp 'rn:aws:iam::012345678910:role/eks-service-role-AWSServiceRoleForAmazonEKS-J7ONKE3BQ4PI' }
end
### certificate\_authority
Returns a String reflecting the certificate authority data used by kubectl to identify to the cluster.
# Ensure that the EKS Cluster is using specific certificate authority data
describe aws_eks_cluster('my-cluster') do
its('certificate_authority') { should cmp 'LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUN5RENDQWJDZ0F3SUJBZ0lCQURBTkJna3Foa2lHOXcwQkFRc0ZBREFWTVJNd0VRWURWUVFERXdwcmRXSmwKY201bGRHVnpNQjRYRFRFNE1EVXpNVEl6TVRFek1Wb1hEVEk0TURVeU9ESXpNVEV6TVZvd0ZURVRNQkVHQTFVRQpBeE1LYTNWaVpYSnVaWFJsY3pDQ0FTSXdEUVlKS29aSWh2Y05BUUVCQlFBRGdnRVBBRENDQVFvQ2dnRUJBTTZWCjVUaG4rdFcySm9Xa2hQMzRlVUZMNitaRXJOZGIvWVdrTmtDdWNGS2RaaXl2TjlMVmdvUmV2MjlFVFZlN1ZGbSsKUTJ3ZURyRXJiQyt0dVlibkFuN1ZLYmE3ay9hb1BHekZMdmVnb0t6b0M1N2NUdGVwZzRIazRlK2tIWHNaME10MApyb3NzcjhFM1ROeExETnNJTThGL1cwdjhsTGNCbWRPcjQyV2VuTjFHZXJnaDNSZ2wzR3JIazBnNTU0SjFWenJZCm9hTi8zODFUczlOTFF2QTBXb0xIcjBFRlZpTFdSZEoyZ3lXaC9ybDVyOFNDOHZaQXg1YW1BU0hVd01aTFpWRC8KTDBpOW4wRVM0MkpVdzQyQmxHOEdpd3NhTkJWV3lUTHZKclNhRXlDSHFtVVZaUTFDZkFXUjl0L3JleVVOVXM3TApWV1FqM3BFbk9RMitMSWJrc0RzQ0F3RUFBYU1qTUNFd0RnWURWUjBQQVFIL0JBUURBZ0trTUE4R0ExVWRFd0VCCi93UUZNQU1CQWY4d0RRWUpLb1pJaHZjTkFRRUxCUUFEZ2dFQkFNZ3RsQ1dIQ2U2YzVHMXl2YlFTS0Q4K2hUalkKSm1NSG56L2EvRGt0WG9YUjFVQzIrZUgzT1BZWmVjRVZZZHVaSlZCckNNQ2VWR0ZkeWdBYlNLc1FxWDg0S2RXbAp1MU5QaERDSmEyRHliN2pVMUV6VThTQjFGZUZ5ZFE3a0hNS1E1blpBRVFQOTY4S01hSGUrSm0yQ2x1UFJWbEJVCjF4WlhTS1gzTVZ0K1Q0SU1EV2d6c3JRSjVuQkRjdEtLcUZtM3pKdVVubHo5ZEpVckdscEltMjVJWXJDckxYUFgKWkUwRUtRNWEzMHhkVWNrTHRGQkQrOEtBdFdqSS9yZUZPNzM1YnBMdVoyOTBaNm42QlF3elRrS0p4cnhVc3QvOAppNGsxcnlsaUdWMm5SSjBUYjNORkczNHgrYWdzYTRoSTFPbU90TFM0TmgvRXJxT3lIUXNDc2hEQUtKUT0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=',
' }
end
### subnets\_count
Returns the number of subnets associated with the Cluster VPC.
# Test that an EKS Cluster has 2 subnets
describe aws_eks_cluster('my-cluster') do
its('subnets_count') { should eq 2 }
end
### created_at
Returns a Time object for the time the cluster was created at.
# Test that an EKS Cluster was created after a certain date
describe aws_eks_cluster('my-cluster') do
its('created_at') { should be > Time.new(2011) }
end
### security\_groups\_count
Returns the number of security groups associated with the Cluster VPC.
# Test that an EKS Cluster has 2 security groups
describe aws_eks_cluster('my-cluster') do
its('security_groups_count') { should eq 2 }
end
### integration with other resources
Using the resource together with other AWS resources.
# find the default security group for our VPC
my_vpc_id = aws_eks_cluster('my-cluster').vpc_id
default_security_group = aws_security_group(group_name: 'default', vpc_id: my_vpc_id)
# make sure we are not using the default security group
describe aws_eks_cluster('my-cluster') do
its('security_group_ids') { should_not include default_security_group.group_id }
end
<br>
## Matchers
This Chef InSpec audit resource has no special matchers. For a full list of available matchers, please visit our [Universal Matchers page](https://www.inspec.io/docs/reference/matchers/).
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `eks:DescribeCluster` action set to Allow.
You can find detailed documentation at [Amazon EKS IAM Policies, Roles, and Permissions](https://docs.aws.amazon.com/eks/latest/userguide/IAM_policies.html)
The documentation for EKS actions is at [Policy Structure](https://docs.aws.amazon.com/eks/latest/userguide/iam-policy-structure.html#UsingWithEKS_Actions)

154
docs/resources/aws_elb.md.erb
View file

@ -1,154 +0,0 @@
---
title: About the aws_elb Resource
platform: aws
---
# aws\_elb
Use the `aws_elb` Chef InSpec audit resource to test properties of a single AWS Elastic Load Balancer (ELB, also known as a Classic Load Balancer).
To audit ELBs in bulk or to search, use `aws_elbs` (plural).
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.2.10 of InSpec.
## Resource Parameters
An `aws_elb` resource block declares the tests for a single AWS ELB by ELB name.
describe aws_elb('my-elb') do
it { should exist }
end
describe aws_elb(elb_name: 'my-elb') do
its('instance_ids.count') { should cmp 2 }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test that an ELB does not exist
describe aws_elb('bad-elb') do
it { should_not exist }
end
### Test that an ELB has a presence in at least two availability zones
describe aws_elb('web') do
its('availability_zones.count') { should be > 1 }
end
<br>
## Properties
### availability\_zones
Returns an array of strings identifying which availability zones in which the load balancer is located.
# Verify we are in both us-east-2a and us-east-2b
describe aws_elb('web-elb') do
its('availability_zones') { should include 'us-east-2a' }
its('availability_zones') { should include 'us-east-2b' }
end
### dns\_name
Returns the FQDN of the load balancer. This is the hostname which is exposed to the world.
# Ensure that the ELB has a DNS name
describe aws_elb('web-elb') do
its('dns_name') { should match /\.com/ }
end
### elb\_name
The name of the ELB within AWS. The ELB name is unique within the region.
# Ensure that the ELB's name is what we said it was
describe aws_elb('web-elb') do
its('elb_name') { should match /web-elb/ }
end
### external\_ports
Returns an array of integers reflecting the public-facing ports on which the load balancer will be listening for traffic.
# Ensure that we are listening on port 80 and nothing else
describe aws_elb('web-elb') do
its('external_ports') { should include 80 }
its('external_ports.count') { should cmp 1 }
end
### instance\_ids
Returns an array of strings reflecting the instance IDs of the EC2 instances attached to the ELB.
# Ensure that a specific instance is attached
describe aws_elb('web-elb') do
its('instance_ids') { should include 'i-12345678' }
end
### internal\_ports
Returns an array of integers reflecting the EC2-facing ports on which the load balancer will be sending traffic to.
# Ensure that we are sending traffic to port 80 on the instances and nothing else
describe aws_elb('web-elb') do
its('internal_ports') { should include 80 }
its('internal_ports.count') { should cmp 1 }
end
### security\_group\_ids
Returns an array of strings reflecting the security group IDs (firewall rule sets) assigned to the ELB.
# Ensure that a specific SG ID is assigned
describe aws_elb('web-elb') do
its('security_group_ids') { should include 'sg-12345678' }
end
### subnet\_ids
Returns an array of strings reflecting the subnet IDs on which the ELB is located.
# Ensure that the ELB is on a specific subnet
describe aws_elb('web-elb') do
its('subnet_ids') { should include 'subnet-12345678' }
end
### vpc\_id
Returns a String reflecting the ID of the VPC in which the ELB is located.
# Ensure that the ELB is on a specific VPC
describe aws_elb('web-elb') do
its('vpc_id') { should cmp 'vpc-12345678' }
end
<br>
## Matchers
This Chef InSpec audit resource has no special matchers. For a full list of available matchers, please visit our [Universal Matchers page](https://www.inspec.io/docs/reference/matchers/).
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `elasticloadbalancing:DescribeLoadBalancers` action set to Allow.
You can find detailed documentation at [Authentication and Access Control for Your Load Balancers](https://docs.aws.amazon.com/elasticloadbalancing/latest/userguide/load-balancer-authentication-access-control.html)

252
docs/resources/aws_elbs.md.erb
View file

@ -1,252 +0,0 @@
---
title: About the aws_elbs Resource
platform: aws
---
# aws\_elbs
Use the `aws_elbs` Chef InSpec audit resource to test properties of AWS Elastic Load Balancers (ELBs, also known as a Classic Load Balancers) in bulk, or to search for a group of them based on their properties.
To audit a specific ELB in detail when its name is known, use `aws_elb` (singular).
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.2.10 of InSpec.
## Syntax
An `aws_elb` resource block uses an optional filter to select a group of ELBs and then tests that group.
# Check that you have at aleast one ELB
describe aws_elbs do
it { should exist }
end
# Ensure that you have at least one ELB in a specific VPC
describe aws_elb.where(vpc_id: 'vpc-12345678') do
it { should exist }
end
<br>
## Filter Criteria
Use filter criteria with `where` to search for ELBs by their properties. `where` may be used in method mode (as in `aws_elbs.where(criterion: value)`) or in block mode (as in `aws_elbs.where { any code here }`). Several criteria on this resource may only be used with block-mode, because they are list-based.
### availability\_zones
An array of strings identifying which availability zones in which the load balancer is located. This criterion must be used with block-mode `where`.
# Find ELBs with a footprint in us-east-2a
describe aws_elbs.where { availability_zones.include? 'us-east-2a' } do
it { should exist }
end
### dns\_name
Returns the FQDN of the load balancer. This is the hostname which is exposed to the world.
# Find ELBs that have the letter z in their DNS name
describe aws_elbs.where(dns_name: /z/) do
it { should exist }
end
### elb\_name
The name of the ELB within AWS. The ELB name is unique within the region. If you know the full ELB name, you should use the `aws_elb` resource instead, as it is much more efficient for testing a specific ELB.
# Find ELBs whose name ends in `prod`
describe aws_elbs.where(elb_name: /prod$/) do
it { should exist }
end
### external\_ports
An array of integers reflecting the public-facing ports on which the load balancer will be listening for traffic. This criterion must be used with block-mode `where`.
# Find ELBs listening on port 80
describe aws_elbs.where { external_ports.include? 80 } do
it { should exist }
end
### instance\_ids
An array of strings reflecting the instance IDs of the EC2 instances attached to the ELB. This criterion must be used with block-mode `where`.
# Find ELBs with at least 3 instances
describe aws_elbs.where { instance_ids.count > 2 } do
it { should exist }
end
### internal\_ports
An array of integers reflecting the EC2-facing ports on which the load balancer will be sending traffic to. This criterion must be used with block-mode `where`.
# Find ELBs sending traffic to port 80
describe aws_elbs.where { internal_ports.include? 80 } do
it { should exist }
end
### security\_group\_ids
An array of strings reflecting the security group IDs (firewall rule sets) assigned to the ELB. This criterion must be used with block-mode `where`.
# Find ELBs using a particular security group
describe aws_elbs.where { security_group_ids.include? 'sg-12345678' } do
it { should exist }
end
### subnet\_ids
An array of strings reflecting the subnet IDs on which the ELB is located. This criterion must be used with block-mode `where`.
# Find ELBs located on a particular subnet
describe aws_elbs.where { subnet_ids.include? 'subnet-12345678' } do
it { should exist }
end
### vpc\_id
A String reflecting the ID of the VPC in which the ELB is located.
# Find all ELBs in a specific VPC.
describe aws_elbs.where(vpc_id: 'vpc-12345678') do
it { should exist }
end
<br>
## Properties
### availability\_zones
An array of strings identifying which availability zones in which the selected load balancers are located. The array is de-duplicated.
# Ensure none of our ELBs are in us-east-1c
describe aws_elbs do
its('availability_zones') { should_not include 'us-east-1c' }
end
### count
Returns an integer reflecting the number of matched ELBs.
# Ensure we have 4 ELBs total.
describe aws_elbs do
its('count') { should cmp 4 }
end
### dns\_names
An array of FQDNs of the selected load balancers. These are the hostnames which are exposed to the world.
# Ensure none of the DNS names are an old name
describe aws_elbs do
its('dns_names') { should_not include 'some.horrid.name' }
end
### elb\_names
The names of the selected ELBs within AWS. The ELB name is unique within the region.
# You can use this to enumerate the ELBs for detailed tests
# Search using the plural, analyze using the singular.
aws_elbs.where { instance_ports.include? 80 }.elb_names.each do |elb_name|
describe aws_elb(elb_name) do
its('security_group_ids') { should include 'sg-12345678' }
end
end
### external\_ports
An array of integers reflecting the public-facing ports on which the selected load balancers will be listening for traffic. The array is de-duplicated.
# Ensure that the only ports we are listening on are 80 and 443
describe aws_elbs do
its('external_ports') { should include 80 }
its('external_ports') { should include 443 }
its('external_ports.count') { should cmp 2 }
end
### instance\_ids
An array of strings reflecting the instance IDs of the EC2 instances attached to the selected ELBs.
# Ensure there are 10-20 instances total attached to all ELBs
describe aws_elbs do
its('instance_ids.count') { should be >= 10 }
its('instance_ids.count') { should be <= 20 }
end
### internal\_ports
An array of integers reflecting the EC2-facing ports on which the selected load balancers will be sending traffic to. The array is de-duplicated.
# Ensure all ELBs only talk to port 80
describe aws_elbs do
its('internal_ports') { should contain 80 }
its('internal_ports.count') { should cmp 1 }
end
### security\_group\_ids
An array of strings reflecting the security group IDs (firewall rule sets) assigned to the selected ELBs. The array is de-duplicated.
# Ensure all ELBs are using one specific security group
describe aws_elbs do
its('security_group_ids') { should include 'sg-12345678' }
its('security_group_ids.count') { should cmp 1 }
end
### subnet\_ids
An array of strings reflecting the subnet IDs on which the selected ELBs are located. The array is de-duplicated.
# Ensure all ELBs are on a particular subnet
describe aws_elbs do
its('subnet_ids') { should include 'subnet-12345678' }
its('subnet_ids.count') { should cmp 1 }
end
### vpc\_ids
An array of strings reflecting the ID of the VPCs in which the selected ELBs are located. The array is de-duplicated.
# Ensure all ELBs are in one VPC
describe aws_elbs do
its('vpc_ids.count') { should cmp 1 }
end
## Matchers
This Chef InSpec audit resource has the following resource-specific matchers. For a full list of available matchers, please visit our [Universal Matchers page](https://www.inspec.io/docs/reference/matchers/).
### exists
The audit test will pass if at least one ELB was matched by the filter. Use with `should_not` to test for absence.
# We like z's in our DNS names
describe aws_elbs.where(dns_name: /z/) do
it { should exist }
end
# But k's are just awful
describe aws_elbs.where(dns_name: /k/) do
it { should_not exist }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `elasticloadbalancing:DescribeLoadBalancers` action set to Allow.
You can find detailed documentation at [Authentication and Access Control for Your Load Balancers](https://docs.aws.amazon.com/elasticloadbalancing/latest/userguide/load-balancer-authentication-access-control.html)

128
docs/resources/aws_flow_log.md.erb
View file

@ -1,128 +0,0 @@
---
title: About the aws_flow_log Resource
platform: aws
---
# aws\_flow\_log
Use the `aws_flow_log` Chef InSpec audit resource to test properties of a single Flow Log.
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.2.10 of InSpec.
## Syntax
describe aws_flow_log('fl-9c718cf5') do
it { should exist }
end
## Resource Parameters
### flow\_log\_id
This resource accepts a single parameter or other search terms. You may pass it as a string, or as the value in a hash:
describe aws_flow_log('fl-9c718cf5') do
it { should exist }
end
describe aws_flow_log(flow_log_id: 'fl-8905f8e0') do
it { should exist }
end
### subnet\_id
To search for a flow log by the associated subnet id:
describe aws_flow_log(subnet_id: 'subnet-c6a4319c') do
it { should exist }
end
### vpc\_id
To search for a flow log by the associated vpc id:
describe aws_flow_log(vpc_id: 'vpc-96cabaef') do
it { should exist }
end
## Properties
### flow\_log\_id
The `flow_log_id` property tests the name of the flow log.
describe aws_flow_log(subnet_id: 'subnet-c6a4319c') do
its('flow_log_id') { should cmp 'fl-9c718cf5' }
end
### log\_group\_name
The `log_group_name` property tests the name of the associated log group.
describe aws_flow_log('fl-9c718cf5') do
its('log_group_name') { should cmp 'test_log_group' }
end
### resource\_id
The `resource_id` property tests the id of the associated VPC, subnet, or network interface.
describe aws_flow_log('fl-9c718cf5') do
its('resource_id') { should cmp 'subnet-c6a4319c' }
end
### resource\_type
The `resource_type` property tests the type of resource the Flow Log is attached to.
The property will return `eni`, `subnet`, or `vpc`.
describe aws_flow_log('fl-9c718cf5') do
its('resource_type') { should cmp 'subnet' }
end
## Matchers
For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### exist
Indicates that the Flow Log provided was found. Use `should_not` to test for Flow Logs that should not exist.
describe aws_flow_log('should-be-there') do
it { should exist }
end
describe aws_flow_log('should-not-be-there') do
it { should_not exist }
end
### be\_attached\_to\_eni
Indicates that the Flow Log is attached to a ENI resource.
describe aws_flow_log('fl-9c718cf5') do
it { should be_attached_to_eni }
end
### be\_attached\_to\_subnet
Indicates that the Flow Log is attached to a subnet resource.
describe aws_flow_log('fl-9c718cf5') do
it { should be_attached_to_subnet }
end
### be\_attached\_to\_vpc
Indicates that the Flow Log is attached to a vpc resource.
describe aws_flow_log('fl-9c718cf5') do
it { should be_attached_to_vpc }
end

139
docs/resources/aws_iam_access_key.md.erb
View file

@ -1,139 +0,0 @@
---
title: About the aws_iam_access_key Resource
platform: aws
---
# aws\_iam\_access\_key
Use the `aws_iam_access_key` Chef InSpec audit resource to test properties of a single AWS IAM access key.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_iam_access_key` resource block declares the tests for a single AWS IAM access key. An access key is uniquely identified by its access key id.
# This is unique - the key will either exist or it won't, but it will never be an error.
describe aws_iam_access_key(access_key_id: 'AKIA12345678ABCD') do
it { should exist }
it { should_not be_active }
its('create_date') { should be > Time.now - 365 * 86400 }
its('last_used_date') { should be > Time.now - 90 * 86400 }
end
# id is an alias for access_key_id
describe aws_iam_access_key(id: 'AKIA12345678ABCD') do
# Same
end
Access keys are associated with IAM users, who may have zero, one or two access keys. You may also lookup an access key by username. If the user has more than one access key, an error occurs (You may use `aws_iam_access_keys` with the `username` resource parameter to access a user's keys when they have multiple keys.)
# This is not unique. If the user has zero or one keys, it is not an error.
# If they have two, it is an error.
describe aws_iam_access_key(username: 'roderick') do
it { should exist }
it { should be_active }
end
You may also use both username and access key id to ensure that a particular key is associated with a particular user.
describe aws_iam_access_key(username: 'roderick', access_key_id: 'AKIA12345678ABCD') do
it { should exist }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test that an IAM access key is not active
describe aws_iam_access_key(username: 'username', id: 'access-key-id') do
it { should_not be_active }
end
### Test that an IAM access key is older than one year
describe aws_iam_access_key(username: 'username', id: 'access-key-id') do
its('create_date') { should be > Time.now - 365 * 86400 }
end
### Test that an IAM access key has been used in the past 90 days
describe aws_iam_access_key(username: 'username', id: 'access-key-id') do
its('last_used_date') { should be > Time.now - 90 * 86400 }
end
<br>
## Properties
* `access_key_id`, `create_date`, `last_used_date`, `username`
<br>
## Property Examples
### access\_key\_id
The unique ID of this access key.
describe aws_iam_access_key(username: 'bob')
its('access_key_id') { should cmp 'AKIA12345678ABCD' }
end
### create\_date
The date and time, as a Ruby DateTime, at which the access key was created.
# Is the access key less than a year old?
describe aws_iam_access_key(username: 'bob')
its('create_date') { should be > Time.now - 365 * 86400 }
end
### last\_used\_date
The date and time, as a Ruby DateTime, at which the access key was last_used.
# Has the access key been used in the last year?
describe aws_iam_access_key(username: 'bob')
its('last_used_date') { should be > Time.now - 365 * 86400 }
end
### username
The IAM user that owns this key.
describe aws_iam_access_key(access_key_id: 'AKIA12345678ABCD')
its('username') { should cmp 'bob' }
end
<br>
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### be\_active
The `be_active` matcher tests if the described IAM access key is active.
it { should be_active }
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `iam:ListAccessKeys` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

214
docs/resources/aws_iam_access_keys.md.erb
View file

@ -1,214 +0,0 @@
---
title: About the aws_iam_access_keys Resource
platform: aws
---
# aws\_iam\_access\_keys
Use the `aws_iam_access_keys` Chef InSpec audit resource to test properties of some or all IAM Access Keys.
To test properties of a single Access Key, use the `aws_iam_access_key` resource instead.
To test properties of an individual user's access keys, use the `aws_iam_user` resource.
Access Keys are closely related to AWS User resources. Use this resource to perform audits of all keys or of keys specified by criteria unrelated to any particular user.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_iam_access_keys` resource block uses an optional filter to select a group of access keys and then tests that group.
# Do not allow any access keys
describe aws_iam_access_keys do
it { should_not exist }
end
# Don't let fred have access keys, using filter argument syntax
describe aws_iam_access_keys.where(username: 'fred') do
it { should_not exist }
end
# Don't let fred have access keys, using filter block syntax (most flexible)
describe aws_iam_access_keys.where { username == 'fred' } do
it { should_not exist }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Disallow access keys created more than 90 days ago
describe aws_iam_access_keys.where { created_days_ago > 90 } do
it { should_not exist }
end
<br>
## Filter Criteria
* `active`, `create_date`, `created_days_ago`, `created_hours_ago`, `created_with_user`, `ever_used`, `inactive`, `last_used_date`, `last_used_hours_ago`, `last_used_days_ago`, `never_used`, `user_created_date`
<br>
## Filter Examples
### active
A true / false value indicating if an Access Key is currently "Active" (the normal state) in the AWS console. See also: `inactive`.
# Check if a particular key is enabled
describe aws_iam_access_keys.where { active } do
its('access_key_ids') { should include('AKIA1234567890ABCDEF')}
end
### create\_date
A DateTime identifying when the Access Key was created. See also `created_days_ago` and `created_hours_ago`.
# Detect keys older than 2017
describe aws_iam_access_keys.where { create_date < DateTime.parse('2017-01-01') } do
it { should_not exist }
end
### created\_days\_ago, created\_hours\_ago
An integer, representing how old the access key is.
# Don't allow keys that are older than 90 days
describe aws_iam_access_keys.where { created_days_ago > 90 } do
it { should_not exist }
end
### created\_with\_user
A true / false value indicating if the Access Key was likely created at the same time as the user, by checking if the difference between created_date and user_created_date is less than 1 hour.
# Do not automatically create keys for users
describe aws_iam_access_keys.where { created_with_user } do
it { should_not exist }
end
### ever\_used
A true / false value indicating if the Access Key has ever been used, based on the last_used_date. See also: `never_used`.
# Check to see if a particular key has ever been used
describe aws_iam_access_keys.where { ever_used } do
its('access_key_ids') { should include('AKIA1234567890ABCDEF')}
end
### inactive
A true / false value indicating if the Access Key has been marked Inactive in the AWS console. See also: `active`.
# Don't leave inactive keys laying around
describe aws_iam_access_keys.where { inactive } do
it { should_not exist }
end
### last\_used\_date
A DateTime identifying when the Access Key was last used. Returns nil if the key has never been used. See also: `ever_used`, `last_used_days_ago`, `last_used_hours_ago`, and `never_used`.
# No one should do anything on Mondays
describe aws_iam_access_keys.where { ever_used and last_used_date.monday? } do
it { should_not exist }
end
### last\_used\_days\_ago, last\_used\_hours\_ago
An integer representing when the key was last used. See also: `ever_used`, `last_used_date`, and `never_used`.
# Don't allow keys that sit unused for more than 90 days
describe aws_iam_access_keys.where { last_used_days_ago > 90 } do
it { should_not exist }
end
### never\_used
A true / false value indicating if the Access Key has never been used, based on the `last_used_date`. See also: `ever_used`.
# Don't allow unused keys to lay around
describe aws_iam_access_keys.where { never_used } do
it { should_not exist }
end
### username
Searches for access keys owned by the named user. Each user may have zero, one, or two access keys.
describe aws_iam_access_keys(username: 'bob') do
it { should exist }
end
### user\_created\_date
The date at which the user was created.
# Users have to be a week old to have a key
describe aws_iam_access_keys.where { user_created_date > Date.now - 7 }
it { should_not exist }
end
<br>
## Properties
* `access_key_ids`, `entries`
## Property Examples
### access\_key\_ids
Provides a list of all access key IDs matched.
describe aws_iam_access_keys do
its('access_key_ids') { should include('AKIA1234567890ABCDEF') }
end
### entries
Provides access to the raw results of the query. This can be useful for checking counts and other advanced operations.
# Allow at most 100 access keys on the account
describe aws_iam_access_keys do
its('entries.count') { should be <= 100}
end
<br>
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### exists
The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
# Sally should have at least one access key
describe aws_iam_access_keys.where(username: 'sally') do
it { should exist }
end
# Don't let fred have access keys
describe aws_iam_access_keys.where(username: 'fred') do
it { should_not exist }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `iam:ListAccessKeys`, and `iam:ListUsers` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

74
docs/resources/aws_iam_group.md.erb
View file

@ -1,74 +0,0 @@
---
title: About the aws_iam_group Resource
platform: aws
---
# aws\_iam\_group
Use the `aws_iam_group` Chef InSpec audit resource to test properties of a single IAM group.
To test properties of multiple or all groups, use the `aws_iam_groups` resource.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_iam_group` resource block identifies a group by group name.
# Find a group by group name
describe aws_iam_group('mygroup') do
it { should exist }
end
# Hash syntax for group name
describe aws_iam_group(group_name: 'mygroup') do
it { should exist }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
As this is the initial release of `aws_iam_group`, its limited functionality precludes examples.
<br>
## Properties
### users
Provides a list of the users that are attached to the group
describe aws_iam_group('mygroup')
its('users') { should include 'iam_user_name' }
end
<br>
## Matchers
### exists
The control will pass if a group with the given group name exists.
describe aws_iam_group('mygroup')
it { should exist }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `iam:GetGroup` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

92
docs/resources/aws_iam_groups.md.erb
View file

@ -1,92 +0,0 @@
---
title: About the aws_iam_groups Resource
platform: aws
---
# aws\_iam\_groups
Use the `aws_iam_groups` Chef InSpec audit resource to test properties of all or multiple groups.
To test properties of a single group, use the `aws_iam_group` resource.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_iam_groups` resource block uses an optional filter to select a collection of IAM groups and then tests that collection.
# The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
describe aws_iam_groups do
it { should exist }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
As this is the initial release of `aws_iam_groups`, its limited functionality precludes examples.
<br>
## Filter Criteria
### group_name
Filters the IAM groups by their group name, a string. If you know the exact group name, use `aws_iam_group` (singular) instead. This criteria may be used when you know a pattern of the name.
# Use a regex to find groups ending with 'Admins'
describe aws_iam_groups.where(group_name: /Admins$/) do
its('group_names') { should include 'FriendlyAdmins' }
its('group_names') { shoud_not include 'ShunnedAdmins' }
end
## Properties
### group_names
An Array of Strings, reflecting the IAM group names matched by the filter. If no groups matched, this will be empty. You can also use this with `aws_iam_group` to enumerate groups.
# Check for friendly people
describe aws_iam_groups.where(group_name: /Admins$/) do
its('group_names') { should include 'FriendlyAdmins' }
its('group_names') { should include 'KindAdmins' }
end
# Use to loop and fetch groups individually for auditing in detail
# Without a `where`, this fetches all groups
aws_iam_groups.group_names.each do |group_names|
# A roundabout way of saying "bob should not be in any groups"
describe aws_iam_group(group_name) do
its('users') { should_not include 'bob' }
end
end
## Matchers
This resource has no resource-specific matchers. For a full list of available matchers, please visit our [Universal Matchers page](https://www.inspec.io/docs/reference/matchers/).
### exists
The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
describe aws_iam_groups
it { should exist }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `iam:ListGroups` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

92
docs/resources/aws_iam_password_policy.md.erb
View file

@ -1,92 +0,0 @@
---
title: About the aws_iam_password_policy Resource
platform: aws
---
# aws\_iam\_password\_policy
Use the `aws_iam_password_policy` Chef InSpec audit resource to test properties of the AWS IAM Password Policy.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_iam_password_policy` resource block takes no parameters. Several properties and matchers are available.
describe aws_iam_password_policy do
it { should require_lowercase_characters }
end
<br>
## Properties
* `max_password_age_in_days`, `minimum_password_length`, `number_of_passwords_to_remember`
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test that the IAM Password Policy requires lowercase characters, uppercase characters, numbers, symbols, and a minimum length greater than eight
describe aws_iam_password_policy do
it { should require_lowercase_characters }
it { should require_uppercase_characters }
it { should require_symbols }
it { should require_numbers }
its('minimum_password_length') { should be > 8 }
end
### Test that the IAM Password Policy allows users to change their password
describe aws_iam_password_policy do
it { should allow_users_to_change_passwords }
end
### Test that the IAM Password Policy expires passwords
describe aws_iam_password_policy do
it { should expire_passwords }
end
### Test that the IAM Password Policy has a max password age
describe aws_iam_password_policy do
its('max_password_age_in_days') { should be 90 }
end
### Test that the IAM Password Policy prevents password reuse
describe aws_iam_password_policy do
it { should prevent_password_reuse }
end
### Test that the IAM Password Policy requires users to remember 3 previous passwords
describe aws_iam_password_policy do
its('number_of_passwords_to_remember') { should eq 3 }
end
<br>
## Matchers
This resource uses the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
* `allows_users_to_change_passwords`, `expire_passwords`, `prevent_password_reuse`, `require_lowercase_characters` , `require_uppercase_characters`, `require_numbers`, `require_symbols`
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `iam:GetAccountPasswordPolicy` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

97
docs/resources/aws_iam_policies.md.erb
View file

@ -1,97 +0,0 @@
---
title: About the aws_iam_policies Resource
platform: aws
---
# aws\_iam\_policies
Use the `aws_iam_policies` Chef InSpec audit resource to test properties of some or all AWS IAM Policies.
A policy is an entity in AWS that, when attached to an identity or resource, defines their permissions. AWS evaluates these policies when a principal, such as a user, makes a request. Permissions in the policies determine if the request is allowed or denied.
Each IAM Policy is uniquely identified by either its `policy_name` or `arn`.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_iam_policies` resource block collects a group of IAM Policies and then tests that group.
# Verify the policy specified by the policy name is included in IAM Policies in the AWS account.
describe aws_iam_policies do
its('policy_names') { should include('test-policy-1') }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
As this is the initial release of `aws_iam_policies`, its limited functionality precludes examples.
<br>
## Properties
* `arns`, `entries`, `policy_names`
<br>
## Property Examples
### policy\_names
Provides a list of policy names for all IAM Policies in the AWS account.
describe aws_iam_policies do
its('policy_names') { should include('test-policy-1') }
end
### arns
Provides a list of policy arns for all IAM Policies in the AWS account.
describe aws_iam_policies do
its('arns') { should include('arn:aws:iam::aws:policy/test-policy-1') }
end
### entries
Provides access to the raw results of the query. This can be useful for checking counts and other advanced operations.
# Allow at most 100 IAM Policies on the account
describe aws_iam_policies do
its('entries.count') { should be <= 100}
end
<br>
## Matchers
For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### exists
The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
# Verify that at least one IAM Policies exists.
describe aws_iam_policies
it { should exist }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `iam:ListPolicies` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

264
docs/resources/aws_iam_policy.md.erb
View file

@ -1,264 +0,0 @@
---
title: About the aws_iam_policy Resource
platform: aws
---
# aws\_iam\_policy
Use the `aws_iam_policy` Chef InSpec audit resource to test properties of a single managed AWS IAM Policy. Use `aws_iam_policies` to audit IAM policies in bulk.
A policy defines the permissions of an identity or resource within AWS. AWS evaluates these policies when a principal, such as a user, makes a request. Policy permissions, also called "policy statements" in AWS, determine if a request is authorized -- and allow or deny it accordingly.
Each IAM Policy is uniquely identified by either its policy\_name or arn.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_iam_policy` resource block identifies a policy by policy name.
# Find a policy by name
describe aws_iam_policy('AWSSupportAccess') do
it { should exist }
end
# Find a customer-managed by name
describe aws_iam_policy('customer-managed-policy') do
it { should exist }
end
# Hash syntax for policy name
describe aws_iam_policy(policy_name: 'AWSSupportAccess') do
it { should exist }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test that a policy does exist
describe aws_iam_policy('AWSSupportAccess') do
it { should exist }
end
### Test that a policy is attached to at least one entity
describe aws_iam_policy('AWSSupportAccess') do
it { should be_attached }
end
### Examine the policy statements
describe aws_iam_policy('my-policy') do
# Verify that there is at least one statement allowing access to S3
it { should have_statement(Action: 's3:PutObject', Effect: 'allow') }
# have_statement does not expand wildcards. If you want to verify
# they are absent, an explicit check is required.
it { should_not have_statement(Action: 's3:*') }
end
<br>
## Properties
* `arn`, `attachment_count`, `attached_groups`, `attached_roles`,`attached_users`, `default_version_id`, `policy`, `statement_count`
## Property Examples
### arn
"The ARN identifier of the specified policy. An ARN uniquely identifies the policy within AWS."
describe aws_iam_policy('AWSSupportAccess') do
its('arn') { should cmp "arn:aws:iam::aws:policy/AWSSupportAccess" }
end
### attachment\_count
The count of attached entities for the specified policy.
describe aws_iam_policy('AWSSupportAccess') do
its('attachment_count') { should cmp 1 }
end
### attached\_groups
The list of groupnames of the groups attached to the policy.
describe aws_iam_policy('AWSSupportAccess') do
its('attached_groups') { should include "test-group" }
end
### attached\_roles
The list of rolenames of the roles attached to the policy.
describe aws_iam_policy('AWSSupportAccess') do
its('attached_roles') { should include "test-role" }
end
### attached\_users
The list of usernames of the users attached to the policy.
describe aws_iam_policy('AWSSupportAccess') do
its('attached_users') { should include "test-user" }
end
### default\_version\_id
The 'default_version_id' value of the specified policy.
describe aws_iam_policy('AWSSupportAccess') do
its('default_version_id') { should cmp "v1" }
end
### policy
This is a low-level, unsupported property.
Returns the default version of the policy document after decoding as a Ruby hash. This hash contains the policy statements and is useful for performing checks that cannot be expressed using higher-level matchers like `have_statement`.
For details regarding the contents of this structure, refer to the [AWS IAM Policy JSON Reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html). A set of examples is [also available](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_examples.html).
Example:
# Fetch the policy structure as a Ruby object
policy_struct = aws_iam_policy('my-policy').policy
# Write a manually-constructed test to check that the policy
# has an IP constraint on the first statement
# ( Based on https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_aws_deny-ip.html )
describe 'Check that we are restricting IP access' do
subject { policy_struct['Statement'].first['Condition'] }
it { should include 'NotIpAddress' }
end
### statement\_count
Returns the number of statements present in the `policy`.
# Make sure there are exactly two statements.
describe aws_iam_policy('my-policy') do
its('statement_count') { should cmp 2 }
end
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [Universal Matchers page](https://www.inspec.io/docs/reference/matchers/).
### be\_attached
The test will pass if the identified policy is attached to at least one IAM user, group, or role.
describe aws_iam_policy('AWSSupportAccess') do
it { should be_attached }
end
### be\_attached\_to\_group(GROUPNAME)
The test will pass if the identified policy attached the specified group.
describe aws_iam_policy('AWSSupportAccess') do
it { should be_attached_to_group(GROUPNAME) }
end
### be\_attached\_to\_user(USERNAME)
The test will pass if the identified policy attached the specified user.
describe aws_iam_policy('AWSSupportAccess') do
it { should be_attached_to_user(USERNAME) }
end
### be\_attached\_to\_role(ROLENAME)
The test will pass if the identified policy attached the specified role.
describe aws_iam_policy('AWSSupportAccess') do
it { should be_attached_to_role(ROLENAME) }
end
### have\_statement
Examines the list of statements contained in the policy and passes if at least one of the statements matches. This matcher does _not_ interpret the policy in a request authorization context, as AWS does when a request processed. Rather, `have_statement` examines the literal contents of the IAM policy, and reports on what is present (or absent, when used with `should_not`).
`have_statement` accepts the following criteria to search for matching statements. If any statement matches all the criteria, the test is successful. All criteria may be used as Titlecase (as in the AWS examples) or lowercase, string or symbol.
* `Action` - Expresses the requested operation. Acceptable literal values are any AWS operation name, including the '*' wildcard character. `Action` may also use a list of AWS operation names.
* `Effect` - Expresses if the operation is permitted. Acceptable values are 'Deny' and 'Allow'.
* `Sid` - A user-provided string identifier for the statement.
* `Resource` - Expresses the operation's target. Acceptable values are ARNs, including the '*' wildcard. `Resource` may also use a list of ARN values.
Please note the following about the behavior of `have_statement`:
* `Action`, `Sid`, and `Resource` allow using a regular expression as the search critera instead of a string literal.
* it does not support wildcard expansion; to check for a wildcard value, check for it explicitly. For example, if the policy includes a statement with `"Action": "s3:*"` and the test checks for `Action: "s3:PutObject"`, the test _will not match_. You must write an additional test checking for the wildcard case.
* it supports searching list values. For example, if a statement contains a list of 3 resources, and a `have_statement` test specifes _one_ of those resources, it will match.
* `Action` and `Resource` allow using a list of string literals or regular expressions in a test, in which case _all_ must match on the _same_ statement for the test to match. Order is ignored.
* it does not support the `[Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal)` or `Conditional` key, or any of `NotAction`, `Not[Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal)`, or `NotResource`.
Examples:
# Verify there is no full-admin statement
describe aws_iam_policy('kryptonite') do
it { should_not have_statement('Effect' => 'Allow', 'Resource' => '*', 'Action' => '*')}
end
# Symbols and lowercase also allowed as criteria
describe aws_iam_policy('kryptonite') do
# All 4 the same
it { should_not have_statement('Effect' => 'Allow', 'Resource' => '*', 'Action' => '*')}
it { should_not have_statement('effect' => 'Allow', 'resource' => '*', 'action' => '*')}
it { should_not have_statement(Effect: 'Allow', Resource: '*', Action: '*')}
it { should_not have_statement(effect: 'Allow', resource: '*', action: '*')}
end
# Verify bob is allowed to manage things on S3 buckets that start with bobs-stuff
describe aws_iam_policy('bob-is-a-packrat') do
it { should have_statement(Effect: 'Allow',
# Using the AWS wildcard - this must match exactly
Resource: 'arn:aws:s3:::bobs-stuff*',
# Specify a list of actions - all must match, no others, order isn't important
Action: ['s3:PutObject', 's3:GetObject', 's3:DeleteObject'])}
# Bob would make new buckets constantly if we let him.
it { should_not have_statement(Effect: 'Allow', Action: 's3:CreateBucket')}
it { should_not have_statement(Effect: 'Allow', Action: 's3:*')}
it { should_not have_statement(Effect: 'Allow', Action: '*')}
# An alternative to checking for wildcards is to specify the
# statements you expect, then restrict statement count
its('statement_count') { should cmp 1 }
end
# Use regular expressions to examine the policy
describe aws_iam_policy('regex-demo') do
# Check to see if anything mentions RDS at all.
# This catches `rds:CreateDBinstance` and `rds:*`, but would not catch '*'.
it { should_not have_statement(Action: /^rds:.+$/)}
# This policy should refer to both sally and kim's s3 buckets.
# This will only match if there is a statement that refers to both resources.
it { should have_statement(Resource: [/arn:aws:s3.+:sally/, /arn:aws:s3.+:kim/]) }
# The following also matches on a statement mentioning only one of them
it { should have_statement(Resource: /arn:aws:s3.+:(sally|kim)/) }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `iam:GetPolicy`, `iam:ListPolicy`, and `iam:ListEntitiesForPolicy` actions set to allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

79
docs/resources/aws_iam_role.md.erb
View file

@ -1,79 +0,0 @@
---
title: About the aws_iam_role Resource
platform: aws
---
# aws\_iam\_role
Use the `aws_iam_role` Chef InSpec audit resource to test properties of a single IAM Role. A Role is a collection of permissions that may be temporarily assumed by a user, EC2 Instance, Lambda Function, or certain other resources.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
# Ensure that a certain role exists by name
describe aws_iam_role('my-role') do
it { should exist }
end
<br>
## Resource Parameters
### role\_name
This resource expects a single parameter that uniquely identifies the IAM Role, the Role Name. You may pass it as a string, or as the value in a hash:
describe aws_iam_role('my-role') do
it { should exist }
end
# Same
describe aws_iam_role(role_name: 'my-role') do
it { should exist }
end
<br>
## Properties
### description
A textual description of the IAM Role.
describe aws_iam_role('my-role') do
its('description') { should be('Our most important Role')}
end
<br>
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### exist
Indicates that the Role Name provided was found. Use `should_not` to test for IAM Roles that should not exist.
describe aws_iam_role('should-be-there') do
it { should exist }
end
describe aws_iam_role('should-not-be-there') do
it { should_not exist }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `iam:GetRole` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

86
docs/resources/aws_iam_root_user.md.erb
View file

@ -1,86 +0,0 @@
---
title: About the aws_iam_root_user Resource
platform: aws
---
# aws\_iam\_root\_user
Use the `aws_iam_root_user` Chef InSpec audit resource to test properties of the root user (owner of the account).
To test properties of all or multiple users, use the `aws_iam_users` resource.
To test properties of a specific AWS user use the `aws_iam_user` resource.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_iam_root_user` resource block requires no parameters but has several matchers.
describe aws_iam_root_user do
it { should have_mfa_enabled }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test that the AWS root account has at-least one access key
describe aws_iam_root_user do
it { should have_access_key }
end
### Test that the AWS root account has Multi-Factor Authentication enabled
describe aws_iam_root_user do
it { should have_mfa_enabled }
end
<br>
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### have\_mfa\_enabled
The `have_mfa_enabled` matcher tests if the AWS root user has Multi-Factor Authentication enabled, requiring them to enter a secondary code when they login to the web console.
it { should have_mfa_enabled }
### have\_hardware\_mfa\_enabled
The `have_hardware_mfa_enabled` matcher tests if the AWS root user has Hardware Multi-Factor Authentication device enabled, requiring them to enter a secondary code when they login to the web console.
it { should have_hardware_mfa_enabled }
### have\_virtual\_mfa\_enabled
The `have_virtual_mfa_enabled` matcher tests if the AWS root user has Virtual Multi-Factor Authentication device enabled, requiring them to enter a secondary code when they login to the web console.
it { should have_virtual_mfa_enabled }
### have\_access\_key
The `have_access_key` matcher tests if the AWS root user has at least one access key.
it { should have_access_key }
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `iam:GetAccountSummary` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

130
docs/resources/aws_iam_user.md.erb
View file

@ -1,130 +0,0 @@
---
title: About the aws_iam_user Resource
platform: aws
---
# aws\_iam\_user
Use the `aws_iam_user` Chef InSpec audit resource to test properties of a single AWS IAM user.
To test properties of more than one user, use the `aws_iam_users` resource.
To test properties of the special AWS root user (which owns the account), use the `aws_iam_root_user` resource.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Resource Parameters
An `aws_iam_user` resource block declares a user by name, and then lists tests to be performed.
describe aws_iam_user(username: 'test_user') do
it { should exist }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test that a user does not exist
describe aws_iam_user(username: 'gone') do
it { should_not exist }
end
### Test that a user has multi-factor authentication enabled
describe aws_iam_user(username: 'test_user') do
it { should have_mfa_enabled }
end
### Test that a service user does not have a password
describe aws_iam_user(username: 'test_user') do
it { should have_console_password }
end
<br>
## Properties
### attached\_policy\_arns
Returns a list of IAM Managed Policy ARNs as strings that identify the policies that are attached to the user. If there are no attached policies, returns an empty list.
describe aws_iam_user('bob') do
# This is a customer-managed policy
its('attached_policy_arns') { should include 'arn:aws:iam::123456789012:policy/test-inline-policy-01' }
# This is an AWS-managed policy
its('attached_policy_arns') { should include 'arn:aws:iam::aws:policy/AlexaForBusinessGatewayExecution' }
end
### attached\_policy\_names
Returns a list of IAM Managed Policy Names as strings that identify the policies that are attached to the user. If there are no attached policies, returns an empty list.
describe aws_iam_user('bob') do
# This is a customer-managed policy
its('attached_policy_names') { should include 'test-inline-policy-01' }
# This is an AWS-managed policy
its('attached_policy_names') { should include 'AlexaForBusinessGatewayExecution' }
end
### inline\_policy\_names
Returns a list of IAM Inline Policy Names as strings that identify the inline policies that are directly embedded in the user. If there are no embedded policies, returns an empty list.
describe aws_iam_user('bob') do
its('inline_policy_names') { should include 'test-inline-policy-01' }
its('inline_policy_names.count') { should eq 1 }
end
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [universal matchers page](https://www.inspec.io/docs/reference/matchers/).
### have\_attached\_policies
The `have\_attached\_policies` matcher tests if the user has at least one IAM managed policy attached to the user.
describe aws_iam_user('bob') do
it { should_not have_attached_policies }
end
### have\_console\_password
The `have_console_password` matcher tests if the user has a password that could be used to log into the AWS web console.
it { should have_console_password }
### have\_inline\_policies
The `have\_inline\_policies` matcher tests if the user has at least one IAM policy embedded directly in the user record.
describe aws_iam_user('bob') do
it { should_not have_inline_policies }
end
### have\_mfa\_enabled
The `have_mfa_enabled` matcher tests if the user has Multi-Factor Authentication enabled, requiring them to enter a secondary code when they login to the web console.
it { should have_mfa_enabled }
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `iam:GetUser`, `iam:GetLoginProfile`, `iam:ListMFADevices`, `iam:ListAccessKeys`, `iam:ListUserPolicies`, and `iam:ListAttachedUserPolicies` actions set to allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

289
docs/resources/aws_iam_users.md.erb
View file

@ -1,289 +0,0 @@
---
title: About the aws_iam_users Resource
platform: aws
---
# aws\_iam\_users
Use the `aws_iam_users` Chef InSpec audit resource to test properties of a all or multiple users.
To test properties of a single user, use the `aws_iam_user` resource.
To test properties of the special AWS root user (which owns the account), use the `aws_iam_root_user` resource.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_iam_users` resource block uses a filter to select a group of users and then tests that group. With no filter, it returns all AWS IAM users.
# No filter
# We expect 42 users
describe aws_iam_users do
its('usernames.count') { should eq 42 }
end
# Using a filter
# All users should have MFA (no user without MFA should exist)
describe aws_iam_users.where(has_mfa_enabled?: false) do
it { should_not exist }
end
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test that all users have Multi-Factor Authentication enabled
describe aws_iam_users.where(has_mfa_enabled?: false) do
it { should_not exist }
end
### Test that at least one user has a console password to log into the AWS web console
describe aws_iam_users.where(has_console_password?: true) do
it { should exist }
end
### Test that all users who have a console password have Multi-Factor Authentication enabled
console_users_without_mfa = aws_iam_users
.where(has_console_password?: true)
.where(has_mfa_enabled?: false)
describe console_users_without_mfa do
it { should_not exist }
end
### Test that all users who have a console password have used it at least once
console_users_with_unused_password = aws_iam_users
.where(has_console_password?: true)
.where(password_never_used?: true)
describe console_users_with_unused_password do
it { should_not exist }
end
### Test that at least one user exists who has a console password and has used it at least once
console_users_with_used_password = aws_iam_users
.where(has_console_password?: true)
.where(password_ever_used?: true)
describe console_users_with_used_password do
it { should exist }
end
### Test that users with passwords that have not been used for 90 days do not
describe aws_iam_users.where { password_last_used_days_ago > 90 } do
it { should_not exist }
end
<br>
## Filter Criteria
You may pass filter criteria to `where` to narrow down the result set.
### has\_attached\_policies
True or false. Filters the users to include only those that have at least one IAM managed policy attached to the user.
# Don't attach policies to users
describe aws_iam_users.where(has_attached_policies: true) do
it { should_not exist }
end
### has\_console\_password
True or false. Filters the users to include only those that have a console password (that is, they are able to login to the AWS web UI using a password).
# No console passwords for anyone
describe aws_iam_users.where(has_console_password: true) do
it { should_not exist }
end
### has\_inline\_policies
True or false. Filters the users to include only those that have at least one IAM policy directly embedded in the user record.
# Embedding policies is usually hard to manage
describe aws_iam_users.where(has_inline_policies: true) do
it { should_not exist }
end
### has\_mfa\_enabled
True or false. Filters the users to include only those that have some kind of Mult-Factor Authentication enabled (virtual or hardware).
# Require MFA for everyone
describe aws_iam_users.where(has_mfa_enabled: false) do
it { should_not exist }
end
### password\_ever\_used
True or false. Filters the users to include only those that have used their password at least once.
# Someone should have used their password
describe aws_iam_users.where(password_ever_used: true) do
it { should exist }
end
### password\_last\_used_days\_ago
Integer. Filters the users to include only those who used their password a certain number of days ago. '0' means today.
# Bob should login every day
describe aws_iam_users.where(password_ever_used: true, password_last_used_days_ago:0) do
its('usernames') { should include 'bob' }
end
# This filter is often more useful in block mode, using a greater-than
# Here, audit users who have not logged in in the last 30 days
describe aws_iam_users.where do
password_ever_used && password_last_used_days_ago > 30
end do
it { should_not exist' }
end
### password\_never\_used
True or false. Filters the users to include only those that have used _never_ their password.
# No zombie accounts!
describe aws_iam_users.where(password_never_used: true) do
it { should_not exist }
end
### username
String. Filters the users to include only those whose username matches the value you provide.
# Block mode example (recommended)
# Service users should not have a password
describe aws_iam_users.where { username.start_with?('service') } do
it { should_not have_console_password }
end
# Method call example. This is a poor use of aws_iam_users (plural);
# if you want to audit an individual user whose username you know, use
# aws_iam_user (singular)
# Verify Bob exists
describe aws_iam_users.where(username: 'bob') do
it { should exist }
end
## Properties
Properties are used with the `its` test to obtain information about the matched users. Properties always return arrays, though they may be empty.
### attached\_policy\_arns
Array of strings. Each entry is the ARN of an IAM managed policy that is attached to at least one matched user. The list is de-duplicated, so if you have five users that are all attached to the same policy, `attached_policy_arns` will return only one ARN, not five.
# Service users should be attached to a custom service policy
describe aws_iam_users.where { username.start_with?('service') } do
its('attached_policy_arns') { should include 'arn:aws:iam::123456789012:policy/MyServicePolicy' }
end
### attached\_policy\_names
Array of strings. Each entry is the friendly name of an IAM managed policy that is attached to at least one matched user. The list is de-duplicated, so if you have five users that are all attached to the same policy, `attached_policy_names` will return only one name, not five.
# Service users should be attached to a custom service policy
# and not include Admin policy!
describe aws_iam_users.where { username.start_with?('service') } do
its('attached_policy_names') { should include 'MyServicePolicy' }
its('attached_policy_names') { should_not include 'AdministratorAccess' }
end
### inline\_policy\_names
Array of strings. Each entry is the name of an embedded policy that is embedded in at least one matched user. Keep in mind that each user has a copy of a policy (which can then be modified). This means that two users can have an embedded policy with the same name, but very different contents. The list is de-duplicated, so if you have five users that have an inline policy with the same name, `inline_policy_names` will return only one name, not five.
# Service users should have a bespoke policy
describe aws_iam_users.where { username.start_with?('service') } do
its('inline_policy_names') { should include 'some-bespoke-policy' }
end
### usernames
Array of strings. Each entry is the name of a user that matched. There will be exactly as many usernames here as there were users that matched, though it is possible to have non-unique usernames.
# 42 Users, including Bob, should have a password.
describe aws_iam_users.where(has_console_password: true) do
its('usernames') { should include 'bob' }
its('usernames.count') { should eq 42 }
end
## Matchers
This Chef InSpec audit resource has the following resource-specific matchers.
For a full list of available matchers, please visit our [universal matchers page](https://www.inspec.io/docs/reference/matchers/).
As a plural resource, all matchers beginning with `have_` will return true if _any_ of the selected users match.
### exist
The test passes if the filtered user set is not empty. This basic matcher is frequently used with `should_not` to detect undesired conditions.
# Require MFA for everyone
describe aws_iam_users.where(has_mfa_enabled: false) do
it { should_not exist }
end
### have\_attached\_policies
The test passes if at least one user in the filtered set has at least one attached IAM managed policy.
# Bachelors don't have attachments
describe aws_iam_users.where { username =~ /bachelor/ } do
it { should_not have_attached_policies }
end
### have\_console\_password
The test passes if at least one user in the filtered set has a console password.
describe aws_iam_users do
it { should_not have_console_password }
end
### have\_inline\_policies
The test passes if at least one user in the filtered set has at least one embedded policy.
# No one should have an inline policy
describe aws_iam_users do
it { should_not have_inline_policies }
end
### have\_mfa\_enabled
The test passes if at least one user in the filtered set has MFA enabled (virtual or hardware).
# At least one person should use MFA.
# This does not mean ALL users have MFA.
describe aws_iam_users do
it { should have_mfa_enabled }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `iam:ListUsers`, `iam:GetLoginProfile`, `iam:ListMFADevices`, `iam:ListAccessKeys`, `iam:ListUserPolicies`, and `iam:ListAttachedUserPolicies` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

187
docs/resources/aws_kms_key.md.erb
View file

@ -1,187 +0,0 @@
---
title: About the aws_kms_key Resource
---
# aws\_kms\_key
Use the `aws_kms_key` Chef InSpec audit resource to test properties of a single AWS KMS Key.
Use aws_kms_key to verify the properties of a single key. Use aws_kms_keys to verify the properties of all or a group of keys.
AWS Key Management Service (AWS KMS) is a managed service that makes it easy for you to create and control the encryption keys used to encrypt your data. AWS KMS lets you create master keys that can never be exported from the service and which can be used to encrypt and decrypt data based on policies you define.
Each AWS KMS Key is uniquely identified by its key_id or arn.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.1.21 of InSpec.
## Syntax
An aws_kms_key resource block identifies a key by key_arn or the key id.
# Find a kms key by arn
describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
it { should exist }
end
# Find a kms key by just the id
describe aws_kms_key('4321dcba-21io-23de-85he-ab0987654321') do
it { should exist }
end
# Hash syntax for key arn
describe aws_kms_key(key_arn: 'arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
it { should exist }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test that the specified key does exist
describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
it { should exist }
end
### Test that the specified key is enabled
describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
it { should be_enabled }
end
### Test that the specified key is rotation enabled
describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
it { should have_rotation_enabled }
end
<br>
## Properties
### key\_id
The globally unique identifier for the key.
describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
its('key_id') { should cmp '4321dcba-21io-23de-85he-ab0987654321' }
end
### arn
The ARN identifier of the specified key. An ARN uniquely identifies the key within AWS.
describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
its('arn') { should cmp "arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321" }
end
### creation_date
Specifies the date and time when the key was created.
# Makes sure that the key was created at least 10 days ago
describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
its('creation_date') { should be < Time.now - 10 * 86400 }
end
### created\_days\_ago
Specifies the number of days since the key was created.
describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
its('created_days_ago') { should be > 10 }
end
### key\_state
Specifies the state of the key one of "Enabled", "Disabled", "PendingDeletion", "PendingImport". To just check if the key is enabled or not, use the `be_enabled` matcher.
describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
its('key_state') { should cmp "Enabled" }
end
### description
Specifies the description of the key.
describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
its('description') { should cmp "key-description" }
end
### deletion\_time
Specifies the date and time after which AWS KMS deletes the key. This value is present only when KeyState is PendingDeletion , otherwise this value is nil.
describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
its('deletion_time') { should cmp > Time.now + 7 * 86400 }
end
### invalidation\_time
Provides the date and time until the key is not valid. Once the key is not valid, AWS KMS deletes the key and it becomes unusable. This value will be null unless the keys Origin is EXTERNAL and its matcher have_key_expiration is set to true.
describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
its('invalidation_time') { should cmp > Time.now + 7 * 86400 }
end
## Matchers
This Chef 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/).
### be\_enabled
The test will pass if the specified key's key_state is set to enabled.
describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
it { should be_enabled }
end
### be\_external
Provides whether the source of the key's key material is external or not. If it is not external than it was created by AWS KMS. When it is external, the key material was imported from an existing key management infrastructure or the key lacks key material.
describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
its { should be_external }
end
### be\_managed\_by\_aws
Provides whether or not the key manager is from AWS. If it is not managed by AWS, it is managed by the customer.
describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
its { should be_managed_by_aws }
end
### have\_key\_expiration
Specifies whether the key's key material expires. This value is null unless the keys Origin is External.
describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
its { should have_key_expiration }
end
### have\_rotation\_enabled
The test will pass if automatic rotation of the key material is enabled for the specified key.
describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
it { should have_rotation_enabled }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `kms:DescribeKey`, and `kms:GetKeyRotationStatus` actions set to allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for AWS Key Management Service](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awskeymanagementservice.html).

99
docs/resources/aws_kms_keys.md.erb
View file

@ -1,99 +0,0 @@
---
title: About the aws_kms_keys Resource
platform: aws
---
# aws\_kms\_keys
Use the `aws_kms_keys` Chef InSpec audit resource to test properties of some or all AWS KMS Keys.
AWS Key Management Service (KMS) is a managed service that makes creating and controlling your encryption keys for your data easier. KMS uses Hardware Security Modules (HSMs) to protect the security of your keys.
AWS Key Management Service is integrated with several other AWS services to help you protect the data you store with these services.
Each AWS KMS Key is uniquely identified by its key-id or key-arn.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_kms_keys` resource block uses an optional filter to select a group of KMS Keys and then tests that group.
# Verify the number of KMS keys in the AWS account
describe aws_kms_keys do
its('entries.count') { should cmp 10 }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
As this is the initial release of `aws_kms_keys`, its limited functionality precludes examples.
<br>
## Properties
* `entries`, `key_arns`, `key_ids`
<br>
## Property Examples
### entries
Provides access to the raw results of a query. This can be useful for checking counts and other advanced operations.
# Allow at most 100 KMS Keys on the account
describe aws_kms_keys do
its('entries.count') { should be <= 100}
end
### key\_arns
Provides a list of key arns for all KMS Keys in the AWS account.
describe aws_kms_keys do
its('key_arns') { should include('arn:aws:kms:us-east-1::key/key-id') }
end
### key\_ids
Provides a list of key ids for all KMS Keys in the AWS account.
describe aws_kms_keys do
its('key_ids') { should include('fd7e608b-f435-4186-b8b5-111111111111') }
end
<br>
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### exists
The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
# Verify that at least one KMS Key exists.
describe aws_kms_keys
it { should exist }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `kms:ListKeys` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for AWS Key Management Service](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awskeymanagementservice.html).

76
docs/resources/aws_rds_instance.md.erb
View file

@ -1,76 +0,0 @@
---
title: About the aws_rds_instance Resource
---
# aws\_rds\_instance
Use the `aws_rds_instance` Chef InSpec audit resource to test detailed properties of an individual RDS instance.
RDS gives you access to the capabilities of a MySQL, MariaDB, PostgreSQL, Microsoft SQL Server, Oracle, or Amazon Aurora database server.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.1.21 of InSpec.
## Syntax
An `aws_rds_instance` resource block uses resource parameters to search for an RDS instance, and then tests that RDS instance. If no RDS instances match, no error is raised, but the `exists` matcher will return `false` and all properties will be `nil`. If more than one RDS instance matches (due to vague search parameters), an error is raised.
# Ensure you have a RDS instance with a certain ID
# This is "safe" - RDS IDs are unique within an account
describe aws_rds_instance('test-instance-id') do
it { should exist }
end
# Ensure you have a RDS instance with a certain ID
# This uses hash syntax
describe aws_rds_instance(db_instance_identifier: 'test-instance-id') do
it { should exist }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
As this is the initial release of `aws_rds_instance`, its limited functionality precludes examples.
<br>
## Resource Parameters
This Chef InSpec resource accepts the following parameters, which are used to search for the RDS instance.
### exists
The control will pass if the specified RDS instance was found. Use should_not if you want to verify that the specified RDS instance does not exist.
# Using Hash syntax
describe aws_rds_instance(db_instance_identifier: 'test-instance-id') do
it { should exist }
end
# Using the instance id directly from the terraform file
describe aws_rds_instance(fixtures['rds_db_instance_id']) do
it { should exist }
end
# Make sure we don't have any RDS instances with the name 'nogood'
describe aws_rds_instance('nogood') do
it { should_not exist }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `rds:DescribeDBInstances` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon RDS](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonrds.html).

63
docs/resources/aws_route_table.md.erb
View file

@ -1,63 +0,0 @@
---
title: About the aws_route_table Resource
platform: aws
---
# aws\_route\_table
Use the `aws_route_table` Chef InSpec audit resource to test properties of a single Route Table. A route table contains a set of rules, called routes, that are used to determine where network traffic is directed.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
# Ensure that a certain route table exists by name
describe aws_route_table('rtb-123abcde') do
it { should exist }
end
## Resource Parameters
### route\_table\_id
This resource expects a single parameter that uniquely identifies the Route Table. You may pass it as a string, or as the value in a hash:
describe aws_route_table('rtb-123abcde') do
it { should exist }
end
# Same
describe aws_route_table(route_table_id: 'rtb-123abcde') do
it { should exist }
end
## Matchers
For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### exist
Indicates that the Route Table provided was found. Use `should_not` to test for Route Tables that should not exist.
describe aws_route_table('should-be-there') do
it { should exist }
end
describe aws_route_table('should-not-be-there') do
it { should_not exist }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ec2:DescribeRouteTables` action with Effect set to Allow.
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).

65
docs/resources/aws_route_tables.md.erb
View file

@ -1,65 +0,0 @@
---
title: About the aws_route_tables Resource
---
# aws\_route\_table
Use the `aws_route_tables` Chef InSpec audit resource to test properties of all or a group of Route Tables. A Route Table contains a set of rules, called routes, that are used to determine where network traffic is directed.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.1.30 of InSpec.
## Syntax
# Ensure that there is at least one route table
describe aws_route_tables do
it { should exist }
end
## Matchers
### exist
Indicates that at least one Route Table was found. Use should_not to test that no Route Tables should exist.
describe aws_route_tables do
it { should exist }
end
describe aws_route_tables do
it { should_not exist }
end
## Properties
### vpc\_ids
Lists all VPCs that are in the Route Tables.
describe aws_route_tables do
its('vpc_ids') { should include 'vpc_12345678' }
end
### route\_table\_ids
Lists all of the Route Table IDs.
describe aws_route_tables do
its('route_table_ids') { should include 'rtb-12345678' }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ec2:DescribeRouteTables` action with Effect set to Allow.
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).

156
docs/resources/aws_s3_bucket.md.erb
View file

@ -1,156 +0,0 @@
---
title: About the aws_s3_bucket Resource
platform: aws
---
# aws\_s3\_bucket
Use the `aws_s3_bucket` Chef InSpec audit resource to test properties of a single AWS bucket.
To test properties of a multiple S3 buckets, use the `aws_s3_buckets` resource.
<br>
## Limitations
S3 bucket 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.
As of January 2018, this resource supports evaluating bucket ACLs and bucket policies. We do not support evaluating object ACLs because it introduces scalability concerns in the AWS API; we recommend using AWS mechanisms such as CloudTrail and Config to detect insecure 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.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_s3_bucket` resource block declares a bucket by name, and then lists tests to be performed.
describe aws_s3_bucket(bucket_name: 'test_bucket') do
it { should exist }
it { should_not be_public }
end
describe aws_s3_bucket('test_bucket') do
it { should exist }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test the bucket-level ACL
describe aws_s3_bucket('test_bucket') do
its('bucket_acl.count') { should eq 1 }
end
### Check if a bucket has a bucket policy
describe aws_s3_bucket('test_bucket') do
its('bucket_policy') { should be_empty }
end
### Check if a bucket appears to be exposed to the public
# See Limitations section above
describe aws_s3_bucket('test_bucket') do
it { should_not be_public }
end
<br>
## Properties
### region
The `region` property identifies the AWS Region in which the S3 bucket is located.
describe aws_s3_bucket('test_bucket') do
# Check if the correct region is set
its('region') { should eq 'us-east-1' }
end
## Unsupported Properties
### bucket\_acl
The `bucket_acl` property is a low-level property that lists the individual Bucket ACL grants in effect on the bucket. Other higher-level properties, such as be\_public, are more concise and easier to use. You can use the `bucket_acl` property to investigate which grants are in effect, causing be\_public to fail.
The value of bucket_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`.
bucket_acl = aws_s3_bucket('my-bucket')
# Look for grants to "AllUsers" (that is, the public)
all_users_grants = bucket_acl.select do |g|
g.grantee.type == 'Group' && g.grantee.uri =~ /AllUsers/
end
# Look for grants to "AuthenticatedUsers" (that is, any authenticated AWS user - nearly public)
auth_grants = bucket_acl.select do |g|
g.grantee.type == 'Group' && g.grantee.uri =~ /AuthenticatedUsers/
end
### bucket\_policy
The `bucket_policy` is a low-level property that describes the IAM policy document controlling access to the bucket. The `bucket_policy` property returns a Ruby structure that you can probe to check for particular statements. We recommend using a higher-level property, such as `be_public`, which is concise and easier to implement in your policy files.
The `bucket_policy` property returns an array of simple objects, each object being an IAM Policy Statement. See the [AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/dev/example-bucket-policies.html#example-bucket-policies-use-case-2) for details about the structure of this data.
If there is no bucket policy, this property returns an empty array.
bucket_policy = aws_s3_bucket('my-bucket')
# Look for statements that allow the general public to do things
# This may be a false positive; it is possible these statements
# could be protected by conditions, such as IP restrictions.
public_statements = bucket_policy.select do |s|
s.effect == 'Allow' && s.principal == '*'
end
<br>
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### be\_public
The `be_public` matcher tests if the bucket 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 bucket if any of the following conditions are met:
1. A bucket ACL grant exists for the 'AllUsers' group
2. A bucket ACL grant exists for the 'AuthenticatedUsers' group
3. A bucket policy has an effect 'Allow' and principal '*'
Note: This resource does not detect insecure object ACLs.
it { should_not be_public }
### have\_access\_logging\_enabled
The `have_access_logging_enabled` matcher tests if access logging is enabled for the s3 bucket.
it { should have_access_logging_enabled }
### have\_default\_encryption\_enabled
The `have_default_encryption_enabled` matcher tests if default encryption is enabled for the s3 bucket.
it { should have_default_encryption_enabled }
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `s3:GetBucketAcl`, `s3:GetBucketLocation`, `s3:GetBucketLogging`, `s3:GetBucketPolicy`, and `s3:GetEncryptionConfiguration` actions set to allow.
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).

99
docs/resources/aws_s3_bucket_object.md.erb
View file

@ -1,99 +0,0 @@
---
title: About the aws_s3_bucket_object Resource
---
# aws\_s3\_bucket\_object
Use the `aws_s3_bucket_object` Chef InSpec audit resource to test properties of a single AWS bucket object.
Each S3 Object has a 'key' which can be thought of as the name of the S3 Object which uniquely identifies it.
<br>
## Limitations
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.
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.
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.1.10 of InSpec.
## Syntax
An `aws_s3_bucket_object` resource block declares a bucket and an object key by name, and then lists tests to be performed.
describe aws_s3_bucket_object(bucket_name: 'test_bucket', key: 'test_object_key') do
it { should exist }
it { should_not be_public }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test a object's object-level ACL
describe aws_s3_bucket_object(bucket_name: 'test_bucket', key: 'test_key') do
its('object_acl.count') { should eq 1 }
end
### Check to see if a object appears to be exposed to the public
# See Limitations section above
describe aws_s3_bucket_object(bucket_name: 'test_bucket', key: 'test_key') do
it { should_not be_public }
end
<br>
## Unsupported Properties
### object\_acl
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.
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`.
object_acl = aws_s3_bucket_object(bucket_name: 'my_bucket', key: 'object_key')
# Look for grants to "AllUsers" (that is, the public)
all_users_grants = object_acl.select do |g|
g.grantee.type == 'Group' && g.grantee.uri =~ /AllUsers/
end
# Look for grants to "AuthenticatedUsers" (that is, any authenticated AWS user - nearly public)
auth_grants = object_acl.select do |g|
g.grantee.type == 'Group' && g.grantee.uri =~ /AuthenticatedUsers/
end
## Matchers
This Chef 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/).
### be\_public
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:
1. A object ACL grant exists for the 'AllUsers' group
2. A object ACL grant exists for the 'AuthenticatedUsers' group
Note: This resource does not detect insecure bucket ACLs.
it { should_not be_public }
## AWS Permissions
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.
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).

69
docs/resources/aws_s3_buckets.md.erb
View file

@ -1,69 +0,0 @@
---
title: About the aws_s3_buckets Resource
---
# aws\_s3\_buckets
Use the `aws_s3_buckets` Chef InSpec audit resource to list all buckets in a single account.
Use the `aws_s3_bucket` Chef InSpec audit resource to perform in-depth auditing of a single S3 bucket.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.1.30 of InSpec.
## Syntax
An `aws_s3_buckets` resource block takes no arguments
describe aws_s3_buckets do
it { should exist }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
As this is the initial release of `aws_s3_buckets`, its limited functionality precludes examples.
<br>
## Matchers
### exists
The control will pass if the resource contains at least one bucket.
# Test if there are any buckets
describe aws_s3_buckets
it { should exist }
end
## Properties
### bucket\_names
Provides an array of strings containing the names of the buckets.
# Examine what buckets have been created.
describe aws_s3_buckets do
its('bucket_names') { should eq ['my_bucket'] }
# OR
its('bucket_names') { should include 'my_bucket' }
end
## AWS Permissions
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.
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).

350
docs/resources/aws_security_group.md.erb
View file

@ -1,350 +0,0 @@
---
title: About the aws_security_group Resource
---
# aws\_security\_group
Use the `aws_security_group` Chef InSpec audit resource to test detailed properties of an individual Security Group (SG).
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.
## Limitations
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:
* References to VPC peers or other AWS services (that is, no support for searches based on 'prefix lists').
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
Resource parameters: group_id, group_name, id, vpc_id
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.
# Ensure you have a Security Group with a specific ID
# This is "safe" - SG IDs are unique within an account
describe aws_security_group('sg-12345678') do
it { should exist }
end
# Ensure you have a Security Group with a specific ID
# This uses hash syntax
describe aws_security_group(id: 'sg-12345678') do
it { should exist }
end
# Ensure you have a Security Group with a specific name. Names are
# unique within a VPC but not across VPCs.
# Using only Group returns an error if multiple SGs match.
describe aws_security_group(group_name: 'my-group') do
it { should exist }
end
# Add vpc_id to ensure uniqueness.
describe aws_security_group(group_name: 'my-group', vpc_id: 'vpc-12345678') do
it { should exist }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
# Ensure that the linux_servers Security Group permits
# SSH from the 10.5.0.0/16 range, but not the world.
describe aws_security_group(group_name: linux_servers) do
# This passes if any inbound rule exists that specifies
# port 22 and the given IP range, regardless of protocol, etc.
it { should allow_in(port: 22, ipv4_range: '10.5.0.0/16') }
# This passes so long as no inbound rule that specifies port 22 exists
# with a source IP range of 0.0.0.0/0. Other properties are ignored.
it { should_not allow_in(port: 22, ipv4_range: '0.0.0.0/0') }
end
# Ensure that the careful_updates Security Group may only initiate contact with specific IPs.
describe aws_security_group(group_name: 'careful_updates') do
# If you have two rules, with one CIDR each:
[ '10.7.23.12/32', '10.8.23.12/32' ].each do |allowed_destination|
# This doesn't care about which ports are enabled
it { should allow_out(ipv4_range: allowed_destination) }
end
# If you have one rule with two CIDRs:
it { should allow_out(ipv4_range: [ '10.7.23.12/32', '10.8.23.12/32' ]) }
# Expect exactly three rules.
its('outbound_rules.count') { should cmp 3 }
end
# Ensure that the canary_deployments Security Group only allows access from one specific security group id on port 443.
describe aws_security_group(group_name: 'canary_deployments') do
it { should allow_in_only(port: 443, security_group: "sg-33334444") }
end
# Ensure that one of the security groups in a list allows access from one of the groups in another list.
# If you have two lists of groups, check if one of the groups in the first list allows access for one of the
# groups in the second list.
control 'master to node access security group' do
desc 'one of the node security groups should allow all access from:
one of the master security groups, so masters can reach all nodes'
describe.one do
[ 'sg-11112222', 'sg-33334444' ].each do |nodeSG|
[ 'sg-55556666', 'sg-77778888' ].each do |masterSG|
describe aws_security_group(id: nodeSG) do
it { should allow_in(security_group: masterSG) }
end
end
end
end
end
<br>
## Resource Parameters
This Chef InSpec resource accepts the following parameters, which are used to search for the Security Group.
### id, group\_id
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.
# Using Hash syntax
describe aws_security_group(id: 'sg-12345678') do
it { should exist }
end
# group_id is an alias for id
describe aws_security_group(group_id: 'sg-12345678') do
it { should exist }
end
# Or omit hash syntax, rely on it being the default parameter
describe aws_security_group('sg-12345678') do
it { should exist }
end
### group\_name
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.
# Get default Security Group for a specific VPC
describe aws_security_group(group_name: 'default', vpc_id: vpc_id: 'vpc-12345678') do
it { should exist }
end
# This throws an error if more than one VPC has a 'backend' SG.
describe aws_security_group(group_name: 'backend') do
it { should exist }
end
### vpc\_id
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.
# This throws an error if more than the default SG exists
describe aws_security_group(vpc_id: 'vpc-12345678') do
it { should exist }
end
<br>
## Properties
* [`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)
<br>
## Property Examples
### description
A String reflecting the human-meaningful description that was given to the SG at creation time.
# Require a description of a particular Security Group
describe aws_security_group('sg-12345678') do
its('description') { should_not be_empty }
end
### group\_id
Provides the Security Group ID.
# Inspect the Security group ID of the default Group
describe aws_security_group(group_name: 'default', vpc_id: vpc_id: 'vpc-12345678') do
its('group_id') { should cmp 'sg-12345678' }
end
# Store the Group ID in a Ruby variable for use elsewhere
sg_id = aws_security_group(group_name: 'default', vpc_id: vpc_id: 'vpc-12345678').group_id
### group\_name
A String reflecting the name that was given to the SG at creation time.
# Inspect the Group name of a particular Group
describe aws_security_group('sg-12345678') do
its('group_name') { should cmp 'my_group' }
end
### inbound\_rules
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.
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.
If the Security Group could not be found (that is, `exists` is false), `inbound_rules` returns an empty list.
describe aws_security_group(group_name: linux_servers) do
its('inbound_rules.first') { should include(from_port: '22', ip_ranges: ['10.2.17.0/24']) }
end
### inbound\_rules\_count
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.
describe aws_security_group(group_name: linux_servers) do
its('inbound_rules_count'){ should eq 10 }
end
### outbound\_rules
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.
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.
If the Security Group could not be found (that is, `exists` is false), `outbound_rules` returns an empty list.
describe aws_security_group(group_name: isolated_servers) do
its('outbound_rules.last') { should_not include(ip_ranges:['0.0.0.0/0']) }
end
### outbound\_rules\_count
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.
describe aws_security_group(group_name: linux_servers) do
its('outbound_rules_count'){ should eq 2 }
end
### vpc\_id
A String in the format 'vpc-' followed by 8 hexadecimal characters reflecting VPC that contains the Security Group.
# Inspect the VPC ID of a particular Group
describe aws_security_group('sg-12345678') do
its('vpc_id') { should cmp 'vpc-12345678' }
end
<br>
## Matchers
This Chef 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/).
* [`allow_in`](#allow_in), [`allow_in_only`](#allow_in_only), [`allow_out`](#allow_out), [`allow_out_only`](#allow_out_only)
### allow\_in
### allow\_out
### allow\_in\_only
### allow\_out\_only
The `allow` series of matchers enable you to perform queries about what network traffic would be permitted through the Security Group rule set.
`allow_in` and `allow_in_exactly` examine inbound rules, and `allow_out` and `allow_out_exactly` examine outbound rules.
`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.
`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.
The matchers accept a key-value list of search criteria. For a rule to match, it must match all provided criteria.
* 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.
* 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.
* 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.
* 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.
* 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.
* protocol - Specifies the IP protocol. 'tcp', 'udp', and 'icmp' are some typical values. The string "-1" or 'any' is used to indicate any protocol.
* 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.
* security_group - Specifies a security-group id, to be checked as permissible origin (for `allow_in`) or destination (for `allow_out`) for traffic. Each AWS Security Group rule may have multiple allowed source or destination security groups.
describe aws_security_group(group_name: 'mixed-functionality-group') do
# Allow RDP from defined range
it { should allow_in(port: 3389, ipv4_range: '10.5.0.0/16') }
it { should allow_in(port: 3389, ipv6_range: '2001:db8::/122') }
# Allow SSH from two ranges
it { should allow_in(port: 22, ipv4_range: ['10.5.0.0/16', '10.2.3.0/24']) }
# Check Bacula port range
it { should allow_in(from_port: 9101, to_port: 9103, ipv4_range: '10.6.7.0/24') }
# Assuming the AWS SG allows 9001-9003, use inexact matching to check 9002
it { should allow_in(port: 9002) }
# Assuming the AWS SG allows 10.2.1.0/24, use inexact matching to check 10.2.1.33/32
it { should allow_in(ipv4_range: '10.2.1.33/32') }
# Ensure the 3rd outbound rule is TCP-based
it { should allow_in(protocol: 'tcp', position: 3') }
# Do not allow unrestricted IPv4 access.
it { should_not allow_in(ipv4_range: '0.0.0.0/0') }
# Allow unrestricted access from security-group.
it { should allow_in(security_group: 'sg-11112222') }
end
# Suppose you have a Group that should allow SSH and RDP from
# the admin network, 10.5.0.0/16. The resource has 2 rules to
# allow this, and you want to ensure no others have been added.
describe aws_security_group(group_name: 'admin-group') do
# Allow RDP from a defined range and nothing else
# The SG must have this rule in position 1 and it must match this exactly
it { should allow_in_only(port: 3389, ipv4_range: '10.5.0.0/16', position: 1) }
# Specify position 2 for the SSH rule. Without `position`,
# allow_in_only only allows one rule, total.
it { should allow_in_only(port: 22, ipv4_range: '10.5.0.0/16', position: 2) }
# Because this is an _only matcher, this fails - _only matchers
# use exact IP matching.
it { should allow_in_only(port: 3389, ipv4_range: '10.5.1.34/32', position: 1) }
end
### exists
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.
# You always have at least one SG, the VPC default SG
describe aws_security_group(group_name: 'default')
it { should exist }
end
# Make sure we don't have any Security Groups with the name 'nogood'
describe aws_security_group(group_name: 'nogood')
it { should_not exist }
end
## AWS Permissions
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.
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).

107
docs/resources/aws_security_groups.md.erb
View file

@ -1,107 +0,0 @@
---
title: About the aws_security_groups Resource
platform: aws
---
# aws\_security\_groups
Use the `aws_security_groups` Chef InSpec audit resource to test properties of some or all security groups.
Security groups are a networking construct that contain ingress and egress rules for network communications. Security groups may be attached to EC2 instances, as well as certain other AWS resources. Along with Network Access Control Lists, Security Groups are one of the two main mechanisms of enforcing network-level security.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_security_groups` resource block uses an optional filter to select a group of security groups and then tests that group.
# Verify you have more than the default security group
describe aws_security_groups do
its('entries.count') { should be > 1 }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
As this is the initial release of `aws_security_groups`, its limited functionality precludes examples.
<br>
## Filter Criteria
### vpc\_id
A string identifying the VPC which contains the security group.
# Look for a particular security group in just one VPC
describe aws_security_groups.where( vpc_id: 'vpc-12345678') do
its('group_ids') { should include('sg-abcdef12')}
end
### group\_name
A string identifying a group. Since groups are contained in VPCs, group names are unique within the AWS account, but not across VPCs.
# Examine the default security group in all VPCs
describe aws_security_groups.where( group_name: 'default') do
it { should exist }
end
<br>
## Properties
* `entries`, `group_ids`
<br>
## Property Examples
### entries
Provides access to the raw results of the query. This can be useful for checking counts and other advanced operations.
# Allow at most 100 security groups on the account
describe aws_security_groups do
its('entries.count') { should be <= 100}
end
### group\_ids
Provides a list of all security group IDs matched.
describe aws_security_groups do
its('group_ids') { should include('sg-12345678') }
end
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### exists
The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
# You will always have at least one SG, the VPC default SG
describe aws_security_groups
it { should exist }
end
## AWS Permissions
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.
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).

140
docs/resources/aws_sns_subscription.md.erb
View file

@ -1,140 +0,0 @@
---
title: About the aws_sns_subscription Resource
---
# aws\_sns\_subscription
Use the `aws_sns_subscription` Chef InSpec audit resource to test detailed properties of a AWS SNS Subscription.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.1.10 of InSpec.
## Syntax
An `aws_sns_subscription` resource block uses resource parameters to search for a SNS Subscription, and then tests that subscriptions properties. If no Subscriptions match, no error is raised, but the `exists` matcher will return `false` and all properties will be `nil`.
describe aws_sns_subscription('arn:aws:sns:us-east-1::test-topic-01:b214aff5-a2c7-438f-a753-8494493f2ff6') do
it { should exist }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
As this is the initial release of `aws_sns_subscription`, its limited functionality precludes examples.
<br>
## Resource Parameters
This Chef InSpec resource accepts the following parameters, which are used to search for the Security Group.
### subscription\_arn
The ARN (Amazon Resource Name) of the AWS SNS Subscription.
# Using Hash syntax
describe aws_sns_subscription(subscription_arn: 'arn:aws:sns:us-east-1::test-topic-01:b214aff5-a2c7-438f-a753-8494493f2ff6') do
it { should exist }
end
# Or omit hash syntax, rely on it being the default parameter
describe aws_sns_subscription('arn:aws:sns:us-east-1::test-topic-01:b214aff5-a2c7-438f-a753-8494493f2ff6') do
it { should exist }
end
<br>
## Matchers
### exists
The control will pass if the specified Aws Subscription was found. Use should_not if you want to verify that the specified Subscription does not exist.
# Test that a specific subscription exists.
describe aws_sns_subscription(subscription_arn: 'arn:aws:sns:us-east-1::test-topic-01:b214aff5-a2c7-438f-a753-8494493f2ff6')
it { should exist }
end
# Test that a Subscription does not exist.
describe aws_sns_subscription(subscription_arn: 'arn:aws:sns:us-east-1::NOGOOD:b214aff5-a2c7-438f-a753-8494493f2ff6')
it { should_not exist }
end
### be\_confirmation\_authenticated
Provides whether or not the subscription confirmation request was authenticated.
describe aws_sns_subscription(subscription_arn: 'arn:aws:sns:us-east-1::NOGOOD:b214aff5-a2c7-438f-a753-8494493f2ff6')
it { should be_confirmation_authenticated }
end
### have\_raw\_message\_delivery
Provides whether or not the original message is passed as is, not formatted as a json or yaml.
describe aws_sns_subscription(subscription_arn: 'arn:aws:sns:us-east-1::NOGOOD:b214aff5-a2c7-438f-a753-8494493f2ff6')
it { should have_raw_message_delivery }
end
## Properties
### endpoint
Provides the destination that the SNS Topic will send notifications to.
# Inspect the endpoint
describe aws_sns_subscription(subscription_arn: 'arn:aws:sns:us-east-1::test-topic-01:b214aff5-a2c7-438f-a753-8494493f2ff6' ) do
# If protocol is 'sms', this should be a phone number:
its('endpoint') { should cmp '+16105551234' }
# If protocol is 'email' or 'email-json', endpoint should be an email address
its('endpoint') { should cmp 'myemail@example.com' }
# If protocal is 'http', endpoint should be a URL beginning with 'https://'
its('endpoint') { should cmp 'https://www.exampleurl.com' }
# If the protocol is 'lambda', its endpoint should be the ARN of a AWS Lambda function
its('endpoint') { should cmp 'rn:aws:lambda:us-east-1:account-id:function:myfunction' }
end
### owner
Provides the AWS Owners ID.
# Inspect the owners ID
describe aws_sns_subscription(subscription_arn: 'arn:aws:sns:us-east-1::test-topic-01:b214aff5-a2c7-438f-a753-8494493f2ff6' ) do
its('owner') { should cmp '12345678' }
end
### protocol
Provides the Subscriptions protocol used. For example http, https, email, email-json, sqs, etc. For more information about protocols please visit https://docs.aws.amazon.com/sns/latest/api/API_Subscribe.html
# Inspect the endpoint
describe aws_sns_subscription(subscription_arn: 'arn:aws:sns:us-east-1::test-topic-01:b214aff5-a2c7-438f-a753-8494493f2ff6' ) do
its('protocol') { should cmp 'sqs' }
end
### topic\_arn
Provides the SNS Topic arn that the Subscription is associated with.
# Inspect the topic arn
describe aws_sns_subscription(subscription_arn: 'arn:aws:sns:us-east-1::test-topic-01:b214aff5-a2c7-438f-a753-8494493f2ff6' ) do
its('topic_arn') { should cmp 'arn:aws:sns:us-east-1::test-topic-01' }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `sns:GetSubscriptionAttributes` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon SNS](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonsns.html).

79
docs/resources/aws_sns_topic.md.erb
View file

@ -1,79 +0,0 @@
---
title: About the aws_sns_topic Resource
---
# aws\_sns\_topic
Use the `aws_sns_topic` Chef InSpec audit resource to test properties of a single AWS Simple Notification Service Topic. SNS topics are channels for related events. AWS resources place events in the SNS topic, while other AWS resources _subscribe_ to receive notifications when new events have appeared.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
# Ensure that a topic exists and has at least one subscription
describe aws_sns_topic('arn:aws:sns:*::my-topic-name') do
it { should exist }
its('confirmed_subscription_count') { should_not be_zero }
end
# You may also use has syntax to pass the ARN
describe aws_sns_topic(arn: 'arn:aws:sns:*::my-topic-name') do
it { should exist }
end
## Resource Parameters
### ARN
This resource expects a single parameter that uniquely identifies the SNS Topic, an ARN. Amazon Resource Names for SNS topics have the format `arn:aws:sns:region:account-id:topicname`. AWS requires a fully-specified ARN for looking up an SNS topic. The account ID and region are required. Wildcards are not permitted.
See also the [AWS documentation on ARNs](http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html).
<br>
## Properties
### confirmed\_subscription\_count
An integer indicating the number of currently active subscriptions.
# Make sure someone is listening
describe aws_sns_topic('arn:aws:sns:*::my-topic-name') do
its('confirmed_subscription_count') { should_not be_zero}
end
<br>
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### exist
Indicates that the ARN provided was found. Use `should_not` to test for SNS topics that should not exist.
# Expect good news
describe aws_sns_topic('arn:aws:sns:*::good-news') do
it { should exist }
end
# No bad news allowed
describe aws_sns_topic('arn:aws:sns:*::bad-news') do
it { should_not exist }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `sns:GetTopicAttributes` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon SNS](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonsns.html).

68
docs/resources/aws_sns_topics.md.erb
View file

@ -1,68 +0,0 @@
---
title: About the aws_sns_topics Resource
---
# aws\_sns\_topics
Use the `aws_sns_topics` Chef InSpec audit resource to test all or a group of the SNS Topic ARNs in an account.
User the 'aws_sns_topic' Chef InSpec audit resource to test a single SNS Topic in an account.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.1.10 of InSpec.
## Syntax
An `aws_sns_topics` resource block takes no filter conditions.
# Get all SNS Topic arns
describe aws_sns_topics do
its('topic_arns') { should include 'arn:aws:sns:us-east-1:333344445555:MyTopic' }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
As this is the initial release of `aws_sns_topics`, its limited functionality precludes examples.
<br>
## Matchers
### exists
The control will pass if the filter returns at least one result. Use should_not if you expect zero matches.
# Test if there is any SNS Topics
describe aws_sns_topics
it { should exist }
end
## Properties
### topic\_arns
Provides an array of all SNS Topic arns.
# Test that a specific SNS Topic exists
describe aws_sns_topics do
its('topic_arns') { should include 'arn:aws:sns:us-east-1:333344445555:MyTopic' }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `sns:ListTopics` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon SNS](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonsns.html).

126
docs/resources/aws_sqs_queue.md.erb
View file

@ -1,126 +0,0 @@
---
title: About the aws_sqs_queue Resource
---
# aws\_sqs\_queue
Use the `aws_sqs_queue` Chef InSpec audit resource to test properties of a single AWS Simple Queue Service queue.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v3.2.5 of InSpec.
## Syntax
# Ensure that a queue exists and has a visibility timeout of 300 seconds
describe aws_sqs_queue('https://sqs.ap-southeast-2.amazonaws.com/1212121/MyQueue') do
it { should exist }
its('visibility_timeout') { should be 300 }
end
# You may also use hash syntax to pass the URL
describe aws_sqs_queue(url: 'https://sqs.ap-southeast-2.amazonaws.com/1212121/MyQueue') do
it { should exist }
end
## Resource Parameters
### URL
This resource expects a single parameter, the SQS queue URL that uniquely identifies the SQS queue.
See also the [AWS documentation on SQS Queue identifiers](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-general-identifiers.html).
<br>
## Properties
### visibility\_timeout
An integer indicating the visibility timeout of the message in seconds
describe aws_sqs_queue('https://sqs.ap-southeast-2.amazonaws.com/1212121/MyQueue') do
its('visibility_timeout') { should be 300}
end
### maximum\_message\_size
An integer indicating the maximum message size in bytes
describe aws_sqs_queue('https://sqs.ap-southeast-2.amazonaws.com/1212121/MyQueue') do
its('maximum_message_size') { should be 262144 } # 256 KB
end
### delay\_seconds
An integer indicating the delay in seconds for the queue
describe aws_sqs_queue('https://sqs.ap-southeast-2.amazonaws.com/1212121/MyQueue') do
its('delay_seconds') { should be 0 }
end
### message\_retention\_period
An integer indicating the maximum retention period for a message in seconds
describe aws_sqs_queue('https://sqs.ap-southeast-2.amazonaws.com/1212121/MyQueue') do
its('message_retention_period') { should be 345600 } # 4 days
end
### receive\_message\_wait\_timeout\_seconds
An integer indicating the number of seconds an attempt to recieve a message will wait before returning
describe aws_sqs_queue('https://sqs.ap-southeast-2.amazonaws.com/1212121/MyQueue') do
its('receive_message_wait_timeout_seconds') { should be 2 }
end
### is\_fifo\_queue
A boolean value indicate if this queue is a FIFO queue
describe aws_sqs_queue('https://sqs.ap-southeast-2.amazonaws.com/1212121/MyQueue') do
its('is_fifo_queue') { should be false }
end
### content\_based\_deduplication
A boolean value indicate if content based dedcuplication is enabled or not
describe aws_sqs_queue('https://sqs.ap-southeast-2.amazonaws.com/1212121/MyQueue.fifo') do
its('is_fifo_queue') { should be true }
its('content_based_deduplication') { should be true }
end
<br>
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### exist
Indicates that the URL provided was found. Use `should_not` to test for SQS topics that should not exist.
# Expect good news
describe aws_sqs_queue('https://sqs.ap-southeast-2.amazonaws.com/1212121/MyQueue') do
it { should exist }
end
# No bad news allowed
describe aws_sqs_queue('https://sqs.ap-southeast-2.amazonaws.com/1212121/MyQueueWhichDoesntExist') do
it { should_not exist }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `sqs:GetQueueAttributes` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon SQS](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-using-identity-based-policies.html).

150
docs/resources/aws_subnet.md.erb
View file

@ -1,150 +0,0 @@
---
title: About the aws_subnet Resource
platform: aws
---
# aws\_subnet
Use the `aws_subnet` Chef InSpec audit resource to test properties of a vpc subnet.
To test properties of a single VPC subnet, use the `aws_subnet` resource.
To test properties of all or a group of VPC subnets, use the `aws_subnets` resource.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_subnet` resource block uses the parameter to select a VPC and a subnet in the VPC.
describe aws_subnet(subnet_id: 'subnet-1234567') do
it { should exist }
its('cidr_block') { should eq '10.0.1.0/24' }
end
<br>
## Resource Parameters
This Chef InSpec resource accepts the following parameters, which are used to search for the VPCs subnet.
### subnet\_id
A string identifying the subnet that the VPC contains.
# This will error if there is more than the default SG
describe aws_subnet(subnet_id: 'subnet-12345678') do
it { should exist }
end
<br>
## Properties
* `availability_zone`, `available_ip_address_count`, `cidr_block`, `subnet_id`, `vpc_id`
<br>
## Property Examples
### availability\_zone
Provides the Availability Zone of the subnet.
describe aws_subnet(subnet_id: 'subnet-12345678') do
its('availability_zone') { should eq 'us-east-1c' }
end
### available\_ip\_address\_count
Provides the number of available IPv4 addresses on the subnet.
describe aws_subnet(subnet_id: 'subnet-12345678') do
its('available_ip_address_count') { should eq 251 }
end
### cidr\_block
Provides the block of ip addresses specified to the subnet.
describe aws_subnet(subnet_id: 'subnet-12345678') do
its('cidr_block') { should eq '10.0.1.0/24' }
end
### subnet\_id
Provides the ID of the Subnet.
describe aws_subnet(subnet_id: 'subnet-12345678') do
its('subnet_id') { should eq 'subnet-12345678' }
end
### vpc\_id
Provides the ID of the VPC the subnet is in.
describe aws_subnet(subnet_id: 'subnet-12345678') do
its('vpc_id') { should eq 'vpc-12345678' }
end
<br>
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### assigning\_ipv\_6\_address\_on\_creation
Detects if the network interface on the subnet accepts IPv6 addresses.
describe aws_subnet(subnet_id: 'subnet-12345678') do
it { should be_assigning_ipv_6_address_on_creation }
end
### available
Provides the current state of the subnet.
describe aws_subnet(subnet_id: 'subnet-12345678') do
it { should be_available }
end
### default\_for\_az
Detects if the subnet is the default subnet for the Availability Zone.
describe aws_subnet(subnet_id: 'subnet-12345678') do
it { should be_default_for_az }
end
### exist
The `exist` matcher indicates that a subnet exists for the specified vpc.
describe aws_subnet(subnet_id: 'subnet-12345678') do
it { should exist }
end
### mapping\_public\_ip\_on\_launch
Provides the VPC ID for the subnet.
describe aws_subnet(subnet_id: 'subnet-12345678') do
it { should be_mapping_public_ip_on_launch }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ec2:DescribeSubnets` action with Effect set to Allow.
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).

142
docs/resources/aws_subnets.md.erb
View file

@ -1,142 +0,0 @@
---
title: About the aws_subnets Resource
platform: aws
---
# aws\_subnets
Use the `aws_subnets` Chef InSpec audit resource to test properties of some or all subnets.
Subnets are networks within a VPC that can have their own block of IP address's and ACL's.
VPCs span across all availability zones in AWS, while a subnet in a VPC can only span a single availability zone.
Separating IP addresses allows for protection if there is a failure in one availability zone.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_subnets` resource block uses an optional filter to select a group of subnets and then tests that group.
# Test all subnets within a single vpc
describe aws_subnets.where(vpc_id: 'vpc-12345678') do
its('subnet_ids') { should include 'subnet-12345678' }
its('subnet_ids') { should include 'subnet-98765432' }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
As this is the initial release of `aws_subnets`, its limited functionality precludes examples.
<br>
## Filter Criteria
* `vpc_id`, `subnet_id`
## Filter Examples
### vpc\_id
A string identifying the VPC which may or may not contain subnets.
# Look for all subnets within a vpc.
describe aws_subnets.where( vpc_id: 'vpc-12345678') do
its('subnet_ids') { should include 'subnet-12345678' }
its('subnet_ids') { should include 'subnet-98765432' }
end
### subnet\_id
A string identifying a specific subnet.
# Examine a specific subnet
describe aws_subnets.where(subnet_id: 'subnet-12345678') do
its('cidr_blocks') { should eq ['10.0.1.0/24'] }
end
<br>
## Properties
* `cidr_blocks`, `states`, `subnet_ids`,`vpc_ids`
<br>
## Property Examples
### cidr\_blocks
Provides a string that contains the cidr block of ip addresses that can be given in the subnet.
# Examine a specific subnets cidr_blocks
describe aws_subnets.where( subnet_id: 'subnet-12345678') do
its('cidr_blocks') { should eq ['10.0.1.0/24'] }
end
### states
Provides an array of strings including if the subnets are available.
# Examine a specific vpcs Subnet IDs
describe aws_subnets.where( vpc_id: 'vpc-12345678') do
its('states') { should_not include 'pending' }
end
### subnet\_ids
Provides an array of strings containing the subnet IDs associated with a vpc.
# Examine a specific vpcs Subnet IDs
describe aws_subnets.where( vpc_id: 'vpc-12345678') do
its('subnet_ids') { should include 'subnet-12345678' }
its('subnet_ids') { should include 'subnet-98765432' }
end
### vpc\_ids
Provides an array containing a string of the vpc_id associated with a subnet.
# Examine a specific subnets VPC IDS
describe aws_subnets.where( subnet_id: 'subnet-12345678') do
its('vpc_ids') { should include 'vpc-12345678' }
end
<br>
## Matchers
For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### exists
The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
# You dont always have subnets, so you can test if there are any.
describe aws_subnets
it { should exist }
end
# Test that there are subnets in a vpc
describe aws_subnets.where(vpc_id: 'vpc-12345678')
it { should exist }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ec2:DescribeSubnets` action with Effect set to Allow.
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).

139
docs/resources/aws_vpc.md.erb
View file

@ -1,139 +0,0 @@
---
title: About the aws_vpc Resource
platform: aws
---
# aws\_vpc
Use the `aws_vpc` Chef InSpec audit resource to test properties of a single AWS Virtual Private Cloud (VPC).
To test properties of all or multiple VPCs, use the `aws_vpcs` resource.
A VPC is a networking construct that provides an isolated environment. A VPC is contained in a geographic region, but spans availability zones in that region. A VPC may have multiple subnets, internet gateways, and other networking resources. Computing resources--such as EC2 instances--reside on subnets within the VPC.
Each VPC is uniquely identified by its VPC ID. In addition, each VPC has a non-unique CIDR IP Address range (such as 10.0.0.0/16) which it manages.
Every AWS account has at least one VPC, the "default" VPC, in every region.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_vpc` resource block identifies a VPC by id. If no VPC ID is provided, the default VPC is used.
# Find the default VPC
describe aws_vpc do
it { should exist }
end
# Find a VPC by ID
describe aws_vpc('vpc-12345678987654321') do
it { should exist }
end
# Hash syntax for ID
describe aws_vpc(vpc_id: 'vpc-12345678') do
it { should exist }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Test that a VPC does not exist
describe aws_vpc('vpc-87654321') do
it { should_not exist }
end
describe aws_vpc('vpc-abcd123454321dcba') do
it { should_not exist }
end
### Test the CIDR of a named VPC
describe aws_vpc('vpc-87654321') do
its('cidr_block') { should cmp '10.0.0.0/16' }
end
<br>
## Properties
* `cidr_block`, `dhcp_options_id`, `state`, `vpc_id`, `instance_tenancy`
<br>
## Property Examples
### cidr\_block
The IPv4 address range that is managed by the VPC.
describe aws_vpc('vpc-87654321') do
its('cidr_block') { should cmp '10.0.0.0/16' }
end
### dhcp\_options\_id
The ID of the set of DHCP options associated with the VPC (or `default` if the default options are associated with the VPC).
describe aws_vpc do
its ('dhcp_options_id') { should eq 'dopt-a94671d0' }
end
### instance\_tenancy
The allowed tenancy of instances launched into the VPC.
describe aws_vpc do
its ('instance_tenancy') { should eq 'default' }
end
### state
The state of the VPC (`pending` | `available`).
describe aws_vpc do
its ('state') { should eq 'available' }
end
### vpc\_id
The ID of the VPC.
describe aws_vpc do
its('vpc_id') { should eq 'vpc-87654321' }
end
<br>
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
### be\_default
The test will pass if the identified VPC is the default VPC for the region.
describe aws_vpc('vpc-87654321') do
it { should be_default }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ec2:DescribeVpcs` action with Effect set to Allow.
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).

135
docs/resources/aws_vpcs.md.erb
View file

@ -1,135 +0,0 @@
---
title: About the aws_vpcs Resource
platform: aws
---
# aws\_vpcs
Use the `aws_vpcs` Chef InSpec audit resource to test properties of some or all AWS Virtual Private Clouds (VPCs).
A VPC is a networking construct that provides an isolated environment. A VPC is contained in a geographic region, but spans availability zones in that region. A VPC may have multiple subnets, internet gateways, and other networking resources. Computing resources--such as EC2 instances--reside on subnets within the VPC.
Each VPC is uniquely identified by its VPC ID. In addition, each VPC has a non-unique CIDR IP Address range (such as 10.0.0.0/16) which it manages.
Every AWS account has at least one VPC, the "default" VPC, in every region.
<br>
## Availability
### Installation
This resource is distributed along with Chef InSpec itself. You can use it automatically.
### Version
This resource first became available in v2.0.16 of InSpec.
## Syntax
An `aws_vpcs` resource block uses an optional filter to select a group of VPCs and then tests that group.
# The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
# Since you always have at least one VPC, this will always pass.
describe aws_vpcs do
it { should exist }
end
# Insist that all VPCs use the same DHCP option set.
describe aws_vpcs.where { dhcp_options_id != 'dopt-12345678' } do
it { should_not exist }
end
<br>
## Examples
The following examples show how to use this Chef InSpec audit resource.
### Check for a Particular VPC ID
describe aws_vpcs do
its('vpc_ids') { should include 'vpc-12345678' }
end
### Use the VPC IDs to Get a List of Default Security Groups
aws_vpcs.vpc_ids.each do |vpc_id|
describe aws_security_group(vpc_id: vpc_id, group_name: 'default') do
it { should_not allow_in(port: 22) }
end
end
<br>
## Filter Criteria
### cidr_block
Filters the results to include only those VPCs that match the given IPv4 range. This is a string value.
# We shun the 10.0.0.0/8 space
describe aws_vpcs.where { cidr_block.start_with?('10') } do
it { should_not exist }
end
### dhcp_option_id
Filters the results to include only those VPCs that have the given DHCP Option Set.
# Insist on one DHCP option set for all VPCs.
describe aws_vpcs.where { dhcp_options_id != 'dopt-12345678' } do
it { should_not exist }
end
## Properties
### cidr_blocks
The cidr_blocks property provides a list of the CIDR blocks that the matched VPCs serve as strings.
describe aws_vpcs do
# This is simple array membership checking - not subnet membership
its('cidr_blocks') { should include '179.0.0.0/16' }
end
### dhcp_options_ids
The dhcp_option_set_ids property provides a de-duplicated list of the DHCP Option Set IDs that the matched VPCs use when assigning IPs to resources.
describe aws_vpcs do
its('dhcp_options_ids') { should include 'dopt-12345678' }
end
### vpc_ids
The vpc_ids property provides a list of the IDs of the matched VPCs.
describe aws_vpcs do
its('vpc_ids') { should include 'vpc-12345678' }
end
# Get a list of all VPC IDs
aws_vpcs.vpc_ids.each do |vpc_id|
# Do something with vpc_id
end
## Matchers
This Chef InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [Universal Matchers page](https://www.inspec.io/docs/reference/matchers/).
### exists
The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
# You will always have at least one VPC
describe aws_vpcs
it { should exist }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ec2:DescribeVpcs` action with Effect set to Allow.
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).

10
tasks/contrib.rb
View file

@ -38,17 +38,14 @@ namespace :contrib do # rubocop: disable Metrics/BlockLength
desc "Copy docs from resource packs into the core for doc building"
task copy_docs: [:fetch_resource_packs] do
puts "Copying resource pack docs..."
config["resource_packs"].each do |name, info|
doc_sub_dir = info["doc_sub_dir"] || "docs/resources"
doc_src_path = File.join(CONTRIB_DIR, name, doc_sub_dir)
dest_path = RESOURCE_DOC_DIR
puts " #{name}:"
Dir.chdir(doc_src_path) do
Dir.glob("*.md*").each do |file|
Dir["*.md*"].sort.each do |file|
# TODO: check file for Availability section in markdown?
FileUtils.cp(file, dest_path)
puts " #{file}"
end
end
end
@ -56,14 +53,13 @@ namespace :contrib do # rubocop: disable Metrics/BlockLength
desc "Cleanup docs from resource packs in core"
task cleanup_docs: [:read_config] do
puts "Purging resource pack docs..."
# TODO: I don't see the point of this cleanup phase
config["resource_packs"].each do |name, info|
doc_sub_dir = info["doc_sub_dir"] || "docs/resources"
doc_src_path = File.join(CONTRIB_DIR, name, doc_sub_dir)
dest_path = RESOURCE_DOC_DIR
puts " #{name}"
Dir.chdir(doc_src_path) do
Dir.glob("*.md*").each do |file|
Dir["*.md*"].sort.each do |file|
cruft = File.join(dest_path, file)
FileUtils.rm_f(cruft)
end

66
tasks/docs.rb
View file

@ -15,20 +15,13 @@
#
require "erb"
require "ruby-progressbar"
require "fileutils"
require "yaml"
require_relative "./shared"
require "git"
require_relative "./contrib"
WWW_DIR = File.expand_path(File.join(__dir__, "..", "www")).freeze
DOCS_DIR = File.expand_path(File.join(__dir__, "..", "docs")).freeze
begin
require "git"
require_relative "./contrib"
rescue LoadError
puts "contrib tasks are unavailable because the git gem is not available."
end
DOCS_DIR = "../docs".freeze
class Markdown
class << self
@ -150,6 +143,8 @@ class ResourceDocs
contrib_config = YAML.load(File.read(File.join(CONTRIB_DIR, "contrib.yaml")))
# TODO: clean this up using Hash.new and friends
# Build a list of resources keyed on the group they are a part of.
# We'll determine the group using regexes.
group_regexes = [
@ -295,26 +290,25 @@ namespace :docs do # rubocop:disable Metrics/BlockLength
task resources_actual: %i{clean contrib:copy_docs} do
src = DOCS_DIR
dst = File.join(WWW_DIR, "source", "docs", "reference", "resources")
FileUtils.mkdir_p(dst)
dst = File.join("source", "docs", "reference", "resources")
mkdir_p(dst)
docs = ResourceDocs.new(src)
resources = Dir.glob([File.join(src, "resources/*.md.erb"), File.join(src, "resources/*.md")])
.map { |x| x.sub(/^#{src}/, "") }
resources =
Dir.chdir(src) { Dir["resources/*.md{.erb,}"] }
.sort
puts "Found #{resources.length} resource docs"
puts "Rendering docs to #{dst}/"
# Render all resources
progressbar = ProgressBar.create(total: resources.length, title: "Rendering")
resources.each do |file|
progressbar.log(" " + file)
seen = {}
resources.reverse_each do |file| # bias towards .erb files?
dst_name = File.basename(file).sub(/\.md(\.erb)?$/, ".html.md")
next if seen[dst_name]
seen[dst_name] = true
res = docs.render(file)
File.write(File.join(dst, dst_name), res)
progressbar.increment
end
progressbar.finish
# Create a resource summary markdown doc
dst = File.join(src, "resources.md")
@ -324,42 +318,28 @@ namespace :docs do # rubocop:disable Metrics/BlockLength
desc "Clean all rendered docs from www/"
task :clean do
dst = File.join(WWW_DIR, "source", "docs", "reference")
puts "Clean up #{dst}"
FileUtils.rm_rf(dst) if File.exist?(dst)
FileUtils.mkdir_p(dst)
dst = File.join("source", "docs", "reference")
rm_rf(dst)
mkdir_p(dst)
end
desc "Copy fixed doc files"
task copy: %i{clean resources} do
src = DOCS_DIR
dst = File.join(WWW_DIR, "source", "docs", "reference")
dst = File.join("source", "docs", "reference")
files = Dir[File.join(src, "*.md")]
progressbar = ProgressBar.create(total: files.length, title: "Copying")
files.each do |path|
name = File.basename(path).sub(/\.md$/, ".html.md")
progressbar.log(" " + File.join(dst, name))
FileUtils.cp(path, File.join(dst, name))
progressbar.increment
end
progressbar.finish
end
end
def run_tasks_in_namespace(ns)
Rake.application.in_namespace(ns) do |x|
x.tasks.each do |task|
puts "----> #{task}"
task.invoke
cp(path, File.join(dst, name))
end
end
end
desc "Create all docs in docs/ from source code"
task :docs do
run_tasks_in_namespace :docs
Verify.file(File.join(WWW_DIR, "source", "docs", "reference", "README.html.md"))
Verify.file(File.join(WWW_DIR, "source", "docs", "reference", "cli.html.md"))
Verify.file(File.join(WWW_DIR, "source", "docs", "reference", "resources.html.md"))
task docs: %w{docs:cli docs:copy docs:resources} do
# TODO: remove:
Verify.file(File.join("source", "docs", "reference", "README.html.md"))
Verify.file(File.join("source", "docs", "reference", "cli.html.md"))
Verify.file(File.join("source", "docs", "reference", "resources.html.md"))
end

14
www/Gemfile
View file

@ -1,15 +1,7 @@
# If you do not have OpenSSL installed, update
# the following line to use 'http://' instead
source "https://rubygems.org"
gem "slim", ">= 3.0"
# For faster file watcher updates on Windows:
gem "wdm", "~> 0.1.0", platforms: %i{mswin mingw}
# windows does not come with time zone data
gem "tzinfo-data", platforms: %i{mswin mingw}
# Middleman Gems
gem "middleman", ">= 4.0.0"
gem "middleman-autoprefixer"
@ -19,18 +11,12 @@ gem "middleman-sprockets", ">= 4.0.0"
gem "middleman-syntax"
gem "redcarpet"
# Tutorial Gems
gem "docker-api"
gem "github-markup"
# Needed to fetch contrib resource packs, etc.
gem "git", "~> 1.4"
# Build process requirements
gem "inquirer"
gem "inspec", path: ".."
gem "rake"
gem "ruby-progressbar"
# Ability to flush the cache during a deploy
gem "fastly"

193
www/Rakefile
View file

@ -1,21 +1,4 @@
#!/usr/bin/env rake
# Copyright:: Copyright (c) 2015 Chef Software, Inc.
# License:: Apache License, Version 2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
$LOAD_PATH.unshift(File.join(File.expand_path(File.dirname(__FILE__)), "..", "lib"))
$LOAD_PATH.unshift "../lib"
require "uri"
require "net/http"
@ -24,166 +7,62 @@ require "fastly"
require_relative "../tasks/docs.rb"
require_relative "../tasks/shared.rb"
task :default do
puts "There is no default task - see `rake --tasks` for available www-related tasks."
puts "Run `rake www` to do a full website release."
exit(1)
end
task default: :www # at bottom
namespace :www do # rubocop:disable Metrics/BlockLength
task :accept_license do
FileUtils.mkdir_p(File.join(Dir.home, ".chef", "accepted_licenses"))
# If the user has not accepted the license, touch the acceptance
# file, but also touch a marker that it is only for testing.
unless File.exist?(File.join(Dir.home, ".chef", "accepted_licenses", "inspec"))
puts "\n\nTemporarily accepting Chef user license for the duration of testing...\n"
FileUtils.touch(File.join(Dir.home, ".chef", "accepted_licenses", "inspec"))
FileUtils.touch(File.join(Dir.home, ".chef", "accepted_licenses", "inspec.for_testing"))
end
# Regardless of what happens, when this process exits, check for cleanup.
at_exit do
if File.exist?(File.join(Dir.home, ".chef", "accepted_licenses", "inspec.for_testing"))
puts "\n\nRemoving temporary Chef user license acceptance file that was placed for test duration.\n"
FileUtils.rm_f(File.join(Dir.home, ".chef", "accepted_licenses", "inspec"))
FileUtils.rm_f(File.join(Dir.home, ".chef", "accepted_licenses", "inspec.for_testing"))
end
end
end
desc "Builds the middleman site"
task :site do
Log.section "Build middleman project"
Bundler.with_clean_env do
sh("bundle install && bundle exec middleman build")
end
sh("bundle exec middleman build --parallel --clean --no-verbose")
# TODO: remove:
Verify.file("build/index.html")
Verify.file("build/javascripts/all.js")
Verify.file("build/stylesheets/site.css")
end
task site: [:accept_license]
desc "Assemble the website site from middleman"
task :assemble do
Log.section "Copy only tutorial into middleman build directory"
sh("rsync -a --exclude=index.html build/")
# do nothing for now
end
task assemble: [:accept_license]
desc "Builds the full site locally"
task build: ["www:site", "www:assemble"]
task build: [:accept_license]
task build: %w{www:site www:assemble}
task :clean do
dst = "build"
FileUtils.rm_rf(dst) if File.directory?(dst)
rm_rf("build")
end
desc "Releases the site to gh-pages"
task :release do
# This folder contains the built files
dst = "build"
unless File.directory?(dst) && File.file?(File.join(dst, "index.html"))
puts "It looks like you have not built the site yet. Calling rake www:build"
Rake::Task["www:build"].invoke
src = File.expand_path "build"
unless system("git diff-index --quiet HEAD --")
warn "WARNING: You have uncommitted changes in this repository."
end
unless File.directory?(dst) && File.file?(File.join(dst, "index.html"))
raise "It looks like the site was not build. Aborting."
end
Dir.mktmpdir do |path|
sh("git worktree add #{path}/gh-pages gh-pages")
# check if git exists
sh("command -v git >/dev/null 2>&1") ||
raise("It looks like `git` isn't installed. It is required to run this build task.")
Dir.chdir "#{path}/gh-pages" do
rm_rf Dir["*"] # easiest way to account for removals
unless sh("git diff-index --quiet HEAD --")
raise "Please make sure you have no uncommitted changes in this repository."
end
cp_r Dir["#{src}/*"], "." # copy build back
File.write("CNAME", "origin.inspec.io") # TODO: just check this file in?
File.write(File.join(dst, "CNAME"), "origin.inspec.io")
file_count = Dir[File.join(dst, "*")].length
file_size = `du -hs #{dst}`.sub(/\s+.*$/m, "")
sh "git add ." # add everything that changed
if system("git rev-parse --verify gh-pages")
Log.info "Remove local gh-pages branch"
sh("git branch -D gh-pages")
end
sh "git status"
if ENV["V"]
sh "git diff --cached"
end
current_branch = `git rev-parse --abbrev-ref HEAD`.strip
if current_branch.empty?
raise "Cannot determine current branch to go back to! Aborting."
end
Log.info "Create empty gh-pages branch"
sh("git checkout --orphan gh-pages")
# this rest of this task needs to be run from the root of the inspec repo
# so it can properly move and clean files in the gh-pages branch
Dir.chdir(File.join(Dir.pwd, "..")) do
dst_from_root = File.join("www", dst)
Log.info "Clear out all local git files!"
sh("git rm -rf .")
Log.info "Add the built files in #{dst_from_root}"
sh("git add #{dst_from_root}")
Log.info "Remove all other files in this empty branch"
sh("git clean -df")
Log.info "Move the site to the root directory"
sh("git mv #{File.join(dst_from_root, "*")} .")
Log.info "Commit to gh-pages"
sh("git commit -m 'website update'")
require "inquirer"
if Ask.confirm("Ready to go, I have #{file_count} files at #{file_size}. "\
"Do you want to push this live?", default: false)
Log.info "push to origin, this may take a moment"
sh("git push -u origin --force-with-lease gh-pages")
else
puts "Aborted."
if ENV["PUSH"]
sh "git commit -m 'website update'"
sh "git push -u origin gh-pages"
end
end
sh("git worktree remove -f #{path}/gh-pages")
end
sh("git checkout #{current_branch}")
end
desc "Release the site to the Netlify acceptance environment"
task :acceptance do
raise "NETLIFYKEY environment variable not set" unless ENV.key?("NETLIFYKEY")
Log.info "Cleaning the existing build directory"
Rake::Task["www:clean"].invoke
Log.info "Building the docs"
Rake::Task["docs"].invoke
Log.info "Building the site"
Rake::Task["www:build"].invoke
Log.info "Creating zip file of website contents"
Dir.chdir(File.join(Dir.pwd, "build")) do
sh("zip -r inspec-acceptance.zip *")
end
Log.info "Uploading to Netlify"
uri = URI.parse("https://api.netlify.com/api/v1/sites/inspec-acceptance.netlify.com/deploys")
request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/zip"
request["Authorization"] = "Bearer #{ENV["NETLIFYKEY"]}"
request.body = File.read(File.join(Dir.pwd, "build", "inspec-acceptance.zip"), mode: "rb")
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
raise "Failed to upload to Netlify: #{response.code} -- #{response.body}" unless response.code == "200"
Log.info "Removing zip file"
File.unlink(File.join(Dir.pwd, "build", "inspec-acceptance.zip"))
end
desc "Flush the inspec.io cache at Fastly"
@ -191,12 +70,12 @@ namespace :www do # rubocop:disable Metrics/BlockLength
api_key = ENV["FASTLY_API_KEY"]
service_id = ENV["FASTLY_SERVICE_ID"]
if api_key.nil? || service_id.nil?
puts ""
unless api_key && service_id
puts
puts "WARNING: could not flush the Fastly cache for inspec.io."
puts "Please set FASTLY_API_KEY and FASTLY_SERVICE_ID environment variables"
puts "and run `rake www:flush`."
puts ""
puts
next
end
@ -219,11 +98,5 @@ namespace :www do # rubocop:disable Metrics/BlockLength
end
end
desc "Full website release: includes local clean, docs build, site build, and then release"
task :www do
Rake::Task["www:clean"].invoke
Rake::Task["docs"].invoke
Rake::Task["www:build"].invoke
Rake::Task["www:release"].invoke
Rake::Task["www:flush"].invoke
end
desc "Full website release: includes docs build, site build, and then release"
task www: %w{docs www:build www:release www:flush}

15
www/config.rb
View file

@ -27,17 +27,18 @@ configure :development do
activate :livereload
end
class Middleman::Cli::Build < Thor::Group
protected
def on_event(event_type, target, extra = nil)
# no logging
end
end
# Methods defined in the helpers block are available in templates
require "lib/sidebar_helpers"
helpers SidebarHelpers
# Methods defined in the helpers block are available in templates
# helpers do
# def some_helper
# 'Helping'
# end
# end
#
# Build-specific configuration
configure :build do
# Minify CSS on build