aws_security_group

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:

  • IPv6 ranges
  • References to other Security Groups
  • References to VPC peers or other AWS services (that is, no support for searches based on ‘prefix lists’).


Syntax

Resource parameters: groupid, groupname, id, vpc_id

An aws_security_group resource block uses resource parameters to search for and then test a Security Group. If no SGs match, no error is raised, but the exists matcher returns false, and all scalar properties are nil. List properties returned under these conditions are empty lists. If more than one SG matches (due to vague search parameters), an error is raised.

# Ensure you have a Security Group with a specific ID
# This is "safe" - SG IDs are unique within an account
describe aws_security_group('sg-12345678') do
  it { should exist }
end

# Ensure you have a Security Group with a specific ID
# This uses hash syntax
describe aws_security_group(id: 'sg-12345678') do
  it { should exist }
end

# Ensure you have a Security Group with a specific name.  Names are 
# unique within a VPC but not across VPCs.
# Using only Group returns an error if multiple SGs match.
describe aws_security_group(group_name: 'my-group') do
  it { should exist }
end
# Add vpc_id to ensure uniqueness. 
describe aws_security_group(group_name: 'my-group', vpc_id: 'vpc-12345678') do
  it { should exist }
end


Examples

The following examples show how to use this InSpec audit resource.

# Ensure that the linux_servers Security Group permits 
# SSH from the 10.5.0.0/16 range, but not the world.
describe aws_security_group(group_name: linux_servers) do
  # This passes if any inbound rule exists that specifies 
  # port 22 and the given IP range, regardless of protocol, etc.
  it { should allow_in(port: 22, ipv4_range: '10.5.0.0/16') }

  # This passes so long as no inbound rule that specifies port 22 exists
  # with a source IP range of 0.0.0.0/0.  Other properties are ignored. 
  it { should_not allow_in(port: 22, ipv4_range: '0.0.0.0/0') }

end

# Ensure that the careful_updates Security Group may only initiate contact with specific IPs.
describe aws_security_group(group_name: 'careful_updates') do

  # If you have two rules, with one CIDR each: 
  [ '10.7.23.12/32', '10.8.23.12/32' ].each do |allowed_destination|
    # This doesn't care about which ports are enabled
    it { should allow_out(ipv4_range: allowed_destination) }
  end

  # If you have one rule with two CIDRs: 
  it { should allow_out(ipv4_range: [ '10.7.23.12/32', '10.8.23.12/32' ] }

  # Expect exactly three rules.
  its('outbound_rules.count') { should cmp 3 }
end


Resource Parameters

This InSpec resource accepts the following parameters, which are used to search for the Security Group.

id, group_id

The Security Group ID of the Security Group. This is of the format sg- followed by 8 hexadecimal characters. The ID is unique within your AWS account; using ID ensures a match of only one SG. The ID is also the default resource parameter, so you may omit the hash syntax.

# Using Hash syntax
describe aws_security_group(id: 'sg-12345678') do
  it { should exist }
end

# group_id is an alias for id
describe aws_security_group(group_id: 'sg-12345678') do
  it { should exist }
end

# Or omit hash syntax, rely on it being the default parameter
describe aws_security_group('sg-12345678') do
  it { should exist }
end

group_name

The string name of the Security Group. Every VPC has a Security Group named ‘default’. Names are unique within a VPC, but not within an AWS account.

# Get default Security Group for a specific VPC
describe aws_security_group(group_name: 'default', vpc_id: vpc_id: 'vpc-12345678') do
  it { should exist }
end

# This throws an error if more than one VPC has a 'backend' SG.
describe aws_security_group(group_name: 'backend') do
  it { should exist }
end

vpc_id

A string identifying the VPC that contains the Security Group. Since VPCs commonly contain many SGs, you should add additional parameters to ensure you find exactly one SG.

# This throws an error if more than the default SG exists
describe aws_security_group(vpc_id: 'vpc-12345678') do
  it { should exist }
end


Properties


Property Examples

description

A String reflecting the human-meaningful description that was given to the SG at creation time.

# Require a description of a particular Security Group
describe aws_security_group('sg-12345678') do
  its('description') { should_not be_empty }
end

group_id

Provides the Security Group ID.

# Inspect the Security group ID of the default Group
describe aws_security_group(group_name: 'default', vpc_id: vpc_id: 'vpc-12345678') do
  its('group_id') { should cmp 'sg-12345678' }
end

# Store the Group ID in a Ruby variable for use elsewhere
sg_id = aws_security_group(group_name: 'default', vpc_id: vpc_id: 'vpc-12345678').group_id

group_name

A String reflecting the name that was given to the SG at creation time.

# Inspect the Group name of a particular Group
describe aws_security_group('sg-12345678') do
  its('group_name') { should cmp 'my_group' }
end

inbound_rules

A list of the rules that the Security Group applies to incoming network traffic. This is a low-level property that is used by the allow_in and allow_in_only matchers; see them for detailed examples. inbound_rules is provided here for those wishing to use Ruby code to inspect the rules directly, instead of using higher-level matchers.

Order is critical in these rules, as the sequentially first rule to match is applied to network traffic. By default, AWS includes a reject-all rule as the last inbound rule. This implicit rule does not appear in the inbound_rules list.

If the Security Group could not be found (that is, exists is false), inbound_rules returns an empty list.

describe aws_security_group(group_name: linux_servers) do
  its('inbound_rules.first') { should include(from_port: '22', ip_ranges: ['10.2.17.0/24']) }
end

outbound_rules

A list of the rules that the Security Group applies to outgoing network traffic initiated by the AWS resource in the Security Group. This is a low-level property that is used by the allow_out matcher; see it for detailed examples. outbound_rules is provided here for those wishing to use Ruby code to inspect the rules directly, instead of using higher-level matchers.

Order is critical in these rules, as the sequentially first rule to match is applied to network traffic. Outbound rules are typically used when it is desirable to restrict which portions of the internet, if any, a resource may access. By default, AWS includes an allow-all rule as the last outbound rule; note that Terraform removes this implicit rule.

If the Security Group could not be found (that is, exists is false), outbound_rules returns an empty list.

describe aws_security_group(group_name: isolated_servers) do
  its('outbound_rules.last') { should_not include(ip_ranges:['0.0.0.0/0']) }
end

vpc_id

A String in the format ‘vpc-’ followed by 8 hexadecimal characters reflecting VPC that contains the Security Group.

# Inspec the VPC ID of a particular Group
describe aws_security_group('sg-12345678') do
  its('vpc_id') { should cmp 'vpc-12345678' }
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.

allow_in

allow_out

allow_in_only

allow_out_only

The allow series of matchers enable you to perform queries about what network traffic would be permitted through the Security Group rule set.

allow_in and allow_in_exactly examine inbound rules, and allow_out and allow_out_exactly examine outbound rules.

allow_in and allow_out examine if at least one rule that matches the criteria exists. allow_in and allow_out also perform inexact (ie, range-based or subset-based) matching on ports and IP addresses ranges, allowing you to specify a candidate port or IP address and determine if it is covered by a rule.

allow_in_only and allow_out_only examines if exactly one rule exists (but see position, below), and if it matches the criteria (this is useful for ensuring no unexpected rules have been added). Additionally, allow_in_only and allow_out_only do not perform inexact matching; you must specify exactly the port range or IP address(es) you wish to match.

The matchers accept a key-value list of search criteria. For a rule to match, it must match all provided criteria.

  • fromport - 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.
  • ipv4range - Specifies an IPv4 address or subnet as a CIDR, or a list of them, to be checked as a permissible origin (for `allowin) or destination (forallow_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. allowin and allowout 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.
  • toport - 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.

    describe awssecuritygroup(groupname: ‘mixed-functionality-group’) do # Allow RDP from defined range it { should allowin(port: 3389, ipv4_range: ‘10.5.0.0/16’) }

    # Allow SSH from two ranges it { should allowin(port: 22, ipv4range: [‘10.5.0.0/16’, ‘10.2.3.0/24’]) }

    # Check Bacula port range it { should allowin(fromport: 9101, toport: 9103, ipv4range: ‘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 allowin(ipv4range: ‘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 { shouldnot allowin(ipv4_range: ‘0.0.0.0/0’) } end

    Suppose you have a Group that should allow SSH and RDP from

    the admin network, 10.5.0.0/16. The resource has 2 rules to

    allow this, and you want to ensure no others have been added.

    describe awssecuritygroup(groupname: ‘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 allowinonly(port: 3389, ipv4range: ‘10.5.0.0/16’, position: 1) }

    # Specify position 2 for the SSH rule. Without position, # allowinonly only allows one rule, total. it { should allowinonly(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 allowinonly(port: 3389, ipv4range: ‘10.5.1.34/32’, position: 1) } end

exists

The control passes if the specified Security Group was found. Use should_not if you want to verify that the specified SG does not exist.

# You always have at least one SG, the VPC default SG
describe aws_security_group(group_name: 'default')
  it { should exist }
end

# Make sure we don't have any Security Groups with the name 'nogood'
describe aws_security_group(group_name: 'nogood')
  it { should_not exist }
end