Fjall Docs — Deploy Production-Ready AWS Infrastructure in Minutes

Overview

The Security Group resource is a virtual firewall for controlling inbound and outbound traffic to AWS resources.

This is a thin wrapper over the standard CDK SecurityGroup. The only Fjall addition is a default description (${id} Security Group) when you omit one. Every other property and method behaves exactly as the CDK construct.

Resource Class

import { SecurityGroup } from "@fjall/components-infrastructure/lib/resources/aws/networking/securityGroup";

Basic Usage

const securityGroup = new SecurityGroup(this, "MySecurityGroup", {
  vpc: myVpc,
  description: "Security group for my application",
});

Configuration Options

Core Properties

Property	Type	Description	Default
`vpc`	`IVpc`	VPC for the security group	Required
`description`	`string`	Security group description	`${id} Security Group`
`securityGroupName`	`string`	Security group name	Auto-generated
`allowAllOutbound`	`boolean`	Allow all outbound traffic	`true`

All standard CDK SecurityGroup properties are supported through the extending class.

Default Behaviour

Description: Automatically set to ${id} Security Group if not provided
Outbound Rules: All traffic allowed by default
Inbound Rules: No inbound traffic allowed by default (deny all)

Common Patterns

Web Server Security Group

const webSg = new SecurityGroup(this, "WebServerSG", {
  vpc: vpc,
  description: "Security group for web servers",
});

// Allow HTTP from anywhere
webSg.addIngressRule(ec2.Peer.anyIpv4(), ec2.Port.tcp(80), "Allow HTTP");

// Allow HTTPS from anywhere
webSg.addIngressRule(ec2.Peer.anyIpv4(), ec2.Port.tcp(443), "Allow HTTPS");

Application Server Security Group

const appSg = new SecurityGroup(this, "AppServerSG", {
  vpc: vpc,
  description: "Security group for application servers",
});

// Only allow traffic from web tier
appSg.addIngressRule(webSg, ec2.Port.tcp(8080), "Allow from web tier");

Database Security Group

const dbSg = new SecurityGroup(this, "DatabaseSG", {
  vpc: vpc,
  description: "Security group for database",
  allowAllOutbound: false, // Restrict outbound for databases
});

// Only allow from app tier
dbSg.addIngressRule(appSg, ec2.Port.tcp(5432), "PostgreSQL from app tier");

Working with Connections

Using Connections Interface

const sg = new SecurityGroup(this, "ServiceSG", {
  vpc: vpc,
});

// Allow another resource to connect
const database = new RdsInstance(this, "Database", { vpc });

sg.connections.allowTo(database, ec2.Port.tcp(5432), "Allow database access");

// Allow from another resource
sg.connections.allowFrom(loadBalancer, ec2.Port.tcp(8080), "Allow from ALB");

Bi-directional Connections

const sg1 = new SecurityGroup(this, "Service1", { vpc });
const sg2 = new SecurityGroup(this, "Service2", { vpc });

// Allow bidirectional communication
sg1.connections.allowTo(sg2, ec2.Port.tcp(8080));
sg2.connections.allowTo(sg1, ec2.Port.tcp(9090));

Advanced Rules

IP-based Rules

const sg = new SecurityGroup(this, "RestrictedSG", {
  vpc: vpc,
});

// Office IP range
sg.addIngressRule(
  ec2.Peer.ipv4("203.0.113.0/24"),
  ec2.Port.tcp(22),
  "SSH from office",
);

// Multiple CIDR blocks
["10.0.0.0/8", "172.16.0.0/12"].forEach((cidr) => {
  sg.addIngressRule(
    ec2.Peer.ipv4(cidr),
    ec2.Port.allTraffic(),
    `Allow from ${cidr}`,
  );
});

Port Ranges

const sg = new SecurityGroup(this, "RangesSG", {
  vpc: vpc,
});

// TCP port range
sg.addIngressRule(
  ec2.Peer.anyIpv4(),
  ec2.Port.tcpRange(8000, 8999),
  "Application ports",
);

// Custom protocol
sg.addIngressRule(
  ec2.Peer.anyIpv4(),
  new ec2.Port({
    protocol: ec2.Protocol.UDP,
    fromPort: 500,
    toPort: 500,
  }),
  "IPSec",
);

Prefix Lists

const sg = new SecurityGroup(this, "PrefixListSG", {
  vpc: vpc,
});

// AWS service prefix lists
sg.addIngressRule(
  ec2.Peer.prefixList("pl-12345678"), // S3 prefix list
  ec2.Port.tcp(443),
  "HTTPS from S3",
);

Security Group Chaining

Three-Tier Architecture

// Public tier
const publicSg = new SecurityGroup(this, "PublicSG", {
  vpc: vpc,
  description: "Public-facing load balancer",
});

publicSg.addIngressRule(
  ec2.Peer.anyIpv4(),
  ec2.Port.tcp(443),
  "HTTPS from internet",
);

// App tier
const appSg = new SecurityGroup(this, "AppSG", {
  vpc: vpc,
  description: "Application servers",
});

appSg.addIngressRule(publicSg, ec2.Port.tcp(8080), "From load balancer");

// Data tier
const dataSg = new SecurityGroup(this, "DataSG", {
  vpc: vpc,
  description: "Database servers",
});

dataSg.addIngressRule(appSg, ec2.Port.tcp(5432), "From application tier");

Egress Rules

Restrict Outbound Traffic

const restrictedSg = new SecurityGroup(this, "RestrictedSG", {
  vpc: vpc,
  allowAllOutbound: false, // No default outbound rules
});

// Only allow HTTPS outbound
restrictedSg.addEgressRule(ec2.Peer.anyIpv4(), ec2.Port.tcp(443), "HTTPS only");

// Allow DNS
restrictedSg.addEgressRule(ec2.Peer.anyIpv4(), ec2.Port.udp(53), "DNS queries");

Service-Specific Egress

const sg = new SecurityGroup(this, "ServiceSG", {
  vpc: vpc,
  allowAllOutbound: false,
});

// S3 access via VPC endpoint
sg.addEgressRule(ec2.Peer.prefixList("pl-s3"), ec2.Port.tcp(443), "S3 access");

// RDS access
sg.addEgressRule(dbSg, ec2.Port.tcp(5432), "Database access");

Integration Examples

With ECS

const clusterSg = new SecurityGroup(this, "ClusterSG", {
  vpc: vpc,
  description: "ECS cluster security group",
});

const service = new ecs.FargateService(this, "Service", {
  cluster: cluster,
  taskDefinition: taskDef,
  securityGroups: [clusterSg],
});

// Allow from ALB
clusterSg.connections.allowFrom(alb, ec2.Port.tcp(containerPort));

With Lambda

const lambdaSg = new SecurityGroup(this, "LambdaSG", {
  vpc: vpc,
  description: "Lambda function security group",
});

const fn = new lambda.Function(this, "Function", {
  vpc: vpc,
  securityGroups: [lambdaSg],
  // ... other props
});

// Allow Lambda to access RDS
lambdaSg.connections.allowTo(database, ec2.Port.tcp(5432));

With RDS

const dbSg = new SecurityGroup(this, "DatabaseSG", {
  vpc: vpc,
  description: "RDS security group",
});

const database = new rds.DatabaseInstance(this, "Database", {
  vpc: vpc,
  securityGroups: [dbSg],
  // ... other props
});

// Application access
appSg.connections.allowTo(database, ec2.Port.tcp(5432));

Best Practices

Least Privilege

// Bad - Too permissive
sg.addIngressRule(
  ec2.Peer.anyIpv4(),
  ec2.Port.allTraffic(),
  "Allow all", // Never do this!
);

// Good - Specific rules
sg.addIngressRule(
  ec2.Peer.ipv4("10.0.0.0/16"),
  ec2.Port.tcp(443),
  "HTTPS from VPC only",
);

Rule Documentation

// Always add meaningful descriptions
sg.addIngressRule(
  webTierSg,
  ec2.Port.tcp(8080),
  "HTTP traffic from web tier ALB for health checks",
);

Avoid Circular Dependencies

// Can cause circular dependency
const sg1 = new SecurityGroup(this, "SG1", { vpc });
const sg2 = new SecurityGroup(this, "SG2", { vpc });

sg1.addIngressRule(sg2, ec2.Port.tcp(80), "From SG2");
sg2.addIngressRule(sg1, ec2.Port.tcp(80), "From SG1");

// Better approach - use connections
sg1.connections.allowFrom(sg2, ec2.Port.tcp(80));
sg2.connections.allowFrom(sg1, ec2.Port.tcp(80));

Monitoring and Compliance

VPC Flow Logs

// Enable flow logs to monitor security group traffic
vpc.addFlowLog("SecurityGroupFlowLog", {
  destination: ec2.FlowLogDestination.toCloudWatchLogs(),
  trafficType: ec2.FlowLogTrafficType.REJECT,
});

AWS Config Rules

new config.CfnConfigRule(this, "SGComplianceRule", {
  source: {
    sourceIdentifier: "INCOMING_SSH_DISABLED",
  },
  scope: {
    complianceResourceTypes: ["AWS::EC2::SecurityGroup"],
  },
});

Complete Example

import { SecurityGroup } from "@fjall/components-infrastructure/lib/resources/aws/networking/securityGroup";
import * as ec2 from "aws-cdk-lib/aws-ec2";

// Create VPC
const vpc = new ec2.Vpc(this, "AppVpc", {
  maxAzs: 2,
});

// Bastion host security group
const bastionSg = new SecurityGroup(this, "BastionSG", {
  vpc: vpc,
  description: "Bastion host security group",
});

bastionSg.addIngressRule(
  ec2.Peer.ipv4("203.0.113.0/24"), // Office IP
  ec2.Port.tcp(22),
  "SSH from office",
);

// Web tier security group
const webSg = new SecurityGroup(this, "WebSG", {
  vpc: vpc,
  description: "Web application security group",
});

webSg.addIngressRule(
  ec2.Peer.anyIpv4(),
  ec2.Port.tcp(443),
  "HTTPS from internet",
);

webSg.addIngressRule(bastionSg, ec2.Port.tcp(22), "SSH from bastion");

// App tier security group
const appSg = new SecurityGroup(this, "AppSG", {
  vpc: vpc,
  description: "Application tier security group",
  allowAllOutbound: false,
});

appSg.addIngressRule(webSg, ec2.Port.tcp(8080), "HTTP from web tier");

appSg.addIngressRule(
  bastionSg,
  ec2.Port.tcp(22),
  "SSH from bastion for debugging",
);

// Restrict outbound
appSg.addEgressRule(
  ec2.Peer.anyIpv4(),
  ec2.Port.tcp(443),
  "HTTPS for external APIs",
);

appSg.addEgressRule(
  ec2.Peer.anyIpv4(),
  ec2.Port.tcp(80),
  "HTTP for package downloads",
);

// Database security group
const dbSg = new SecurityGroup(this, "DatabaseSG", {
  vpc: vpc,
  description: "Database security group",
  allowAllOutbound: false, // Databases shouldn't initiate connections
});

dbSg.addIngressRule(appSg, ec2.Port.tcp(5432), "PostgreSQL from app tier");

dbSg.addIngressRule(
  bastionSg,
  ec2.Port.tcp(5432),
  "PostgreSQL from bastion for maintenance",
);

// Export security group IDs
new CfnOutput(this, "WebSecurityGroupId", {
  value: webSg.securityGroupId,
  description: "Web tier security group ID",
});

Troubleshooting

Common Issues

Connection timeouts: Check both ingress and egress rules
Circular dependencies: Use connections interface
Rule limits: Maximum 60 inbound and 60 outbound rules
ICMP traffic: Remember to allow for ping/traceroute

Debug Commands

# List security groups
aws ec2 describe-security-groups --group-ids sg-12345

# Check rules
aws ec2 describe-security-group-rules \
  --filters "Name=security-group-id,Values=sg-12345"

# Test connectivity
aws ec2 describe-vpc-peering-connections

Next Steps

VPC

Define the network the security group attaches to

ECS Cluster

Attach security groups to container services

RDS Instance

Restrict database access by tier

Lambda Function

Place functions inside a secured VPC

​Overview

​Resource Class

​Basic Usage

​Configuration Options

​Core Properties

​Default Behaviour

​Common Patterns

​Web Server Security Group

​Application Server Security Group

​Database Security Group

​Working with Connections

​Using Connections Interface

​Bi-directional Connections

​Advanced Rules

​IP-based Rules

​Port Ranges

​Prefix Lists

​Security Group Chaining

​Three-Tier Architecture

​Egress Rules

​Restrict Outbound Traffic

​Service-Specific Egress

​Integration Examples

​With ECS

​With Lambda

​With RDS

​Best Practices

​Least Privilege

​Rule Documentation

​Avoid Circular Dependencies

​Monitoring and Compliance

​VPC Flow Logs

​AWS Config Rules

​Complete Example

​Troubleshooting

​Common Issues

​Debug Commands

​Next Steps

VPC

ECS Cluster

RDS Instance

Lambda Function

Overview

Resource Class

Basic Usage

Configuration Options

Core Properties

Default Behaviour

Common Patterns

Web Server Security Group

Application Server Security Group

Database Security Group

Working with Connections

Using Connections Interface

Bi-directional Connections

Advanced Rules

IP-based Rules

Port Ranges

Prefix Lists

Security Group Chaining

Three-Tier Architecture

Egress Rules

Restrict Outbound Traffic

Service-Specific Egress

Integration Examples

With ECS

With Lambda

With RDS

Best Practices

Least Privilege

Rule Documentation

Avoid Circular Dependencies

Monitoring and Compliance

VPC Flow Logs

AWS Config Rules

Complete Example

Troubleshooting

Common Issues

Debug Commands

Next Steps