app-sec-groups.html.md.erb

---
title: Restricting App Access to Internal Pivotal Platform Components
owner: Security
---

<% current_page.data.title = "Restricting App Access to Internal " + vars.product_name + " Components" %>

<style>
    .note.warning {
        background-color: #fdd;
        border-color: #fbb
    }

    .note.warning:before {
        color: #f99;
     }
</style>

This topic describes how to secure the component virtual machines (VMs) of your <%= vars.first_product_name  %> deployment from being accessed by apps. 


## <a id='overview'></a> Overview

See the following list to understand the concepts for this topic:

* **How <%= vars.product_name %> determines where apps can send traffic**: 
  * <%= vars.product_name %> uses _App Security Groups (ASGs)_, which are network policy rules specifying protocols, ports, and IP ranges that apply to outbound network connections initiated from apps. For more information, see [App Security Groups](../concepts/asg.html).
* **Why you must create new rules for outbound app traffic**: 
  * <%= vars.product_name %> installs with a default ASG that allows apps running on your deployment to send traffic to almost any IP address. This means apps are not blocked from initiating connections to most network destinations unless an administrator takes action to update the ASGs with a more restrictive policy. For more information, see the [Default ASGs](../concepts/asg.html#default-asg) section of the _App Security Groups_ topic.
* **How you can set up new rules**: 
  * To help secure your component VMs against apps while ensuring your apps can access the services they need, follow the steps in the [Procedure](#procedure) section, which includes:
    <table>
    <tr>
    <th>Step</th>
    <th>Description</th
    </tr>
    <tr>
      <td>1</td>
      <td><a href="#network">Determine Your Network Layout</a>: <br>The procedure for securing your deployment with ASGs varies depending on your network layout, which you can determine using Ops Manager.</td>
    </tr>
    <tr>
      <td>2</td>
      <td><a href="#bind-default">Ensure Access for <%= vars.product_name %> System Apps</a>: <br>Bind the default ASG to the <code>system</code> org so that <%= vars.product_name %> system apps can continue accessing the system components they need after you remove the  deployment-wide default ASG in Step 4.</td>
    </tr>
    <tr>
      <td>3</td>
      <td><a href="#initial">Create New ASGs</a>: <br>Block apps from sending traffic to system components, but allow them to send traffic to the services they need.</td>
    </tr>
    <tr>
      <td>4</td>
      <td><a href="#unbind-default">Remove the Default ASG</a>: <br>After you create and bind new ASGs, you no longer need the deployment-wide default ASG bindings that allow apps to send traffic to any IP.</td>
    </tr>
    <tr>
      <td>5</td>
      <td><a href="#restart">Restart Your Apps</a>: <br>To apply the ASG changes, you must restart all of the apps in your deployment.</td>
    </tr>
    </table>
* **When to set up new rules**: 
  * Pivotal recommends that you complete this procedure directly after installing <%= vars.product_name %>, prior to developers pushing apps to the platform. If you complete the procedure after apps have been pushed to the platform, you must restart all the apps in your deployment.  


## <a id='prerequisites'></a> Prerequisites

The procedure below requires that you have the latest release of [ASG Creator](https://github.com/cloudfoundry-incubator/asg-creator/releases/latest) from the Cloud Foundry incubator repository on Github. See [About the ASG Creator Tool](../concepts/asg.html#asg-baseline).


## <a id='procedure'></a> Procedure

This procedure outlines how to apply ASGs that prevent apps running on your deployment from accessing internal <%= vars.product_name %> components.

### <a name='network'></a> Step 1: Determine Your Network Layout

The procedure for securing your deployment with ASGs varies depending on your network layout. To determine your network layout, do the following: 

1. Log in to Ops Manager. 

1. For each tile, click **Assign AZs and Networks** and record the selected **Network** that the tile is installed on. 

1. Based on the information you gathered, determine which of the following network layouts you have:
  <table>
    <tr>
      <th>Layout Name</th>
      <th>Layout Description</th>
    </tr>
    <tr>
      <td>One Network</td>
      <td><ul><li>One network for Ops Manager and the BOSH Director, Pivotal Application Service (PAS), and services.</li></ul>
      <p class="note"><strong>Note:</strong> You cannot secure your deployment with ASGs if you have this network layout. Because <%= vars.product_name %> dynamically allocates IPs, they cannot be easily excluded in the case of a single network.</p>  
      </td>
    </tr>
    <tr>
      <td>Two Networks</td>
      <td><ul><li>One network for Ops Manager and the BOSH Director.</li>
          <li>One network for PAS and Services.</li></ul></td>
    </tr>
    <tr>
      <td>Three Networks</td>
      <td><ul><li>One network for Ops Manager and the BOSH Director.</li>
          <li>One network for PAS.</li>
          <li>One network for all services.</li></ul></td>
    </tr>
    <tr>
      <td>Three or More Networks</td>
      <td><ul><li>One network for Ops Manager and the BOSH Director.</li>
          <li>One network for PAS.</li>
          <li>One network for each service.</ul></td>
    </tr>
  </table>

1. If your network layout includes two or more networks, continue [Step 2: Ensure Access for <%= vars.product_name %> System Apps](#bind-default).

### <a name='bind-default'></a> Step 2: Ensure Access for <%= vars.product_name %> System Apps

Applying the default ASG to the `system` org provides network access to <%= vars.product_name %> system apps without restrictions, which enables them to continue functioning properly after you perform [Step 4: Remove the Deployment-wide Default ASG Binding](#unbind-default). To apply the default ASG to the `system` org, do the following:

1. Bind the default ASG to the [staging set](../concepts/asg.html#asg-sets) in the `system` org:
    <pre class="terminal">$ cf bind-staging-security-group default\_security\_group</pre>

1. Bind the default ASG to the [running set](../concepts/asg.html#asg-sets) in the `system` org:
    <pre class="terminal">$ cf bind-running-security-group default\_security\_group</pre>

### <a name='initial'></a> Step 3: Create New ASGs

This step outlines how to create ASGs that block apps from accessing <%= vars.product_name %> components and create any additional ASGs that allow apps to access the services they require. 

#### <a name='get-cidrs'></a> Part A: Record CIDRs

To gather the CIDRs for each network in your deployment, do the following:

1. From the BOSH Director tile, click **Create Networks** within the **Settings** tab.

1. In the **Networks** section, expand each network in your deployment by clicking its name.

1. Record the **CIDR** for each network.

#### <a name='initial-asgs'></a> Part B: Create and Bind ASGs that Block Network Access

To create ASGs that block apps from sending traffic to the networks that host Ops Manager, PAS, and, optionally, any installed services, do the following:

1. Create a `config.yml` containing the appropriate content for your network layout and replace the indicated values with the CIDRs you gathered:
  * **Two Network Layout**:

        ```
        exclude:
        - YOUR-OPS-MANAGER-CIDR
        - YOUR-PAS-AND-SERVICES-CIDR
        ```
   * **Three Network Layout**:
      <p class="note"><strong>Note</strong>: If you want to secure only the Ops Manager and PAS components, you can remove the services CIDR from the <code>exclude</code> section.</p>

         ```
          exclude:
          - YOUR-OPS-MANAGER-CIDR
          - YOUR-PAS-CIDR
          - YOUR-SERVICES-CIDR
         ```
    * **Three or More Network Layout**:
      <p class="note"><strong>Note</strong>: If you want to secure only the Ops Manager and PAS components, you can remove the services CIDRs from the <code>exclude</code> section.</p>

        ```
        exclude:
        - YOUR-OPS-MANAGER-CIDR
        - YOUR-PAS-CIDR
        - YOUR-SERVICE-CIDR-1
        - YOUR-SERVICE-CIDR-2
        etc...
        ```

1. Run the following command to generate the default `public-networks.json` and `private-networks.json` files that contain your ASG rules, specifying the location of the `config.yml` file as input:
  <pre class="terminal">$ asg-creator create --config config.yml</pre>

1. Create the `public-networks` ASG by running the following command:
  <pre class="terminal">$ cf create-security-group public-networks public-networks.json</pre>

1. Bind the ASG to the default staging set:
  <pre class="terminal">$ cf bind-staging-security-group public-networks</pre>

1. Bind the ASG to the default running set:
  <pre class="terminal">$ cf bind-running-security-group public-networks</pre>

1. Create the `private-networks` ASG by running the following command:
  <pre class="terminal">$ cf create-security-group private-networks private-networks.json</pre>

1. Bind the ASG to the default staging set:
  <pre class="terminal">$ cf bind-staging-security-group private-networks</pre>

1. Bind the ASG to the default running set:
  <pre class="terminal">$ cf bind-running-security-group private-networks</pre>

<p class="note"><strong>Note:</strong> You can create and bind additional ASGs by following the procedures in <a href="../concepts/asg.html#asg-individual">Create ASGs</a> and <a href="../concepts/asg.html#binding-groups">Bind ASGs</a>.</p>

#### <a name='service-access'></a> Part C: Create and Bind ASGs for Service Access

<p class="note"><strong>Note:</strong> This part is only necessary if you blocked apps from a network that hosts services in the previous part. If you did not block apps from a network that hosts services, proceed to <a href="#unbind-default">Step 4: Remove the Default ASG</a>.</p>

<p class="note warning"><strong>Warning:</strong> In the two network layout, PAS and services share the same network. This means that each time you create an ASG that allows apps to access a new port and protocol within the network, you further expose the PAS component VMs. This is a limitation of a two network layout. For guidance on network topology, see <a href="../refarch/index.html">Reference Architectures</a>.</p>

Now that you have created ASGs to secure the Ops Manager, PAS, and service components, work with developers to create additional ASGs that give apps access to the services they need. 

For more information about creating and binding ASGs, see the following:

* [Managing ASGs with the cf CLI](../concepts/asg.html#procedures)
* [Typical ASGs](../concepts/asg.html#typical-groups)

### <a name='unbind-default'></a> Step 4: Remove the Default ASG

Now that you have bound new ASGs to determine outbound traffic rules, you no longer need the default ASG bindings that allow apps to send traffic to any IP address. Do the following:

1. Unbind the default ASG from the staging set:
    <pre class="terminal">$ cf unbind-staging-security-group default\_security\_group</pre>

1. Unbind the default ASG from the running set:
    <pre class="terminal">$ cf unbind-running-security-group default\_security\_group</pre>


### <a name='restart'></a> Step 5: Restart your Apps

To apply the ASG changes, you must restart all of the apps in your deployment. To mitigate app downtime during the restart, Pivotal recommends a [blue-green](../devguide/deploy-apps/blue-green.html) deployment strategy.

To restart all of the apps in your deployment, do the following:

<p class="note"><strong>Note:</strong> You do not need to restart the apps in the <code>system</code> org.</p>

1. Work with developers to restart a few of their apps individually and test that they still work correctly with the new ASGs in place. If an app does not work as expected, you likely must create another ASG that allows the app to send traffic to a service it requires. 
  <p class="note"><strong>Note:</strong> To quickly roll back to the original overly-permissive state, you can re-bind the <code>default\_security\_group</code> ASG to the <code>default-staging</code> and <code>default-running</code> sets. You must then restart your apps to re-apply the original ASGs.</p>

1. Restart the rest of the apps running on your deployment. Optionally, you can use the [app-restarter cf CLI plugin](https://github.com/cloudfoundry-incubator/app-restarter) to restart all apps in a particular space, org, or deployment.