Mirrors/inspec
2
0
Fork 0
mirror of https://github.com/inspec/inspec synced 2024-11-23 05:03:07 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #5868 from inspec/im/migrate_resources

Browse source 
Delete resource docs from inspec/inspec
This commit is contained in:
Clinton Wolfe 2022-02-27 19:43:05 -05:00 committed by GitHub
commit 1a4d58a691
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
99 changed files with 9 additions and 9515 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
docs-chef-io/content/inspec/resources/_index.md
View file

@ -13,6 +13,8 @@ gh_repo = "inspec"
The following list of InSpec resources are available.
{{< inspec_resources_filter >}}
## OS
{{< inspec_resources platform="os" >}}
@ -29,6 +31,10 @@ The following resources work on Windows operating systems.
{{< inspec_resources platform="windows" >}}
## Alibaba
{{< inspec_resources platform="alicloud" >}}
## AWS
{{< inspec_resources platform="aws" >}}

90
docs-chef-io/content/inspec/resources/aws_alb.md
View file

@ -1,90 +0,0 @@
+++
title = "aws_alb resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_alb"
identifier = "inspec/resources/aws/aws_alb.md aws_alb resource"
parent = "inspec/resources/aws"
+++
Use the `aws_alb` InSpec audit resource to test properties of a single AWS Application Load Balancer (ALB).
## Syntax
Ensure that an `aws_alb` exists
describe aws_alb('arn:aws:elasticloadbalancing') do
it { should exist }
end
describe aws_alb(load_balancer_arn: 'arn:aws:elasticloadbalancing') do
it { should exist }
end
## Parameters
### load_balancer_arn _(required)_
This resource accepts a single parameter, the ALB Arn which uniquely identifies the ALB.
This can be passed either as a string or as a `load_balancer_arn: 'value'` key-value entry in a hash.
See also the [AWS documentation on Elastic Load Balancing](https://docs.aws.amazon.com/elasticloadbalancing/latest/APIReference).
## Properties
| Property | Description |
| ------------------------ | ---------------------------------------------------------------------------------- |
| load_balancer_name | The name of the load balancer. |
| load_balancer_addresses | A collection of the load balancer addresses. |
| canonical_hosted_zone_id | The ID of the Amazon Route 53 hosted zone for the load balancer. |
| dns_name | The DNS name of the load balancer. |
| availability_zones | The Availability Zones for the load balancer. |
| security_groups | The security groups for the load balancer. Valid only for load balancers in a VPC. |
| scheme | The type of load balancer. Valid only for load balancers in a VPC. |
| state | The state of the load balancer. |
| subnets | A collection of the subnet ids. |
| type | The type of the load balancer. |
| vpc_id | The ID of the VPC for the load balancer. |
| zone_names | A collection of the names of the availability zones. |
| listeners | A collection of the listeners for the load balancer. |
| ssl_policies | A list of the SSL Policies configured for the listeners of the load balancer. |
| external_ports | A list of the ports configured for the listeners of the load balancer. |
| protocols | A list of the protocols configured for the listeners of the load balancer. |
## Examples
### Test that an ALB has its availability zones configured correctly
describe aws_alb('arn::alb') do
its('zone_names.count') { should be > 1 }
its('zone_names') { should include 'us-east-2a' }
its('zone_names') { should include 'us-east-2b' }
end
## Matchers
This InSpec audit resource has no special matchers. For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_alb('AnExistingALB') do
it { should exist }
end
describe aws_alb('ANonExistentALB') 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)

76
docs-chef-io/content/inspec/resources/aws_albs.md
View file

@ -1,76 +0,0 @@
+++
title = "aws_albs resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_albs"
identifier = "inspec/resources/aws/aws_albs.md aws_albs resource"
parent = "inspec/resources/aws"
+++
Use the `aws_albs` InSpec audit resource to test the configuration of a collection of Application Load Balancers.
## Syntax
Ensure that an `aws_albs` exists
describe aws_albs do
its('load_balancer_arns') { should include 'arn:aws:elasticloadbalancing' }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on Elastic Load Balancing](https://docs.aws.amazon.com/elasticloadbalancing/latest/APIReference).
## Properties
| Property | Description |
| ------------------------- | ----------------------------------------------------------------------------------- |
| load_balancer_names | The names of the load balancers. |
| load_balancer_addresses | A collection of the load balancers addresses. |
| canonical_hosted_zone_ids | The IDs of the Amazon Route 53 hosted zone for the load balancers. |
| dns_names | The DNS names of the load balancers. |
| availability_zones | The Availability Zones for the load balancers. |
| security_groups | The security groups for the load balancers. Valid only for load balancers in a VPC. |
| schemes | The types of load balancers. Valid only for load balancers in a VPC. |
| states | The states of the load balancers. |
| subnets | A collection of the subnet ids. |
| types | The types of the load balancers. |
| vpc_ids | The IDs of the VPCs for the load balancers. |
| zone_names | A collection of the names of the availability zones. |
## Examples
### Test that an ALB has its availability zones configured correctly
describe aws_alb('arn::alb') do
its('zone_names.count') { should be > 1 }
its('zone_names') { should include 'us-east-2a' }
its('zone_names') { should include 'us-east-2b' }
end
## Matchers
This InSpec audit resource has no special matchers. For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_albs do
it { should exist }
its('availability_zones') { should_not include 'us-east-1a'}
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)

90
docs-chef-io/content/inspec/resources/aws_auto_scaling_group.md
View file

@ -1,90 +0,0 @@
+++
title = "aws_auto_scaling_group resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_auto_scaling_group"
identifier = "inspec/resources/aws/aws_auto_scaling_group.md aws_auto_scaling_group resource"
parent = "inspec/resources/aws"
+++
Use the `aws_auto_scaling_group` InSpec audit resource to test properties of a single AWS Auto Scaling group.
## Syntax
Ensure that an auto scaling group exists and has the correct scale sizes
describe aws_auto_scaling_group('MyAutoScalingGroup') do
it { should exist }
its('min_size') { should be 1}
its('max_size') { should be 4}
end
You may also use hash syntax to pass the auto scaling group name
describe aws_auto_scaling_group(name: 'MyAutoScalingGroup') do
it { should exist }
end
## Parameters
### name _(required)_
This resource accepts a single parameter, the Auto Scaling Group Name which uniquely identifies the auto scaling group.
This can be passed either as a string or as a `name: 'value'` key-value entry in a hash.
See also the [AWS documentation on Auto Scaling Group](https://docs.aws.amazon.com/autoscaling/ec2/userguide/AutoScalingGroup.html).
## Properties
| Property | Description |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| min_size | An integer indicating the minimum number of instances in the auto scaling group |
| maximum_size | An integer indicating the maximum number of instances in the auto scaling group |
| desired_capacity | An integer indicating the desired number of instances in the auto scaling group |
| launch_configuration_name | The name of the auto scaling launch configuration associated with the auto scaling group |
| vpc_zone_identifier | An array of strings corresponding to the subnet IDs associated with the auto scaling group |
| tags | An hash with each key-value pair corresponding to a tag associated with the entity |
## Examples
### Ensure that an auto scaling group has the correct desired capacity
describe aws_auto_scaling_group('MyAutoScalingGroup') do
it { should exist }
its('desired_capacity') { should be 2 }
end
### Ensure that an auto scaling group has the correct Launch Configuration name and VPC identifier
describe aws_auto_scaling_group('MyAutoScalingGroup') do
it { should exist }
its('launch_configuration_name') { should eq 'MyLaunchConfiguration'}
its('vpc_zone_identifier') { should include 'subnet-1234'}
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_auto_scaling_group('AnExistingASG') do
it { should exist }
end
describe aws_auto_scaling_group('ANonExistentASG') 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 `autoscaling:Describe*` actions with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon Auto Scaling Groups](https://docs.aws.amazon.com/autoscaling/ec2/userguide/control-access-using-iam.html).

73
docs-chef-io/content/inspec/resources/aws_auto_scaling_groups.md
View file

@ -1,73 +0,0 @@
+++
title = "aws_auto_scaling_groups resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_auto_scaling_groups"
identifier = "inspec/resources/aws/aws_auto_scaling_groups.md aws_auto_scaling_groups resource"
parent = "inspec/resources/aws"
+++
Use the `aws_auto_scaling_groups` InSpec audit resource to test the properties of a collection of AWS Auto Scaling Groups.
## Syntax
An `aws_auto_scaling_groups` resource block returns all Auto Scaling Groups and allows the testing of those ASGs.
describe aws_auto_scaling_groups do
its('names') { should include 'group-name' }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on Auto Scaling Group](https://docs.aws.amazon.com/autoscaling/ec2/userguide/AutoScalingGroup.html).
## Properties
| Property | Description |
| -------------------------- | -------------------------------------------------------------------------------------------- |
| min_sizes | An integer indicating the minimum number of instances in the auto scaling group |
| max_sizes | An integer indicating the maximum number of instances in the auto scaling group |
| desired_capacities | An integer indicating the desired number of instances in the auto scaling group |
| launch_configuration_names | The name of the auto scaling launch configuration associated with the auto scaling group |
| vpc_zone_identifiers | An array of strings corresponding to the subnet IDs associated with the auto scaling group |
| health_check_types | The service to use for the health checks. The valid values are EC2 and ELB. |
| tags | A hash of key-value pairs corresponding to the tags associated with the entity. |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
### Ensure there are no groups with incorrect vpc_zone_identifiers.
describe aws_auto_scaling_groups do
it { should exist }
its('vpc_zone_identifiers') { should_not include 'UNDESIRED-ZONE'}
end
## Matchers
For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_auto_scaling_groups.where( <property>: <value>) do
it { should exist }
end
describe aws_auto_scaling_groups.where( <property>: <value>) 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 `autoscaling:Describe*` actions with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon Auto Scaling Groups](https://docs.aws.amazon.com/autoscaling/ec2/userguide/control-access-using-iam.html).

95
docs-chef-io/content/inspec/resources/aws_cloudformation_stack.md
View file

@ -1,95 +0,0 @@
+++
title = "aws_cloudformation_stack resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_cloudformation_stack"
identifier = "inspec/resources/aws/aws_cloudformation_stack.md aws_cloudformation_stack resource"
parent = "inspec/resources/aws"
+++
Use the `aws_cloudformation_stack` InSpec audit resource to test properties of a single AWS Cloud Formation Stack.
## Syntax
Ensure that an `aws_cloudformation_stack` exists
describe aws_cloudformation_stack('stack-name') do
it { should exist }
end
describe aws_cloudformation_stack(stack_name: 'stack-name') do
it { should exist }
end
## Parameters
### stack_name _(required)_
This resource accepts a single parameter, the CloudFormation Stack name which uniquely identifies the stack.
This can be passed either as a string or as a `stack_name: 'value'` key-value entry in a hash.
See also the [AWS documentation on Cloud Formation](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/Welcome.html).
## Properties
|Property | Description|
| --- | --- |
|stack_id | Unique identifier of the stack. |
|stack_name | The name associated with the stack. |
|change_set_id | The unique ID of the change set. |
|description | A user-defined description associated with the stack. |
|parameters | A list of Parameter structures. |
|creation_time | The time at which the stack was created. |
|deletion_time | The time the stack was deleted. |
|last_updated_time | The time the stack was last updated. |
|rollback_configuration | The rollback triggers for AWS CloudFormation to monitor during stack creation and updating operations, and for the specified monitoring period afterwards. |
|stack_status | Current status of the stack. |
|stack_status_reason | Success/failure message associated with the stack status. |
|drift_information | Information on whether a stack's actual configuration differs, or has drifted, from it's expected configuration, as defined in the stack template and any values specified as template parameters. |
|disable_rollback | Boolean to enable or disable rollback on stack creation failures: |
|notification_arns | SNS topic ARNs to which stack related events are published. |
|timeout_in_minutes | The amount of time within which stack creation should complete. |
|capabilities | The capabilities allowed in the stack. |
|outputs | A list of output structures. |
|role_arn | The Amazon Resource Name (ARN) of an AWS Identity and Access Management (IAM) role that is associated with the stack. |
|tags | A list of Tags that specify information about the stack. |
|enable_termination_protection | Whether termination protection is enabled for the stack. |
|parent_id | For nested stacks--stacks created as resources for another stack--the stack ID of the direct parent of this stack. |
|root_id | For nested stacks--stacks created as resources for another stack--the stack ID of the the top-level stack to which the nested stack ultimately belongs. |
## Examples
### Test that a CloudFormation Stack has its stack_status configured correctly
describe aws_cloudformation_stack('stack_name') do
its ('stack_status') { should eq 'CREATE_COMPLETE' }
end
## Matchers
This InSpec audit resource has no special matchers. For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_cloudformation_stack('AnExistingStack') do
it { should exist }
end
describe aws_cloudformation_stack('ANonExistentStack') 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 `cloudformation:DescribeStacks` action set to Allow.
You can find detailed documentation at [Authentication and Access Control for CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)

124
docs-chef-io/content/inspec/resources/aws_cloudtrail_trail.md
View file

@ -1,124 +0,0 @@
+++
title = "aws_cloudtrail_trail resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_cloudtrail_trail"
identifier = "inspec/resources/aws/aws_cloudtrail_trail.md aws_cloudtrail_trail resource"
parent = "inspec/resources/aws"
+++
Use the `aws_cloudtrail_trail` InSpec audit resource to test properties of a single AWS CloudTrail.
## 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
## Parameters
### trail_name _(required)_
This resource expects a single parameter, the CloudTrail Name which uniquely identifies it.
This can be passed either as a string or as a `trail_name: 'value'` key-value entry in a hash.
See also the [AWS documentation on CloudTrail](https://docs.aws.amazon.com/cloudtrail/index.html#lang/en_us).
## Properties
|Property | Description|
| --- | --- |
|trail_arn | Specifies the ARN of the trail. |
|trail_name | Name of the trail. |
|home_region | The region in which the trail was created. |
|s3_bucket_name | Name of the Amazon S3 bucket into which CloudTrail delivers your trail files. |
|cloud_watch_logs_role_arn | Specifies the role for the CloudWatch Logs endpoint to assume to write to a user's log group. |
|cloud_watch_logs_log_group_arn | Specifies an Amazon Resource Name (ARN), a unique identifier that represents the log group to which CloudTrail logs will be delivered. |
|kms_key_id | Specifies the KMS key ID that encrypts the logs delivered by CloudTrail. |
## Examples
### Test that the specified trail does exist
describe aws_cloudtrail_trail('my-cloudtrail') do
it { should exist }
end
describe aws_cloudtrail_trail(trail_name: 'my-cloudtrail') do
it { should exist }
end
### Check the KMS key used to encrypt
describe aws_cloudtrail_trail('my-cloudtrail') do
its('kms_key_id') { should eq "my-kms-key" }
end
### Check the Home Region is correct
describe aws_cloudtrail_trail('my-cloudtrail') do
its('home_region') { should eq 'us-east-1' }
end
### Test that the specified trail is a multi-region trail
describe aws_cloudtrail_trail('my-cloudtrail') do
it { should be_multi_region_trail }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
# Verify that at least one CloudTrail Trail exists.
describe aws_cloudtrail_trail('my-cloudtrail') do
it { should exist }
end
### be_multi_region_trail
The test will pass if the identified trail is a multi-region trail.
describe aws_cloudtrail_trail('my-cloudtrail') do
it { should be_multi_region_trail }
end
### be_encrypted
The test will pass if the logs delivered by the identified trail are encrypted.
describe aws_cloudtrail_trail('my-cloudtrail') 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('my-cloudtrail') 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).

74
docs-chef-io/content/inspec/resources/aws_cloudtrail_trails.md
View file

@ -1,74 +0,0 @@
+++
title = "aws_cloudtrail_trails resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_cloudtrail_trails"
identifier = "inspec/resources/aws/aws_cloudtrail_trails.md aws_cloudtrail_trails resource"
parent = "inspec/resources/aws"
+++
Use the `aws_cloudtrail_trails` InSpec audit resource to test properties of a collection of AWS CloudTrail Trails.
## Syntax
An `aws_cloudtrail_trails` resource block returns all CloudTrail Trails and allows the testing of those trails.
describe aws_cloudtrail_trails do
it { should exist }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on Auto Scaling Group](https://docs.aws.amazon.com/autoscaling/ec2/userguide/AutoScalingGroup.html).
## Properties
| Property | Description |
| ---------- | -------------------------------------------------------------------------------------------- |
| trail_arns | Specifies the ARNs of the trails. |
| names | The names of the trails. |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
### Ensure a CloudTrail with a specific name exists
describe aws_cloudtrail_trails do
its('names') { should include('trail-1') }
end
### Ensure a CloudTrail with a specific arn exists
describe aws_cloudtrail_trails do
its('trail_arns') { should include('arn:aws:cloudtrail:us-east-1::trail/trail-1') }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_cloudtrail_trails do
it { should exist }
end
describe aws_cloudtrail_trails 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 `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).

85
docs-chef-io/content/inspec/resources/aws_cloudwatch_alarm.md
View file

@ -1,85 +0,0 @@
+++
title = "aws_cloudwatch_alarm resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_cloudwatch_alarm"
identifier = "inspec/resources/aws/aws_cloudwatch_alarm.md aws_cloudwatch_alarm resource"
parent = "inspec/resources/aws"
+++
Use the `aws_cloudwatch_alarm` InSpec audit resource to test properties of a single CloudWatch Alarm.
**If more than one Alarm matches, an error will be raised.**
## Syntax
### Ensure an Alarm exists.
aws_cloudwatch_alarm(metric_name: 'my-metric-name', metric_namespace: 'my-metric-namespace') do
it { should exist }
end
## Parameters
### metric_name _(required)_
The metric name used by this alarm. This must be passed as a `metric_name: 'value'` key-value entry in a hash.
### metric_namespace _(required)_
The metric namespace used by this alarm. This must be passed as a `metric_namespace: 'value'` key-value entry in a hash.
### dimensions _(optional)_
The dimensions associated with this alarm. This must be passed as an array of hashes `dimensions: [{key:'value'}]` .
## Properties
| Property | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| alarm_actions | The actions to execute when this alarm transitions to the ALARM state from any other state. Each action is specified as an Amazon Resource Name (ARN). |
| alarm_name | The name of the alarm. |
| metric_name | The name of the metric. |
| metric_namespace | The namespace of the metric. |
## Examples
### Ensure an Alarm has at least one alarm action
describe aws_cloudwatch_alarm(metric_name: 'my-metric-name', metric_namespace: 'my-metric-namespace') do
its('alarm_actions') { should_not be_empty }
end
### Ensure an Alarm with Dimensions exists
describe aws_cloudwatch_alarm(metric_name: 'my-metric-name', metric_namespace: 'my-metric-namespace', dimensions: [{key: 'value'}]) do
it { should exist }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_cloudwatch_alarm(metric_name: 'good-metric', metric_namespace: 'my-metric-namespace') do
it { should exist }
end
describe aws_cloudwatch_alarm(metric_name: '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).

56
docs-chef-io/content/inspec/resources/aws_cloudwatch_log_group.md
View file

@ -1,56 +0,0 @@
+++
title = "aws_cloudwatch_log_group resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_cloudwatch_log_group"
identifier = "inspec/resources/aws/aws_cloudwatch_log_group.md aws_cloudwatch_log_group resource"
parent = "inspec/resources/aws"
+++
Use the `aws_cloudwatch_log_group` InSpec audit resource to test properties of a single AWS CloudWatch Log Group.
## Syntax
Ensure that an `aws_cloudwatch_log_group` exists
describe aws_cloudwatch_log_group('my_log_group') do
it { should exist }
end
describe aws_cloudwatch_log_group(log_group_name: 'my_log_group') do
it { should exist }
end
## Parameters
### log_group_name _(required)_
This resource accepts a single parameter, the log group name which uniquely identifies the CloudWatch Log Group.
This can be passed either as a string or as a `log_group_name: 'value'` key-value entry in a hash.
See also the [AWS documentation on CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_DescribeLogGroups.html).
## Properties
| Property | Description |
| ----------------- | ------------------------------------------------------------------------- |
| retention_in_days | The number of days to retain the log events in the specified log group |
| kms_key_id | The Amazon Resource Name (ARN) of the CMK to use when encrypting log data |
| tags | The tags for the log group. |
### Test tags on the CloudWatch Log Group
describe aws_cloudwatch_log_group('my_log_group') do
its('tags') { should include(:Environment => 'env-name',
:Name => 'my_log_group')}
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `logs:DescribeLogGroups` and `logs:ListTagsLogGroup` actions with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon CloudWatch Logs](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazoncloudwatchlogs.html).

108
docs-chef-io/content/inspec/resources/aws_cloudwatch_log_metric_filter.md
View file

@ -1,108 +0,0 @@
+++
title = "aws_cloudwatch_log_metric_filter resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_cloudwatch_log_metric_filter"
identifier = "inspec/resources/aws/aws_cloudwatch_log_metric_filter.md aws_cloudwatch_log_metric_filter resource"
parent = "inspec/resources/aws"
+++
Use the `aws_cloudwatch_log_metric_filter` InSpec audit resource to search for and test properties of individual AWS Cloudwatch Log Metric Filters.
## Syntax
describe aws_cloudwatch_log_metric_filter(filter_name: 'my-filter', log_group_name: 'my-log-group') do
it { should exist }
end
describe aws_cloudwatch_log_metric_filter(log_group_name: 'my-log-group', pattern: 'my-filter') do
it { should exist }
end
## Parameters
**Note**: _While all parameters are optional, at least one must be provided. In practice, the more parameters you provide the narrower a result you will return._
### filter_name _(optional)_
The name of the Log Metric Filter. Expected in a hash as `filter_name: 'value'`.
### log_group_name _(optional)_
The log group of the filter. Expected in a hash as `log_group_name: 'value'`.
### pattern _(optional)_
A pattern by which to narrow down the result-set, if you expect multiple results. Expected in a hash as `pattern: 'value'`.
See also the [AWS documentation on CloudWatch](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazoncloudwatch.html).
## Properties
| Property | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filter_name | The name of the metric filter. |
| log_group_name | The name of the log group. |
| metric_name | The name of the metric. |
| metric_namespace | The namespace of the metric. |
| pattern | A symbolic description of how CloudWatch Logs should interpret the data in each log event. For example, a log event may contain timestamps, IP addresses, strings, and so on. You use the filter pattern to specify what to look for in the log event message. |
## Examples
### Ensure a Filter exists
describe aws_cloudwatch_log_metric_filter(filter_name: 'my-filter', log_group_name: 'my-log-group') do
it { should exist }
end
### Ensure a Filter exists for a specific pattern
describe aws_cloudwatch_log_metric_filter(pattern: '"ERROR" - "Exiting"') do
it { should exist }
end
### Check the name of a Filter
describe aws_cloudwatch_log_metric_filter(log_group_name: 'app-log-group', pattern: 'KERBLEWIE') do
its('filter_name') { should eq 'kaboom_lmf' }
end
### Check the Log Group name of a Filter
describe aws_cloudwatch_log_metric_filter(filter_name: 'error-watcher') do
its('log_group_name') { should eq 'app-log-group' }
end
### Check a filter has the correct pattern
describe aws_cloudwatch_log_metric_filter(filter_name: 'error-watcher', log_group_name: 'app-log-group') do
its('pattern') { should cmp 'ERROR' }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_cloudwatch_log_metric_filter(log_group_name: 'my-log-group') do
it { should exist }
end
describe aws_cloudwatch_log_metric_filter(log_group_name: 'i-dont-exist') 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).

91
docs-chef-io/content/inspec/resources/aws_config_delivery_channel.md
View file

@ -1,91 +0,0 @@
+++
title = "aws_config_delivery_channel resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_config_delivery_channel"
identifier = "inspec/resources/aws/aws_config_delivery_channel.md aws_config_delivery_channel resource"
parent = "inspec/resources/aws"
+++
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` InSpec audit resource to examine how the AWS Config service delivers those change notifications.
One delivery channel is allowed per region per AWS account, and the delivery channel is required to use AWS Config.
## Syntax
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
Since you may only have one Delivery Channel per region, and 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
## Parameters
### channel_name _(optional)_
This resource can be passed a single parameter, the Channel Name.
This can be passed either as a string or as a `channel_name: 'value'` key-value entry in a hash.
See also the [AWS documentation on Delivery Channels](https://docs.aws.amazon.com/config/latest/developerguide/manage-delivery-channel.html).
## Properties
| Property | Description |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| channel_name | The name of the delivery channel. By default, AWS Config assigns the name "default" when creating the delivery channel. |
| s3_bucket_name | The name of the Amazon S3 bucket to which AWS Config delivers configuration snapshots and configuration history files. |
| s3_key_prefix | The prefix for the specified Amazon S3 bucket. |
| sns_topic_arn | The Amazon Resource Name (ARN) of the Amazon SNS topic to which AWS Config sends notifications about configuration changes. |
| delivery_frequency_in_hours | Specifies how often the AWS Config sends configuration changes to the s3 bucket in the delivery channel. |
## Examples
### 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
### Ensure configuration change notifications are being delivered to the correct bucket and key
describe aws_config_delivery_channel(channel_name: 'my_channel')
its('s3_bucket_name') { should eq 'my_bucket' }
its('s3_key_prefix') { should eq 'logs/' }
end
## Matchers
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_config_delivery_channel('my_channel') do
it { should exist }
end
describe aws_config_delivery_channel('my-nonexistent-channel') 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 `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).

106
docs-chef-io/content/inspec/resources/aws_config_recorder.md
View file

@ -1,106 +0,0 @@
+++
title = "aws_config_recorder resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_config_recorder"
identifier = "inspec/resources/aws/aws_config_recorder.md aws_config_recorder resource"
parent = "inspec/resources/aws"
+++
Use the `aws_config_recorder` 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.
## Syntax
Ensure that an auto scaling group exists and has the correct scale sizes
describe aws_config_recorder('my-recorder') do
it { should exist }
end
You may also use hash syntax to pass the recorder name
describe aws_config_recorder(recorder_name: 'my-recorder') do
it { should exist }
end
Since you may only have one recorder per region, and 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
## Parameters
### recorder_name _(optional)_
This resource accepts a single parameter, the Configuration Recorder Name.
This can be passed either as a string or as a `recorder_name: 'value'` key-value entry in a hash.
See also the [AWS documentation on Configuration](https://docs.aws.amazon.com/config/latest/developerguide/aws-config-landing-page.html).
## Properties
| Property | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| recorder_name | The name of the recorder. By default, AWS Config automatically assigns the name "default" when creating the configuration recorder. You cannot change the assigned name. |
| role_arn | Amazon Resource Name (ARN) of the IAM role used to describe the AWS resources associated with the account. |
| resource_types | A comma-separated list that specifies the types of AWS resources for which AWS Config records configuration changes (i.e. AWS::EC2::Instance) |
## Examples
### Test if the recorder is active and recording
describe aws_config_recorder do
it { should be_recording }
end
### Ensure the role_arn is correct for the recorder
The role is used to grant permissions to S3 Buckets, SNS topics and to get configuration details for supported AWS resources.
```ruby
describe aws_config_recorder do
its('role_arn') { should eq 'arn:aws:iam::721741954427:role/My_Recorder' }
end
```
### Test the recorder is monitoring changes to the correct resources.
describe aws_config_recorder do
its('resource_types') { should include 'AWS::EC2::CustomerGateway' }
its('resource_types') { should include 'AWS::EC2::EIP' }
end
## Matchers
### be_recording
Ensure the recorder is active
it { should be_recording }
### 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).

78
docs-chef-io/content/inspec/resources/aws_db_subnet_group.md
View file

@ -1,78 +0,0 @@
+++
title = "aws_db_subnet_group resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_db_subnet_group"
identifier = "inspec/resources/aws/aws_db_subnet_group.md aws_db_subnet_group resource"
parent = "inspec/resources/aws"
+++
Use the `aws_db_subnet_group` InSpec audit resource to test properties of a db subnet group.
## Syntax
An `aws_db_subnet_group` resource block uses the parameter to select a subnet group.
describe aws_db_subnet_group(db_subnet_group_name: 'subnet-group-name-12345') do
it { should exist }
end
## Parameters
### db_subnet_group_name _(required)_
This resource accepts a single parameter, the DB Subnet Group Name.
This can be passed either as a string or as a `aws_db_subnet_group: 'value'` key-value entry in a hash.
See also the [AWS documentation on DB Subnet Groups](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_VPC.WorkingWithRDSInstanceinaVPC.html#USER_VPC.Subnets).
## Properties
| Property | Description |
| --------------------------- | ------------------------------------------------- |
| db_subnet_group_name | The name of the DB subnet group. |
| db_subnet_group_description | Provides the description of the DB subnet group. |
| vpc_id | Provides the VPC ID of the DB subnet group. |
| subnet_group_status | Provides the status of the DB subnet group. |
| subnets | Contains a list of Subnet elements. |
| db_subnet_group_arn | The Amazon Resource Name for the DB subnet group. |
For a comprehensive list of properties available, see [the API reference documentation](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DBSubnetGroup.html)
## Examples
### Check DB Subnet Group Name of a subnet group
describe aws_db_subnet_group(db_subnet_group_name: 'subnet-group-name-12345') do
its('db_subnet_group_name') { should eq 'subnet-group-name-12345' }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_db_subnet_group(db_subnet_group_name: 'subnet-group-name-12345') do
it { should exist }
end
describe aws_rds_cluster(db_cluster_identifier: 'subnet-group-name-6789') 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:DescribeDBSubnetGroup` action with Effect set to Allow.
You can find detailed documentation at
[Actions, Resources, and Condition Keysfor Amazon RDS](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonrds.html).

77
docs-chef-io/content/inspec/resources/aws_db_subnet_groups.md
View file

@ -1,77 +0,0 @@
+++
title = "aws_db_subnet_groups resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_db_subnet_groups"
identifier = "inspec/resources/aws/aws_db_subnet_groups.md aws_db_subnet_groups resource"
parent = "inspec/resources/aws"
+++
Use the `aws_db_subnet_groups` InSpec audit resource to test properties of a collection of AWS RDS subnet groups.
RDS gives you access to the capabilities of a MySQL, MariaDB, PostgreSQL, Microsoft SQL Server, Oracle, or Amazon Aurora database server.
## Syntax
Ensure you have exactly 3 subnet groups
describe aws_db_subnet_groups do
its('db_subnet_group_names.count') { should cmp 3 }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on RDS](https://docs.aws.amazon.com/rds/?id=docs_gateway).
## Properties
| Property | Description |
| ---------------------------- | ------------------------------------------------- |
| db_subnet_group_names | The name of the DB subnet group. |
| db_subnet_group_descriptions | Provides the description of the DB subnet group. |
| vpc_ids | Provides the VPC ID of the DB subnet group. |
| subnet_group_status | Provides the status of the DB subnet group. |
| subnets | Contains a list of Subnet elements. |
| db_subnet_group_arns | The Amazon Resource Name for the DB subnet group. |
For a comprehensive list of properties available, see [the API reference documentation](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DBSubnetGroup.html)
## Examples
### Ensure DB Subnet Group Name of a subnet group exists
describe aws_db_subnet_groups do
its('db_subnet_group_names') { should include 'subnet-group-name' }
end
## Matchers
For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_db_subnet_groups.where( <property>: <value> ) do
it { should exist }
end
describe aws_db_subnet_groups.where( <property>: <value> ) 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:DescribeDBSubnetGroups` 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).

57
docs-chef-io/content/inspec/resources/aws_dhcp_options.md
View file

@ -1,57 +0,0 @@
+++
title = "aws_dhcp_options resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_dhcp_options"
identifier = "inspec/resources/aws/aws_dhcp_options.md aws_dhcp_options resource"
parent = "inspec/resources/aws"
+++
Use the `aws_dhcp_options` InSpec audit resource to test properties of a single AWS DHCP Options.
## Syntax
Ensure that an `aws_dhcp_options` exists
describe aws_dhcp_options('dopt-0123456789abcdefg') do
it { should exist }
end
describe aws_dhcp_options(dhcp_options_id: 'dopt-0123456789abcdefg') do
it { should exist }
end
## Parameters
### dhcp_options_id _(required)_
This resource accepts a single parameter, the DHCP Options ID which uniquely identifies the DHCP Options.
This can be passed either as a string or as a `dhcp_options_id: 'value'` key-value entry in a hash.
See also the [AWS documentation on EC2](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeDhcpOptions.html).
## Properties
| Property | Description |
| ------------------- | --------------------------------------------------------- |
| dhcp_configurations | The list of dhcp configurations |
| domain_name_servers | The list of domain name servers in the dhcp configuration |
| ntp_servers | The list of ntp servers in the dhcp configuration |
| tags | The tags of the DHCP Options. |
### Test tags on the DHCP Options
describe aws_dhcp_options('dopt-0123456789abcdefg') do
its('tags') { should include(:Environment => 'env-name',
:Name => 'dhcp-options-name')}
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ec2:DescribeDhcpOptions` 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).

105
docs-chef-io/content/inspec/resources/aws_dynamodb_table.md
View file

@ -1,105 +0,0 @@
+++
title = "aws_dynamodb_table resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_dynamodb_table"
identifier = "inspec/resources/aws/aws_dynamodb_table.md aws_dynamodb_table resource"
parent = "inspec/resources/aws"
+++
Use the `aws_dynamodb_table` InSpec audit resource to test properties of a single DynamoDb Table.
## Syntax
### Ensure an DynamoDb Table exists.
describe aws_dynamodb_table(table_name: 'table-name') do
it { should exist }
end
## Parameters
### table_name _(required)_
The table name used by this DynamoDb Table. This must be passed as a `table_name: 'value'` key-value entry in a hash.
## Properties
| Property | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| table_name | The name of the DynamoDb Table. |
| table_status | The status of the DynamoDb Table. |
| table_arn | The Amazon Resource Names of the DynamoDb Table. |
| creation_date | The date the DynamoDb Table was created. eg. `01/01/2019` |
| number_of_decreases_today | The number of provisioned throughput decreases for this table during this UTC calendar day. |
| write_capacity_units | The maximum number of writes consumed per second before DynamoDb returns a ThrottlingException. |
| read_capacity_units | The maximum number of strongly consistent reads consumed per second before DynamoDb returns a ThrottlingException. |
| item_count | The number of entries in the DynamoDb Table. |
| attributes | An array of attributes that describe the key schema for the table and indexes. This is returned as a hash. Each entry is composed of: `attribute_name` - The name of this key attribute. `attribute_type` - The datatype of the attribute : `B` - Boolean, `N` - Number, `S` - string |
| key_schema | Specifies the attributes that make up the primary key for a table or an index. This is returned as a hash. The attributes in KeySchema must also be defined in the Attributes array. Each element in the KeySchemaElement array is composed of: `attribute_name` - The name of this key attribute. `key_type` - The role that the key attribute will assume: `HASH` - partition key, `RANGE` - sort key |
| global_secondary_indexes | A list of global secondary indexes if there is any referenced on the selected table. |
## Examples
### Ensure DynamoDb Table status is active
describe aws_dynamodb_table(table_name: 'table-name') do
its('table_status') { should eq 'ACTIVE' }
end
### Ensure DynamoDb Table has an attribute
describe aws_dynamodb_table(table_name: 'table-name') do
its('attributes') { should_not be_empty }
its('attributes') { should include({:attribute_name =>'table_field', :attribute_type =>'N'}) }
end
### Ensure DynamoDb Table has a key_schema
describe aws_dynamodb_table(table_name: 'table-name') do
its('key_schema') { should_not be_empty }
its('key_schema') { should include({:attribute_name =>'table_field', :key_type =>'HASH'}) }
end
### Ensure DynamoDb Table has the correct global secondary indexes set
aws_dynamodb_table(table_name: 'table-name').global_secondary_indexes.each do |global_sec_idx|
describe global_sec_idx do
its('index_name') { should eq 'TitleIndex' }
its('index_status') { should eq 'ACTIVE' }
its('key_schema') { should include({:attribute_name =>'Title', :key_type =>'HASH'}) }
its('provisioned_throughput.write_capacity_units') { should cmp 10 }
its('provisioned_throughput.read_capacity_units') { should cmp 10 }
its('projection.projection_type') { should eq 'INCLUDE' }
end
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_dynamodb_table(table_name: 'table-name') do
it { should exist }
end
describe aws_dynamodb_table(table_name: 'table-name') 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 `DynamoDB::DescribeTable` action with Effect set to Allow.
You can find detailed documentation at
[Actions, Resources, and Condition Keys for Amazon Dynamodb](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazondynamodb.html).

107
docs-chef-io/content/inspec/resources/aws_ebs_volume.md
View file

@ -1,107 +0,0 @@
+++
title = "aws_ebs_volume resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_ebs_volume"
identifier = "inspec/resources/aws/aws_ebs_volume.md aws_ebs_volume resource"
parent = "inspec/resources/aws"
+++
Use the `aws_ebs_volume` InSpec audit resource to test properties of a single AWS EBS volume.
## Syntax
Ensure an EBS exists
describe aws_ebs_volume('vol-01a2349e94458a507') do
it { should exist }
end
You may also use hash syntax to pass the EBS volume name
describe aws_ebs_volume(name: 'data-vol') do
it { should exist }
end
## Parameters
This resource accepts a single parameter, either the EBS Volume name or id. At least one must be provided.
### volume_id _(required if `name` not provided)_
The EBS Volume ID which uniquely identifies the volume.
This can be passed as either a string or an `volume_id: 'value'` key-value entry in a hash.
### name _(required if `volume_id` not provided)_
The EBS Volume Name which uniquely identifies the volume.
This must be passed as a `name: 'value'` key-value entry in a hash.
See also the [AWS documentation on EBS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AmazonEBS.html).
## Properties
| Property | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| availability_zone | The Availability Zone for the volume. |
| encrypted | Indicates whether the volume will be encrypted. |
| iops | The number of I/O operations per second (IOPS) that the volume supports. |
| kms_key_id | The full ARN of the AWS Key Management Service (AWS KMS) customer master key (CMK) that was used to protect the volume encryption key for the volume. |
| size | The size of the volume, in GiBs. |
| snapshot_id | The snapshot from which the volume was created, if applicable. |
| status | The volume state. |
| volume_type | The volume type. |
## Examples
### 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
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_ebs_volume(name: 'data_vol') do
it { should exist }
end
describe aws_ebs_volume(name: 'data_vol') do
it { should_not exist }
end
### 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).

78
docs-chef-io/content/inspec/resources/aws_ebs_volumes.md
View file

@ -1,78 +0,0 @@
+++
title = "aws_ebs_volumes resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_ebs_volumes"
identifier = "inspec/resources/aws/aws_ebs_volumes.md aws_ebs_volumes resource"
parent = "inspec/resources/aws"
+++
Use the `aws_ebs_volumes` InSpec audit resource to test properties of a collection of AWS EBS volumes.
EBS volumes are persistent block storage volumes for use with Amazon EC2 instances in the AWS Cloud.
## Syntax
Ensure you have exactly 3 volumes
describe aws_ebs_volumes do
its('volume_ids.count') { should cmp 3 }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on EBS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AmazonEBS.html).
## Properties
| Property | Description |
| ---------- | -------------------------------------------------------------------------------------------- |
| volume_ids | The unique IDs of the EBS Volumes returned. |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
### Ensure a specific volume exists
```ruby
describe aws_ebs_volumes do
its('volume_ids') { should include 'vol-12345678' }
end
```
### Use the InSpec resource to request the IDs of all EBS volumes, then test in-depth using `aws_ebs_volume` to ensure all volumes are encrypted and have a sensible size.
aws_ebs_volumes.volume_ids.each do |volume_id|
describe aws_ebs_volume(volume_id) do
it { should be_encrypted }
its('size') { should be > 10 }
its('iops') { should cmp 100 }
end
end
## Matchers
For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_ebs_volumes do
it { should exist }
end
describe aws_ebs_volumes do
it { should_not exist }
end
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).

163
docs-chef-io/content/inspec/resources/aws_ec2_instance.md
View file

@ -1,163 +0,0 @@
+++
title = "aws_ec2_instance resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_ec2_instance"
identifier = "inspec/resources/aws/aws_ec2_instance.md aws_ec2_instance resource"
parent = "inspec/resources/aws"
+++
Use the `aws_ec2_instance` InSpec audit resource to test properties of a single AWS EC2 instance.
## Syntax
An `aws_ec2_instance` resource block declares the tests for a single AWS EC2 instance by either name or instance id.
describe aws_ec2_instance('i-01a2349e94458a507') do
it { should exist }
end
describe aws_ec2_instance(name: 'my-instance') do
it { should exist }
end
## Parameters
One of either the EC2 instance's ID or name must be be provided.
### instance_id _(required if `name` not provided)_
The ID of the EC2 instance. This is in the format of `i-` followed by 8 or 17 hexadecimal characters.
This can be passed either as a string or as an `instance_id: 'value'` key-value entry in a hash.
### name _(required if `instance_id` not provided)_
If you have a `Name` tag applied to the EC2 instance, this can be used to lookup the instance.
This must be passed as a `name: 'value'` key-value entry in a hash.
## Properties
| Property | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| state | The current state of the EC2 Instance, for example 'running'. |
| image_id | The id of the AMI used to launch the instance. |
| role | The IAM role attached to the instance. |
| launch_time | The time the instance was launched. |
| availability_zone | The availability zone of the instance. |
| security_groups | A hash containing the security group ids and names associated with the instance. |
| security_group_ids | The security group ids associated with the instance. |
| ebs_volumes | A hash containing the names and ids of any EBS volumes associated with the instance. |
| tags | A list of hashes with each key-value pair corresponding to an EC2 instance tag, e.g, `[{:key=>"Name", :value=>"Testing Box"}, {:key=>"Environment", :value=>"Dev"}]` |
| tags_hash | A hash, with each key-value pair corresponding to an EC2 instance tag, e.g, `{"Name"=>"Testing Box", "Environment"=>"Dev"}`. This property is available in InSpec AWS resource pack version **[1.12.0](https://github.com/inspec/inspec-aws/releases/tag/v1.12.0)** onwards. |
There are also additional properties available. For a comprehensive list, see [the API reference documentation](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_Instance.html)
## Examples
### 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 AMI
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
### Test that an EC2 instance has the correct tag (using the `tags_hash` property)
describe aws_ec2_instance('i-090c29e4f4c165b74') do
its('tags_hash') { should include('Contact' => 'Gilfoyle') }
its('tags_hash') { should include('Contact') } # Regardless of the value
end
### Test that an EC2 instance has no roles
describe aws_ec2_instance('i-090c29e4f4c165b74') do
it { should_not have_roles }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of
available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
it { should exist }
it { should_not exist }
### has_roles
Test if the EC2 instance has any roles associated with it.
Use `should_not` to test the entity does not have roles.
it { should have_roles }
it { should_not have_roles }
### 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).

111
docs-chef-io/content/inspec/resources/aws_ec2_instances.md
View file

@ -1,111 +0,0 @@
+++
title = "aws_ec2_instances resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_ec2_instances"
identifier = "inspec/resources/aws/aws_ec2_instances.md aws_ec2_instances resource"
parent = "inspec/resources/aws"
+++
Use the `aws_ec2_instances` InSpec audit resource to test properties of some or all AWS EC2 instances. To audit a single EC2 instance, use `aws_ec2_instance` (singular).
## Syntax
An `aws_ec2_instances` resource block collects a group of EC2 Instances and then tests that group.
describe aws_ec2_instances
it { should exist }
end
## Parameters
This resource does not expect any parameters.
## Properties
| Property | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| instance_ids | The ID of the EC2 instance. The field name is `instance_id`. |
| names | The value of the `Name` tag if applied to the instance. The filed name is `name`. |
| vpc_ids | The VPC with which the EC2 instance is associated. The field name is `vpc_id`. |
| subnet_ids | The subnet with which the EC2 instance is associated. The field name is `subnet_id`. |
| instance_types | The type of instance, for example m5.large. The field name is `instance_type`. |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
| tags | A hash, with each key-value pair corresponding to an EC2 instance tag, e.g, `{"Name"=>"Testing Box", "Environment"=>"Dev"}`. This property is available in InSpec AWS resource pack version **[1.12.0](https://github.com/inspec/inspec-aws/releases/tag/v1.12.0)** onwards. The field name is `tags`. |
| iam_profiles | The IAM instance profile associated with the instance. The `role` property of the `aws_ec2_instance` singular resource can be used to check the attached IAM role on the profile. The field name is `iam_profile`. |
## Examples
### Ensure you have exactly 3 instances
describe aws_ec2_instances do
its('instance_ids.count') { should cmp 3 }
end
### Use this InSpec resource to request the IDs of all EC2 instances, then test in-depth using `aws_ec2_instance`.
aws_ec2_instances.instance_ids.each do |instance_id|
describe aws_ec2_instance(instance_id) do
it { should_not have_roles }
its('key_name') { should cmp 'admin-ssh-key' }
its('image_id') { should eq 'ami-27a58d5c' }
end
end
### Filter EC2 instances with their `Environment` tags<superscript>\*</superscript> equal to `Dev`, then test in-depth using `aws_ec2_instance`.
aws_ec2_instances.where(tags: {"Environment" => "Dev"}).instance_ids.each do |id|
describe aws_ec2_instance(id) do
it { should be_stopped }
end
end
<superscript>\*</superscript>Note that the filter won't return the EC2 instances with multiple tags. In this case use regex: `/{"Environment"=>"Dev"}/`
### Filter EC2 instances with a `stop-at-10-pm` tag regardless of its value, then test in-depth using `aws_ec2_instance`.
aws_ec2_instances.where(tags: /"stop-at-10-pm"=>/).instance_ids.each do |id|
describe aws_ec2_instance(id) do
it { should be_stopped }
end
end
### Filter EC2 instances with their `name` equal to `Test Box`, then check their role using `aws_ec2_instance`.
aws_ec2_instances.where(name: "Test Box").instance_ids.each do |id|
describe aws_ec2_instance(id) do
its('role) { should eq "test-role" }
end
end
## Matchers
For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
The field names described in the [properties table](#properties) should be used for the `<property>` in the `where` clause.
Use `should_not` to test the entity should not exist.
describe aws_ec2_instances.where( <property>: <value>) do
it { should exist }
end
describe aws_ec2_instances.where( <property>: <value>) 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: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).

90
docs-chef-io/content/inspec/resources/aws_ecr.md
View file

@ -1,90 +0,0 @@
+++
title = "aws_ecr resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_ecr"
identifier = "inspec/resources/aws/aws_ecr.md aws_ecr resource"
parent = "inspec/resources/aws"
+++
{{< warning >}}
This resource is deprecated. Please use one of the following resources instead.
- `aws_ecr_image`
- `aws_ecr_images`
- `aws_ecr_repository`
- `aws_ecr_repositories`
{{< /warning >}}
Use the `aws_ecr` InSpec audit resource to test properties of a single AWS Elastic Container Registry.
## Syntax
An `aws_ecr` resource block declares the tests for a single AWS ECR by repository name.
describe aws_ecr(repository_name: aws_ecr_name) do
it { should exist }
its ('repository_name') { should eq aws_ecr_name }
end
## Parameters
The ECR repository_name must be provided.
### repository_name _(required)_
The name of the repository
This can be passed either as a string or as an `repository_name: 'value'` key-value entry in a hash.
## Properties
| Property | Description |
| ------------------- | ------------------------------------------------------------------------------ |
| registry_id | The AWS account ID associated with the registry |
| repository_arn | The Amazon Resource Name of the repository |
| repository_name | The name of the repository |
| repository_uri | The uri of the repository |
| image_tags | The tags associated with the image |
| image_digest | A sha256 hash of the image |
| image_size_in_bytes | The size of the image in bytes. |
| image_pushed_at | The datetime as a string when the image was uploaded. 'yyyy-mm-dd hh:mm:ss tz' |
| image_uploaded_date | The date as a string when the image was uploaded. 'yyyy-mm-dd' |
## Examples
### Test that an ECR has the correct image properties
describe aws_ecr(repository_name: aws_ecr_name).images do
its ('image_tags') { should include 'latest'}
its ('image_digest') { should eq 'sha256:6dce4a9c1635c4c9b6a2b645e6613fa0238182fe13929808ee2258370d0f3497'}
its ('image_size_in_bytes') { should eq 764234}
its ('image_uploaded_date') { should eq '2019-06-11'}
its ('image_pushed_at') { should eq '2019-06-11 15:08:29 +0100'}
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
it { should exist }
it { should_not exist }
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ecr:DescribeRepositories` and `ecr:DescribeImages` actions set to allow.
You can find detailed documentation at
[Actions, Resources, and Condition Keys for Amazon ECR](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonelasticcontainerregistry.html),
and [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

105
docs-chef-io/content/inspec/resources/aws_ecr_image.md
View file

@ -1,105 +0,0 @@
+++
title = "aws_ecr_image resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_ecr_image"
identifier = "inspec/resources/aws/aws_ecr_image"
parent = "inspec/resources/aws"
+++
Use the `aws_ecr_image` InSpec audit resource to test the properties of a single image in an AWS Elastic Container Registry (ECR) repository.
This resource is available in InSpec AWS resource pack version **[1.11.0](https://github.com/inspec/inspec-aws/releases/tag/v1.11.0)** onwards.
## Syntax
An `aws_ecr_image` resource block declares the tests for a single image in an AWS ECR repository by repository name and image identifier.
describe aws_ecr_image(repository_name: 'my-repo', image_tag: 'latest') do
it { should exist }
end
## Parameters
The repository name and the image identifier (either `image_tag` or `image_digest`) must be provided. The ID of the registry is optional.
### repository_name _(required)_
The name of the ECR repository must satisfy the following constraints:
- Regex pattern `(?:[a-z0-9]+(?:[._-][a-z0-9]+)*/)*[a-z0-9]+(?:[._-][a-z0-9]+)*`.
- Minimum 2 and maximum of 256 characters long.
### image_tag _(required if `image_digest` not provided)_
The tag used for the image. It can not be longer than 300 characters.
### image_digest _(required if `image_tag` not provided)_
The `sha256` digest of the image manifest. It must satisfy this regex pattern: `[a-zA-Z0-9-_+.]+:[a-fA-F0-9]+`.
### registry_id _(optional)_
The 12-digit ID of the AWS Elastic Container Registry. If not provided, the [default](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_DescribeRepositories.html) registry is assumed.
## Properties
| Property | Description |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| repository_name | The name of the repository. |
| registry_id | The AWS account ID associated with the registry that contains the repository. |
| tags | The list of tags associated with this image. |
| vulnerability_severity_counts | The image vulnerability counts, sorted by severity, e.g. `{:high=>1}`. |
| vulnerabilities | A list of hashes with each key-value pair corresponding to an image [scan findings](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_ImageScanFinding.html). E.g. `{:name=>"CVE-2019-14697", :uri=>"https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-14697", :severity=>"HIGH", :package_version=>"1.1.18-r3", :package_name=>"musl", :CVSS2_VECTOR=>"AV:N/AC:L/Au:N/C:P/I:P/A:P", :CVSS2_SCORE=>"7.5"}` |
| cve_ids | The list of [CVE IDs](https://cve.mitre.org/cve/identifiers/) of the vulnerabilities in the image. |
| highest_vulnerability_severity | The [CVSS v2](https://www.first.org/cvss/v2/guide) score of the most severe vulnerability in the image. |
There are also additional properties available. For a comprehensive list, see [the API reference documentation](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_ImageDetail.html)
## Examples
### Test the scan status of an image
describe aws_ecr_image(repository_name: 'my-repo', image_tag: 'latest') do
its('image_scan_status.status') { should eq 'COMPLETE' }
end
### Test that an image has a certain tag
describe aws_ecr_image(repository_name: 'my-repo', image_digest: 'sha256:687fba9b76554c8dea4c40fed4144011f29b8e1d5db5f2fc976c64ed31894967') do
its('tags') { should include('latest') }
end
### Test that an image does not contain the [Heartbleed](https://heartbleed.com/) vulnerability
describe aws_ecr_image(repository_name: 'my-repo', image_tag: 'latest') do
its('cve_ids') { should_not include('CVE-2014-0160') }
end
### Test that an image does not contain a vulnerability more severe than CVSS v2 score 8
describe aws_ecr_image(repository_name: 'my-repo', image_tag: 'latest') do
its('highest_vulnerability_severity') { should be <= 8 }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
describe aws_ecr_image(repository_name: 'my-repo', image_tag: 'latest') 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 `ecr:DescribeImages` and `ecr:DescribeImageScanFindings` actions set to allow.
You can find detailed documentation at
[Actions, Resources, and Condition Keys for Amazon ECR](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_Operations.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-chef-io/content/inspec/resources/aws_ecr_images.md
View file

@ -1,89 +0,0 @@
+++
title = "aws_ecr_images resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_ecr_images"
identifier = "inspec/resources/aws/aws_ecr_images.md aws_ecr_images"
parent = "inspec/resources/aws"
+++
Use the `aws_ecr_images` InSpec audit resource to test the properties of all images in an AWS Elastic Container Registry (ECR) repository.
This resource is available in InSpec AWS resource pack version **[1.11.0](https://github.com/inspec/inspec-aws/releases/tag/v1.11.0)** onwards.
## Syntax
An `aws_ecr_images` resource block declares the tests for all images in an AWS ECR repository by the repository name.
describe aws_ecr_images(repository_name: 'my-repo') do
it { should exist }
end
## Parameters
The repository name must be provided. The ID of the registry is optional.
### repository_name _(required)_
The name of the ECR repository must satisfy the following constraints:
- Regex pattern `(?:[a-z0-9]+(?:[._-][a-z0-9]+)*/)*[a-z0-9]+(?:[._-][a-z0-9]+)*`.
- Minimum 2 and maximum of 256 characters long.
### registry_id _(optional)_
The 12-digit ID of the AWS Elastic Container Registry. If not provided, the [default](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_DescribeRepositories.html) registry is assumed.
## Properties
| Property | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| digests | The sha256 digest of the image manifest. The field name is `digest`. |
| size_in_bytes | The size, in bytes, of the image in the repository. |
| tags | The list of tags associated with an image. The field name is `tags`. |
| vulnerability_severity_counts | The image vulnerability counts, sorted by severity. |
| vulnerability_scan_status | The current state of the scan. It returns an [image scan status object](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_ImageScanStatus.html). |
| pushed_at_dates | The date and time at which an image was pushed to the repository. The field name is `pushed_at_date`. |
## Examples
### Ensure that there are exactly 3 images
describe aws_ecr_images(repository_name: 'my-repo') do
its('count') { should cmp 3 }
end
### Use this InSpec resource to request the digests of all images, then test in-depth using `aws_ecr_image`.
aws_ecr_images(repository_name: 'my-repo').digests.each do |image_digest|
describe aws_ecr_image(repository_name: 'my-repo', image_digest: image_digest) do
its('tags') { should include('latest') }
end
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_ecr_images(repository_name: 'my-repo').where( <property>: <value>) do
it { should exist }
end
describe aws_ecr_images(repository_name: 'my-repo').where( <property>: <value>) 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 `ecr:DescribeImages` action set to allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon ECR](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_Operations.html), and [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

88
docs-chef-io/content/inspec/resources/aws_ecr_repositories.md
View file

@ -1,88 +0,0 @@
+++
title = "aws_ecr_repositories resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_ecr_repositories"
identifier = "inspec/resources/aws/aws_ecr_repositories.md aws_ecr_repositories"
parent = "inspec/resources/aws"
+++
Use the `aws_ecr_repositories` InSpec audit resource to test the properties of all repositories in an AWS Elastic Container Registry (ECR).
This resource is available in InSpec AWS resource pack version **[1.11.0](https://github.com/inspec/inspec-aws/releases/tag/v1.11.0)** onwards.
## Syntax
An `aws_ecr_repositories` resource block declares the tests for all AWS ECR repositories in the default registry unless the registry ID is provided.
describe aws_ecr_repositories do
it { should exist }
end
Repositories in a non-default registry can be tested by supplying the registry ID if the AWS user has necessary permissions on it.
describe aws_ecr_repositories(registry_id: '123456789012') do
it { should exist }
end
## Parameters
The registry id is optional.
### registry_id _(optional)_
The 12-digit ID of the AWS Elastic Container Registry. If not provided, the [default](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_DescribeRepositories.html) registry is assumed.
## Properties
| Property | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------ |
| arns | The Amazon Resource Name (ARN) that identifies the repository. |
| names | The name of the repository. |
| uris | The URI for the repository. |
| created_at_dates | The date and time, in JavaScript date format, when the repository was created. |
| image_tag_mutability_status | The tag mutability setting for the repository. |
| image_scanning_on_push_status | The setting that determines whether images are scanned after being pushed to a repository. |
## Examples
### Ensure that there are exactly 3 repositories in the default registry
describe aws_ecr_repositories do
its("count") { should cmp 3 }
end
### Use this InSpec resource to request the names of all repositories, then test in-depth using `aws_ecr_repository`.
aws_ecr_repositories.names.each do |repository_name|
describe aws_ecr_repository(repository_name) do
its('image_tag_mutability') { should eq 'MUTABLE' }
end
end
## Matchers
For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_ecr_repositories.where( <property>: <value>) do
it { should exist }
end
describe aws_ecr_repositories.where( <property>: <value>) 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 `ecr:DescribeRepositories` action set to allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon ECR](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_Operations.html), and [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

94
docs-chef-io/content/inspec/resources/aws_ecr_repository.md
View file

@ -1,94 +0,0 @@
+++
title = "aws_ecr_repository resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_ecr_repository"
identifier = "inspec/resources/aws/aws_ecr_repository.md aws_ecr_repository"
parent = "inspec/resources/aws"
+++
Use the `aws_ecr_repository` InSpec audit resource to test the properties of a single AWS Elastic Container Registry (ECR) repository.
This resource is available in InSpec AWS resource pack version **[1.11.0](https://github.com/inspec/inspec-aws/releases/tag/v1.11.0)** onwards.
## Syntax
An `aws_ecr_repository` resource block declares the tests for a single AWS ECR repository by repository name.
describe aws_ecr_repository(repository_name: 'my-repo') do
it { should exist }
end
The value of the `repository_name` can be provided as a string.
describe aws_ecr_repository('my-repo') do
it { should exist }
end
## Parameters
The repository name must be provided. The registry id is optional.
### repository_name _(required)_
The name of the ECR repository must satisfy the following constraints:
- Regex pattern `(?:[a-z0-9]+(?:[._-][a-z0-9]+)*/)*[a-z0-9]+(?:[._-][a-z0-9]+)*`.
- Minimum 2 and maximum of 256 characters long.
This can be passed either as a string or as a `repository_name: 'value'` key-value entry in a hash.
### registry_id _(optional)_
The 12-digit ID of the AWS Elastic Container Registry. If not provided, the [default](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_DescribeRepositories.html) registry is assumed.
## Properties
| Property | Description |
| -------------------- | ------------------------------------------------------------------------------------------ |
| repository_name | The name of the repository. |
| image_tag_mutability | The tag mutability settings for the repository. Valid values are `MUTABLE` or `IMMUTABLE`. |
| registry_id | The AWS account ID associated with the registry that contains the repository. |
| tags | An hash with each key-value pair corresponding to a tag associated with the entity. |
There are also additional properties available. For a comprehensive list, see [the API reference documentation](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_Repository.html)
## Examples
### Test that image tags are `IMMUTABLE` in an ECR repository
describe aws_ecr_repository('my-repo') do
its('image_tag_mutability') { should eq 'IMMUTABLE' }
end
### Test that images are scanned for vulnerabilities at a push to repository
describe aws_ecr_repository(repository_name: 'my-repo') do
its('image_scanning_configuration.scan_on_push') { should eq true}
end
### Test that an ECR repository has a certain tag
describe aws_ecr_repository('my-repo') do
its('tags') { should include('environment' => 'dev') }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
describe aws_ecr_repository(repository_name: 'my-repo') 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 `ecr:DescribeRepositories` action set to allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon ECR](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_Operations.html), and [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

83
docs-chef-io/content/inspec/resources/aws_ecs_cluster.md
View file

@ -1,83 +0,0 @@
+++
title = "aws_ecs_cluster resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_ecs_cluster"
identifier = "inspec/resources/aws/aws_ecs_cluster.md aws_ecs_cluster resource"
parent = "inspec/resources/aws"
+++
Use the `aws_ecs_cluster` InSpec audit resource to test properties of a single AWS ECS Cluster.
## Syntax
An `aws_ecs_cluster` resource block declares the tests for a single AWS ECS Cluster by cluster name.
describe aws_ecs_cluser(cluster_name: 'cluster-8') do
it { should exist }
end
## Parameters
If no parameters are passed, the resource will attempt to retrieve the `default` ECS Cluster.
### cluster_name _(optional)_
This resource accepts a single parameter, the Cluster Name.
This can be passed either as a string or as a `cluster_name: 'value'` key-value entry in a hash.
See also the [AWS documentation on ECS Clusters](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_clusters.html).
## Properties
| Property | Description |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| cluster_arn | The Amazon Resource Name (ARN) that identifies the cluster. |
| cluster_name | A user-generated string that you use to identify your cluster. |
| status | The status of the cluster. |
| running_tasks_count | The number of tasks in the cluster that are in the RUNNING state. |
| pending_tasks_count | The number of tasks in the cluster that are in the PENDING state. |
| active_services_count | The number of services that are running on the cluster in an ACTIVE state. |
| registered_container_instances_count | The number of container instances registered into the cluster. This includes container instances in both ACTIVE and DRAINING status. |
| statistics | Additional information about your clusters that are separated by launch type. |
## Examples
### Test that an ECS Cluster does not exist
describe aws_ecs_cluster(cluster_name: 'invalid-cluster') do
it { should_not exist }
end
### Test that an ECS Cluster is active
describe aws_ecs_cluster('cluster-8') do
its ('status') { should eq 'ACTIVE' }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_ecs_cluster('cluster-8') do
it { should exist }
end
describe aws_ecs_cluster('cluster-9') 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:DescribeClusters` action set to allow.

74
docs-chef-io/content/inspec/resources/aws_ecs_clusters.md
View file

@ -1,74 +0,0 @@
+++
title = "aws_ecs_clusters resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_ecs_clusters"
identifier = "inspec/resources/aws/aws_ecs_clusters.md aws_ecs_clusters resource"
parent = "inspec/resources/aws"
+++
Use the `aws_ecs_clusters` InSpec audit resource to test properties of some or all AWS ECS Clusters.
## Syntax
An `aws_ecs_clusters` resource block returns all ECS Clusters and allows the testing of that group of Clusters.
describe aws_ecs_clusters do
its('cluster_names') { should include 'cluster-root' }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on ECS Clusters](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_clusters.html).
## Properties
| Property | Description |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| cluster_arn | The Amazon Resource Name (ARN) that identifies the cluster. |
| cluster_name | A user-generated string that you use to identify your cluster. |
| status | The status of the cluster. |
| running_tasks_count | The number of tasks in the cluster that are in the RUNNING state. |
| pending_tasks_count | The number of tasks in the cluster that are in the PENDING state. |
| active_services_count | The number of services that are running on the cluster in an ACTIVE state. |
| registered_container_instances_count | The number of container instances registered into the cluster. This includes container instances in both ACTIVE and DRAINING status. |
| statistics | Additional information about your clusters that are separated by launch type. |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
### Ensure there are no Clusters in an undesired state.
describe aws_ecs_clusters do
it { should exist }
its('statuses') { should_not include 'UNDESIRED-STATUS'}
its('cluster_names') { should include 'SQL-cluster' }
end
## Matchers
For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_ecs_clusters.where( <property>: <value>) do
it { should exist }
end
describe aws_ecs_clusters.where( <property>: <value>) 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 `ecs:ListClusters` & `ecs:DescribeClusters` action set to allow.

109
docs-chef-io/content/inspec/resources/aws_efs_file_system.md
View file

@ -1,109 +0,0 @@
+++
title = "aws_efs_file_system resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_efs_file_system"
identifier = "inspec/resources/aws/aws_efs_file_system.md aws_efs_file_system"
parent = "inspec/resources/aws"
+++
Use the `aws_efs_file_system` InSpec audit resource to test the properties of a single AWS EFS file system.
This resource is added to InSpec AWS resource pack in version **[1.10.0](https://github.com/inspec/inspec-aws/releases/tag/v1.10.0)** and it is available with InSpec **[4.18.108](https://github.com/inspec/inspec/releases/tag/v4.18.108)** and later versions.
## Syntax
An `aws_efs_file_system` resource block declares the tests for a single AWS EFS file system by either file system id or creation token.
describe aws_efs_file_system(file_system_id: 'fs-12345678') do
it { should be_encrypted }
its('size_in_bytes.value') { should cmp 6144 }
end
describe aws_efs_file_system(creation_token: 'my-token') do
its('encrypted') { should cmp true }
its('throughput_mode') { should eq 'bursting' }
end
The value of the `file_system_id` can be provided as a string.
describe aws_efs_file_system('fs-12345678') do
it { should exist }
end
## Parameters
Either the EFS file system id or creation token must be provided.
### file_system_id _(required if `creation_token` not provided)_
The ID of the EFS file system. This is in the format of `fs-` followed by 8 or 17 hexadecimal characters.
This can be passed either as a string or as a `file_system_id: 'value'` key-value entry in a hash.
### creation_token _(required if `file_system_id` not provided)_
The creation token is automatically assigned by AWS if not provided by the user at creation.
This is a string with minimum 1 and maximum 64-character long.
This must be passed as a `creation_token: 'value'` key-value entry in a hash.
## Properties
| Property | Description |
| ---------------- | ----------------------------------------------------------------------------------- |
| creation_token | The value of the creation token. |
| file_system_id | The id of the file system which is auto-assigned by the AWS. |
| encrypted | Indicates whether the file system is encrypted or not. |
| life_cycle_state | The lifecycle phase of the file system, e.g. 'creating'. |
| owner_id | The AWS account that created the file system. |
| performance_mode | The performance mode of the file system, e.g. 'maxIO'. |
| throughput_mode | The throughput mode for a file system, e.g. 'bursting'. |
| tags | An hash with each key-value pair corresponding to a tag associated with the entity. |
There are also additional properties available. For a comprehensive list, see [the API reference documentation](https://docs.aws.amazon.com/efs/latest/ug/API_FileSystemDescription.html)
## Examples
### Test that an EFS file system is available
describe aws_efs_file_system("fs-12345678") do
its("life_cycle_state") { should eq 'available' }
end
### Test that an EFS file system is in 'maxIO' performance mode
describe aws_efs_file_system(creation_token: "My Token") do
its("performance_mode") { should eq "maxIO" }
end
### Test that an EFS file system has a certain tag
describe aws_efs_file_system(creation_token: "My Token") do
its("tags") { should include("companyName" => "My Company") }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list
of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
describe aws_efs_file_system(file_system_id: "fs-12345678") do
it { should exist }
end
### be_encrypted
describe aws_efs_file_system(creation_token: "My Token") do
it { should be_encrypted }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `elasticfilesystem:DescribeFileSystems` action set to allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon EFS](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonelasticfilesystem.html), and [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

91
docs-chef-io/content/inspec/resources/aws_efs_file_systems.md
View file

@ -1,91 +0,0 @@
+++
title = "aws_efs_file_systems resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_efs_file_systems"
identifier = "inspec/resources/aws/aws_efs_file_systems.md aws_efs_file_systems"
parent = "inspec/resources/aws"
+++
Use the `aws_efs_file_systems` InSpec audit resource to test the properties of
some or all AWS EFS file systems. To audit a single EFS file system, use
`aws_efs_file_ststem` (singular).
This resource is added to InSpec AWS resource pack in version **[1.10.0](https://github.com/inspec/inspec-aws/releases/tag/v1.10.0)** and it is available with InSpec **[4.18.108](https://github.com/inspec/inspec/releases/tag/v4.18.108)** and later versions.
## Syntax
An `aws_efs_file_systems` resource block collects a group of EFS file system descriptions and then tests that group.
describe aws_efs_file_systems
it { should exist }
end
## Parameters
This resource does not expect any parameters.
## Properties
| Property | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| tags | The list of tags that the EFS file system has. |
| names | The value of the `Name` (case sensitive) tag if it is defined. |
| file_system_ids | The ID of the EFS file system. |
| creation_tokens | The creation token that the EFS file system is associated. |
| owner_ids | The owner id of the EFS file system. |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
| creation_times | The creation time of the EFS file system |
| performance_modes | The performance mode of the EFS file system, e.g. 'maxIO'. |
| encryption_status | This indicates whether the EFS file system is encrypted or not. |
| throughput_modes | The throughput mode of the EFS file system. |
| kms_key_ids | The ID of an AWS Key Management Service (AWS KMS) customer master key (CMK) that was used to protect the encrypted EFS file system. |
| size_in_bytes | The latest known metered size (in bytes) of data stored in the file system, in its `value` field. |
| life_cycle_states | The life cycle phase of the EFS file system, e.g. 'deleting'. |
## Examples
### Ensure you have exactly 3 file systems
describe aws_efs_file_systems do
its("entries.count") { should cmp 3 }
end
### Use this InSpec resource to request the IDs of all EFS file systems, then test in-depth using `aws_efs_file_system`.
aws_efs_file_systems.file_system_ids.each do |file_system_id|
describe aws_efs_file_system(file_system_id) do
its("tags") { should include("companyName" => "My Company Name") }
it { should be_encrypted }
its("throughput_mode") { should eq "bursting" }
its("performance_mode") { should eq "generalPurpose" }
end
end
## Matchers
For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_efs_file_systems.where( <property>: <value>) do
it { should exist }
end
describe aws_efs_file_systems.where( <property>: <value>) 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 `elasticfilesystem:DescribeFileSystems` action set to allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon EFS](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonelasticfilesystem.html), and [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

122
docs-chef-io/content/inspec/resources/aws_eks_cluster.md
View file

@ -1,122 +0,0 @@
+++
title = "aws_eks_cluster resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_eks_cluster"
identifier = "inspec/resources/aws/aws_eks_cluster.md aws_eks_cluster resource"
parent = "inspec/resources/aws"
+++
Use the `aws_eks_cluster` InSpec audit resource to test properties of a single AWS Elastic Container Service for Kubernetes.
## Syntax
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
it { should exist }
end
## Parameters
### cluster_name _(required)_
This resource requires a single parameter, the EKS Cluster Name.
This can be passed either as a string or as a `cluster_name: 'value'` key-value entry in a hash.
See also the [AWS documentation on EKS Clusters](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html).
## Properties
| Property | Description |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| arn | The Amazon Resource Name (ARN) of the cluster. |
| name | The name of the cluster. |
| endpoint | The endpoint for your Kubernetes API server. |
| status | The current status of the cluster. |
| version | The Kubernetes server version for the cluster. |
| certificate_authority | The certificate-authority-data for your cluster. |
| subnets_count | The number of subnets associated with your cluster. |
| subnet_ids | The subnets associated with your cluster. |
| security_groups_count | The count of security groups associated with your cluster. |
| security_group_ids | The security groups associated with the cross-account elastic network interfaces that are used to allow communication between your worker nodes and the Kubernetes control plane. |
| role_arn | The Amazon Resource Name (ARN) of the IAM role that provides permissions for the Kubernetes control plane to make calls to AWS API operations on your behalf. |
| vpc_id | The VPC associated with your cluster. |
| created_at | The Unix epoch timestamp in seconds for when the cluster was created. |
| creating | Boolean indicating whether or not the state of the cluster is CREATING. |
| active | Boolean indicating whether or not the state of the cluster is ACTIVE. |
| failed | Boolean indicating whether or not the state of the cluster is FAILED. |
| deleting | Boolean indicating whether or not the state of the cluster is DELETING. |
| tags | Cluster tags |
## Examples
### Test that an EKS Cluster has at least 2 subnets
describe aws_eks_cluster('my-cluster') do
its('subnets_count') { should be > 1 }
end
### Ensure a Cluster has the correct status.
describe aws_eks_cluster(cluster_name: 'my-eks') do
its('status') { should eq 'ACTIVE' }
end
### Ensure that the EKS Cluster is on the correct VPC
describe aws_eks_cluster('my-cluster') do
its('vpc_id') { should eq 'vpc-12345678' }
end
### Ensure the EKS Cluster is using the correct 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
### Integrate with other resources
Use a combination of InSpec AWS resources to ensure your EKS Cluster does not use the Default VPC.
# Find the default Security Group for our VPC
cluster_vpc = aws_eks_cluster(cluster_name: 'my-cluster').vpc_id
default_sg = aws_security_group(group_name: 'default', vpc_id: cluster_vpc)
# Ensure we are not using the default Security Group
describe aws_eks_cluster(cluster_name: 'my-cluster') do
its('security_group_ids') { should_not include default_security_group.group_id }
end
## Matchers
This InSpec audit resource has no special matchers. For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_eks_cluster('AnExistingCluster') do
it { should exist }
end
describe aws_eks_cluster('ANonExistentCluster') 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 `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)

95
docs-chef-io/content/inspec/resources/aws_eks_clusters.md
View file

@ -1,95 +0,0 @@
+++
title = "aws_eks_clusters resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_eks_clusters"
identifier = "inspec/resources/aws/aws_eks_clusters.md aws_eks_clusters resource"
parent = "inspec/resources/aws"
+++
Use the `aws_eks_clusters` resource to test the configuration of a collection of AWS Elastic Container Service for Kubernetes.
## Syntax
describe aws_eks_clusters do
its('names.count') { should cmp 10 }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on EKS Clusters](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html).
## Properties
| Property | Description |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| arn | The Amazon Resource Name (ARN) of the cluster. |
| name | The name of the cluster. |
| endpoint | The endpoint for your Kubernetes API server. |
| status | The current status of the cluster. |
| version | The Kubernetes server version for the cluster. |
| certificate_authority | The certificate-authority-data for your cluster. |
| subnets_count | The number of subnets associated with your cluster. |
| subnet_ids | The subnets associated with your cluster. |
| security_groups_count | The count of security groups associated with your cluster. |
| security_group_ids | The security groups associated with the cross-account elastic network interfaces that are used to allow communication between your worker nodes and the Kubernetes control plane. |
| role_arn | The Amazon Resource Name (ARN) of the IAM role that provides permissions for the Kubernetes control plane to make calls to AWS API operations on your behalf. |
| vpc_id | The VPC associated with your cluster. |
| created_at | The Unix epoch timestamp in seconds for when the cluster was created. |
| creating | Boolean indicating whether or not the state of the cluster is CREATING. |
| active | Boolean indicating whether or not the state of the cluster is ACTIVE. |
| failed | Boolean indicating whether or not the state of the cluster is FAILED. |
| deleting | Boolean indicating whether or not the state of the cluster is DELETING. |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
### Allow at most 100 EKS Clusters on the account
describe aws_eks_clusters do
its('entries.count') { should be <= 100}
end
### Ensure a specific Cluster exists, by name
describe aws_eks_clusters do
its('names') { should include('cluster-1') }
end
### Ensure no Clusters are in a failed state
describe aws_eks_clusters.where( failed: true ) do
it { should_not exist )
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list
of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_eks_clusters.where( <property>: <value>) do
it { should exist }
end
describe aws_eks_clusters.where( <property>: <value>) 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 `eks:DescribeCluster` action with Effect 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)

101
docs-chef-io/content/inspec/resources/aws_elasticache_cluster.md
View file

@ -1,101 +0,0 @@
+++
title = "aws_elasticache_cluster resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_elasticache_cluster"
identifier = "inspec/resources/aws/aws_elasticache_cluster.md aws_elasticache_cluster"
parent = "inspec/resources/aws"
+++
Use the `aws_elasticache_cluster` InSpec audit resource to test the properties of a single AWS ElastiCache cluster.
## Syntax
An `aws_elasticache_cluster` resource block declares the tests for a single AWS ElastiCache cluster by `cache_cluster_id`.
describe aws_elasticache_cluster(cache_cluster_id: 'my-cluster-123') do
it { should exist }
end
The value of the `cache_cluster_id` can be provided as a string.
describe aws_elasticache_cluster('my-cluster-123') do
its('engine') { should cmp 'redis' }
end
## Parameters
The ElastiCache cluster ID must be provided.
### cache_cluster_id _(required)_
The ID of the ElastiCache cluster:
- contains between 1 and 50 alphanumeric characters or hyphens,
- should start with a letter,
- cannot end with a hyphen or contain two consecutive hyphens.
It can be passed either as a string or as a `cache_cluster_id: 'value'` key-value entry in a hash.
## Properties
| Property | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------- |
| cache_cluster_id | The user-supplied identifier of the cluster. This identifier is a unique key that identifies a cluster. |
| engine | The name of the cache engine, e.g. `redis`. |
| node_ids | The id list of all cluster nodes. |
| ports | A hash of the node ID and port number pairs. |
| status | The current state of the cluster, e.g. `creating`, `available`. |
| encrypted_at_rest | Indicates whether the content is encrypted at rest or not. |
| encrypted_at_transit | Indicates whether the content is encrypted at transit or not. |
There are also additional properties available. For a comprehensive list, see [the API reference documentation](https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_CacheCluster.html).
## Examples
### Test that an ElastiCache cluster is available
describe aws_elasticache_cluster("my-cluster-123") do
its("status") { should eq 'available' }
end
### Test that an Elasticache cluster engine is listening on port `11211`
describe aws_elasticache_cluster(cache_cluster_id: "my-cluster-123") do
its("port") { should cmp 11211 }
end
### Test that an Elasticache cluster's engine version is `1.5.16`
describe aws_elasticache_cluster(cache_cluster_id: "my-cluster-123") do
its("engine_version") { should cmp 1.5.16 }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
describe aws_elasticache_cluster(cache_cluster_id: "my-cluster-123") do
it { should exist }
end
### be_encrypted_at_rest
describe aws_elasticache_cluster(cache_cluster_id: "my-cluster-123") do
it { should be_encrypted_at_rest }
end
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal)
will need the `elasticache:DescribeCacheClusters` action set to allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon ElastiCache](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonelasticache.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-chef-io/content/inspec/resources/aws_elasticache_cluster_node.md
View file

@ -1,89 +0,0 @@
+++
title = "aws_elasticache_cluster_node resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_elasticache_cluster_node"
identifier = "inspec/resources/aws/aws_elasticache_cluster_node.md aws_elasticache_cluster_node"
parent = "inspec/resources/aws"
+++
Use the `aws_elasticache_cluster_node` InSpec audit resource to test the properties of a single AWS ElastiCache cluster node.
## Syntax
An `aws_elasticache_cluster_node` resource block declares the tests for a single AWS ElastiCache cluster node by `cache_cluster_id` and `node_id`.
describe aws_elasticache_cluster_node(cache_cluster_id: 'my-cluster-123', node_id: '0001') do
it { should exist }
end
## Parameters
The ElastiCache cluster ID and node ID must be provided.
### cache_cluster_id _(required)_
The ID of the ElastiCache cluster:
- contains between 1 and 50 alphanumeric characters or hyphens,
- should start with a letter,
- cannot end with a hyphen or contain two consecutive hyphens.
It can be passed either as a string or as a `cache_cluster_id: 'value'` key-value entry in a hash.
### node_id _(required)_
The ID of the node must be a string containing 4 digits. It can be passed as a `node_id: 'value'` key-value entry in a hash.
## Properties
| Property | Description |
| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
| id | The cache node identifier, e.g. `0001`. |
| port | The port number that the cache engine is listening on. |
| address | The DNS hostname of the cache node. |
| status | The current state of the cache node. One of the following values: `available`, `creating`, `rebooting`, or `deleting`. |
| create_time | The date and time when the cache node was created. |
There are also additional properties available. For a comprehensive list, see [the API reference documentation](https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_CacheNode.html).
## Examples
### Test that an ElastiCache cluster node is available
describe aws_elasticache_cluster_node(cache_cluster_id: "my-cluster-123", node_id: "0001") do
its("status") { should eq 'available' }
end
### Test that an Elasticache cluster engine is listening on port `11211`
describe aws_elasticache_cluster_node(cache_cluster_id: "my-cluster-123", node_id: "0001") do
its("port") { should cmp 11211 }
end
### Test that an Elasticache cluster node's customer availability zone is `us-east-2b`
describe aws_elasticache_cluster_node(cache_cluster_id: "my-cluster-123", node_id: "0001") do
its("customer_availability_zone") { should cmp "us-east-2b" }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
describe aws_elasticache_cluster_node(cache_cluster_id: "my-cluster-123", node_id: "0001") 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 `elasticache:DescribeCacheClusters` action set to allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon ElastiCache](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonelasticache.html),
and [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

83
docs-chef-io/content/inspec/resources/aws_elasticache_clusters.md
View file

@ -1,83 +0,0 @@
+++
title = "aws_elasticache_clusters resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_elasticache_clusters"
identifier = "inspec/resources/aws/aws_elasticache_clusters.md aws_elasticache_clusters"
parent = "inspec/resources/aws"
+++
Use the `aws_elasticache_clusters` InSpec audit resource to test the properties
of all AWS ElastiCache clusters. To audit a single ElastiCache cluster, use `aws_elasticache_cluster` (singular).
## Syntax
An `aws_elasticache_clusters` resource block collects a group of ElastiCache cluster descriptions and then tests that group.
describe aws_elasticache_clusters
it { should exist }
end
## Parameters
This resource does not expect any parameters.
## Properties
| Property | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| ids | The user-supplied identifier of the cluster. This identifier is a unique key that identifies a cluster. |
| node_types | The name of the compute and memory capacity node type for the cluster, e.g. `cache.m5.large`. |
| engines | The name of the cache engine, e.g. `redis`. |
| status | The current state of the cluster, e.g. `creating`, `available`. |
| zones | The name of the availability zone in which the cluster is located or "Multiple" if the cache nodes are located in different availability zones. |
| subnet_group_names | The name of the cache subnet group. |
| encrypted_at_rest | Indicates whether the content is encrypted at rest or not. |
| encrypted_at_transit | Indicates whether the content is encrypted at transit or not. |
## Examples
### Ensure that exactly 3 ElastiCache clusters exist
describe aws_elasticache_clusters do
its("entries.count") { should cmp 3 }
end
### Use this InSpec resource to request the IDs of all ElastiCache clusters, then test in-depth using `aws_elasticache_cluster` and `aws_elasticache_cluster_node`.
aws_elasticache_clusters.ids.each do |id|
aws_elasticache_cluster(id).node_ids.each do |node_id|
describe aws_elasticache_cluster_node(cache_cluster_id: id, node_id: node_id) do
it { should exist }
end
end
end
## Matchers
For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_elasticache_clusters.where( <property>: <value>) do
it { should exist }
end
describe aws_elasticache_clusters.where( <property>: <value>) 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 `elasticache:DescribeCacheClusters` action set to allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon ElastiCache](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonelasticache.html),
and [Actions, Resources, and Condition Keys for Identity And Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html).

114
docs-chef-io/content/inspec/resources/aws_elb.md
View file

@ -1,114 +0,0 @@
+++
title = "aws_elb resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_elb"
identifier = "inspec/resources/aws/aws_elb.md aws_elb resource"
parent = "inspec/resources/aws"
+++
Use the `aws_elb` InSpec audit resource to test properties of a single AWS Elastic Load Balancer (ELB).
## Syntax
An `aws_elb` resource block declares the tests for a single AWS ELB by ELB name. AWS ELB Names are unique per region.
describe aws_elb('my-elb') do
it { should exist }
end
describe aws_elb(load_balancer_name: 'my-elb') do
it { should exist }
end
## Parameters
### load_balancer_name _(required)_
This resource accepts a single parameter, the ELB Name which uniquely identifies the ELB.
This can be passed either as a string or as a `load_balancer_name: 'value'` key-value entry in a hash.
See also the [AWS documentation on Elastic Load Balancing](https://docs.aws.amazon.com/elasticloadbalancing/latest/APIReference).
## Properties
| Property | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------- |
| load_balancer_name | The name of the load balancer. |
| dns_name | The DNS name of the load balancer. |
| availability_zones | The Availability Zones for the load balancer. |
| instance_ids | An array containing all instance ids associated with the ELB. |
| external_ports | An array of the external ports exposed on the ELB. |
| internal_ports | An array of the internal ports exposed on the ELB. |
| security_group_ids | The security groups for the load balancer. Valid only for load balancers in a VPC. |
| vpc_id | The ID of the VPC for the load balancer. |
| subnet_ids | The IDs of the subnets for the load balancer. |
| listeners | A collection of the listeners for the load balancer. |
| ssl_policies | A collection of the SSL Policies configured in-use for the load balancer (and their policy attributes). |
| protocols | A list of the protocols configured for the listeners of the load balancer. |
## Examples
### Test that an ELB has its availability zones configured correctly
describe aws_elb('prod_web_app_elb') do
its('availability_zones.count') { should be > 1 }
its('availability_zones') { should include 'us-east-2a' }
its('availability_zones') { should include 'us-east-2b' }
end
### Ensure an ELB has the correct number of EC2 Instances associated with it
describe aws_elb('prod_web_app_elb') do
its('instance_ids.count') { should cmp 3 }
end
### Ensure the correct DNS is set
describe aws_elb('prod_web_app_elb') do
its('dns_name') { should cmp 'your-fqdn.com' }
end
### Ensure we only expose port 80, both to the public and internal
describe aws_elb('prod_web_app_elb') do
its('external_ports.count') { should cmp 1 }
its('external_ports') { should include 80 }
its('internal_ports.count') { should cmp 1 }
its('internal_ports') { should include 80 }
end
### Ensure the correct EC2 Instances are associated
describe aws_elb('prod_web_app_elb') do
its('instance_ids') { should include 'i-12345678' }
end
## Matchers
This InSpec audit resource has no special matchers. For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_elb('AnExistingELB') do
it { should exist }
end
describe aws_elb('ANonExistentELB') 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)

85
docs-chef-io/content/inspec/resources/aws_elbs.md
View file

@ -1,85 +0,0 @@
+++
title = "aws_elbs resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_elbs"
identifier = "inspec/resources/aws/aws_elbs.md aws_elbs resource"
parent = "inspec/resources/aws"
+++
Use the `aws_elbs` InSpec audit resource to test the configuration of a collection
of AWS Elastic Load Balancers.
## Syntax
describe aws_elbs do
its('load_balancer_names') { should include 'elb-name' }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on Elastic Load Balancing](https://docs.aws.amazon.com/elasticloadbalancing/latest/APIReference).
## Properties
| Property | Description |
| ------------------- | ---------------------------------------------------------------------------------- |
| load_balancer_names | The name of the load balancer. |
| dns_names | The DNS name of the load balancer. |
| availability_zones | The Availability Zones for the load balancer. |
| instance_ids | An array containing all instance ids associated with the ELB. |
| external_ports | An array of the external ports exposed on the ELB. |
| internal_ports | An array of the internal ports exposed on the ELB. |
| security_group_ids | The security groups for the load balancer. Valid only for load balancers in a VPC. |
| vpc_ids | The ID of the VPC for the load balancer. |
| subnet_id s | The IDs of the subnets for the load balancer. |
## Examples
### Ensure there are no Load Balancers with an undesired zone.
describe aws_elbs do
it { should exist }
its('availability_zones') { should_not include 'us-east-1a'}
end
### Ensure all ELBs expose only port 80
aws_elbs.each do |elb|
describe elb do
its('external_ports.count') { should cmp 1 }
its('external_ports') { should include 80 }
its('internal_ports.count') { should cmp 1 }
its('internal_ports') { should include 80 }
end
end
## Matchers
For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_elbs.where( <property>: <value>) do
it { should exist }
end
describe aws_elbs.where( <property>: <value>) 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)

122
docs-chef-io/content/inspec/resources/aws_flow_log.md
View file

@ -1,122 +0,0 @@
+++
title = "aws_flow_log resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_flow_log"
identifier = "inspec/resources/aws/aws_flow_log.md aws_flow_log resource"
parent = "inspec/resources/aws"
+++
Use the `aws_flow_log` InSpec audit resource to test properties of a single Flow Log.
## Syntax
describe aws_flow_log(flow_log_id: 'fl-9c718cf5') do
it { should exist }
end
## Parameters
This resource requires at least one of the following parameters to be provided: `flow_log_id`, `subnet_id`, `vpc_id`.
### flow_log_id _(required if no other parameters provided)_
The Flow Log ID which uniquely identifies the Flow Log.
This can be passed either as a string or as a `flow_log_id: 'value'` key-value entry in a hash.
### subnet_id _(required if no other parameters provided)_
The subnet associated with the Flow Log, if applicable.
This must be passed as a `subnet_id: 'value'` key-value entry in a hash.
### vpc_id _(required if no other parameters provided)_
The VPC associated with the Flow Log, if applicable.
This must be passed as a `vpc_id: 'value'` key-value entry in a hash.
See also the [AWS documentation on Flow Logs](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html).
## Properties
| Property | Description |
| -------------- | ------------------------------------------------------------------------- |
| flow_log_id | The ID of the Flow Log. |
| log_group_name | The name of the associated log group. |
| resource_id | The ID of the assosiated resource, e.g. VPC, Subnet or Network Interface. |
## Examples
### Search for a flow log by the associated subnet id
describe aws_flow_log(subnet_id: 'subnet-c6a4319c') do
it { should exist }
end
### Search for a flow log by the associated VPC id
describe aws_flow_log(vpc_id: 'vpc-96cabaef') do
it { should exist }
end
### Ensure the correct Flow Log is associated with a Subnet
describe aws_flow_log(subnet_id: 'subnet-c6a4319c') do
its('flow_log_id') { should cmp 'fl-9c718cf5' }
end
### Ensure the Flow Log is associated with the correct resource type
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](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_flow_log('AnExistingFlowLog') do
it { should exist }
end
describe aws_flow_log('ANonExistentFlowLog') 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
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal)
will need the `ec2:DescribeFlowLogs` actions with Effect set to Allow.

99
docs-chef-io/content/inspec/resources/aws_hosted_zone.md
View file

@ -1,99 +0,0 @@
+++
title = "aws_hosted_zone resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_hosted_zone"
identifier = "inspec/resources/aws/aws_hosted_zone.md aws_hosted_zone resource"
parent = "inspec/resources/aws"
+++
Use the `aws_hosted_zone` resource to test a specific hosted zone configuration.
## Syntax
```ruby
describe aws_hosted_zone('zone-name') do
it { should exist }
its ('name_servers.count') { should eq 4 }
its ('private_zone') { should be false }
its ('record_names') { should include 'sid-james.carry-on.films.com' }
end
```
## Parameters
This resource takes one parameter, the name of the hosted zone to validate.
## Properties
| Property | Description |
| ------------ | ------------------------------------------------------------------------------------------------ |
| name | The name of the hosted zone. |
| id | It's id. |
| name_servers | List of the associated name servers |
| private_zone | If the hosted zone if private or public |
| record_count | Number of associated records |
| records | The associated records, flattens the list, so each rule will have multiple records for each type |
## Examples
### Ensure a specific hosted zone exists
```ruby
describe aws_hosted_zone('zone-name') do
it { should exist }
end
```
## Matchers
This InSpec audit resource has the following special matchers. For a full list
of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe passes all tests.
Use `exist` to validate the hosted zone exists
```ruby
describe aws_hosted_zone('zone-name') do
it { should exist }
end
```
Use `should_not` to test the entity should not exist.
```ruby
describe aws_hosted_zone('zone-name') do
it { should_not exist }
end
```
### should
The control will pass if the describe passes all tests.
Use `should` to validate the hosted zone if public or private, the number of name
servers is correct or that a specific record exists e.g.
```ruby
describe aws_hosted_zone('zone-name') do
it { should exist }
its ('name_servers.count') { should eq 4 }
its ('private_zone') { should be false }
its ('record_names') { should include 'sid-james.carry-on.films.com' }
end
```
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal)
will need the `route53:ListHostedZones` action with Effect set to Allow.
You can find detailed documentation at
[Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/r53-api-permissions-ref.html)

66
docs-chef-io/content/inspec/resources/aws_hosted_zones.md
View file

@ -1,66 +0,0 @@
+++
title = "aws_hosted_zones resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_hosted_zones"
identifier = "inspec/resources/aws/aws_hosted_zones.md aws_hosted_zones resource"
parent = "inspec/resources/aws"
+++
Use the `aws_hosted_zones` resource to test the hosted zones configuration.
## Syntax
```ruby
describe aws_hosted_zones do
its('names') { should include ("carry-on.films.com") }
end
```
## Parameters
This resource does not expect any parameters.
## Properties
| Property | Description |
| -------- | ---------------------------- |
| name | The name of the hosted zone. |
| id | It's id. |
## Examples
### Ensure a specific hosted zone exists
```ruby
describe aws_hosted_zones do
its('names') { should include ("carry-on.films.com") }
end
```
## Matchers
This InSpec audit resource uses the following special matcher. For a full list
of available matchers, please visit our [matchers page](/inspec/matchers/).
### should
The control will pass if the describe passes all tests.
Use `should` to validate if a specific hosted zone exists
```ruby
describe aws_hosted_zones do
its('names') { should include ("carry-on.films.com") }
end
```
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `route53:ListHostedZones` action with Effect set to Allow.
You can find detailed documentation at [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/r53-api-permissions-ref.html)

90
docs-chef-io/content/inspec/resources/aws_iam_access_key.md
View file

@ -1,90 +0,0 @@
+++
title = "aws_iam_access_key resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_iam_access_key"
identifier = "inspec/resources/aws/aws_iam_access_key.md aws_iam_access_key resource"
parent = "inspec/resources/aws"
+++
Use the `aws_iam_access_key` InSpec audit resource to test properties of a single AWS IAM Access Key.
## Syntax
An `aws_iam_access_key` resource allows the testing of a single AWS IAM Access Key.
describe aws_iam_access_key(access_key_id: 'AKIA1111111111111111') do
it { should exist }
end
## Parameters
This resources requires either an `access_key_id` or the IAM `username` associated with the Access Key.
### access_key_id _(required if `username` not provided.)_
The Access Key ID which uniquely identifies the Key. Begins with the characters "AKIA".
This can be passed either as a string or as a `access_key_id: 'value'` key-value entry in a hash.
### username _(required if `access_key_id` not provided.)_
The IAM Username which is associated with the Access Key.
This can be passed either as a string or as a `username: 'value'` key-value entry in a hash.
See also the [AWS documentation on IAM Access Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html).
## Properties
| Property | Description |
| ------------- | --------------------------------------------------------- |
| access_key_id | The ID of the Access Key. |
| username | The IAM Username which is associated with the Access Key. |
| status | The status of the Access Key, e.g. "Active". |
| create_date | The creation date of the Access Key. |
## Examples
The following examples show how to use this InSpec audit resource.
### Test that an IAM Access Key has been used in the last 90 days
describe aws_iam_access_key(access_key_id: 'AKIA1111111111111111') do
it { should exist }
its('last_used_date') { should be > Time.now - 90 * 86400 }
end
### Test that an IAM Access Key for a specific user exists
describe aws_iam_access_key(username: 'psmith', id: 'AKIA1111111111111111') do
it { should exist }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
it { should exist }
it { should_not exist }
### active
The `active` matcher tests if the described IAM Access Key has a status of 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 following permissions action set to allow:
`iam:ListAccessKeys`
`iam:GetAccessKeyLastUsed`

91
docs-chef-io/content/inspec/resources/aws_iam_access_keys.md
View file

@ -1,91 +0,0 @@
+++
title = "aws_iam_access_keys resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_iam_access_keys"
identifier = "inspec/resources/aws/aws_iam_access_keys.md aws_iam_access_keys resource"
parent = "inspec/resources/aws"
+++
Use the `aws_iam_access_keys` InSpec audit resource to test properties of some or all AWS IAM Access Keys.
## Syntax
An `aws_iam_access_keys` resource block returns all IAM Access Keys and allows the testing of that group of Access Keys.
describe aws_iam_access_keys do
it { should exist }
its('access_key_ids') { should include 'AKIA1111111111111111' }
end
## Parameters
This resources accepts a single optional parameter, a Username for which to retrieve all Access Keys.
If not provided, all Access Keys for all Users will be retrieved.
### username _(optional)_
The IAM Username for which to retrieve the Access Keys.
This can be passed either as a string or as a `username: 'value'` key-value entry in a hash.
See also the [AWS documentation on IAM Access Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html).
## Properties
| Property | Description |
| ------------------- | -------------------------------------------------------------------------------------------- |
| access_key_id | The ID of the Access Key. |
| username | The IAM Username which is associated with the Access Key. |
| active | Indicates if the status of the Key is Active. |
| inactive | Indicates if the status of the Key is Inactive. |
| ever_used | Indicates if the Key has ever been used. |
| never_used | Indicates if the Key has never been used. |
| create_date | The creation date of the Access Key. |
| created_days_ago | How many days ago the Access Key was created. |
| created_hours_ago | How many hours ago the Access Key was created. |
| created_with_user | Boolean indicating if the Access Key was created with a User. |
| last_used_date | The date the Access Key was last used. |
| last_used_hours_ago | How many hours ago the Key was last used. |
| last_used_days_ago | How many days ago the Key was last used. |
| user_created_date | The date on which the associated User was created. |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
### Test all Active keys
describe aws_iam_access_keys.where(active: true) do
its('access_key_ids') { should include 'AKIA1111111111111111' }
end
### Ensure a User has no Access Keys
describe aws_iam_access_keys.where(username: 'untrusted-account') do
it { should_not exist }
end
## Matchers
For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
it { should exist }
it { should_not exist }
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the following permissions set to Allow:
`iam:GetUser`
`iam:GetAccessKeyLastUsed`
`iam:ListUsers`
`iam:ListAccessKeys`

65
docs-chef-io/content/inspec/resources/aws_iam_account_alias.md
View file

@ -1,65 +0,0 @@
+++
title = "aws_iam_account_alias resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_iam_account_alias"
identifier = "inspec/resources/aws/aws_iam_account_alias.md aws_iam_account_alias resource"
parent = "inspec/resources/aws"
+++
Use the `aws_iam_account_alias` InSpec audit resource to test properties of the AWS IAM account alias.
## Syntax
An `aws_iam_account_alias` resource block may be used to perform tests on details of the AWS account alias.
describe aws_iam_account_alias do
it { should exist }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on Account Aliases](https://docs.aws.amazon.com/IAM/latest/UserGuide/console_account-alias.html).
## Properties
| Property | Description |
| -------- | ------------------------------------------- |
| alias | String containing the Alias of the account. |
## Examples
### Check that the account alias has not be set
describe aws_iam_account_alias do
it { should_not exist }
end
### Test if the account alias starts with expected prefix
describe aws_iam_account_alias do
it { should exist }
its('alias') { should match /^chef-/ }
end
## Matchers
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_iam_account_alias 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 `iam:ListAccountAliases` action with Effect set to Allow.

75
docs-chef-io/content/inspec/resources/aws_iam_group.md
View file

@ -1,75 +0,0 @@
+++
title = "aws_iam_group resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_iam_group"
identifier = "inspec/resources/aws/aws_iam_group.md aws_iam_group resource"
parent = "inspec/resources/aws"
+++
Use the `aws_iam_group` InSpec audit resource to test properties of a single IAM group.
## Syntax
An `aws_iam_group` resource block identifies 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
## Parameters
### group_name _(required)_
This resource accepts a single parameter, the Group Name which uniquely identifies the IAM Group.
This can be passed either as a string or as a `group_name: 'value'` key-value entry in a hash.
See also the [AWS documentation on IAM Groups](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html).
## Properties
| Property | Description |
| ---------- | ----------------------------------------- |
| group_name | The group name. |
| group_id | The group ID. |
| arn | The Amazon Resource Name of the group. |
| users | Array of users associated with the group. |
## Examples
### Ensure group contains a certain user
describe aws_iam_group('admin-group') do
its('users') { should include 'deployment-service-account')}
end
## Matchers
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_iam_group('AnExistingGroup') do
it { should exist }
end
describe aws_iam_group('ANonExistentGroup') 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: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).

68
docs-chef-io/content/inspec/resources/aws_iam_groups.md
View file

@ -1,68 +0,0 @@
+++
title = "aws_iam_groups resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_iam_groups"
identifier = "inspec/resources/aws/aws_iam_groups.md aws_iam_groups resource"
parent = "inspec/resources/aws"
+++
Use the `aws_iam_groups` InSpec audit resource to test properties of a collection of IAM groups.
## Syntax
An `aws_iam_groups` resource block identifies a group by group name.
describe aws_iam_groups('mygroup') do
it { should exist }
end
# Hash syntax for group name
describe aws_iam_groups(group_name: 'mygroup') do
it { should exist }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on IAM Groups](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html).
## Properties
| Property | Description |
| ----------- | -------------------------------------------------------------------------------------------- |
| group_names | The group name. |
| group_ids | The group ID. |
| arns | The Amazon Resource Name of the group. |
| users | Array of users associated with the group. |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
### Ensure group contains a certain user
describe aws_iam_groups do
it { should exist }
its('group_names') { should include 'prod-access-group' }
end
## Matchers
### exist
The control will pass if a group with the given group name exists.
describe aws_iam_groups 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 `iam:ListGroup` 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).

164
docs-chef-io/content/inspec/resources/aws_iam_inline_policy.md
View file

@ -1,164 +0,0 @@
+++
title = "aws_iam_inline_policy resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_iam_inline_policy"
identifier = "inspec/resources/aws/aws_iam_inline_policy.md aws_iam_inline_policy resource"
parent = "inspec/resources/aws"
+++
Use the `aws_iam_inline_policy` InSpec audit resource to test properties of a single inline AWS IAM Policy embedded with IAM User, IAM Group or IAM Role. For managed policies, use the `aws_iam_policy` resource.
## Syntax
An `aws_iam_inline_policy` resource block identifies an inline policy by policy name and user/group/role by name
# Find an inline policy by name and role name
describe aws_iam_inline_policy(role_name: 'role-x', policy_name: 'policy-1') do
it { should exist }
end
# Find an inline policy by name and group name
describe aws_iam_inline_policy(group_name: 'group-x', policy_name: 'policy-1') do
it { should exist }
end
# Find an inline policy by name and user name
describe aws_iam_inline_policy(user_name: 'user-a', policy_name: 'policy-1') do
it { should exist }
end
## Parameters
This resource requires `policy_name` and one of the `role_name`, `group_name` or `user_name` to be provided.
See AWS Documentation on inline policies for more details
- [get-role-policy](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/get-role-policy.html)
- [get-group-policy](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/get-group-policy.html)
- [get-user-policy](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/get-user-policy.html)
## Properties
| Property | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| policy | 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`. |
| statement_count | Returns the number of statements present in the `policy`. |
## Examples
### Test that a policy does exist
describe aws_iam_inline_policy(role_name: 'role-x', policy_name: 'policy-1') do
it { should exist }
end
### Examine the policy statements
describe aws_iam_inline_policy(role_name: 'role-x', policy_name: 'policy-1') 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:*') }
# You can also check NotAction
it { should_not have_statement(NotAction: 'iam:*') }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
it { should exist }
it { should_not exist }
### 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_inline_policy(role_name: 'role-x', policy_name: 'policy-1') do
it { should_not have_statement('Effect' => 'Allow', 'Resource' => '*', 'Action' => '*')}
end
# Symbols and lowercase also allowed as criteria
describe aws_iam_inline_policy(role_name: 'role-x', policy_name: 'policy-1') 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_inline_policy(role_name: 'role-x', policy_name: 'policy-1') 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_inline_policy(role_name: 'role-x', policy_name: 'policy-1') 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:GetUserPolicy`, `iam:GetRolePolicy`, and `iam:GetGroupPolicy` 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).

95
docs-chef-io/content/inspec/resources/aws_iam_password_policy.md
View file

@ -1,95 +0,0 @@
+++
title = "aws_iam_password_policy resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_iam_password_policy"
identifier = "inspec/resources/aws/aws_iam_password_policy.md aws_iam_password_policy resource"
parent = "inspec/resources/aws"
+++
Use the `aws_iam_password_policy` InSpec audit resource to test properties of an AWS IAM Password Policy.
## Syntax
An `aws_iam_password_policy` resource block declares the tests for an AWS IAM Password Policy.
describe aws_iam_password_policy do
it { should exist }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on Auto Scaling Group](https://docs.aws.amazon.com/autoscaling/ec2/userguide/AutoScalingGroup.html).
## Properties
| Property | Description |
| ------------------------------- | -------------------------------------------------------------------------- |
| minimum_password_length | The minimum character count of the password policy. |
| max_password_age_in_days | Integer representing in days how long a password may last before expiring. |
| number_of_passwords_to_remember | Number of previous passwords to remember. |
## Examples
### Test that a Password Policy meets your company's requirements.
describe aws_iam_password_policy do
it { should require_uppercase_characters }
it { should require_lowercase_characters }
it { should require_numbers }
its('minimum_password_length') { should be > 8 }
end
### Test that users can change their own passwords
describe aws_iam_password_policy do
it { should allow_users_to_change_password }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
it { should exist }
### prevent_password_reuse
it { should prevent_password_reuse }
### expire_passwords
it { should expire_passwords }
### require_numbers
it { should require_numbers }
### require_symbols
it { should require_symbols }
### require_lowercase_characters
it { should require_lowercase_characters }
### require_uppercase_characters
it { should require_uppercase_characters}
### allow_users_to_change_passwords
it { should allow_users_to_change_password }
All matchers can use the inverse `should_not` predicate.
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the following permissions action set to allow: `iam:GetAccountPasswordPolicy`

88
docs-chef-io/content/inspec/resources/aws_iam_policies.md
View file

@ -1,88 +0,0 @@
+++
title = "aws_iam_policies resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_iam_policies"
identifier = "inspec/resources/aws/aws_iam_policies.md aws_iam_policies resource"
parent = "inspec/resources/aws"
+++
Use the `aws_iam_policies` InSpec audit resource to test properties of a collection of AWS IAM Policies.
## Syntax
`aws_iam_policies` Resource returns a collection of IAM Policies and allows testing of that collection.
describe aws_iam_policies do
its('policy_names') { should include('test-policy-1') }
end
## Parameters
### only_attached _(optional)_
This resource allows filtering by only_attached.
When `OnlyAttached` is `true`, the returned list contains only the policies that are attached to an IAM user, group, or role. When `OnlyAttached` is `false`, or when the parameter is not included, all policies are returned.
### scope _(optional)_
This resource allows filtering by scope.
To list only AWS managed policies, set `Scope` to `AWS`. To list only the customer managed policies in your AWS account, set `Scope` to `Local`. If scope is not supplied `ALL` policies are returned.
See also the [AWS documentation on IAM Policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html).
## Properties
| Property | Description |
| ------------------- | -------------------------------------------------------------------------------------------- |
| arns | The ARN identifier of the specified policy. |
| policy_ids | The policy ids. |
| policy_names | The policy names. |
| attachment_counts | The count of attached entities for each policy. |
| attached_groups | The list of group names of the groups attached to each policy. |
| attached_roles | The list of role names of the roles attached to each policy. |
| attached_users | The list of usernames of the users attached to each policy. |
| default_version_ids | The 'default_version_id' value of each policy. |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
### Ensure a policy exists
describe aws_iam_policies do
its('policy_names') { should include('test-policy-1') }
end
### Allow at most 100 IAM Policies on the account
describe aws_iam_policies do
its('entries.count') { should be <= 100}
end
## Matchers
For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_iam_policies.where( <property>: <value>) do
it { should exist }
end
describe aws_iam_policies.where( <property>: <value>) 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: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).

203
docs-chef-io/content/inspec/resources/aws_iam_policy.md
View file

@ -1,203 +0,0 @@
+++
title = "aws_iam_policy resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_iam_policy"
identifier = "inspec/resources/aws/aws_iam_policy.md aws_iam_policy resource"
parent = "inspec/resources/aws"
+++
Use the `aws_iam_policy` InSpec audit resource to test properties of a single managed AWS IAM Policy.
## Syntax
An `aws_iam_policy` resource block identifies a policy by policy name or arn
# Find a policy by name
describe aws_iam_policy('AWSSupportAccess') do
it { should exist }
end
# Hash syntax for policy name
describe aws_iam_policy(policy_name: 'AWSSupportAccess') do
it { should exist }
end
## Parameters
This resource requires either the `policy_name` or the `policy_arn` to be provided.
### policy_name _(required if `policy_arn` not provided)_
The Policy Name which uniquely identifies the Policy.
This must be passed as a `policy_name: 'value'` key-value entry in a hash.
### policy_arn _(required if `policy_name` not provided)_
The Policy ARN which uniquely identifies the Policy.
This must be passed as a `policy_arn: 'value'` key-value entry in a hash.
See also the [AWS documentation on IAM Policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html).
## Properties
| Property | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| arn | The ARN identifier of the specified policy. |
| attachment_count | The count of attached entities for the specified policy. |
| attached_groups | The list of group names of the groups attached to the policy. |
| attached_roles | The list of role names of the roles attached to the policy. |
| attached_users | The list of usernames of the users attached to the policy. |
| default_version_id | The 'default_version_id' value of the specified policy. |
| policy | 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`. |
| statement_count | Returns the number of statements present in the `policy`. |
## Examples
### 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:*') }
# You can also check NotAction
it { should_not have_statement(NotAction: 'iam:*') }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
it { should exist }
it { should_not exist }
### 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/reference_policies_elements_principal.html), [NotPrincipal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_notprincipal.html) or [Condition](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html).
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).

81
docs-chef-io/content/inspec/resources/aws_iam_role.md
View file

@ -1,81 +0,0 @@
+++
title = "aws_iam_role resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_iam_role"
identifier = "inspec/resources/aws/aws_iam_role.md aws_iam_role resource"
parent = "inspec/resources/aws"
+++
Use the `aws_iam_role` InSpec audit resource to test properties of an AWS IAM Role.
## Syntax
An `aws_iam_role` resource block declares the tests for a single AWS IAM Role by Role Name.
describe aws_iam_role(role_name: 'my-role') do
it { should exist }
end
## Parameters
### role_name _(required)_
This resource accepts a single parameter, the Role Name which uniquely identifies the Role.
This can be passed either as a string or as a `role_name: 'value'` key-value entry in a hash.
See also the [AWS documentation on IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html).
## Properties
| Property | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| path | The path to the role. |
| role_name | The name of the role. |
| role_id | The id of the role. |
| arn | The Amazon Resource Name (ARN) specifying the role. |
| create_date | The date and time, in ISO 8601 date-time format , when the role was created. |
| assume_role_policy_document | The policy that grants an entity permission to assume the role. |
| description | The description of the role. |
| max_session_duration | The maximum session duration (in seconds) for the specified role. Anyone who uses the AWS CLI, or API to assume the role can specify the duration using the optional DurationSeconds API parameter or duration-seconds CLI parameter. |
| permissions_boundary_type | The permissions boundary usage type that indicates what type of IAM resource is used as the permissions boundary for an entity. This data type can only have a value of Policy . |
| permissions_boundary_arn | The ARN of the policy used to set the permissions boundary for the user or role. |
| inline_policies | A list of inline policy names associated with the described role. |
| attached_policies_name | A list of attached policy names associated with the described role. |
| attached_policies_arn | A list of attached policy ARNs associated with the described role. |
## Examples
### Test that an IAM Role exists
describe aws_iam_role(role_name: aws_iam_role_name) do
it { should exist }
its('role_name') { should eq aws_iam_role_name }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_iam_role('AnExistingRole') do
it { should exist }
end
describe aws_iam_role('ANonExistentRole') 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 following permissions action set to allow:
`iam:GetRole`

77
docs-chef-io/content/inspec/resources/aws_iam_roles.md
View file

@ -1,77 +0,0 @@
+++
title = "aws_iam_roles resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_iam_roles"
identifier = "inspec/resources/aws/aws_iam_roles.md aws_iam_roles resource"
parent = "inspec/resources/aws"
+++
Use the `aws_iam_roles` InSpec audit resource to test properties of a collection of AWS IAM Roles.
## Syntax
An `aws_iam_roles` resource block returns all IAM Roles and allows the testing of that group of Roles.
describe aws_iam_roles do
it { should exist }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html).
## Properties
| Property | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| paths | The path to the role. |
| role_names | The name of the role. |
| role_ids | The id of the role. |
| arns | The Amazon Resource Name (ARN) specifying the role. |
| create_date | The date and time, in ISO 8601 date-time format , when the role was created. |
| assume_role_policy_document | The policy that grants an entity permission to assume the role. |
| description | The description of the role. |
| max_session_duration | The maximum session duration (in seconds) for the specified role. Anyone who uses the AWS CLI, or API to assume the role can specify the duration using the optional DurationSeconds API parameter or duration-seconds CLI parameter. |
| permissions_boundary_type | The permissions boundary usage type that indicates what type of IAM resource is used as the permissions boundary for an entity. This data type can only have a value of Policy . |
| permissions_boundary_arn | The ARN of the policy used to set the permissions boundary for the user or role. |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
### Ensure the Role 'RDS-RW' exists.
describe aws_iam_roles do
its('role_names') { should include 'RDS-RW' }
end
### Ensure no Roles have `max_session_duration` greater or equal to 2hrs.
describe aws_iam_roles.where{ max_session_duration >= (60*120) } do
it { should_not exist }
end
## Matchers
For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The `exists` matcher tests if the filtered IAM User(s) exists.
describe aws_iam_roles.where( <property>: <param>) do
it { should exist }
end
You may also use `it { should_not exist }`.
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the following permissions set to Allow:
`iam:ListRoles`

91
docs-chef-io/content/inspec/resources/aws_iam_root_user.md
View file

@ -1,91 +0,0 @@
+++
title = "aws_iam_root_user resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_iam_root_user"
identifier = "inspec/resources/aws/aws_iam_root_user.md aws_iam_root_user resource"
parent = "inspec/resources/aws"
+++
Use the `aws_iam_root_user` InSpec audit resource to test properties of an AWS IAM Root User.
## Syntax
An `aws_iam_root_user` resource block declares the tests for a single AWS IAM Root User by user name.
describe aws_iam_root_user do
it { should exist }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on Root Users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html).
## Properties
| Property | Description |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| summary_account | A hash containing a summary of the Root User's account. Properties within this hash can be accessed and tested against. Please see the [API Documentation](https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetAccountSummary.html) for details on the available properties. |
| virtual_devices | A list of the virtual MFA devices in the AWS account. |
## Examples
### Test that an IAM Root User has MFA enabled
describe aws_iam_root_user do
it { should have_mfa_enabled }
end
### Test that an IAM Root User does not have an access key
describe aws_iam_root_user do
it { should_not have_access_key }
end
### Test the IAM Root User has virtual MFA enabled
describe aws_iam_root_user do
it { should have_virtual_mfa_enabled }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_iam_root_user do
it { should exist }
end
### have_mfa_enabled
it { should have_mfa_enabled }
### have_virtual_mfa_enabled
it { should have_virtual_mfa_enabled }
### have_access_key
it { should have_access_key }
### have_hardware_mfa_enabled
it { should have_hardware_mfa_enabled }
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the following permissions action set to allow:
`iam:GetAccountSummary`
`iam:ListVirtualMFADevices`

68
docs-chef-io/content/inspec/resources/aws_iam_saml_provider.md
View file

@ -1,68 +0,0 @@
+++
title = "aws_iam_saml_provider resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_iam_saml_provider"
identifier = "inspec/resources/aws/aws_iam_saml_provider.md aws_iam_saml_provider resource"
parent = "inspec/resources/aws"
+++
Use the `aws_iam_saml_provider` InSpec audit resource to test properties of an AWS IAM SAML Provider.
## Syntax
An `aws_iam_saml_provider` resource block declares the tests for a single AWS IAM SAML Provider by Provider ARN.
describe aws_iam_saml_provider('arn:aws:iam::123456789012:saml-provider/FANCY') do
it { should exist }
end
## Parameters
### saml_provider_arn _(required)_
This resource accepts a single parameter, the ARN of the SAML Provider.
This can be passed either as a string or as a `saml_provider_arn: 'value'` key-value entry in a hash.
## Properties
| Property | Description |
| ---------------------- | ---------------------------------------------------------------------------- |
| provider | The provider. |
| arn | The arn of the provider. |
| saml_metadata_document | Metadata document associated with the saml provider. |
| valid_until | The expiration date and time for the SAML provider. |
| create_date | The date and time, in ISO 8601 date-time format , when the role was created. |
## Examples
#### Ensure we have at least one provider currently valid
describe aws_iam_saml_provider("arn:aws:iam::123456789012:saml-provider/FANCY") do
it { should exist }
its("arn") { should match("arn:aws:iam::.*:saml-provider\/FANCY") }
its("valid_until") { should be > Time.now + 90 * 86400 }
end
## Matchers
For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exists
The `exists` matcher tests if the filtered IAM SAML Provider(s) exists.
describe aws_iam_saml_provider('arn:aws:iam::123456789012:saml-provider/FANCY') do
it { should exist }
end
You may also use `it { should_not exist }`.
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the following permissions set to Allow:
`iam:GetSamlProvider`

83
docs-chef-io/content/inspec/resources/aws_iam_saml_providers.md
View file

@ -1,83 +0,0 @@
+++
title = "aws_iam_saml_providers resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_iam_saml_providers"
identifier = "inspec/resources/aws/aws_iam_saml_providers.md aws_iam_saml_providers resource"
parent = "inspec/resources/aws"
+++
Use the `aws_iam_saml_providers` InSpec audit resource to test properties of some or all AWS IAM SAML Providers.
## Syntax
An `aws_iam_saml_providers` resource block returns all IAM SAML Providers and allows the testing of that group of Providers.
describe aws_iam_saml_providers do
it { should exist }
end
## Parameters
### saml_provider_arn _(required)_
This resource accepts a single parameter, the ARN of the SAML Provider.
This can be passed either as a string or as a `saml_provider_arn: 'value'` key-value entry in a hash.
## Properties
| Property | Description |
| ------------- | -------------------------------------------------------------------------------------------- |
| provider_arns | The ARNs of the returned providers. |
| valid_untils | The expiration date and time for the SAML provider. |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
### Ensure we have at least one provider currently valid
describe.one do
aws_iam_saml_providers.provider_arns.each do |provider_arn|
describe aws_iam_saml_provider(provider_arn) do
it { should exist }
its('arn') { should match("arn:aws:iam::.*:saml-provider\/FANCY") }
its('valid_until') { should be > Time.now + 90 * 86400 }
end
end
end
### Ensure we have one and only one SAML provider
describe aws_iam_saml_providers do
its('entries.count') { should cmp 1 }
end
### Ensure we have at least one provider that matches
describe aws_iam_saml_providers.where{ arn =~ /arn:aws:iam::.*:saml-provider\/FANCY/ } do
it { should exist }
end
## Matchers
For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exists
The `exists` matcher tests if the filtered IAM SAML Provider(s) exists.
describe aws_iam_saml_providers.where( <property>: <param>) do
it { should exist }
end
You may also use `it { should_not exist }`.
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the following permissions set to Allow:
`iam:ListSamlProviders`
`iam:GetSamlProvider`

105
docs-chef-io/content/inspec/resources/aws_iam_user.md
View file

@ -1,105 +0,0 @@
+++
title = "aws_iam_user resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_iam_user"
identifier = "inspec/resources/aws/aws_iam_user.md aws_iam_user resource"
parent = "inspec/resources/aws"
+++
Use the `aws_iam_user` InSpec audit resource to test properties of a single AWS IAM User.
## Syntax
An `aws_iam_user` resource block declares the tests for a single AWS IAM User by user name.
describe aws_iam_user(user_name: 'psmith') do
it { should exist }
end
## Parameters
### user_name _(required)_
This resource accepts a single parameter, the User's username which uniquely identifies the User.
This can be passed either as a string or as a `user_name: 'value'` key-value entry in a hash.
See also the [AWS documentation on IAM Users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html).
## Properties
| Property | Description |
| --------------------- | ------------------------------------------------------------------------- |
| username | The user's username. |
| user_id | The user's ID. |
| user_arn | The Amazon Resource Name of the user. |
| access_keys | An array of hashes each containing metadata about the user's Access Keys. |
| inline_policy_names | The names of policies directly attached to the user. |
| attached_policy_names | The name of standalone IAM policies which are attached to the user. |
| attached_policy_arns | The arns of the standalone IAM policies which are attached to the user. |
- has_mfa_enabled
- has_console_password
## Examples
The following examples show how to use this InSpec audit resource.
### Test that an IAM user does not exist
describe aws_iam_user(user_name: 'invalid-user') do
it { should_not exist }
end
### Test that an IAM user has MFA enabled
describe aws_iam_user('psmith') do
it { should exist }
it { should have_mfa_enabled }
end
### Ensure a User has no Access Keys or Inline Policies
describe aws_iam_user('psmith') do
it { should exist }
its('access_keys') { should be_empty }
its('inline_policy_names') { should be_empty }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
it { should exist }
### has_mfa_enabled
This will check if the requested User has Multi Factor Authentication enabled.
it { should have_mfa_enabled }
#### has_console_password
This will ensure the User has a console password set.
it { should have_console_password }
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the following permissions action set to allow:
`iam:GetUser`
`iam:GetLoginProfile`
`iam:ListMFADevices`
`iam:ListAccessKeys`
`iam:ListUserPolicies`
`iam:ListAttachedUserPolicies`

95
docs-chef-io/content/inspec/resources/aws_iam_users.md
View file

@ -1,95 +0,0 @@
+++
title = "aws_iam_users resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_iam_users"
identifier = "inspec/resources/aws/aws_iam_users.md aws_iam_users resource"
parent = "inspec/resources/aws"
+++
Use the `aws_iam_users` InSpec audit resource to test properties of some or all AWS IAM Users.
## Syntax
An `aws_iam_users` resource block returns all IAM Users and allows the testing of that group of Users.
describe aws_iam_users do
its('usernames') { should include 'payroll-admin' }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on IAM Users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html).
## Properties
| Property | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| usernames | The usernames of the returned Users. |
| user_arns | The Amazon Resource Names of the returned Users. |
| user_ids | The IDs of the returned Users. |
| access_keys | Array of Access Keys belonging to each User. |
| has_attached_policies | Whether or not the User has IAM Policies attached. |
| attached_policy_names | The names (if any) of the IAM Policies attached to the User. |
| attached_policy_arns | The Amazon Resource Names (if any) of the IAM Policies attached to the User. |
| has_console_password | Whether or not the User has a console password set. |
| has_inline_policies | Boolean indicating whether or not the User has policies set directly on them. |
| inline_policy_names | The names of the policies (if any) which are directly on the User. |
| has_mfa_enabled | Boolean indicating whether the User has MFA enabled or not. |
| password_ever_used? | Whether the user has even used their console password. |
| password_last_used_days_ago | How long ago, in days, since the user last used their console password. Returns `-1` if the password has never been used. |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
### Ensure there are no Users who do not have MFA enabled.
describe aws_iam_users.where( has_mfa_enabled: false) do
it { should_not exist }
end
### Ensure there are no Users with inline policies
describe aws_iam_users.where(has_inline_policies: true) do
its('usernames') { should be_empty }
end
### Ensure there are no Users with attached policies
describe aws_iam_users.where(has_attached_policies: true) do
its('usernames') { should be_empty }
end
## Matchers
For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_iam_users.where( <property>: <value>) do
it { should exist }
end
describe aws_iam_users.where( <property>: <value>) 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 following permissions set to Allow:
`iam:GetLoginProfile`
`iam:ListUsers`
`iam:ListMFADevices`
`iam:ListAccessKeys`
`iam:ListUserPolicies`
`iam:ListAttachedUserPolicies`

92
docs-chef-io/content/inspec/resources/aws_internet_gateway.md
View file

@ -1,92 +0,0 @@
+++
title = "aws_internet_gateway resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_internet_gateway"
identifier = "inspec/resources/aws/aws_internet_gateway"
parent = "inspec/resources/aws"
+++
Use the `aws_internet_gateway` InSpec audit resource to test the properties of a single AWS internet gateway.
## Syntax
An `aws_internet_gateway` resource block declares the tests for a single AWS internet gateway by id or name.
describe aws_internet_gateway(id: 'igw-abc0123456789deff') do
it { should exist }
end
describe aws_internet_gateway(name: 'my-igw') do
it { should exist }
end
## Parameters
Either the id or the name must be provided.
### id _(required if `name` not provided)_
The value of the `internet_gateway_id` assigned by the AWS after the resource has been created.
This should be in the format of `igw-` followed by 8 or 17 hexadecimal characters and passed as an `id: 'value'` key-value entry in a hash.
### name _(required if `id` not provided)_
If a `Name` tag is applied to the internet gateway, this can be used to lookup the resource.
This must be passed as a `name: 'value'` key-value entry in a hash.
If there are multiple internet gateways with the same name, this resource will raise an error.
## Properties
| Property | Description |
| --------- | --------------------------------------------------------------------------------------------- |
| id | The ID of the internet gateway. |
| name | The value of the `Name` tag. It is `nil` if not defined. |
| vpc_id | The ID of the attached VPC. It is `nil` if the resource is in a `detached` state. |
| tags | A hash, with each key-value pair corresponding to an internet gateway tag. |
| attached? | Indicates whether the internet gateway is **attached** to a VPC or not (`true` or `false`). |
| detached? | Indicates whether the internet gateway is in a **detached** state or not (`true` or `false`). |
| owner_id | The ID of the AWS account that owns the internet gateway. |
There are also additional properties available. For a comprehensive list, see [the API reference documentation](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_InternetGateway.html)
## Examples
### Test that the internet gateway is attached
describe aws_internet_gateway(name: 'my-igw') do
it { should be_attached }
end
### Test that the ID of the attached VPC is `vpc-1234567890abcdef1`
describe aws_internet_gateway(id: 'igw-abc0123456789deff') do
its('vpc_id') { should eq `vpc-1234567890abcdef1` }
end
### Test that the internet gateway has a certain tag
describe aws_internet_gateway(name: 'my-igw') do
its('tags') { should include('environment' => 'dev') }
its('tags') { should include('shutdown-at-10-pm') } # Regardless of the value
end
## Matchers
This InSpec audit resource has the following special matcher. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
describe aws_internet_gateway(name: 'my-igw') 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 `ec2:DescribeInternetGateways` action 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).

78
docs-chef-io/content/inspec/resources/aws_internet_gateways.md
View file

@ -1,78 +0,0 @@
+++
title = "aws_internet_gateways resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_internet_gateways"
identifier = "inspec/resources/aws/aws_internet_gateways.md aws_internet_gateways"
parent = "inspec/resources/aws"
+++
Use the `aws_internet_gateways` InSpec audit resource to test the properties of all AWS internet gateways owned by the AWS account.
## Syntax
An `aws_internet_gateways` resource block collects all of the internet gateways and then tests that group.
describe aws_internet_gateways do
it { should exist }
end
## Parameters
This resource does not expect any parameters.
## Properties
| Property | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| ids | The ID of the internet gateway. The field name is `id`. |
| names | The value of the `Name` tag. It is `nil` if not defined. The field name is `name`. |
| vpc_ids | The ID of the attached VPC. It is `nil` if the resource is in a `detached` state. The field name is `vpc_id`. |
| tags | A hash, with each key-value pair corresponding to an internet gateway tag. The field name is `tags`. |
| attachment_states | Indicates whether the internet gateway is attached to a VPC (`attached` or `detached`). The field name is `attachment_state`. |
| owner_ids | The ID of the AWS account that owns the internet gateway. The field name is `owner_id`. |
## Examples
### Test that there are exactly 3 internet gateways
describe aws_internet_gateway do
its('count') { should cmp 3 }
end
### Use this InSpec resource to request the ids of all internet gateways, then test in-depth using `aws_internet_gateway`.
aws_internet_gateways.ids.each do |id|
describe aws_internet_gateway(id: id) do
it { should be_attached }
end
end
## Matchers
For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
The field names described in the [properties table](#properties) should be used for the `<property>` in the `where` clause.
Use `should_not` to test the entity should not exist.
describe aws_internet_gateways.where( <property>: <value>) do
it { should exist }
end
describe aws_internet_gateways.where( <property>: <value>) 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:DescribeInternetGateways` action 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).

140
docs-chef-io/content/inspec/resources/aws_kms_key.md
View file

@ -1,140 +0,0 @@
+++
title = "aws_kms_key resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_kms_key"
identifier = "inspec/resources/aws/aws_kms_key.md aws_kms_key resource"
parent = "inspec/resources/aws"
+++
Use the `aws_kms_key` InSpec audit resource to test properties of a single AWS KMS Key.
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.
## 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_id: 'arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
it { should exist }
end
## Parameters
### alias _(required if `key_id` not specified)_
This resource accepts searching for a KMS Key by it's Alias.
This can be passed as a `alias: 'alias/value'` key-value entry in a hash. This will then use the `target_key_id` from the Alias to search for the KMS Key.
### key_id _(required if `alias` not specified)_
This resource accepts searching for a KMS Key by the KMS Key ID which can represent both the actual Key ID or the ARN of the Key.
This can be passed either as a string or as a `key_id: 'value'` key-value entry in a hash.
See also the [AWS documentation on KS Keys](https://docs.aws.amazon.com/kms/latest/developerguide/getting-started.html).
## Properties
| Property | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key_id | The globally unique identifier for the key. |
| arn | The ARN identifier of the specified key. |
| creation_date | Specifies the date and time when the key was created. |
| created_days_ago | Specifies the number of days since the key was created. |
| 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. |
| description | The description of the key. |
| 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. |
| 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. |
## Examples
### 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
### 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
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers (such as `exist`) please visit our [matchers page](/inspec/matchers/).
Use `should_not` to test the entity should not exist in all cases.
### exist
The control will pass if the describe returns at least one result.
it { should exist }
it { should_not exist }
### be_enabled
The test will pass if the specified key's key_state is set to enabled.
it { should be_enabled }
### 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.
it { should be_external }
### 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.
it { should be_managed_by_aws }
### have_key_expiration
Specifies whether the key's key material expires. This value is null unless the keys Origin is External.
it { should have_key_expiration }
### have_rotation_enabled
The test will pass if automatic rotation of the key material is enabled for the specified key.
it { should have_rotation_enabled }
## 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).

84
docs-chef-io/content/inspec/resources/aws_kms_keys.md
View file

@ -1,84 +0,0 @@
+++
title = "aws_kms_keys resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_kms_keys"
identifier = "inspec/resources/aws/aws_kms_keys.md aws_kms_keys resource"
parent = "inspec/resources/aws"
+++
Use the `aws_kms_keys` 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.
## 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
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on KS Keys](https://docs.aws.amazon.com/kms/latest/developerguide/getting-started.html).
## Properties
| Property | Description |
| -------- | -------------------------------------------------------------------------------------------- |
| key_ids | The IDs of the returned keys. |
| key_arns | The Amazon Resource Names of the returned keys. |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
The following examples show how to use this InSpec audit resource.
### Ensure a Key exists
describe aws_kms_keys do
its('key_ids') { should include 'fd7e608b-f435-4186-b8b5-111111111111'}
end
### Allow at most 100 KMS Keys on the account
describe aws_kms_keys do
its('entries.count') { should be <= 100}
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_kms_keys do
it { should exist }
end
describe aws_kms_keys.where( <property>: <value>) 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 `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).

56
docs-chef-io/content/inspec/resources/aws_lambda.md
View file

@ -1,56 +0,0 @@
+++
title = "aws_lambda resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_lambda"
identifier = "inspec/resources/aws/aws_lambda.md aws_lambda resource"
parent = "inspec/resources/aws"
+++
Use the `aws_lambda` resource to test a specific lambda.
## Syntax
```ruby
describe aws_lambda do
it { should exist}
its ('handler') { should eq 'main.on_event'}
its ('version') { should eq '$LATEST' }
its ('runtime') { should eq 'python3.7' }
end
```
## Parameters
This resource expects the name of the function.
## Properties
All properties as defined by the [Aws::lambda::Types::GetFunctionResponse](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/Lambda/Types/GetFunctionResponse.html)
## Examples
### tests that all lambdas with a particular tag is correctly deployed
```ruby
describe aws_lambda('my_new_lambda') do
it { should exist}
its ('handler') { should eq 'main.on_event'}
its ('version') { should eq '$LATEST' }
its ('runtime') { should eq 'python3.7' }
end
```
## Matchers
This InSpec audit resource uses the standard matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `lambda:GetFunction` action with Effect set to Allow.
You can find detailed documentation at [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/lambda-api-permissions-ref.html)

68
docs-chef-io/content/inspec/resources/aws_lambdas.md
View file

@ -1,68 +0,0 @@
+++
title = "aws_lambdas resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_lambdas"
identifier = "inspec/resources/aws/aws_lambdas.md aws_lambdas resource"
parent = "inspec/resources/aws"
+++
Use the `aws_lambdas` resource to test the collection of lambdas deployed into an account.
## Syntax
```ruby
describe aws_lambdas do
its('count') { should eq 20 }
end
```
## Parameters
This resource does not expect any parameters.
## Properties
| Property | Description |
| -------- | --------------------------------- |
| names | The names of the lambda deployed. |
| tags | The tags of the lambda deployed. |
## Examples
### tests that all lambdas with a particular tag is correctly deployed
```ruby
lambdas = aws_lambdas()
describe lambdas do
its ('count') { should eq 33}
end
lambdas.tags.each_with_index { | tag, i |
if tag!= {} and tag.include? 'Application' and tag['Application']=='test')
lambda_name = lambdas.names[i]
describe aws_lambda(lambda_name) do
it { should exist}
its ('handler') { should eq 'main.on_event'}
its ('version') { should eq '$LATEST' }
its ('runtime') { should eq 'python3.7' }
end
end
}
```
## Matchers
This InSpec audit resource uses the standard matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `lambda:ListFunctions` action with Effect set to Allow.
You can find detailed documentation at [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/lambda-api-permissions-ref.html)

108
docs-chef-io/content/inspec/resources/aws_launch_configuration.md
View file

@ -1,108 +0,0 @@
+++
title = "aws_launch_configuration resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_launch_configuration"
identifier = "inspec/resources/aws/aws_launch_configuration.md aws_launch_configuration resource"
parent = "inspec/resources/aws"
+++
Use the `aws_launch_configuration` InSpec audit resource to test properties of a
single AWS Launch Configuration.
## Syntax
# Ensure that a launch configuration exists and has the correct key name
describe aws_launch_configuration('my-config') do
it { should exist }
its('key_name') { should be 'my-key-name' }
end
# You may also use hash syntax to pass the launch configuration name
describe aws_launch_configuration(launch_configuration_name: 'my-config') do
it { should exist }
end
## Parameters
### launch_configuration_name _(required)_
This resource expects a single parameter, the `launch_configuration_name` which
uniquely identifies the of a Launch Configuration.
See also the [AWS documentation on Launch Configurations](https://docs.aws.amazon.com/autoscaling/ec2/userguide/LaunchConfiguration.html).
## Properties
| Property | Description |
| --------------------------- | ----------------------------------------------------------------------------------------- |
| arn | An string indicating the ARN of the launch configuration |
| image_id | An string indicating the AMI of the launch configuration |
| instance_type | A string indicating the instance type of the launch configuration |
| iam_instance_profile | A string indicating the IAM profile for the launch configuration |
| key_name | A string indicating the AWS key pair for the launch configuration |
| security_groups | An array of strings of the security group IDs associated with the launch configuration |
| associate_public_ip_address | A boolean indicating if the launch configuration is configured to set a public IP address |
| user_data | A string containing the user data configured for the launch configuration |
| ebs_optimized | A boolean indicating if the launch configuration is optimized for Amazon EBS |
| instance_monitoring | A string indicating if instance monitoring is set to `detailed` or `basic` |
| spot_price | A floating point number indicating the spot price configured |
## Examples
### Ensure a Launch Config is using the correct AMI
describe aws_launch_configuration('my-config') do
its('image_id') { should eq 'ami-012345'}
end
### Test the instance type used in a Launch Config
describe aws_launch_configuration('my-config') do
its('instance_type') { should eq 't3.micro'}
end
### Ensure a Launch Config is associated with the right IAM Profile
describe aws_launch_configuration('my-config') do
its('iam_instance_profile') { should eq 'iam-profile' }
end
### Ensure the Launch Config does not set a public IP
describe aws_launch_configuration('my-config') do
its('associate_public_ip_address') { should be false }
end
### Ensure the correct UserData is set on launched instances
describe aws_launch_configuration('my-config') do
its('user_data') { should include 'user-data' }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_launch_configuration('AnExistingLC') do
it { should exist }
end
describe aws_launch_configuration('ANonExistentLC') 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 `autoscaling:Describe*` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon Auto Scaling Groups and launch configurations](https://docs.aws.amazon.com/autoscaling/ec2/userguide/control-access-using-iam.html).

122
docs-chef-io/content/inspec/resources/aws_nat_gateway.md
View file

@ -1,122 +0,0 @@
+++
title = "aws_nat_gateway resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_nat_gateway"
identifier = "inspec/resources/aws/aws_nat_gateway.md aws_nat_gateway"
parent = "inspec/resources/aws"
+++
Use the `aws_nat_gateway` InSpec audit resource to test the properties of a single AWS NAT gateway.
## Syntax
An `aws_nat_gateway` resource block declares the tests for a single AWS NAT gateway by id, name, vpc_id or subnet_id.
describe aws_nat_gateway(id: 'nat-abc0123456789deff') do
it { should exist }
end
describe aws_nat_gateway(name: 'my-nat-gateway') do
it { should exist }
end
Multiple parameters can be provided for better granularity.
describe aws_nat_gateway(vpc_id: 'vpc-abc01234', subnet_id: 'subnet-6789deff') do
it { should exist }
end
## Parameters
At least one of the following parameters must be provided.
- id
- name
- subnet_id
- vpc_id
### id
The value of the `nat_gateway_id` assigned by the AWS after the resource has been created.
This should be in the format of `nat-` followed by 8 or 17 hexadecimal characters and passed as an `id: 'value'` key-value entry in a hash.
### name
If a `Name` tag is applied to the NAT gateway, this can be used to lookup the resource.
This must be passed as a `name: 'value'` key-value entry in a hash.
If there are multiple NAT gateways with the same name, this resource will raise an error.
### subnet_id
The ID of the subnet in which the NAT gateway is placed.
This should be in the format of `subnet-` followed by 8 or 17 hexadecimal characters and passed as an `subnet_id: 'value'` key-value entry in a hash.
### vpc_id
The ID of the VPC in which the NAT gateway is located.
This should be in the format of `vpc-` followed by 8 or 17 hexadecimal characters and passed as an `vpc_id: 'value'` key-value entry in a hash.
## Properties
| Property | Description |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | The ID of the NAT gateway. |
| name | The value of the `Name` tag. It is `nil` if not defined. |
| vpc_id | The ID of the VPC in which the NAT gateway is located. |
| subnet_id | The ID of the subnet in which the NAT gateway is placed. |
| tags | A hash, with each key-value pair corresponding to a NAT gateway tag. |
| nat_gateway_address_set | A hash of [NatGatewayAddress object](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_NatGatewayAddress.html) that gives information about the IP addresses and network interface associated with the NAT gateway. |
| state | The sate of the NAT gateway. Valid values are: `pending`, `failed`, `available`, `deleting` and `deleted`. |
There are also additional properties available. For a comprehensive list, see [the API reference documentation](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_NatGateway.html)
## Examples
### Test that the NAT gateway is in `available` state
describe aws_nat_gateway(name: 'my-nat-gateway') do
its('state') { should eq 'available' }
end
### Test that the ID of the VPC is `vpc-1234567890abcdef1`
describe aws_nat_gateway(id: 'nat-abc0123456789deff') do
its('vpc_id') { should eq `vpc-1234567890abcdef1` }
end
### Test that the NAT gateway has a certain tag
describe aws_nat_gateway(name: 'my-nat-gateway') do
its('tags') { should include('environment' => 'dev') }
its('tags') { should include('delete-at-10-pm') } # Regardless of the value
end
### Test that the private IP address is `10.0.1.68`
describe aws_nat_gateway(vpc_id: 'vpc-abc01234', subnet_id: 'subnet-12345678') do
its('nat_gateway_address_set') { should include(:private_ip => '10.0.1.68') }
end
For more examples, please check the [integration tests](https://github.com/inspec/inspec-aws/blob/main/test/integration/verify/controls/aws_nat_gateway.rb).
## Matchers
This InSpec audit resource has the following special matcher. For a full list of
available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
describe aws_nat_gateway(name: 'my-nat-gateway') 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 `ec2:DescribeNatGateways` action 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-chef-io/content/inspec/resources/aws_nat_gateways.md
View file

@ -1,86 +0,0 @@
+++
title = "aws_nat_gateways resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_nat_gateways"
identifier = "inspec/resources/aws/aws_nat_gateways.md aws_nat_gateways"
parent = "inspec/resources/aws"
+++
Use the `aws_nat_gateways` InSpec audit resource to test the properties of all
AWS NAT gateways owned by the AWS account.
## Syntax
An `aws_nat_gateways` resource block collects all of the NAT gateways and then tests that group.
describe aws_nat_gateways do
it { should exist }
end
## Parameters
This resource does not expect any parameters.
## Properties
| Property | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| ids | The ID of the NAT gateway. The field name is `id`. |
| names | The value of the `Name` tag. It is `nil` if not defined. The field name is `name`. |
| vpc_ids | The ID of the VPC in which the NAT gateway is located. The field name is `vpc_id`. |
| subnet_ids | The ID of the subnet in which the NAT gateway is placed. The field name is `subnet_id`. |
| tags | A hash, with each key-value pair corresponding to a NAT gateway tag. The field name is `tags`. |
| states | The sate of the NAT gateway. Valid values are: `pending`, `failed`, `available`, `deleting` and `deleted`. The field name is `state`. |
## Examples
### Test that there are exactly 3 NAT Gateways
describe aws_nat_gateways do
its('count') { should cmp 3 }
end
### Request The IDs of all NAT Gateways
Use this InSpec resource to request the ids of all NAT gateways, then test in-depth
using `aws_nat_gateway` InSpec singular AWS resource.
aws_nat_gateways.ids.each do |id|
describe aws_nat_gateway(id: id) do
its('state') { should eq 'available' }
end
end
For more examples, please check the [integration tests](https://github.com/inspec/inspec-aws/blob/main/test/integration/verify/controls/aws_nat_gateways.rb).
## Matchers
For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
#### exist
The control will pass if the describe returns at least one result.
The field names described in the [properties table](#properties) should be used for the `<property>` in the `where` clause.
Use `should_not` to test the entity should not exist.
describe aws_nat_gateways.where( <property>: <value>) do
it { should exist }
end
describe aws_nat_gateways.where( <property>: <value>) do
it { should_not exist }
end
Please see [here](https://github.com/inspec/inspec/blob/main/dev-docs/filtertable-usage.md) for more information on how to use filter table.
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ec2:DescribeNatGateways` action 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).

88
docs-chef-io/content/inspec/resources/aws_organizations_member.md
View file

@ -1,88 +0,0 @@
+++
title = "aws_organizations_member resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_organizations_member"
identifier = "inspec/resources/aws/aws_organizations_member.md aws_organizations_member resource"
parent = "inspec/resources/aws"
+++
Use the `aws_organizations_member` InSpec audit resource to test the current AWS Account being used within an organization.
## Syntax
An `aws_organizations_member` resource block tests if the current AWS Account is the Master Account.
The `master` matcher will return `true` or `false` accordingly.
You may also verify that the `master_account_id` and `master_account_arn` properties match known values.
If the current AWS Account _**is**_ the Master Account, you may also access properties of that account.
describe aws_organizations_member do
it { should exist }
end
## Parameters
This resource does not expect any parameters.
{{< note >}}
This resource must target AWS Region `us-east-1`. If another region is specified
in your configuration, it will be overwritten at runtime.
{{< /note >}}
## Properties
| Property | Description |
| ------------------ | ----------------------------------------------- |
| master_account_id | The ID of the AWS Organizations Master Account |
| master_account_arn | The ARN of the AWS Organizations Master Account |
_**If the current Account is the Master Account, the following properties are also available:**_
| Property | Description |
| ------------- | ------------------------------------------------------ |
| account_id | The ID of the current Account. |
| account_arn | The ARN of the current Account. |
| account_name | The Name of the current Account. |
| account_email | The Email address associated with the current Account. |
## Examples
### Ensure you are a child account with a certain ID for the top level account.
describe aws_organizations_member do
it { should_not be_master }
its('master_account_id') { should cmp '56845218745' }
end
### Ensure you are the top level account, with the right name and email associated.
describe aws_organizations_member do
it { should be_master }
its('account_name') { should eq 'MyAWSMasterAccount' }
its('account_email') { should eq 'aws.admin@org.com' }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list
of available matchers, please visit our [matchers page](/inspec/matchers/).
### be_master
The `be_master` matcher tests if the account is a 'master' AWS Account.
it { should_not be_master }
### exist
The control will pass if the describe returns at least one result.
it { should exist }

100
docs-chef-io/content/inspec/resources/aws_rds_cluster.md
View file

@ -1,100 +0,0 @@
+++
title = "aws_rds_cluster resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_rds_cluster"
identifier = "inspec/resources/aws/aws_rds_cluster.md aws_rds_cluster"
parent = "inspec/resources/aws"
+++
Use the `aws_rds_cluster` InSpec audit resource to test detailed properties of an individual RDS cluster.
RDS gives you access to the capabilities of a MySQL, MariaDB, PostgreSQL, Microsoft SQL Server, Oracle, or Amazon Aurora database server.
## Syntax
An `aws_rds_cluster` resource block uses resource parameters to search for an RDS
cluster, and then tests that RDS cluster. If no RDS clusters match, no error is
raised, but the `exists` matcher will return `false` and all properties will be
`nil`. If more than one RDS cluster matches (due to vague search parameters),
an error is raised.
describe aws_rds_cluster('test-cluster-id') do
it { should exist }
end
# Can also use hash syntax
describe aws_rds_cluster(db_cluster_identifier: 'test-cluster-id') do
it { should exist }
end
## Parameters
### db_cluster_identifier _(required)_
This resource accepts a single parameter, the user-supplied cluster identifier. This parameter isn't case-sensitive.
This can be passed either as a string or as a `db_cluster_identifier: 'value'` key-value entry in a hash.
See also the [AWS documentation on RDS cluster](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Aurora.Overview.html).
## Properties
For a comprehensive list of properties available to test on an RDS cluster see the [AWS Response Object](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/RDS/DBCluster.html).
## Examples
### Test the engine used with an RDS cluster
describe aws_rds_cluster(db_cluster_identifier: 'awsrds123') do
its('engine') { should eq 'mysql' }
its('engine_version') { should eq '5.6.37' }
end
### Test the storage allocated to an RDS cluster
describe aws_rds_cluster(db_cluster_identifier: 'awsrds123') do
its('storage_encrypted') { should eq true }
its('allocated_storage') { should eq 10 }
end
### Test the cluster status and master username
describe aws_rds_cluster(db_cluster_identifier: 'awsrds123') do
its('master_username') { should eq 'db-maintain' }
its('status') { should eq 'available' }
end
### Test the maximum and minumum capacity of a serverless RDS cluster
describe aws_rds_cluster(db_cluster_identifier: 'awsrds123') do
its('scaling_configuration_info.min_capacity') { should eq 2 }
its('scaling_configuration_info.max_capacity') { should eq 64 }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_rds_cluster(db_cluster_identifier: 'AnExistingRDS') do
it { should exist }
end
describe aws_rds_cluster(db_cluster_identifier: 'ANonExistentRDS') 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:DescribeDBclusters` 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).

88
docs-chef-io/content/inspec/resources/aws_rds_clusters.md
View file

@ -1,88 +0,0 @@
+++
title = "aws_rds_clusters resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_rds_clusters"
identifier = "inspec/resources/aws/aws_rds_clusters.md aws_rds_clusters resource"
parent = "inspec/resources/aws"
+++
Use the `aws_rds_clusters` InSpec audit resource to test properties of a collection of AWS RDS clusters.
RDS gives you access to the capabilities of a MySQL, MariaDB, PostgreSQL,
Microsoft SQL Server, Oracle, or Amazon Aurora database server.
## Syntax
Ensure you have exactly 3 clusters
describe aws_rds_clusters do
its('db_cluster_identifiers.count') { should cmp 3 }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on RDS](https://docs.aws.amazon.com/rds/?id=docs_gateway).
## Properties
| Property | Description |
| ------------------ | ------------------------------------------------------------------------------------- |
| cluster_identifier | The unique IDs of the RDS clusters returned. |
| database_name | The name of the database associated with each RDS cluster. |
| cluster_members | The RDS instances attached to each RDS cluster. |
| engine | The name of the database engine used by each cluster. |
| engine_version | The version of the database engine used by each cluster. |
| status | The current status of each cluster. |
| allocated_storage | The storage allocated to each cluster. |
| storage_encrypted | Returns T/F whether the cluster is encrypted or not. |
| availability_zones | A list of availability zones of the RDS clusters returned. |
| multi_az | Returns T/F depending on whether multiple availability zones are used in the cluster. |
| arn | The unique Amazon resource name of the RDS clusters. |
## Examples
### Ensure a specific cluster exists
describe aws_rds_clusters do
its('db_cluster_identifier') { should include 'cluster-12345678' }
end
### Test That All RDS Clusters Are Encrypted by ID
Use the InSpec resource to request the IDs of all RDS clusters, then test
in-depth using `aws_rds_cluster` to ensure all clusters are encrypted and have a
sensible size.
aws_rds_clusters.cluster_identifier.each do |cluster_identifier|
describe aws_rds_cluster(cluster_identifier) do
it { should have_encrypted_storage }
end
end
## Matchers
For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_rds_clusters do
it { should exist }
end
describe aws_rds_clusters do
it { should_not exist }
end
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ec2:Describeclusters`, 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-chef-io/content/inspec/resources/aws_rds_instance.md
View file

@ -1,89 +0,0 @@
+++
title = "aws_rds_instance resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_rds_instance"
identifier = "inspec/resources/aws/aws_rds_instance.md aws_rds_instance"
parent = "inspec/resources/aws"
+++
Use the `aws_rds_instance` 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.
## 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.
describe aws_rds_instance('test-instance-id') do
it { should exist }
end
# Can also use hash syntax
describe aws_rds_instance(db_instance_identifier: 'test-instance-id') do
it { should exist }
end
## Parameters
### db_instance_identifier _(required)_
This resource accepts a single parameter, the user-supplied instance identifier. This parameter isn't case-sensitive.
This can be passed either as a string or as a `db_instance_identifier: 'value'` key-value entry in a hash.
See also the [AWS documentation on RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_GettingStarted.html).
## Properties
For a comprehensive list of properties available to test on an RDS Instance see the [AWS Response Object](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/RDS/Types/DBInstance.html)
## Examples
### Test the engine used with an RDS instance
describe aws_rds_instance(db_instance_identifier: 'awsrds123') do
its ('engine') { should eq 'mysql' }
its ('engine_version') { should eq '5.6.37' }
end
### Test the storage allocated to an RDS instance
describe aws_rds_instance(db_instance_identifier: 'awsrds123') do
its ('storage_type') { should eq 'gp2' }
its ('allocated_storage') { should eq 10 }
end
### Test the instance type and master username
describe aws_rds_instance(db_instance_identifier: 'awsrds123') do
its ('master_username') { should eq 'db-maintain' }
its ('db_instance_class') { should eq 'db.t3.micro' }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_rds_instance(db_instance_identifier: 'AnExistingRDS') do
it { should exist }
end
describe aws_rds_instance(db_instance_identifier: 'ANonExistentRDS') 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).

79
docs-chef-io/content/inspec/resources/aws_rds_instances.md
View file

@ -1,79 +0,0 @@
+++
title = "aws_rds_instances resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_rds_instances"
identifier = "inspec/resources/aws/aws_rds_instances.md aws_rds_instances resource"
parent = "inspec/resources/aws"
+++
Use the `aws_rds_instances` InSpec audit resource to test properties of a collection of AWS RDS instances.
RDS gives you access to the capabilities of a MySQL, MariaDB, PostgreSQL, Microsoft SQL Server, Oracle, or Amazon Aurora database server.
RDS instances are compute instances used by the RDS service.
## Syntax
Ensure you have exactly 3 instances
describe aws_rds_instances do
its('db_instance_identifiers.count') { should cmp 3 }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on RDS](https://docs.aws.amazon.com/rds/?id=docs_gateway).
## Properties
| Property | Description |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| db_instance_identifiers | The unique IDs of the RDS Instances returned. |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
### Ensure a specific instance exists
describe aws_rds_instances do
its('db_instance_identifiers') { should include 'rds-12345678' }
end
### Test That All Rds Instances Are Encrypted by Id
Use the InSpec resource to request the IDs of all RDS instances, then test in-depth
using `aws_rds_instance` to ensure all instances are encrypted and have a sensible size.
aws_rds_instances.db_instance_identifiers.each do |db_instance_identifier|
describe aws_rds_instance(db_instance_identifier) do
it { should be_encrypted }
end
end
## Matchers
For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_rds_instances do
it { should exist }
end
describe aws_rds_instances do
it { should_not exist }
end
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).

72
docs-chef-io/content/inspec/resources/aws_region.md
View file

@ -1,72 +0,0 @@
+++
title = "aws_region resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_region"
identifier = "inspec/resources/aws/aws_region.md aws_region resource"
parent = "inspec/resources/aws"
+++
Use the `aws_region` InSpec audit resource to test properties of a single AWS region.
## Syntax
An `aws_region` resource block identifies an AWS region by ID. If no region is provided, the current default is used.
describe aws_region('eu-west-2') do
it { should exist }
end
describe aws_region(region_name: 'us-east-1') do
it { should exist }
end
## Parameters
### region_name _(optional)_
This resource accepts a single parameter, the region_name.
This can be passed either as a string or as a `region_name: 'value'` key-value entry in a hash.
See also the [AWS documentation on Regions](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html).
## Properties
| Property | Description |
| ----------- | ------------------------------------ |
| region_name | The Name of the region. |
| endpoint | The resolved endpoint of the region. |
## Examples
### Test whether a region exists
describe aws_region('region-not-real') do
it { should_not exist }
end
### Test the Region Endpoint
describe aws_region(region_name: 'eu-west-2') do
its('endpoint') { should eq 'ec2.eu-west-2.amazonaws.com' }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
it { should exist }
## AWS Permissions
Your [Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html#intro-structure-principal) will need the `ec2:DescribeRegions` 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).

79
docs-chef-io/content/inspec/resources/aws_regions.md
View file

@ -1,79 +0,0 @@
+++
title = "aws_regions resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_regions"
identifier = "inspec/resources/aws/aws_regions.md aws_regions resource"
parent = "inspec/resources/aws"
+++
Use the `aws_regions` InSpec audit resource to test properties of some or all AWS regions in bulk.
Note that this resource lists all AWS regions that are currently available to the caller.
## Syntax
An `aws_regions` resource block uses an optional filter to select a group of regions and then tests that group.
describe aws_regions.where { region_name: 'us-not-there-1' } do
it { should_not exist }
end
## Parameters
### name _(required)_
This resource does not expect any parameters.
See also the [AWS documentation on Regions](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html).
## Properties
| Property | Description |
| ------------ | -------------------------------------- |
| region_names | The Names of the regions. |
| endpoints | The resolved endpoints of the regions. |
## Examples
The following examples show how to use this InSpec audit resource.
### Check for a Particular Region
describe aws_regions do
its('region_names') { should include 'eu-west-2' }
end
### Check an endpoint exists
describe aws_regions do
its('endpoints') { should include 'ec2.eu-west-2.amazonaws.com' }
end
### Use the regions resource to check single regions in more detail
aws_regions.region_names.each do |aws_region_name|
describe aws_region(region_name: aws_region_name) do
it { should exist }
end
end
## Matchers
For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
it { should exist }
## 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).

103
docs-chef-io/content/inspec/resources/aws_route_table.md
View file

@ -1,103 +0,0 @@
+++
title = "aws_route_table resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_route_table"
identifier = "inspec/resources/aws/aws_route_table.md aws_route_table resource"
parent = "inspec/resources/aws"
+++
Use the `aws_route_table` 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.
## Syntax
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
describe aws_route_table(route_table_id: 'rtb-123abcde') do
it { should exist }
end
## Parameters
### route_table_id _(required)_
This resource accepts a single parameter, the route_table_id.
This can be passed either as a string or as a `route_table_id: 'value'` key-value entry in a hash.
See also the [AWS documentation on Route Tables](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Route_Tables.html).
## Properties
| Property | Description |
| ---------------- | ----------------------------------------------------------------- |
| route_table_id | The ID of the route table. |
| owner_id | The ID of the AWS account that owns the route table. |
| vpc_id | The ID of the VPC. |
| routes | The routes in the route table. |
| associations | The associations between the route table and one or more subnets. |
| propagating_vgws | Any virtual private gateway (VGW) propagating routes. |
| tags | Any tags assigned to the route table. |
## Examples
### Confirm that the route table has expected VPC identifier
describe aws_route_table(route_table_id: 'rtb-123abcde') do
its('vpc_id') { should eq 'vpc-01625e36123456789' }
end
### Confirm that the route table has expected owner identifier
describe aws_route_table(route_table_id: 'rtb-123abcde') do
its('owner_id') { should eq '123456789012' }
end
### Ensure the expected number of routes is present
describe aws_route_table(route_table_id: 'rtb-123abcde') do
its('routes.count') { should eq 2 }
end
### Ensure the expected number of associations is present
describe aws_route_table(route_table_id: 'rtb-123abcde') do
its('associations.count') { should eq 1 }
end
### Ensure there are no virtual private gateway (VGW) propagating routes
describe aws_route_table(route_table_id: 'rtb-123abcde') do
its('propagating_vgws') { should be_empty }
end
## Matchers
For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity 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).

68
docs-chef-io/content/inspec/resources/aws_route_tables.md
View file

@ -1,68 +0,0 @@
+++
title = "aws_route_tables resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_route_tables"
identifier = "inspec/resources/aws/aws_route_tables.md aws_route_tables"
parent = "inspec/resources/aws"
+++
Use the `aws_route_tables` 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.
## Syntax
Ensure that there is at least one route table
describe aws_route_tables do
it { should exist }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on Route Tables](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Route_Tables.html).
## Properties
| Property | Description |
| --------------- | -------------------------------------------------------------------------------------------- |
| route_table_ids | The route table IDs |
| vpc_ids | The VPC IDs |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
### Confirm that a route table exists
describe aws_route_tables do
its('vpc_ids') { should include 'vpc-01625e36123456789' }
end
### Confirm a Route Table exists.
describe aws_route_tables do
its('route_table_ids') { should include 'rtb-12345678' }
end
## Matchers
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
it { should exist }
it { should_not exist }
## 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-chef-io/content/inspec/resources/aws_s3_bucket.md
View file

@ -1,156 +0,0 @@
+++
title = "aws_s3_bucket resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_s3_bucket"
identifier = "inspec/resources/aws/aws_s3_bucket.md aws_s3_bucket resource"
parent = "inspec/resources/aws"
+++
Use the `aws_s3_bucket` InSpec audit resource to test properties of a single AWS bucket.
## 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
## Parameters
### bucket_name _(required)_
This resource accepts a single parameter, the S3 Bucket Name which uniquely identifies the bucket.
This can be passed either as a string or as a `bucket_name: 'value'` key-value entry in a hash.
See also the [AWS documentation on S3 Buckets](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html).
## Properties
| Property | Description |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| region | The region of the bucket. Region is overridden based on the location returned from S3 |
| bucket_acl | An array of AWS Grants detailing permission grants on the bucket. |
| bucket_policy | The IAM policy document controlling access to the bucket. |
| bucket_lifecycle_rules | The lifecycle policy rules that define actions S3 will take for all objects (or a subset of objects) in their lifetime. |
| tags | An hash with each key-value pair corresponding to a tag associated with the entity |
## Examples
### 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
describe aws_s3_bucket('test_bucket') do
it { should_not be_public }
end
### Check if the correct region is set
describe aws_s3_bucket('test_bucket') do
its('region') { should eq 'us-east-1' }
end
### Check bucket's ACL for correct grants
bucket_acl = aws_s3_bucket('my-bucket').bucket_acl
# 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
### Test all buckets
aws_s3_buckets.bucket_names.each do |bucket_name|
describe aws_s3_bucket(bucket_name) do
it { should have_default_encryption_enabled }
end
end
### Test buckets in a specific region
aws_s3_buckets.bucket_names.each do |bucket_name|
if aws_s3_bucket(bucket_name: bucket_name).region == region
describe aws_s3_bucket(bucket_name) do
it { should have_default_encryption_enabled }
end
end
end
### Check if a bucket has a bucket policy that requires requests to use HTTPS
describe aws_s3_bucket('test_bucket') do
it { should have_secure_transport_enabled }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/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 }
### have_versioning_enabled
The `have_versioning_enabled` matcher tests if versioning is enabled for the s3 bucket.
it { should have_versioning_enabled }
### have_secure_transport_enabled
The `have_secure_transport_enabled` matcher tests if a bucket policy that explicitly denies requests via HTTP is enabled for the s3 bucket.
it { should have_secure_transport_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).

100
docs-chef-io/content/inspec/resources/aws_s3_bucket_object.md
View file

@ -1,100 +0,0 @@
+++
title = "aws_s3_bucket_object resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_s3_bucket_object"
identifier = "inspec/resources/aws/aws_s3_bucket_object.md aws_s3_bucket_object resource"
parent = "inspec/resources/aws"
+++
Use the `aws_s3_bucket_object` 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.
## 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
## Parameters
### bucket_name _(required)_
The S3 Bucket Name which uniquely identifies the bucket.
This must be passed as a `bucket_name: 'value'` key-value entry in a hash.
### key _(required)_
The S3 Bucket Key which uniquely identifies the bucket object.
This must be passed as a `key: 'value'` key-value entry in a hash.
See also the [AWS documentation on S3 Buckets](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html).
## Properties
| Property | Description |
| -------------- | ------------------------------------------------------------------------ |
| bucket_name | The name of the bucket. |
| key | The key within the bucket. |
| content_length | Size of the body in bytes. |
| content_type | A standard MIME type describing the format of the object data. |
| object_acl | An array of AWS Grants detailing permission grants on the bucket object. |
There are also additional properties available. For a comprehensive list, see [the API reference documentation](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html).
## Examples
### Test an 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
### Test an object's size in bytes is less than `100000`
describe aws_s3_bucket_object(bucket_name: 'test_bucket', key: 'test_key') do
its('content_length') { should be < 1_000_000 }
end
### Test an object's type is "image/jpeg"
describe aws_s3_bucket_object(bucket_name: 'test_bucket', key: 'test_key') do
its('content_type') { should eq "image/jpeg" }
end
### Check to see if a object appears to be exposed to the public
describe aws_s3_bucket_object(bucket_name: 'test_bucket', key: 'test_key') do
it { should_not be_public }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers (such as `exist`) please visit our [matchers page](/inspec/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
1. A object ACL grant exists for the 'AuthenticatedUsers' group
{{< note >}}
This resource does not detect insecure bucket ACLs.
{{< /note >}}
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).

70
docs-chef-io/content/inspec/resources/aws_s3_buckets.md
View file

@ -1,70 +0,0 @@
+++
title = "aws_s3_buckets resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_s3_buckets"
identifier = "inspec/resources/aws/aws_s3_buckets.md aws_s3_buckets"
parent = "inspec/resources/aws"
+++
Use the `aws_s3_buckets` InSpec audit resource to list all buckets in a single account.
## Syntax
An `aws_s3_buckets` resource block takes no arguments
describe aws_s3_buckets do
it { should exist }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on S3 Buckets](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html).
## Properties
| Property | Description |
| ------------ | -------------------------------------------------------------------------------------------- |
| bucket_names | An Array of bucket names. |
| tags | An hash with each key-value pair corresponding to a tag associated with the entity |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
### 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
### Check the tags on buckets
describe aws_s3_buckets.where( bucket_names: 'my-bucket' ) do
its('tags') { should include(:Environment => 'env-name',
:Name => 'bucket-name')}
end
## 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
## 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).

238
docs-chef-io/content/inspec/resources/aws_security_group.md
View file

@ -1,238 +0,0 @@
+++
title = "aws_security_group resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_security_group"
identifier = "inspec/resources/aws/aws_security_group.md aws_security_group"
parent = "inspec/resources/aws"
+++
Use the `aws_security_group` 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').
## Syntax
describe aws_security_group('sg-12345678') do
it { should exist }
end
# May also use hash syntax
describe aws_security_group(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
## Parameters
You must provide at least one parameter; `group_id`, `group_name` or `vpc_id`
### group_id _(required if no other parameter provided)_
The Security Group ID which uniquely identifies the SG.
This can be passed either as a string or as a `group_id: 'value'` key-value entry in a hash.
### group_name _(required if no other parameter provided)_
The Security Group name.
This can be passed either as a string or as a `group_name: 'value'` key-value entry in a hash.
### vpc_id _(required if no other parameter provided)_
The ID of the VPC associated with the SG.
This can be passed either as a string or as a `vpc_id: 'value'` key-value entry in a hash.
See also the [AWS documentation on Security Groups](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html).
## Properties
| Property | Description |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| description | A String reflecting the human-meaningful description that was given to the SG at creation time. |
| group_id | Provides the Security Group ID. |
| group_name | A String reflecting the name that was given to the SG at creation time. |
| inbound_rules | A list of the rules that the Security Group applies to incoming network traffic. |
| 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. |
| 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. |
| 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. |
| vpc_id | A String in the format `vpc-` followed by 8 hexadecimal characters reflecting VPC that contains the Security Group. |
| tags | The tags of the security group. |
## Examples
### Test outbound rules
describe aws_security_group(group_name: isolated_servers) do
its('outbound_rules.last') { should_not include(ip_ranges:['0.0.0.0/0']) }
end
### Test a rule that allows All Traffic
describe aws_security_group(group_name: my_group) do
it { should allow_in(ipv4_range: ["10.1.2.0/24", "10.3.2.0/24"], protocol: 'all') }
end
### Ensure a SG only allows SSH from a specific range
describe aws_security_group(group_name: linux_servers) do
it { should allow_in(port: 22, ipv4_range: '10.5.0.0/16') }
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
## Matchers
This InSpec audit resource has the following special matchers. For a full list of additional available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### allow
The `allow` series of matchers includes:
- 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.
### Matchers search criteria
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.
```ruby
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.
```ruby
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
```
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
it { should exist }
it { should_not exist }
## 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).

83
docs-chef-io/content/inspec/resources/aws_security_groups.md
View file

@ -1,83 +0,0 @@
+++
title = "aws_security_groups resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_security_groups"
identifier = "inspec/resources/aws/aws_security_groups.md aws_security_groups resource"
parent = "inspec/resources/aws"
+++
Use the `aws_security_groups` 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.
## Syntax
An `aws_security_groups` resource block uses an optional filter to select a group of security groups and then tests that group.
describe aws_security_groups do
its('entries.count') { should be > 1 }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on Security Groups](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html).
## Properties
| Property | Description |
| ----------- | -------------------------------------------------------------------------------------------- |
| group_ids | The name of the auto scaling launch configuration associated with the auto scaling group |
| group_names | An integer indicating the maximum number of instances in the auto scaling group |
| vpc_ids | An integer indicating the desired number of instances in the auto scaling group |
| tags | An integer indicating the minimum number of instances in the auto scaling group |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
The following examples show how to use this InSpec audit resource.
### 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
### Examine the default security group in all VPCs
describe aws_security_groups.where( group_name: 'default') do
it { should exist }
end
### Allow at most 100 security groups on the account
describe aws_security_groups do
its('entries.count') { should be <= 100}
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
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).

103
docs-chef-io/content/inspec/resources/aws_sns_subscription.md
View file

@ -1,103 +0,0 @@
+++
title = "aws_sns_subscription resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_sns_subscription"
identifier = "inspec/resources/aws/aws_sns_subscription.md aws_sns_subscription"
parent = "inspec/resources/aws"
+++
Use the `aws_sns_subscription` InSpec audit resource to test detailed properties of a AWS SNS Subscription.
## 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
## Parameters
### subscription_arn _(required)_
This resource accepts a single parameter, the subscription_arn.
This can be passed either as a string or as a `subscription_arn: 'value'` key-value entry in a hash.
See also the [AWS documentation on SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-getting-started.html).
## Properties
| Property | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------ |
| arn | An integer indicating the minimum number of instances in the auto scaling group |
| owner | An integer indicating the maximum number of instances in the auto scaling group |
| raw_message_delivery | An integer indicating the desired number of instances in the auto scaling group |
| topic_arn | The name of the auto scaling launch configuration associated with the auto scaling group |
| protocol | An array of strings corresponding to the subnet IDs associated with the auto scaling group |
| confirmation_was_authenticated | An hash with each key-value pair corresponding to a tag associated with the entity |
## Examples
### 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 protocol 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
### 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
### 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
## Matchers
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
it { should exist }
it { should_not exist }
### 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
## 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).

72
docs-chef-io/content/inspec/resources/aws_sns_topic.md
View file

@ -1,72 +0,0 @@
+++
title = "aws_sns_topic resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_sns_topic"
identifier = "inspec/resources/aws/aws_sns_topic.md aws_sns_topic"
parent = "inspec/resources/aws"
+++
Use the `aws_sns_topic` 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 occur.
## Syntax
describe aws_sns_topic('arn:aws:sns:*::my-topic-name') do
it { should exist }
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
## Parameters
### arn _(required)_
This resource accepts a single parameter, the ARN of the SNS Topic.
This can be passed either as a string or as a `arn: 'value'` key-value entry in a hash.
See also the [AWS documentation on SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-getting-started.html).
## Properties
| Property | Description |
| ---------------------------- | ------------------------------------------------------------------- |
| confirmed_subscription_count | An integer indicating the number of currently active subscriptions. |
## Examples
### Make sure something is subscribed to the topic
describe aws_sns_topic('arn:aws:sns:*::my-topic-name') do
its('confirmed_subscription_count') { should_not be_zero}
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_sns_topic('arn:aws:sns:*::good-news') do
it { should exist }
end
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-chef-io/content/inspec/resources/aws_sns_topics.md
View file

@ -1,68 +0,0 @@
+++
title = "aws_sns_topics resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_sns_topics"
identifier = "inspec/resources/aws/aws_sns_topics.md aws_sns_topics"
parent = "inspec/resources/aws"
+++
Use the `aws_sns_topics` InSpec audit resource to test all or a group of the SNS Topic ARNs in an account.
User the 'aws_sns_topic' InSpec audit resource to test a single SNS Topic in an account.
## Syntax
# Get all SNS Topic arns
describe aws_sns_topics do
its('topic_arns') { should include 'arn:aws:sns:us-east-1:333344445555:MyTopic' }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-getting-started.html).
## Properties
| Property | Description |
| ---------- | -------------------------------------------------------------------------------------------- |
| topic_arns | The ARNs of the SNS Topics. |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
The following examples show how to use this InSpec audit resource.
### Ensure a Topic exists
describe aws_sns_topics do
its('topic_arns') { should include 'arn:aws:sns:us-east-1:333344445555:MyTopic' }
end
## Matchers
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_sns_topics do
it { should exist }
end
describe aws_sns_topics 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: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).

99
docs-chef-io/content/inspec/resources/aws_sqs_queue.md
View file

@ -1,99 +0,0 @@
+++
title = "aws_sqs_queue resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_sqs_queue"
identifier = "inspec/resources/aws/aws_sqs_queue.md aws_sqs_queue"
parent = "inspec/resources/aws"
+++
Use the `aws_sqs_queue` InSpec audit resource to test properties of a single AWS Simple Queue Service queue.
## Syntax
describe aws_sqs_queue(queue_url: 'https://sqs.ap-southeast-2.amazonaws.com/1212121/MyQueue') do
it { should exist }
end
## Parameters
### queue_url _(required)_
This resource accepts a single parameter, the SQS Queue URL.
This can be passed either as a string or as a `queue_url: 'value'` key-value entry in a hash.
See also the [AWS documentation on SQS](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/welcome.html).
## Properties
| Property | Description |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| arn | The ARN of the SQS Queue. |
| is_fifo_queue | A boolean value indicating if this queue is a FIFO queue |
| visibility_timeout | An integer indicating the visibility timeout of the message in seconds |
| maximum_message_size | An integer indicating the maximum message size in bytes |
| message_retention_period | An integer indicating the maximum retention period for a message in seconds |
| delay_seconds | An integer indicating the delay in seconds for the queue |
| receive_message_wait_timeout_seconds | An integer indicating the number of seconds an attempt to receive a message will wait before returning |
| content_based_deduplication | A boolean value indicating if content based dedcuplication is enabled or not |
| redrive_policy | A string indicating the redrive policy |
## Examples
### 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
### Ensure maximum message size is set
describe aws_sqs_queue('https://sqs.ap-southeast-2.amazonaws.com/1212121/MyQueue') do
its('maximum_message_size') { should be 262144 } # 256 KB
end
### Test the delay time
describe aws_sqs_queue('https://sqs.ap-southeast-2.amazonaws.com/1212121/MyQueue') do
its('delay_seconds') { should be 0 }
end
### Ensure messages are retained for 4 days
describe aws_sqs_queue('https://sqs.ap-southeast-2.amazonaws.com/1212121/MyQueue') do
its('message_retention_period') { should be 345600 } # 4 days
end
### Check if queue is fifo
describe aws_sqs_queue('https://sqs.ap-southeast-2.amazonaws.com/1212121/MyQueue') do
its('is_fifo_queue') { should be false }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_sqs_queue('https://sqs.ap-southeast-2.amazonaws.com/1212121/MyQueue') do
it { should exist }
end
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).

71
docs-chef-io/content/inspec/resources/aws_sqs_queues.md
View file

@ -1,71 +0,0 @@
+++
title = "aws_sqs_queues"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_sqs_queues"
identifier = "inspec/resources/aws/aws_sqs_queues.md aws_sqs_queues"
parent = "inspec/resources/aws"
+++
Use the `aws_sqs_queues` InSpec audit resource to test properties of some or all AWS Simple Queue Service queues.
## Syntax
describe aws_sqs_queues() do
it { should exist }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on SQS](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/welcome.html).
## Properties
| Property | Description |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| arns | The ARNs of the SQS Queues. |
| is_fifo_queues | A boolean value indicating if queues are FIFO queues |
| visibility_timeouts | An integer indicating the visibility timeout of the message in seconds |
| maximum_message_sizes | An integer indicating the maximum message size in bytes |
| message_retention_periods | An integer indicating the maximum retention period for a message in seconds |
| delay_seconds | An integer indicating the delay in seconds for the queues |
| receive_message_wait_timeout_seconds | An integer indicating the number of seconds an attempt to receive a message will wait before returning |
| content_based_deduplications | A boolean value indicating if content based deduplication is enabled or not |
## Examples
### Ensure that a queue exists and has a visibility timeout of 300 seconds
describe aws_sqs_queues.where(queue_url: 'https://sqs.ap-southeast-2.amazonaws.com/1212121/MyQueue') do
it { should exist }
its('visibility_timeout') { should be 300 }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_sqs_queues() do
it { should exist }
end
describe aws_sqs_queues() 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).

83
docs-chef-io/content/inspec/resources/aws_ssm_parameter.md
View file

@ -1,83 +0,0 @@
+++
title = "aws_ssm_parameter resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_ssm_parameter"
identifier = "inspec/resources/aws/aws_ssm_parameter.md aws_ssm_parameter resource"
parent = "inspec/resources/aws"
+++
Use the `aws_ssm_parameter` InSpec audit resource to test properties of a ssm parameter.
## Syntax
An `aws_ssm_parameter` resource block uses the parameter to select a ssm parameter.
describe aws_ssm_parameter(name: 'ssm-parameter-name-1234') do
it { should exist }
end
## Parameters
### name _(required)_
This resource accepts a single parameter, the SSM Parameter Name.
This can be passed either as a string or as a `aws_ssm_parameter: 'value'` key-value entry in a hash.
### with_decryption _(optional)_
This decrypts the value associated with the ssm parameter. This must be passed as a string `with_decryption: "true"`.
See also the [AWS documentation on SSM Parameters](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html).
## Properties
| Property | Description |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| arn | Provides the Amazon Resource Name (ARN) of the parameter. |
| data_type | Provides the data type of the parameter. |
| last_modified_date | Provides the date the parameter was last changed or updated and the parameter version was created. |
| name | Provides the name of the parameter. |
| selector | Provides the version number or label used to retrieve the parameter value. |
| source_result | Applies to parameters that reference information in other AWS services. |
| type | Provides the type of the parameter. |
| value | Provides the value of the parameter. |
| version | Provides the version of the parameter. |
For a comprehensive list of properties available, see [the API reference documentation](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_Parameter.html)
## Examples
### Check the Name of a SSM Parameter
describe aws_ssm_parameter(name: 'ssm_parameter-name-1234') do
its('name') { should eq 'ssm_parameter-name-1234' }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_ssm_parameter(name: 'ssm_parameter-name-1234') do
it { should exist }
end
describe aws_ssm_parameter(name: 'ssm_parameter-name-6789') 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 `ssm:GetParameter` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon Systems Manager](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awssystemsmanager.html).

75
docs-chef-io/content/inspec/resources/aws_ssm_parameters.md
View file

@ -1,75 +0,0 @@
+++
title = "aws_ssm_parameters resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_ssm_parameters"
identifier = "inspec/resources/aws/aws_ssm_parameters.md aws_ssm_parameters resource"
parent = "inspec/resources/aws"
+++
Use the `aws_ssm_parameters` InSpec audit resource to test properties of a collection of AWS SSM parameters.
## Syntax
Ensure you have exactly 3 SSM Parameters
describe aws_ssm_parameters do
its('names.count') { should cmp 3 }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on SSM](https://docs.aws.amazon.com/systems-manager/?id=docs_gateway).
## Properties
| Property | Description |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| names | Provides the name of the parameter. |
| types | Provides the type of the parameter. |
| key_ids | Provides the key id of the parameter. |
| last_modified_dates | Provides the date the parameter was last changed or updated and the parameter version was created. |
| last_modified_users | Provides the user that last changed or updated the parameter. |
| descriptions | Provides the description of the parameter. |
| versions | Provides the version of the parameter. |
| tiers | Provides the tier of the parameter. |
For a comprehensive list of properties available, see [the API reference documentation](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_Parameter.html)
## Examples
### Ensure Name of a SSM Parameter exists
describe aws_ssm_parameters do
its('names') { should include 'ssm-parameter-name' }
end
## Matchers
For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_ssm_parameters.where( <property>: <value> ) do
it { should exist }
end
describe aws_ssm_parameters.where( <property>: <value> ) 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 `ssm:DescribeParameters` action with Effect set to Allow.
You can find detailed documentation at [Actions, Resources, and Condition Keys for Amazon Systems Manager](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awssystemsmanager.html).

73
docs-chef-io/content/inspec/resources/aws_sts_caller_identity.md
View file

@ -1,73 +0,0 @@
+++
title = "aws_sts_caller_identity resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_sts_caller_identity"
identifier = "inspec/resources/aws/aws_sts_caller_identity.md aws_sts_caller_identity resource"
parent = "inspec/resources/aws"
+++
Use the `aws_sts_caller_identity` InSpec audit resource to test properties of AWS IAM identity whose credentials are used in the current InSpec scan.
## Syntax
An `aws_sts_caller_identity` resource block may be used to perform tests on details of the AWS credentials being used in the current InSpec scan. You can also test if the credentials belong to a GovCloud account or not.
describe aws_sts_caller_identity do
it { should exist }
end
## Parameters
### name _(required)_
This resource does not expect any parameters.
## Properties
| Property | Description |
| -------- | --------------------------- |
| arn | The ARN of the IAM Identity |
## Examples
### Check that the credentials used to run the scan is correct
describe aws_sts_caller_identity do
its("arn") { should match "arn:aws:iam::.*:user/service-account-inspec" }
end
### Test if the account belongs to GovCloud
describe aws_sts_caller_identity do
it { should be_govcloud }
end
### Skip a test if we are using GovCloud
if aws_sts_caller_identity.govcloud?
describe 'Skipping Root User MFA check as we are on GovCloud' do
skip
end
else
describe aws_iam_root_user do
it { should have_mfa_enabled }
end
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list
of available matchers, please visit our [matchers page](/inspec/matchers/).
### be_govcloud
The `be_govcloud` matcher tests if the account is a 'GovCloud' AWS Account.
describe aws_sts_caller_identity do
it { should_not be_govcloud }
end

117
docs-chef-io/content/inspec/resources/aws_subnet.md
View file

@ -1,117 +0,0 @@
+++
title = "aws_subnet resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_subnet"
identifier = "inspec/resources/aws/aws_subnet.md aws_subnet resource"
parent = "inspec/resources/aws"
+++
Use the `aws_subnet` InSpec audit resource to test properties of a vpc subnet.
## 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 }
end
## Parameters
### subnet_id _(required)_
This resource accepts a single parameter, the Subnet ID.
This can be passed either as a string or as a `subnet_id: 'value'` key-value entry in a hash.
See also the [AWS documentation on Subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html).
## Properties
| Property | Description |
| -------------------------- | -------------------------------------------------------------- |
| subnet_id | Provides the ID of the Subnet. |
| vpc_id | Provides the ID of the VPC the subnet is in. |
| availability_zone | Provides the Availability Zone of the subnet. |
| cidr_block | Provides the block of ip addresses specified to the subnet. |
| available_ip_address_count | Provides the number of available IPv4 addresses on the subnet. |
## Examples
### Check availability zone of a subnet
describe aws_subnet(subnet_id: 'subnet-12345678') do
its('availability_zone') { should eq 'us-east-1c' }
end
### Check the number of available IP addresses
describe aws_subnet(subnet_id: 'subnet-12345678') do
its('available_ip_address_count') { should eq 251 }
end
### Test 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
### Ensure the subnet is in the right VPC
describe aws_subnet(subnet_id: 'subnet-12345678') do
its('vpc_id') { should eq 'vpc-12345678' }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/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
### 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
### 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
## 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).

97
docs-chef-io/content/inspec/resources/aws_subnets.md
View file

@ -1,97 +0,0 @@
+++
title = "aws_subnets resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_subnets"
identifier = "inspec/resources/aws/aws_subnets.md aws_subnets resource"
parent = "inspec/resources/aws"
+++
Use the `aws_subnets` 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.
## 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
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on Subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html).
## Properties
| Property | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------- |
| subnet_ids | The name of the auto scaling launch configuration associated with the auto scaling group |
| vpc_ids | An integer indicating the maximum number of instances in the auto scaling group |
| cidr_blocks | An integer indicating the minimum number of instances in the auto scaling group |
| availability_zone | The availability zone this subnet is part of. |
| map_public_ip_on_launch | A boolean indicating if a public IP is automatically mapped to instances launched in this subnet. |
| states | An array of strings corresponding to the subnet IDs associated with the auto scaling group |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
### 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
### Examine a specific subnet
describe aws_subnets.where(subnet_id: 'subnet-12345678') do
its('cidr_blocks') { should eq ['10.0.1.0/24'] }
end
### Examine a specific vpcs Subnet IDs
describe aws_subnets.where( vpc_id: 'vpc-12345678') do
its('states') { should_not include 'pending' }
end
### Examine a specific subnets VPC IDS
describe aws_subnets.where( subnet_id: 'subnet-12345678') do
its('vpc_ids') { should include 'vpc-12345678' }
end
## Matchers
For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
## exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_subnets.where( <property>: <value>) do
it { should exist }
end
describe aws_subnets.where( <property>: <value>) 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: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).

69
docs-chef-io/content/inspec/resources/aws_transit_gateway.md
View file

@ -1,69 +0,0 @@
+++
title = "aws_transit_gateway resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_transit_gateway"
identifier = "inspec/resources/aws/aws_transit_gateway.md aws_transit_gateway resource"
parent = "inspec/resources/aws"
+++
Use the `aws_transit_gateway` InSpec audit resource to test properties of a transit gateway.
## Syntax
An `aws_transit_gateway` resource block uses the parameter to select a transit gateway.
describe aws_transit_gateway(transit_gateway_id: 'tgw-1234567') do
it { should exist }
end
## Parameters
### transit_gateway_id _(required)_
This resource accepts a single parameter, the Transit Gateway ID.
This can be passed either as a string or as a `transit_gateway_id: 'value'` key-value entry in a hash.
See also the [AWS documentation on Transit Gateways](https://docs.aws.amazon.com/vpc/latest/tgw/).
## Properties
| Property | Description |
| ---------------------------------- | ----------------------------------------------------------------------- |
| transit_gateway_id | Provides the ID of the Transit Gateway. |
| transit_gateway_arn | Provides the ARN of the Transit Gateway. |
| transit_gateway_owner_id | Provides the id of the owner of the Transit Gateway. |
| default_route_table_id | Provides the id of the default route table of the Transit Gateway. |
| propagation_default_route_table_id | Provides the propagation default route table id for the Transit gateway |
| dns_support | Provides the status of dns support for the Transit Gateway |
| vpn_ecmp_support | Provides the status of vpn ecmp support for the Transit Gateway |
## Examples
### Check the owner id zone of the Transit Gateway
describe aws_transit_gateway(transit_gateway_id: 'tgw-0e231ae7f5e5e7bd5') do
its('transit_gateway_owner_id') { should eq 'owner_id' }
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
### exist
The `exist` matcher indicates that a transit gateway exists.
describe aws_transit_gateway(transit_gateway_id: 'tgw-0e231ae7f5e5e7bd5') 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 `ec2:DescribeTransitGateways` 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).

108
docs-chef-io/content/inspec/resources/aws_vpc.md
View file

@ -1,108 +0,0 @@
+++
title = "aws_vpc resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_vpc"
identifier = "inspec/resources/aws/aws_vpc.md aws_vpc resource"
parent = "inspec/resources/aws"
+++
Use the `aws_vpc` InSpec audit resource to test properties of a single AWS Virtual Private Cloud (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.
## 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
## Parameters
If no parameter is provided, the subscription's default VPC will be returned.
### vpc_id _(optional)_
This resource accepts a single parameter, the VPC ID.
This can be passed either as a string or as a `vpc_id: 'value'` key-value entry in a hash.
See also the [AWS documentation on VPCs](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html).
## Properties
| Property | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| cidr_block | The IPv4 address range that is managed by the VPC. |
| 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). |
| instance_tenancy | The allowed tenancy of instances launched into the VPC. |
| state | The state of the VPC (`pending` | `available`). |
| vpc_id | The ID of the VPC. |
| tags | The tags of the VPC. |
## Examples
The following examples show how to use this InSpec audit resource.
### Test the CIDR of a named VPC
describe aws_vpc('vpc-87654321') do
its('cidr_block') { should cmp '10.0.0.0/16' }
end
### Test the state of the VPC
describe aws_vpc do
its ('state') { should eq 'available' }
# or equivalently
it { should be_available }
end
### Test the allowed tenancy of instances launched into the VPC
describe aws_vpc do
its ('instance_tenancy') { should eq 'default' }
end
### Test tags on the VPC
describe aws_vpc do
its('tags') { should include(:Environment => 'env-name',
:Name => 'vpc-name')}
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](/inspec/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).

102
docs-chef-io/content/inspec/resources/aws_vpcs.md
View file

@ -1,102 +0,0 @@
+++
title = "aws_vpcs resource"
draft = false
gh_repo = "inspec"
platform = "aws"
[menu]
[menu.inspec]
title = "aws_vpcs"
identifier = "inspec/resources/aws/aws_vpcs.md aws_vpcs resource"
parent = "inspec/resources/aws"
+++
Use the `aws_vpcs` InSpec audit resource to test properties of some or all AWS Virtual Private Clouds (VPCs).
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.
## Syntax
An `aws_vpcs` resource block uses an optional filter to select a group of VPCs and then tests that group.
# Since you always have at least one VPC, this will always pass.
describe aws_vpcs do
it { should exist }
end
## Parameters
This resource does not expect any parameters.
See also the [AWS documentation on VPCs](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html).
## Properties
| Property | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| cidr_blocks | The cidr_blocks property provides a list of the CIDR blocks that the matched VPCs serve as strings. |
| 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. |
| vpc_ids | The vpc_ids property provides a list of the IDs of the matched VPCs. |
| tags | A hash of key-value pairs corresponding to the tags associated with the entity. |
| entries | Provides access to the raw results of the query, which can be treated as an array of hashes. |
## Examples
### Ensure all VPCs use the same DHCP option set
describe aws_vpcs.where { dhcp_options_id != 'dopt-12345678' } do
it { should_not exist }
end
### 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
### We shun the 10.0.0.0/8 space
describe aws_vpcs.where { cidr_block.start_with?('10') } do
it { should_not exist }
end
### Check tags
describe aws_vpc do
its('tags') { should include(:Environment => 'env-name',
:Name => 'vpc-name')}
end
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [Universal Matchers page](/inspec/matchers/).
### exist
The control will pass if the describe returns at least one result.
Use `should_not` to test the entity should not exist.
describe aws_vpcs do
it { should exist }
end
describe aws_vpcs.where( <property>: <value>) 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: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).

1
docs-chef-io/content/inspec/resources/azure_generic_resource.md → docs-chef-io/content/inspec/resources/azure_generic_resource_core.md
View file

@ -1,5 +1,6 @@
+++
title = "azure_generic_resource resource"
title_append = "(inspec-core)"
draft = false
gh_repo = "inspec"
platform = "azure"

1
docs-chef-io/content/inspec/resources/azure_resource_group.md → docs-chef-io/content/inspec/resources/azure_resource_group_core.md
View file

@ -1,5 +1,6 @@
+++
title = "azure_resource_group resource"
title_append = "(inspec-core)"
draft = false
gh_repo = "inspec"
platform = "azure"

1
docs-chef-io/content/inspec/resources/azure_virtual_machine.md → docs-chef-io/content/inspec/resources/azure_virtual_machine_core.md
View file

@ -1,5 +1,6 @@
+++
title = "azure_virtual_machine resource"
title_append = "(inspec-core)"
draft = false
gh_repo = "inspec"
platform = "azure"

213
docs-chef-io/content/inspec/resources/habitat_package.md
View file

@ -1,213 +0,0 @@
+++
title = "habitat_package resource"
draft = false
gh_repo = "inspec"
platform = "habitat"
[menu]
[menu.inspec]
title = "habitat_package"
identifier = "inspec/resources/habitat/habitat_package.md habitat_package resource"
parent = "inspec/resources/habitat"
+++
Use the `habitat_package` InSpec audit resource to test properties of a single Habitat package.
## Availability
### Status: EXPERIMENTAL
This resource, like all of the inspec-habitat resource pack, is in the early stages of research and development. Functionality may be defective, incomplete, or be withdrawn in the future. If you are interested in helping this project mature, please join the conversation or contribute code at the [inspec-habitat project](https://github.com/inspec/inspec-habitat).
### Connecting to Habitat
To configure `inspec` to be able to communicate with Chef Habitat, be sure [to follow the instructions](https://github.com/inspec/inspec-habitat#configuring-inspec-to-reach-habitat) regarding configuring the connection options. This will prevent 'unsupported platform' errors.
## Examples
### Check for core/httpd package
```ruby
describe habitat_package(origin: 'core', name: 'httpd') do
it { should exist }
its('version') { should eq '2.4.35'}
its('release') { should eq '20190307151146'}
end
```
## Limitations
### API versus CLI access
Habitat exposes certain data via the CLI, and other data via the HTTP Gateway API.
This resource is **only** available using CLI credentials.
If you use the API interface without the CLI, instances of this resource will behave as if the sought-after package was not found.
### Behavior when not found
If the package is not found, then this resource behaves as follows:
- `it { should exist }` will be a failing test. Check this test if you are unsure if the resource will exist; it is guaranteed to be reliable in the future.
- `name`, `origin`, `version`, and `release` will continue to return their values as set in the resource parameters. This allows output messaging to refer to the missing package clearly.
- `identifier` will return as much information as it can assemble from `name`, `origin`, `version`, and `release`.
- All other single-value properties will return `nil`.
- All array- and hash-valued properties will return empty objects.
- All matchers will return `false`.
### Behavior when multiple packages match
A system can have multiple versions of the same-named package installed (or even multiple releases of the same version of the same named package). For this reason, if you under-specify the resource parameters, you may match with multiple packages. Under these conditions, this resource will throw an `ArgumentError` exception, and the resource test will be recorded as a failure.
To avoid this possibility, fully specify the resource parameters, including `version` and `release`.
To list all installed versions and releases of a named package, use the plural resource `habitat_packages`.
## Availability
### Installation
This resource is in the `inspec-habitat` resource pack. You can use the resource by setting an InSpec profile dependency on this resource pack. See [inspec-habitat instructions](https://github.com/inspec/inspec-habitat#installation)
### Version
This resource was first available in version 0.1.0 of the resource pack.
## Resource Parameters
Use [resource parameters](/inspec/glossary/#resource-parameter) to identify the particular package you wish to test.
`habitat_package` can accept a single resource parameter, a `String` package identifier; or it can accept a `Hash` of identifier components.
### As a single `String`
Using this approach, you pass the package identifier as a single `String`. It should consist of `<origin>/<name>/<version>/<release>`, though `version` and `release` are optional.
```ruby
describe habitat_package('core/httpd') do
it { should exist }
end
```
### Using individual identifier components as a `Hash`
This approach can make it easier to write resource tests that use InSpec inputs or Ruby variables.
#### origin
`String`. The name of the `origin` (distribution facility) that provides the package.
```ruby
# Most common origin is 'core', publicly distributed packages created by Chef
describe habitat_package(origin: 'core', name: 'httpd') do
it { should exist }
end
# Your company might run a private origin
describe habitat_package(origin: 'mycorp', name: 'secret-sauce') do
it { should exist }
end
```
#### name
`String`. The name (unique within the namespace of the origin) of the package. This may match more than one package; see [Behavior when multiple packages match](#behavior-when-multiple-packages-match).
```ruby
describe habitat_package(origin: 'core', name: 'httpd') do
it { should exist }
end
```
#### release
`String`, a 14-digit timestamp of the form 'YYYMMDDHHmmSS'. The release number of the package as determined by the packager of the software. If you provide this, you must also provide the version; with all four components, the match is guarenteed to be unique.
```ruby
describe habitat_package(origin: 'core', name: 'httpd', version: '2.3.5', release: '20190307151146') do
it { should exist }
end
```
#### version
`String`, typically of the form `1.2.3` but formats vary. The version of the package as determined by the author of the software. This may match more than one package, because multiple releases of the same version may be co-installed; see [Behavior when multiple packages match](#behavior-when-multiple-packages-match).
```ruby
describe habitat_package(origin: 'core', name: 'httpd', version: '2.3.5') do
it { should exist }
end
```
## Properties
Use [properties](/inspec/glossary/#property) to create tests that compare an expected value to the actual value.
### identifier
`String`. The origin, name, version (if known) and release (if known) concatenated with `/`, to create the package identifier.
```ruby
describe habitat_package(origin: 'core', name: 'httpd') do
its('identifier') { should eq 'core/httpd/2.4.35/20190307151146' }
end
```
### name
`String`. The name of the package, as passed in via the resource parameter. Always available, even if the resource was not found. See also [origin](#origin) and [version](#version).
```ruby
describe habitat_package(origin: 'core', name: 'httpd') do
its('name') { should cmp 'httpd' }
end
```
### origin
`String`. The origin name of the package, as passed in via the resource parameter. Always available, even if the resource was not found. See also [name](#name) and [version](#version).
```ruby
describe habitat_package(origin: 'core', name: 'httpd') do
its('origin') { should cmp 'core' }
end
```
### pkg_id
`String`. The full package identifier of the package, in the form `origin/name/version/release`. See also [name](#name) and [version](#version).
```ruby
describe habitat_package(origin: 'core', name: 'httpd') do
its('pkg_id') { should cmp 'core/httpd/2.4.35/20190307151146' }
end
```
### release
`String`. The release number of the package, as assigned by the packager. These values are always strings, but are 14-digit timestamps. See also [version](#version).
```ruby
describe habitat_package(origin: 'core', name: 'httpd') do
its('release') { should be >= '20190307151146' }
end
```
### version
`String`. The version of the package, as assigned by the maintainer of the package project. While many versions are of the 3-digit form, there is no set rule, and exceptions are common. See also [release](#release).
```ruby
describe habitat_package(origin: 'core', name: 'httpd') do
its('version') { should be >= '2.2' }
end
```
## Matchers
Use [matchers](/inspec/glossary/#matcher) to create tests that test a true or false question.
InSpec includes a number of [universal matchers](/inspec/matchers/). See below for matchers specific to this resource.
This resource does not provide any resource-specific matchers.

204
docs-chef-io/content/inspec/resources/habitat_packages.md
View file

@ -1,204 +0,0 @@
+++
title = "habitat_packages resource"
draft = false
gh_repo = "inspec"
platform = "habitat"
[menu]
[menu.inspec]
title = "habitat_packages"
identifier = "inspec/resources/habitat/habitat_packages.md habitat_packages resource"
parent = "inspec/resources/habitat"
+++
Use the `habitat_package` (singular) InSpec audit resource to perform in-depth auditing of a single package.
Use the `habitat_packages` (plural) InSpec audit resource to list Habitat packages, and perform bulk operations.
## Availability
### Status: EXPERIMENTAL
This resource, like all of the inspec-habitat resource pack, is in the early stages of research and development. Functionality may be defective, incomplete, or be withdrawn in the future. If you are interested in helping this project mature, please join the conversation or contribute code at the [inspec-habitat project](https://github.com/inspec/inspec-habitat).
### Connecting to Habitat
To configure `inspec` to be able to communicate with Chef Habitat, be sure [to follow the instructions](https://github.com/inspec/inspec-habitat#configuring-inspec-to-reach-habitat) regarding configuring the connection options. This will prevent 'unsupported platform' errors.
## Examples
### Ensure httpd and memcached are installed
```ruby
describe habitat_packages do
its('names') { should include 'httpd' }
its('names') { should include 'memcached' }
end
```
### Ensure all packages were updated since January 1, 2018
```ruby
describe habitat_packages.where { release <= '20180101000000' } do
it { should_not exist }
end
```
### Search for packages, then examine them in detail using `habitat_package`
```ruby
# Use the plural resource as a data lookup (not as a test)...
habitat_packages.where { origin != 'core' }.habitat_package_params.each do |params|
# ... then use the singular resource to do in-depth testing
describe habitat_package(params) do
# ...
end
end
```
## Limitations
### API versus CLI access
Habitat exposes certain data via the CLI, and other data via the HTTP Gateway API. This resource is not available via the API; you must provide CLI credentials to use the resource. See the [train-habitat](https://github.com/inspec/train-habitat) documentation for more details.
If you use this resource without the CLI, this resource will always return zero matches.
## Availability
### Installation
This resource is in the `inspec-habitat` resource pack. You can use this resource by setting an InSpec profile dependency on the resource pack. See [inspec-habitat instructions](https://github.com/inspec/inspec-habitat#installation).
### Version
This resource was first available in version 0.1.0 of the resource pack.
## Resource Parameters
[Resource parameters](/inspec/glossary/#resource-parameter) are arguments passed to the resource in the control code.
This resource does not accept resource parameters, which is typical for plural resources.
## Filter Criteria
[Filter criteria](/inspec/glossary/#filter-criteria) are used to select which packages you wish to examine. If no filter criteria are used, all packages are selected.
### name
String. The (unqualified) name of the package under consideration.
```ruby
# No packages named *ftp* permitted
describe habitat_packages.where(name: /ftp/) do
it { should_not exist }
end
```
### origin
String. The name of the origin that created the package under consideration.
```ruby
# Examine only packages released by Chef
describe habitat_packages.where(origin: 'bad-origin') do
it { should_not exist }
end
```
### release
String. A 14-digit timestamp, in the format `YYYYMMDDHHMmmSS`. The timestamp reflects the time at which the package backing the package was released. These strings are sortable and comparable.
```ruby
# Examine packages older than Jan 1 2018
describe habitat_packages.where { release < '20180101000000' } do
it { should_not exist }
end
# Examine packages older than 1 year
describe habitat_packages.where { Date.parse(release[0..7]) < Date.today - 365 } do
it { should_not exist }
end
# Another way
describe habitat_packages.where { release < (Date.today - 365).strftime('%Y%m%d000000') } do
it { should_not exist }
end
```
## Properties
Use [properties](/inspec/glossary/#property) to create tests that compare an expected value to the actual value.
### count
Number. The count of packages that matched the filter criteria.
```ruby
# Expect 12 total
describe habitat_packages do
its(count) { should cmp 12 }
end
```
### habitat_package_params
`Array` of `Hash`es. Returns a list of a set of options that can be passed directly to `habitat_package` (singular) to load an individual package for in-depth analysis.
```ruby
# Use the plural resource as a data lookup (not as a test)...
habitat_packages.where { origin != 'core' }.habitat_package_params.each do |params|
# ... then use the singular resource to do in-depth testing
describe habitat_package(params) do
its('release') { should_not be < '201904090000' }
end
end
```
### names
Array of strings. The unqualified name of the package, such as 'httpd'. This list is de-duplicated, though a name is almost always unique anyway.
```ruby
describe habitat_packages do
its('names') { should include 'httpd' }
its('names') { should include 'memcached' }
its('names') { should_not include 'telnetd' }
end
```
### origins
Array of strings. The names of the origins that created the matched packages.
This list is de-duplicated.
```ruby
# Only allow core and mycorp-packaged packages
describe habitat_packages do
its('origins') { should include 'core' }
its('origins') { should include 'mycorp' }
# Advanced usage - count an array-valued property
its('origins', 'count') { should cmp 2 }
end
```
### releases
Array of strings. Each string is a 14-digit timestamp, in the format `YYYYMMDDHHMmmSS`. The timestamp reflects the time at which the package backing the package was released. These strings are sortable and comparable. This list is de-duplicated.
```ruby
# We had a bad Monday
describe habitat_packages do
its('releases') { should_not include '20180325000000' }
end
```
## Matchers
Use [matchers](/inspec/glossary/#matcher) to create tests that test a true or false question.
InSpec includes a number of [universal matchers](/inspec/matchers/).
This resource does not define any resource-specific matchers.

237
docs-chef-io/content/inspec/resources/habitat_service.md
View file

@ -1,237 +0,0 @@
+++
title = "habitat_service resource"
draft = false
gh_repo = "inspec"
platform = "habitat"
[menu]
[menu.inspec]
title = "habitat_service"
identifier = "inspec/resources/habitat/habitat_service.md habitat_service resource"
parent = "inspec/resources/habitat"
+++
Use the `habitat_service` InSpec audit resource to test properties of a single Habitat service.
## Availability
### Status: EXPERIMENTAL
This resource, like all of the inspec-habitat resource pack, is in the early stages of research and development. Functionality may be defective, incomplete, or be withdrawn in the future. If you are interested in helping this project mature, please join the conversation or contribute code at the [inspec-habitat project](https://github.com/inspec/inspec-habitat).
### Connecting to Habitat
To configure `inspec` to be able to communicate with Chef Habitat, be sure [to follow the instructions](https://github.com/inspec/inspec-habitat#configuring-inspec-to-reach-habitat) regarding configuring the connection options. This will prevent 'unsupported platform' errors.
## Examples
### Check for core/httpd service
```ruby
describe habitat_service(origin: 'core', name: 'httpd') do
it { should exist }
its('version') { should eq '2.4.35'}
its('topology') { should eq 'standalone' }
its('update_strategy') { should eq 'none' }
end
```
## Limitations
### API versus CLI access
Habitat exposes certain data via the CLI, and other data via the HTTP Gateway API. To enjoy the full functionality of this resource, use a set of credentials that includes the API. Limited data is available by CLI. See the [train-habitat](https://github.com/inspec/train-habitat) documentation for more details.
If you use the CLI interface without the API, unavailable properties will behave as if the resource was not found (see below).
### Behavior when not found
If the service is not found, then this resource behaves as follows:
- `it { should exist }` will be a failing test. Check this test if you are unsure if the resource will exist; it is guaranteed to be reliable in the future.
- `name` and `origin` will continue to return their values as set in the resource parameters. This allows output messaging to refer to the missing service clearly.
- All other single-value properties will return nil.
- All array and hash-valued properties will return empty objects.
- All matchers will return false.
## Availability
### Installation
This resource is in the `inspec-habitat` resource pack. You can use the resource by setting an InSpec profile dependency on the resource pack. See [inspec-habitat instructions](https://github.com/inspec/inspec-habitat#installation)
### Version
This resource was first available in version 0.1.0 of the resource pack.
## Resource Parameters
Use [resource parameters](/inspec/glossary/#resource-parameter) to identify the particular service you wish to test.
### origin
Required string. The name of the `origin` (distribution facility) of the package that provides the service.
```ruby
# Most common origin is 'core', publicly distributed packages created by Chef
describe habitat_service(origin: 'core', name: 'httpd') do
it { should exist }
end
# Your company might run a private origin
describe habitat_service(origin: 'mycorp', name: 'secret-sauce') do
it { should exist }
end
```
### name
Required string. The name (unique within the namespace of the origin) of the package that provides the service.
```ruby
describe habitat_service(origin: 'core', name: 'httpd') do
it { should exist }
end
```
## Properties
Use [properties](/inspec/glossary/#property) to create tests that compare an expected value to the actual value.
### dependency_names
Array of strings. A list of the packages that this service depends on, in the form of `dep_origin/dep_name`. This property does not contain version information; see `dependency_ids` for that.
Requires API connection; not available via CLI.
```ruby
describe habitat_service(origin: 'core', name: 'httpd') do
its('dependency_names') { should include 'core/pcre' }
its('dependency_names') { should_not include 'core/nginx' }
end
```
### dependency_ids
Array of strings. A list of the packages that this service depends on, in the form of `dep_origin/dep_name/1.2.3/20190325123456`. This value may be difficult to compare, because the version identifier (`1.2.3`, the third component) may be formatted in any way the maintainer of the project chooses; they need not be of the form `1.2.3`.
Requires API connection; not available via CLI.
```ruby
describe habitat_service(origin: 'core', name: 'httpd') do
# Suppose this version was unwanted, for example
its('dependency_names') { should_not include 'core/pcre/8.42/20190115012526' }
end
```
### name
The name of the service, as passed in via the resource parameter. Always available, even if the resource was not found. See also [origin](#origin) and [version](#version).
```ruby
describe habitat_service(origin: 'core', name: 'httpd') do
its('name') { should cmp 'httpd' }
end
```
### origin
The origin name of the service, as passed in via the resource parameter. Always available, even if the resource was not found. See also [name](#name) and [version](#version).
```ruby
describe habitat_service(origin: 'core', name: 'httpd') do
its('origin') { should cmp 'core' }
end
```
### pkg_id
String. The full package identifier of the package that supports the service, in the form `origin/name/version/release`. See also [name](#name) and [version](#version).
```ruby
describe habitat_service(origin: 'core', name: 'httpd') do
its('pkg_id') { should cmp 'core/httpd/2.4.35/20190307151146' }
end
```
### release
String. The release number of the package that supports the service, as assigned by the packager. These values are always strings, but are 14-digit timestamps. See also [version](#version).
```ruby
describe habitat_service(origin: 'core', name: 'httpd') do
its('release') { should be >= '20190307151146' }
end
```
### version
The version of the package that supports the service, as assigned by the maintainer of the package project. While many versions are of the 3-digit form, there is no set rule, and exceptions are common. See also [release](#release).
```ruby
describe habitat_service(origin: 'core', name: 'httpd') do
its('version') { should be >= '2.2' }
end
```
## Matchers
Use [matchers](/inspec/glossary/#matcher) to create tests that test a true or false question.
InSpec includes a number of [universal matchers](/inspec/matchers/). See below for matchers specific to this resource.
### have_standalone_topology
This matcher returns `true` if the service is configured in a [`standalone`](https://www.habitat.sh/docs/using-habitat/#standalone) topology.
```ruby
describe habitat_service(origin: 'core', name: 'httpd') do
it { should have_standalone_topology }
end
```
### have_leader_follower_topology
This matcher returns `true` if the service is configured in a [`leader-follower`](https://www.habitat.sh/docs/using-habitat/#leader-follower-topology) topology.
```ruby
describe habitat_service(origin: 'core', name: 'httpd') do
it { should have_leader_follower_topology }
end
```
### be_updated_by_none
This matcher returns `true` if the update strategy for the service is [`none`](https://www.habitat.sh/docs/using-habitat/#none-strategy).
Requires API connection; not available via CLI.
```ruby
describe habitat_service(origin: 'core', name: 'postgresql') do
it { should be_updated_by_none }
end
```
### be_updated_by_rolling
This matcher returns `true` if the update strategy for the service is [`rolling`](https://www.habitat.sh/docs/using-habitat/#rolling-strategy).
Requires API connection; not available via CLI.
```ruby
describe habitat_service(origin: 'core', name: 'postgresql') do
it { should be_updated_by_rolling }
end
```
### be_updated_at_once
This matcher returns `true` if the update strategy for the service is [`at once`](https://www.habitat.sh/docs/using-habitat/#at-once-strategy).
Requires API connection; not available via CLI.
```ruby
describe habitat_service(origin: 'core', name: 'nginx') do
it { should be_updated_at_once }
end
```

295
docs-chef-io/content/inspec/resources/habitat_services.md
View file

@ -1,295 +0,0 @@
+++
title = "habitat_services resource"
draft = false
gh_repo = "inspec"
platform = "habitat"
[menu]
[menu.inspec]
title = "habitat_services"
identifier = "inspec/resources/habitat/habitat_services.md habitat_services resource"
parent = "inspec/resources/habitat"
+++
Use the `habitat_service` (singular) InSpec audit resource to perform in-depth auditing of a single service.
Use the `habitat_services` (plural) InSpec audit resource to list Habitat services, and perform bulk operations.
## Availability
### Status: EXPERIMENTAL
This resource, like all of the inspec-habitat resource pack, is in the early stages of research and development. Functionality may be defective, incomplete, or be withdrawn in the future. If you are interested in helping this project mature, please join the conversation or contribute code at the [inspec-habitat project](https://github.com/inspec/inspec-habitat).
### Connecting to Habitat
To configure `inspec` to be able to communicate with Chef Habitat, be sure [to follow the instructions](https://github.com/inspec/inspec-habitat#configuring-inspec-to-reach-habitat) regarding configuring the connection options. This will prevent 'unsupported platform' errors.
## Examples
### Ensure there are 2 services, with the expected names
```ruby
describe habitat_services do
its('count') { should cmp 2 }
its('names') { should include 'httpd' }
its('names') { should include 'memcached' }
end
```
### Ensure all running services were updated since January 1, 2018
```ruby
describe habitat_services.where { release <= '20180101000000' } do
it { should_not exist }
end
```
### Ensure gcc is not a dependency of any service
```ruby
# One way - list all services, insist none have a dependency on gcc
describe habitat_services do
its('dependency_names') { should_not include 'core/gcc' }
end
# Another way - list all services with a dependency on gcc, insist there are none
describe habitat_services.where { dependency_names.include?('core/gcc') } do
it { should_not exist }
end
```
### Search for services, then examine them in detail using `habitat_service`
```ruby
# Use the plural resource as a data lookup (not as a test)...
habitat_services.where { origin != 'core' }.habitat_service_params.each do |params|
# ... then use the singular resource to do in-depth testing
describe habitat_service(params) do
its('release') { should_not be_standalone }
end
end
```
## Limitations
### API versus CLI access
Habitat exposes certain data via the CLI, and other data via the HTTP Gateway API. To enjoy the full functionality of this resource, use a set of credentials that includes the API. Limited data is available by CLI. See the [train-habitat](https://github.com/inspec/train-habitat) documentation for more details.
If you use the CLI interface without the API, unavailable properties will return empty arrays or `nil`, and unavailable filter criteria will never match. See each property and filter criteria for details.
## Availability
### Installation
This resource is in the `inspec-habitat` resource pack. You can use the resource by setting an InSpec profile dependency on the resource pack. See [inspec-habitat instructions](https://github.com/inspec/inspec-habitat#installation).
### Version
This resource was first available in version 0.1.0 of the resource pack.
## Resource Parameters
[Resource parameters](/inspec/glossary/#resource-parameter) are arguments passed to the resource in the control code.
This resource does not accept resource parameters, which is typical for plural resources.
## Filter Criteria
[Filter criteria](/inspec/glossary/#filter-criteria) are used to select which services you wish to examine. If no filter criteria are used, all services are selected.
### dependency_names
An array of strings in the form `origin/name`. Each string is the qualified name of a dependency of a service that is being filtered.
Requires API connection; not available (never matches) via CLI.
```ruby
describe habitat_services.where { dependency_names.include?('core/gcc') } do
it { should_not exist }
end
```
### name
String. The (unqualified) name of the service under consideration.
```ruby
# No services named *ftp* permitted
describe habitat_services.where(name: /ftp/) do
it { should_not exist }
end
```
### origin
String. The name of the origin that created the package that backs the service under consideration.
```ruby
# Examine only services released by Chef
describe habitat_services.where(origin: 'chef') do
its('topologies') { should_not include 'standalone' }
end
```
### release
String. A 14-digit timestamp, in the format `YYYYMMDDHHMmmSS`. The timestamp reflects the time at which the package backing the service was released. These strings are sortable and comparable.
```ruby
# Examine packages older than Jan 1 2018
describe habitat_services.where { release < '20180101000000' } do
its('update_strategies' ) { should_not include 'none' }
end
# Examine packages older than 1 year
describe habitat_services.where { Date.parse(release[0..7]) < Date.today - 365 } do
its('update_strategies' ) { should_not include 'none' }
end
# Another way
describe habitat_services.where { release < (Date.today - 365).strftime('%Y%m%d000000') } do
its('update_strategies' ) { should_not include 'none' }
end
```
### topology
String reflecting the topology of the service. Values include `standalone` and `leader` (for leader-follower). See [the Habitat docs](https://www.habitat.sh/docs/using-habitat/#topologies) for implications of these values.
```ruby
# HA or the highway
describe habitat_services.where(topology: 'standalone') do
it { should_not exist }
end
```
### update_strategy
String reflecting how the software package backing the service should be updated. Values include `none`, `rolling`, and `at-once`. See [the Habitat docs](https://www.habitat.sh/docs/using-habitat/#using-updates) for implications of these values.
Requires API connection; not available (never matches) via CLI.
```ruby
# No YOLO
describe habitat_services.where(update_strategy: 'at-once') do
it { should_not exist }
end
```
## Properties
Use [properties](/inspec/glossary/#property) to create tests that compare an expected to value to the actual value.
### count
Number. The count of services that matched the filter criteria.
```ruby
# Expect 12 total
describe habitat_services do
its(count) { should cmp 12 }
end
describe habitat_services.where(update_strategy: 'at-once') do
it { should_not exist }
its(count) { should cmp 0 } # Same as `should_not exist`
end
```
### dependency_names
Array of strings in the form `origin/name`. Each string is the qualified name of a dependency of a service that was selected by the filter criteria. This list is de-duplicated.
Requires API connection; not available (always an empty array) via CLI.
```ruby
describe habitat_services do
its('dependency_names') { should_not include 'core/gcc' }
end
```
### habitat_service_params
Hash. Returns a set of options that can be passed directly to `habitat_service` (singular) to load an individual service for in-depth analysis.
```ruby
# Use the plural resource as a data lookup (not as a test)...
habitat_services.where { origin != 'core' }.habitat_service_params.each do |params|
# ... then use the singular resource to do in-depth testing
describe habitat_service(params) do
its('release') { should_not be_standalone }
end
end
```
### names
Array of strings. The unqualified name of the service, such as 'httpd'. This list is de-duplicated, though a name is almost always unique anyway.
```ruby
describe habitat_services do
its('names') { should include 'httpd' }
its('names') { should include 'memcached' }
its('names') { should_not include 'telnetd' }
end
```
### origins
Array of strings. The names of the origins that created the packages that backs the services that were matched.
This list is de-duplicated.
```ruby
# Only allow core and mycorp-packaged services
describe habitat_services do
its('origins') { should include 'core' }
its('origins') { should include 'mycorp' }
# Advanced usage - count an array-valued property
its('origins', 'count') { should cmp 2 }
end
```
### releases
Array of strings. Each string is a 14-digit timestamp, in the format `YYYYMMDDHHMmmSS`. The timestamp reflects the time at which the package backing the service was released. These strings are sortable and comparable. This list is de-duplicated.
```ruby
# We had a bad Monday
describe habitat_services do
its('releases') { should_not include '20180325000000' }
end
```
### topologies
Array of strings reflecting the topology of the matched services. Values include `standalone` and `leader` (for leader-follower). See [the Habitat docs](https://www.habitat.sh/docs/using-habitat/#topologies) for implications of these values. This list is de-duplicated.
```ruby
describe habitat_services do
its('topologies') { should_not include 'standalone' }
end
```
### update_strategies
Array of strings reflecting how the software package backing the services that matched the filter should be updated. Values include `none`, `rolling`, and `at-once`. See [the Habitat docs](https://www.habitat.sh/docs/using-habitat/#using-updates) for implications of these values. This list is de-duplicated.
Requires API connection; not available (never matches) via CLI.
```ruby
# No YOLO
describe habitat_services do
its('update_strategies') { should_not include 'at-once' }
end
```
## Matchers
Use [matchers](/inspec/glossary/#matcher) to create tests that test a true or false question.
InSpec includes a number of [universal matchers](/inspec/matchers/).
This resource does not define any resource-specific matchers.