SecurityGroup

class aws_cdk.aws_ec2.SecurityGroup(scope, id, *, vpc, allow_all_ipv6_outbound=None, allow_all_outbound=None, description=None, disable_inline_rules=None, security_group_name=None)

Bases: Resource

Creates an Amazon EC2 security group within a VPC.

Security Groups act like a firewall with a set of rules, and are associated with any AWS resource that has or creates Elastic Network Interfaces (ENIs). A typical example of a resource that has a security group is an Instance (or Auto Scaling Group of instances)

If you are defining new infrastructure in CDK, there is a good chance you won’t have to interact with this class at all. Like IAM Roles, Security Groups need to exist to control access between AWS resources, but CDK will automatically generate and populate them with least-privilege permissions for you so you can concentrate on your business logic.

All Constructs that require Security Groups will create one for you if you don’t specify one at construction. After construction, you can selectively allow connections to and between constructs via–for example– the instance.connections object. Think of it as “allowing connections to your instance”, rather than “adding ingress rules a security group”. See the Allowing Connections section in the library documentation for examples.

Direct manipulation of the Security Group through addIngressRule and addEgressRule is possible, but mutation through the .connections object is recommended. If you peer two constructs with security groups this way, appropriate rules will be created in both.

If you have an existing security group you want to use in your CDK application, you would import it like this:

security_group = ec2.SecurityGroup.from_security_group_id(self, "SG", "sg-12345",
    mutable=False
)
ExampleMetadata:

infused

Example:

# vpc: ec2.Vpc


my_security_group = ec2.SecurityGroup(self, "SecurityGroup", vpc=vpc)
autoscaling.AutoScalingGroup(self, "ASG",
    vpc=vpc,
    instance_type=ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE2, ec2.InstanceSize.MICRO),
    machine_image=ec2.MachineImage.latest_amazon_linux2(),
    security_group=my_security_group
)
Parameters:

  • scope (Construct) –

  • id (str) –

  • vpc (IVpc) – The VPC in which to create the security group.

  • allow_all_ipv6_outbound (Optional[bool]) – Whether to allow all outbound ipv6 traffic by default. If this is set to true, there will only be a single egress rule which allows all outbound ipv6 traffic. If this is set to false, no outbound traffic will be allowed by default and all egress ipv6 traffic must be explicitly authorized. To allow all ipv4 traffic use allowAllOutbound Default: false

  • allow_all_outbound (Optional[bool]) – Whether to allow all outbound traffic by default. If this is set to true, there will only be a single egress rule which allows all outbound traffic. If this is set to false, no outbound traffic will be allowed by default and all egress traffic must be explicitly authorized. To allow all ipv6 traffic use allowAllIpv6Outbound Default: true

  • description (Optional[str]) – A description of the security group. Default: The default name will be the construct’s CDK path.

  • disable_inline_rules (Optional[bool]) – Whether to disable inline ingress and egress rule optimization. If this is set to true, ingress and egress rules will not be declared under the SecurityGroup in cloudformation, but will be separate elements. Inlining rules is an optimization for producing smaller stack templates. Sometimes this is not desirable, for example when security group access is managed via tags. The default value can be overriden globally by setting the context variable ‘@aws-cdk/aws-ec2.securityGroupDisableInlineRules’. Default: false

  • security_group_name (Optional[str]) – The name of the security group. For valid values, see the GroupName parameter of the CreateSecurityGroup action in the Amazon EC2 API Reference. It is not recommended to use an explicit group name. Default: If you don’t specify a GroupName, AWS CloudFormation generates a unique physical ID and uses that ID for the group name.

Methods

add_egress_rule(peer, connection, description=None, remote_rule=None)

Add an egress rule for the current security group.

remoteRule controls where the Rule object is created if the peer is also a securityGroup and they are in different stack. If false (default) the rule object is created under the current SecurityGroup object. If true and the peer is also a SecurityGroup, the rule object is created under the remote SecurityGroup object.

Parameters:

  • peer (IPeer) –

  • connection (Port) –

  • description (Optional[str]) –

  • remote_rule (Optional[bool]) –

Return type:

None

add_ingress_rule(peer, connection, description=None, remote_rule=None)

Add an ingress rule for the current security group.

remoteRule controls where the Rule object is created if the peer is also a securityGroup and they are in different stack. If false (default) the rule object is created under the current SecurityGroup object. If true and the peer is also a SecurityGroup, the rule object is created under the remote SecurityGroup object.

Parameters:

  • peer (IPeer) –

  • connection (Port) –

  • description (Optional[str]) –

  • remote_rule (Optional[bool]) –

Return type:

None

apply_removal_policy(policy)

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you’ve removed it from the CDK application or because you’ve made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

Parameters:

policy (RemovalPolicy) –

Return type:

None

to_egress_rule_config()

Produce the egress rule JSON for the given connection.

Return type:

Any

to_ingress_rule_config()

Produce the ingress rule JSON for the given connection.

Return type:

Any

to_string()

Returns a string representation of this construct.

Return type:

str

Attributes

allow_all_ipv6_outbound

Whether the SecurityGroup has been configured to allow all outbound ipv6 traffic.

allow_all_outbound

Whether the SecurityGroup has been configured to allow all outbound traffic.

can_inline_rule

Whether the rule can be inlined into a SecurityGroup or not.

connections

The network connections associated with this resource.

default_port
env

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

node

The tree node.

security_group_id

The ID of the security group.

Attribute:

true

security_group_vpc_id

The VPC ID this security group is part of.

Attribute:

true

stack

The stack in which this resource is defined.

unique_id

A unique identifier for this connection peer.

Static Methods

classmethod from_lookup_by_id(scope, id, security_group_id)

Look up a security group by id.

Parameters:

  • scope (Construct) –

  • id (str) –

  • security_group_id (str) –

Return type:

ISecurityGroup

classmethod from_lookup_by_name(scope, id, security_group_name, vpc)

Look up a security group by name.

Parameters:

  • scope (Construct) –

  • id (str) –

  • security_group_name (str) –

  • vpc (IVpc) –

Return type:

ISecurityGroup

classmethod from_security_group_id(scope, id, security_group_id, *, allow_all_ipv6_outbound=None, allow_all_outbound=None, mutable=None)

Import an existing security group into this app.

This method will assume that the Security Group has a rule in it which allows all outbound traffic, and so will not add egress rules to the imported Security Group (only ingress rules).

If your existing Security Group needs to have egress rules added, pass the allowAllOutbound: false option on import.

Parameters:

  • scope (Construct) –

  • id (str) –

  • security_group_id (str) –

  • allow_all_ipv6_outbound (Optional[bool]) – Mark the SecurityGroup as having been created allowing all outbound ipv6 traffic. Only if this is set to false will egress rules for ipv6 be added to this security group. Be aware, this would undo any potential “all outbound traffic” default. Default: false

  • allow_all_outbound (Optional[bool]) – Mark the SecurityGroup as having been created allowing all outbound traffic. Only if this is set to false will egress rules be added to this security group. Be aware, this would undo any potential “all outbound traffic” default. Default: true

  • mutable (Optional[bool]) – If a SecurityGroup is mutable CDK can add rules to existing groups. Beware that making a SecurityGroup immutable might lead to issue due to missing ingress/egress rules for new resources. Default: true

Return type:

ISecurityGroup

classmethod is_construct(x)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

Parameters:

x (Any) – Any object.

Return type:

bool

Returns:

true if x is an object created from a class which extends Construct.

classmethod is_owned_resource(construct)

Returns true if the construct was created by CDK, and false otherwise.

Parameters:

construct (IConstruct) –

Return type:

bool

classmethod is_resource(construct)

Check whether the given construct is a Resource.

Parameters:

construct (IConstruct) –

Return type:

bool

classmethod is_security_group(x)

Return whether the indicated object is a security group.

Parameters:

x (Any) –

Return type:

bool