aws_security_groups Resource

[edit on GitHub]

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.

For additional information, including details on parameters and properties, see the AWS documentation on Security Groups.

Installation

This resource is available in the Chef InSpec AWS resource pack.

See the Chef InSpec documentation on cloud platforms for information on configuring your AWS environment for InSpec and creating an InSpec profile that uses the InSpec AWS resource pack.

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 require any parameters.

Properties

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.

ip_permissions

A list of the rules that the Security Group applies to incoming network traffic.

ip_permissions_egress

A list of the rules that the Security Group applies to outgoing network traffic initiated by the AWS resource in the Security Group.

descriptions

Description for the rule, which can help to identify it later. A description can be up to 255 characters in length. Allowed characters are a-z, A-Z, 0-9, spaces, and ._-:/()#,@[]+=;{}!$*.

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

Pass entry resource data from security groups to the singular resource for testing.

Use the security_group_objects resource to pass resource data to the singular resource for testing. This method uses local in-memory caching for quicker execution of large sets of test cases.

aws_security_groups.entries.each do |entry|
    describe aws_security_group(resource_data: entry) do
        it { should exist }
        its('count') { should be >= 4 }
    end
end

Matchers

This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our matchers page.

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 will need the EC2:Client:DescribeSecurityGroupsResult action with Effect set to Allow.

You can find detailed documentation at Actions, Resources, and Condition Keys for Amazon EC2.