Application Security Groups

Page last updated: October 17, 2015

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

Application security groups act as virtual firewalls to control outbound traffic from the applications in your deployment. A security group consists of a list of network egress access rules.

An administrator can assign one or more security groups to a Cloud Foundry deployment or to a specific space in an org within a deployment.

Note: A security group assigned to a Cloud Foundry deployment affects all spaces in all orgs within the deployment.

Within a space, Cloud Foundry runs each instance of an application inside a separate application container. When you launch an application for the first time, Cloud Foundry creates a new container for each application instance, then applies any space-specific and deployment-wide security groups to the container. Cloud Foundry determines whether to allow or deny outbound traffic from the container by evaluating the rules defined in these security groups.

Creating Security Groups

A security group consists of a list of operator-defined network egress allow rules. These rules define the outgoing traffic allowed to application containers. Each rule contains the following three parts:

  • Protocol: TCP, UDP, or ICMP
  • Open Port / Port Range:
    • For TCP and UDP: Either a single port or a range of ports
    • For ICMP: An ICMP type and code
  • Destination: Destination of the traffic allowed by this rule as an IP address or CIDR block

Run cf create-security-group SECURITY-GROUP PATH-TO-RULES-FILE from a command line to create a security group named SECURITY-GROUP. PATH-TO-RULES-FILE can be an absolute or relative path to a rules file. The rules file must be a JSON-formatted single array containing objects that describe the rules.

Example JSON-formatted rules file:

[{"protocol":"tcp","destination":"10.0.11.0/24","ports":"1-65535"},
{"protocol":"udp","destination":"10.0.11.0/24","ports":"1-65535"}]

Binding Security Groups

A security group consists of a list of rules. You must bind this list to either your entire deployment or to a space in an org for Cloud Foundry to apply the rules to outgoing traffic.

Note: New security rules apply to new containers as they are created, but not to containers that are already running when the rules are created. To apply new security rules immediately, restart all running apps in the relevant space, or across your whole installation if the new rules are for all spaces.

To apply the rules in a security group to your entire Cloud Foundry deployment, bind the security group to either the Default Staging or the Default Running security group set. Cloud Foundry applies the rules in every security group in the Default Staging and Default Running sets to all applications in your Cloud Foundry deployment.

Note: If you do not bind a security group to either the Default Staging or the Default Running set, Cloud Foundry only applies the rules to applications created in the specific space where you bound the security group.

Binding to your Cloud Foundry Deployment

To create a rule to be applied to every space in every org of your Cloud Foundry deployment, bind the security group to either the Default Staging or the Default Running security group set.

Cloud Foundry applies the rules in every security group in these sets as follows:

  • Default Staging: Cloud Foundry applies rules in this set to every application staged anywhere in your CF deployment. To bind a security group to the Default Staging set, run cf bind-staging-security-group SECURITY-GROUP.
  • Default Running: Cloud Foundry applies rules in this set to every application running anywhere in your CF deployment. To bind a security group to the Default Running set, run cf bind-running-security-group SECURITY-GROUP.

Binding to a Space

Run cf bind-security-group SECURITY-GROUP ORG SPACE to bind a security group to a specific space. Cloud Foundry applies the rules that this security group defines to all application containers in the space. A space may belong to more than one security group.

Network Traffic Rules Evaluation Sequence

Cloud Foundry evaluates security groups and other network traffic rules in a strict priority order. Cloud Foundry returns an allow, deny, or reject result for the first rule that matches the outbound traffic request parameters, and does not evaluate any lower-priority rules.

Cloud Foundry evaluates the network traffic rules for an application in the following order:

  1. Security Groups: The rules described by the Default Staging set, the Default Running set, and all security groups bound to the space.
  2. Warden ALLOW rules: Any Warden Server configuration allow rules. Set Warden Server configuration rules in the Droplet Execution Agent (DEA) configuration section of your deployment manifest.
  3. Warden DENY rules: Any Warden Server configuration deny rules. Set Warden Server configuration rules in the DEA configuration section of your deployment manifest.
  4. Hard-coded REJECT rule: Cloud Foundry returns a reject result for all outbound traffic from a container if not allowed by a higher-priority rule.

Viewing Security Groups

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

  • cf security-groups: Displays all security groups in an org
  • cf staging-security-groups: Displays all security groups in the Default Staging set
  • cf running-security-groups: Displays all security groups in the Default Running set
  • cf security-group SECURITY-GROUP: Displays details about the specified security group