Amazon Elastic Compute Cloud
API Reference (API Version 2013-02-01)
AWS Documentation » Amazon EC2 » API Reference » Actions » DescribeSecurityGroups
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

DescribeSecurityGroups

Description

A security group is for use with instances either in the EC2-Classic platform or in a specific VPC. For more information, see Amazon EC2 Security Groups in the Amazon Elastic Compute Cloud User Guide and Security Groups for Your VPC in the Amazon Virtual Private Cloud User Guide.

Request Parameters

GroupName.n

One or more security group names.

Type: String

Default: Describes all your security groups, or only those otherwise specified.

Condition: For EC2-Classic, default VPC, you can specify either GroupName or GroupId

Required: No

GroupId.n

One or more security group IDs.

Type: String

Default: Describes all your security groups, or only those otherwise specified.

Condition: Required for a EC2-VPC; for EC2-Classic, default VPC, you can specify either GroupName or GroupId

Required: No

Filter.n.Name

The name of a filter. See the Supported Filters section for a list of supported filter names.

Type: String

Default: None

Required: No

Filter.n.Value.m

A value for the filter. See the Supported Filters section for a list of supported values for each filter.

Type: String

Default: None

Required: No

Supported Filters

You can specify filters so that the response includes information for only certain security groups. For example, you can use a filter to specify that you're interested in groups whose name contains a specific string. You can specify multiple values for a filter. The response includes information for a security group only if it matches at least one of the filter values that you specified.

You can specify multiple filters; for example, specify group's whose name contains a specific string, and that give permission to another security group with a different string in its name. The response includes information for a group only if it matches all the filters that you specified. If there's no match, no special message is returned, the response is simply empty.

Important

Filters are based on literal strings only. This is important to remember when you want to use filters to return only security groups with access allowed on a specific port number or numbers. For example, suppose that you want to get all groups that have access on port 22, and that GroupA gives access on a range of ports using fromPort=20 and toPort=30. If you filter with ip-permission.from-port=22 or ip-permission.to-port=22 (or both), the response does not contain information for GroupA. You get information for GroupA only if you specify ip-permission.from-port=20 or ip-permission.to-port=30 (or both).

You can use wildcards in a filter value. An asterisk (*) matches zero or more characters, and a question mark (?) matches exactly one character. You can escape special characters using a backslash (\) before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\.

The following are the available filters.

description

The description of the security group.

Type: String

group-id

The ID of the security group.

Type: String

group-name

The name of the security group.

Type: String

ip-permission.cidr

The CIDR range that has been granted the permission.

Type: String

ip-permission.from-port

The start of port range for the TCP and UDP protocols, or an ICMP type number.

Type: String

ip-permission.group-name

The name of security group that has been granted the permission.

Type: String

ip-permission.protocol

The IP protocol for the permission.

Type: String

Valid values: tcp | udp | icmp or a protocol number

ip-permission.to-port

The end of port range for the TCP and UDP protocols, or an ICMP code.

Type: String

ip-permission.user-id

The ID of an AWS account that has been granted the permission.

Type: String

owner-id

The AWS account ID of the owner of the security group.

Type: String

tag-key

The key of a tag assigned to the security group.

Type: String

tag-value

The value of a tag assigned to the security group.

Type: String

vpc-id

Only return the security groups that belong to the specified EC2-VPC ID.

Type: String

Response Elements

The following elements are returned in a DescribeSecurityGroupsResponse element.

requestId

The ID of the request.

Type: xsd:string

securityGroupInfo

A list of security groups, each one wrapped in an item element.

Type: SecurityGroupItemType

Examples

Example Request

This example returns information about two security groups that are configured for the account.

https://ec2.amazonaws.com/?Action=DescribeSecurityGroups
&GroupName.1=WebServers
&GroupName.2=RangedPortsBySource
&AUTHPARAMS

Example Response

<DescribeSecurityGroupsResponse xmlns="http://ec2.amazonaws.com/doc/2013-02-01/">
   <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> 
   <securityGroupInfo>
      <item>
         <ownerId>111122223333</ownerId>
         <groupId>sg-1a2b3c4d</groupId>
         <groupName>WebServers</groupName>
         <groupDescription>Web Servers</groupDescription>
         <vpcId/>
         <ipPermissions>
            <item>
               <ipProtocol>tcp</ipProtocol>
               <fromPort>80</fromPort>
               <toPort>80</toPort>
               <groups/>
               <ipRanges>
                  <item>
                     <cidrIp>0.0.0.0/0</cidrIp>
                  </item>
               </ipRanges>
            </item>
         </ipPermissions>
         <ipPermissionsEgress/>
      </item>
      <item>
         <ownerId>111122223333</ownerId>
         <groupId>sg-2a2b3c4d</groupId>
         <groupName>RangedPortsBySource</groupName>
         <groupDescription>Group A</groupDescription>
         <ipPermissions>
            <item>
               <ipProtocol>tcp</ipProtocol>
               <fromPort>6000</fromPort>
               <toPort>7000</toPort>
               <groups>
                  <item>
                     <userId>111122223333</userId>
                     <groupId>sg-3a2b3c4d</groupId>
                     <groupName>Group B</groupName>
                  </item>
               </groups>
               <ipRanges/>
            </item>
         </ipPermissions>
         <ipPermissionsEgress/>
      </item>
   </securityGroupInfo>
</DescribeSecurityGroupsResponse>

Example Request

This example returns information about all security groups that grant access over TCP specifically on port 22 from instances in either the app_server_group or database_group. 

https://ec2.amazonaws.com/?Action=DescribeSecurityGroups
&Filter.1.Name=ip-permission.protocol
&Filter.1.Value.1=tcp
&Filter.2.Name=ip-permission.from-port
&Filter.2.Value.1=22
&Filter.3.Name=ip-permission.to-port
&Filter.3.Value.1=22
&Filter.4.Name=ip-permission.group-name
&Filter.4.Value.1=app_server_group
&Filter.4.Value.2=database_group
&AUTHPARAMS
Document Conventions« PreviousNext »
Terms of UseDid this page help you?  Yes | No |  Tell us about it...