LATEST VERSION: 1.10 - CHANGELOG
Pivotal Cloud Foundry v1.7

Application Security Groups

Page last updated:

This page assumes you are using cf CLI v6.4 or higher.

Elastic Runtime blocks all outbound network connections from application containers by default. Administrators can override this block-by-default behavior with Application Security Groups (ASGs).

ASGs are a collection of egress rules that specify one or more individual protocols, ports, and destinations to allow network access to.

ASGs can be complicated to configure correctly, especially when the specific IPs listed in the group change. To simplify securing a deployment while still letting apps reach external services, operators can deploy the services into a subnet that is separate from their Cloud Foundry deployment. Then the operators can create ASGs for the apps that whitelist those service subnets, while denying access to any VMs hosting other apps.

Note: For examples of typical ASGs, see Typical Application Security Groups.

Elastic Runtime has two default sets of ASGs: default-staging and default-running. All application containers in Elastic Runtime use a base policy from one of these.

The default-staging ASG set applies to application containers that are in the staging application lifecycle phase. This includes both the buildpack staging and Docker staging process.

The default-running ASG set applies to application containers that are started and running applications.

In addition to the default-staging and default-running ASG sets, administrators can configure additional ASGs and bind them to Elastic Runtime spaces. ASGs bound to spaces add network access only to the application containers within that space.

When Elastic Runtime creates an application container, the egress rules for the application container include the following:

  • All ASGs in either the default-staging or default-running set
  • All ASGs bound to the space of the application

Viewing Application Security Groups

Run the following commands to view information about existing application security groups:

Command Output
cf security-groups All security groups
cf staging-security-groups All security groups in the default-staging set
cf running-security-groups All security groups in the default-running set
cf security-group SG-NAME All rules in the specified security group

Creating Application Security Groups

Note: After creating an ASG you must bind it for it to take effect. See Binding Application Security Groups.

ASG rules are specified as a JSON array of ASG objects. An ASG object has the following attributes:

Attribute Description Notes
protocol tcp, udp, icmp, or all Required
destination A single IP address, an IP address range (e.g. 192.0.2.0-192.0.2.50), or a CIDR block to allow network access to
ports A single port, multiple comma-separated ports, or a single range of ports that can receive traffic, e.g. "443", "80,8080,8081", "8080-8081" Required when protocol is tcp or udp
code ICMP code Required when protocol is icmp
type ICMP type Required when protocol is icmp
log Set to true to enable logging. For more information on how to configure system logs to be sent to a syslog drain see Using Log Management Services

Follow the instructions in the sections below to create individual ASGs and baseline ASGs.

Create Individual ASGs

To create individual ASGs, perform the following steps:

  1. Create a rules file as a JSON-formatted single array containing objects that describe the rules. Refer to the example below, which allows ICMP traffic of code 1 and type 0 to all destinations, and TCP traffic to 10.0.11.0/24 on ports 80-443:

    [
      {
        "protocol": "icmp",
        "destination": "0.0.0.0/0",
        "type": 0,
        "code": 1
      },
      {
        "protocol": "tcp",
        "destination": "10.0.11.0/24",
        "ports": "80-443",
        "log": true 
      }
    ]
    
  2. Run the following cf CLI command, replacing SECURITY-GROUP with the name of your security group and PATH-TO-RULES-FILE with the absolute or relative path to a rules file.

    $ cf create-security-group SECURITY-GROUP PATH-TO-RULES-FILE
    

  3. Bind the ASG.

Create Baseline ASGs

ASG Creator is a CLI tool to generate baseline ASGs that allow network access for all application containers based on a blacklist of networks and individual IPs. The ASG rules files generated by ASG Creator contain those IP ranges that application containers are allowed access to.

To use ASG Creator to create baseline ASGs, perform the following steps:

  1. Download the latest release of ASG Creator.
  2. Create a configuration file called config.yml that contains the networks and IPs you want to blacklist. Follow the format of the example below and consult the table for descriptions of the attributes.

    excluded_ips:
    - 192.0.2.4
    
    excluded_networks:
    - 192.0.2.0/24
    
    Attribute Description
    excluded_ips An array of IPs to exclude; these IPs will be omitted from the baseline ASG rules
    excluded_networks An array of CIDRs to exclude; all IPs in these networks will be omitted from the baseline ASG rules
  3. Run asg-creator create, supplying the optional config.yml to create the baseline ASG rules files public-networks.json and private-networks.json.

    $ asg-creator create --config config.yml
    Wrote public-networks.json
    Wrote private-networks.json
    OK
    

    Note: If you do not supply asg-creator with a configuration file, it excludes only the 169.254.169.254 from public-networks.json.

  4. Review the generated ASG rules files public-networks.json and private-networks.json and make changes per your network policy for application containers running untrusted code.

  5. Use the ASG rules files to create baseline staging and running ASGs with the following cf CLI commands:

    $ cf create-security-group YOUR-PRIVATE-NETWORKS-SECURITY-GROUP private-networks.json
    $ cf bind-staging-security-group YOUR-PRIVATE-NETWORKS-SECURITY-GROUP 
    $ cf bind-running-security-group YOUR-PRIVATE-NETWORKS-SECURITY-GROUP 
    
    $ cf create-security-group YOUR-PUBLIC-NETWORKS-SECURITY-GROUP public-networks.json
    $ cf bind-staging-security-group YOUR-PUBLIC-NETWORKS-SECURITY-GROUP 
    $ cf bind-running-security-group YOUR-PUBLIC-NETWORKS-SECURITY-GROUP 
    

Updating Application Security Groups

Note: Updating an ASG does not affect started applications until you restart them. To restart all of the apps in an org or a space, use the app-restarter cf CLI plugin.

To update an existing ASG, run the following command, replacing SECURITY-GROUP with the name of your security group and PATH-TO-RULES-FILE with the absolute or relative path to a rules file.

$ cf update-security-group SECURITY-GROUP PATH-TO-RULES-FILE

Binding Application Security Groups

Note: Binding an ASG does not affect started applications until you restart them. To restart all of the apps in an org or a space, use the app-restarter cf CLI plugin.

To apply an ASG to application containers, you must first bind it to a default set or a space.

To bind an ASG to the default-staging set, run the following command:

$ cf bind-staging-security-group SECURITY-GROUP

To bind an ASG to the default-running set, run the following command:

$ cf bind-running-security-group SECURITY-GROUP

To bind an ASG to a specific space, run the following command:

$ cf bind-security-group SECURITY-GROUP ORG SPACE

To bind an ASG to all of an organization’s existing spaces, run the following command (requires CF CLI 6.20.0+):

$ cf bind-security-group SECURITY-GROUP ORG

Unbinding Application Security Groups

Note: Unbinding an ASG does not affect started applications until you restart them. To restart all of the apps in an org or a space, use the app-restarter cf CLI plugin.

To unbind an ASG from the default-staging set, run the following command:

$ cf unbind-staging-security-group SECURITY-GROUP

To unbind an ASG from the default-running set, run the following command:

$ cf unbind-running-security-group SECURITY-GROUP

To unbind an ASG from a specific space, run the following command:

$ cf unbind-security-group SECURITY-GROUP ORG SPACE

Deleting Application Security Groups

Note: You can only delete unbound ASGs. See Unbinding Application Security Groups.

To delete an ASG, run the following command:

$ cf delete-security-group SECURITY-GROUP

Typical Application Security Groups

Below are examples of typical ASGs. Configure your ASGs in accordance with your organization’s network access policy for untrusted applications.

ASG For access to
dns DNS, either public or private
public-networks Public networks, excluding IaaS metadata endpoints
private-networks Private networks per RFC-1918
load-balancers The internal Elastic Runtime load balancer, others
internal-proxies Internal proxies
internal-databases Internal databases

DNS

In order to resolve hostnames to IPs, applications require DNS server connectivity, which typically use port 53. Administrators should create or update a dns ASG with appropriate rules. Administrators may further restrict the DNS servers to specific IPs or ranges of IPs.

Example dns ASG:

[
  {
    "protocol": "tcp",
    "destination": "0.0.0.0/0",
    "ports": "53"
  },
  {
    "protocol": "udp",
    "destination": "0.0.0.0/0",
    "ports": "53"
  }
]

Public Networks

Applications often require public network connectivity to retrieve application dependencies or to integrate with services available on public networks. Example application dependencies include public Maven repositories, NPM, RubyGems, Docker registries and others.

Note: Exclude IaaS metadata endpoints, such as 169.254.169.254, because the metadata endpoint can expose sensitive environment information to untrusted applications. The public_networks example below accounts for this recommendation.

Example public_networks ASG:

[
  {
    "destination": "0.0.0.0-9.255.255.255",
    "protocol": "all"
  },
  {
    "destination": "11.0.0.0-169.253.255.255",
    "protocol": "all"
  },
  {
    "destination": "169.255.0.0-172.15.255.255",
    "protocol": "all"
  },
  {
    "destination": "172.32.0.0-192.167.255.255",
    "protocol": "all"
  },
  {
    "destination": "192.169.0.0-255.255.255.255",
    "protocol": "all"
  }
]

Private Networks

Network connections that are commonly allowable in private networks include endpoints such as proxy servers, Docker registries, load balancers, databases, messaging servers, directory servers, and file servers. Configure appropriate private network ASGs as appropriate. It may be helpful to use a naming convention with private_networks as part of the ASG name, such as private_networks_databases.

Note: Be sure to exclude any private networks/IPs that application containers should not have access to.

Example private_networks ASG:

[
  {
    "protocol": "tcp",
    "destination": "10.0.0.0-10.255.255.255",
    "ports": "443"
  },
  {
    "protocol": "tcp",
    "destination": "172.16.0.0-172.31.255.255",
    "ports": "443"
  },
  {
    "protocol": "tcp",
    "destination": "192.168.0.0-192.168.255.255",
    "ports": "443"
  }
]

Marketplace Services

Each installed Marketplace Service requires its own set of ASG rules to function properly. Please refer to the installation instructions for each installed Marketplace Service for which ASG rules it requires. See the Services Overview topic for more information about how to provision and integrate services.

Create a pull request or raise an issue on the source for this page in GitHub