Merge pull request #444 from BCDevOps/olena-update-devguide

Added cross-references to the docs in the security/aporeto folder

security/aporeto/architecture/design_decisions.md

@@ -1,12 +1,17 @@
-# Aporeto Design Decisions
+# Zero Trust Model Implementation Design Decisions
 
-## Namespaces
-Aporeto namespaces are used to logically group objects such as, `enforcers`, `network access policies`, `external networks`, and so on. Each namespace can have a parent namespace and children namespaces. Access control can he placed at the namespace level, and any parent namespace can propogate it's objects to children namespaces. This is an important detail as the overall structure can help simplify the deployment of security policy across a large group of Aporeto peocessing units if placed at the right place in the heiararchy. 
+## Technology behind Zero Trust Model
+Aporeto cloud-native security solution was selected to implement the Zero-Trust Network security model on the BCDevExchange's Openshift Platform.
+
+To learn more about Aporeto, its architecture and find links to other useful resources, click [here](./readme.md#aporeto-zero-trust-network-security-enforcement).
+
+## Aporeto Namespaces
+Aporeto namespaces are used to logically group objects such as, `enforcers`, `network access policies`, `external networks`, and so on. Each namespace can have a parent namespace and children namespaces. Access control can he placed at the namespace level, and any parent namespace can propogate it's objects to children namespaces. This is an important detail as the overall structure can help simplify the deployment of security policy across a large group of Aporeto peocessing units if placed at the right place in the hierarchy. 
 
 
 ### Namespace Naming Convention
 At this point in time, the Aporeto namespace naming convention and heiarachy is intended to: 
-- align with the appropriate teams who may have need access to create/read/update/delete policy
+- align with the appropriate teams who may need access to create/read/update/delete policy
 - provide an overall governance/enforcement point at the root/parent namespace 
 - support the pattern where teams outside of **Platform Services** will own and manage their own Aporeto resources and policies
 
@@ -29,6 +34,7 @@ The following table outlines the namespace heirarchy and high-level access / own
 
 | Team / Sector     | Namespace                                                     | Description                                                     | Access Control                       | Notes                                                                                                             |
 |-------------------|---------------------------------------------------------------|-----------------------------------------------------------------|--------------------------------------|-------------------------------------------------------------------------------------------------------------------|
+| The namespaces for platform related policies |
 | Platform Services | /bcgov                                                        | Root / Parent Namespace                                         |                                      |                                                                                                                   |
 | Platform Services | /bcgov/platform-services                                      | Platform-Services enforcers and policies                        | DXC / Platform Services              |                                                                                                                   |
 | Platform Services | /bcgov/platform-services/non-production                       | Non Prod Container Platform Resources                           | Access propagated from parent        |                                                                                                                   |
@@ -40,10 +46,10 @@ The following table outlines the namespace heirarchy and high-level access / own
 | Platform Services | /bcgov/platform-services/production/kamloops                  | No description                                                  | Access propagated from parent        |                                                                                                                   |
 | Platform Services | /bcgov/platform-services/production/kamloops/pathfinder       | No description                                                  | Access propagated from parent        | Holds all production pathfinder cluster enforcers and base policies                                               |
 | Platform Services | /bcgov/platform-services/production/kamloops/pathfinder/*     | No description                                                  | Access propagated from parent        | Child namespaces are automatically created /mapped to OpenShift Projects                                          |
-| Nobody            | /bcgov/app                                                    | Parent namespace to hold sector related enforcers and policies  | No access definied at this level yet | General namespace to separate App or Team specific resources from Container Platform related resources            |
-| NR                | /bcgov/apps/nr                                                | Natural Resources Sector                                        | NR Team                              |                                                                                                                   |
-| NR                | /bcgov/apps/nr/non-prod                                       | Natural Resources Sector Non-Prod                               | Access propagated from parent        |                                                                                                                   |
-| NR                | /bcgov/apps/nr/non-prod/calgary                               | Natural Resources Sector Non-Prod Calgary                       | Access propagated from parent        |                                                                                                                   |
+| Nobody            | /bcgov/apps                                                    | Parent namespace to hold sector related enforcers and policies for components **outside the Platform**  | No access definied at this level yet | General namespace to separate App or Team specific resources from Container Platform related resources            |
+| NR                | /bcgov/apps/nr                                                | Natural Resources Sector                                        | NR Team                              |      Reserved for components outside the Platform                                                                                                             |
+| NR                | /bcgov/apps/nr/non-prod                                       | Natural Resources Sector Non-Prod                               | Access propagated from parent        | Reserved for components outside the Platform                                                                                                                          |
+| NR                | /bcgov/apps/nr/non-prod/calgary                               | Natural Resources Sector Non-Prod Calgary                       | Access propagated from parent        | Reserved for components outside the Platform                                                                                                                          |
 ### Namespace Automation
 There are two key automations in place for Aporeto Namespace management: 
 - The Aporeto Operator synchronizes OpenShift projects into child namespaces
@@ -54,7 +60,7 @@ There are two key automations in place for Aporeto Namespace management:
 
 
 ## Base Policies 
-A series of "base" policies exist for the container platform specifically. These base policies are applied relative to the namespaces they need to be enforced upon; for example, the lab base policies are maintained in `/bcgov/platform-services/non-production/kamloops/lab/ocp311` while the production pathfinder base policies are maintained in `/bcgov/platform-services/production/kamloops/pathfinder`. These base policies are used to ensure that the OpenShift platform operates correctly with Aporeto deployed and are configured during the installation of Aporeto into the platform. They do not leverage the **BCGov NetworkSecurityPolicy Operator** for managing policy, and as a result, these policies can only be managed by the Aporeto ansible playbook or through the Aporeto CLU/UI with the appropriate permissions. The playbook is the preferred method for updating base policies and ensuring all changes are captured in code. 
+A series of ["base" policies](../build/ansible/templates/network_access_policies) exist for the container platform specifically. These base policies are applied relative to the namespaces they need to be enforced upon; for example, the lab base policies are maintained in `/bcgov/platform-services/non-production/kamloops/lab/ocp311` while the production pathfinder base policies are maintained in `/bcgov/platform-services/production/kamloops/pathfinder`. These base policies are used to ensure that the OpenShift platform operates correctly with Aporeto deployed and are configured during the installation of Aporeto into the platform. They do not leverage the [**BCGov NetworkSecurityPolicy Operator**](../architecture/high_level_design.md#the-bcgov-networksecuritypolicy-operator) that is used for managing application specific access policies, and as a result, these policies can only be managed by the Aporeto ansible playbook or through the Aporeto CLU/UI with the appropriate permissions. The playbook is the preferred method for updating base policies and ensuring all changes are captured in code. 
 
 Please refer to the **Playbook Flow** section of the Ansible [Build Docs ](../build/ansible/readme.md#playbook-flow-install) for a list of the base policies and their descriptions. These are created in the `apply_policies.yml` section of the playbook. 
 
@@ -65,18 +71,19 @@ There are no hard restrictions on what developers will use for naming their poli
 Developers can use any name that they wish for the `object-name`, however, it should be easy to determine what the policy does by it's name. This will help other team members when they are reviewing these objects. Some examples are outlined in the [developer guide](../docs/CustomPolicy.md). 
 
 ### Fallback Policies 
-Aporeto has a concept of **Fallback Policies** that can be used to generate a more permissive and forgiving policy that would be used if users have not created any other matching policy. It was determined that with the desire to achieve a Zero Trust network enforcement policy that fallback policies are not leveraged in this deployment. New container-platform teams will start to consider the desired network flow of their applications and will **manually create NetworkSecurityPolicy objects to allow network traffic to flow**. 
+Aporeto has a concept of **Fallback Policies** that can be used to generate a more permissive and forgiving policy that would be used if users have not created any other matching policy. It was determined that with the desire to achieve a Zero Trust network enforcement policy that fallback policies are not leveraged in this deployment. New container-platform teams will need to consider the desired network flow of their applications as early as the design phase and will **manually create NetworkSecurityPolicy objects** at the first deployment to allow network traffic to flow. 
 
 ### Developer Controlled Policies
-Each OpenShift project/namespace is directly mapped to an Aporeto child namespace and developers are enabled to create/read/edit/delete Network Access Policies for their applications. This is achieved through the **BCGov NetworkSecurityPolicy Operator** and Custom Resources. Please refer to the [Developer Docs](../docs/README.md) for additional details and instructions. 
+Each OpenShift project/namespace is directly mapped to an Aporeto child namespace and developers are enabled to create/read/edit/delete Network Access Policies for their applications. This is achieved through the **BCGov NetworkSecurityPolicy Operator** and `NetworkSecurityPolicy` custom resources. Please refer to the [Developer Docs](../docs/README.md) for additional details and instructions. 
 
-**Please Note:** Child namespace Network Access Policies cannot override policies that are created at a parent or higher level. This permites teams to create more granular policies for their applications, but security teams within government can apply high-level policies that are propagated to these child namespaces. 
+**:point_up: Note**
+> Child namespace Network Access Policies cannot override policies that are created at a parent or higher level. This permites teams to create more granular policies for their applications, but security teams within government can apply high-level policies that are propagated to these child namespaces. 
 
 ## Operations
 This section describes any additional operational design decisions that apply to this solution. 
 
 ### Audit
-The Aporeto SaaS solution provides a complete audit trail of every CRUD activity. It has a search engine that can be used to identify actions taken by specific users. 
+The [Aporeto Console SaaS](../readme.md#accessing-the-console) solution provides a complete audit trail of every policy CRUD activity. It has a search engine that can be used to identify actions taken by specific users. 
 
 ### Backup
 A backup CronJob has been created to backup all configurations and policy within the `/bcgov` namespace on a daily basis. This can be used as secondary audit trail of daily configuration changes and can be leveraged if needed to re-import specific configurations into the Aporeto SaaS console. These backups are stored in the private git repo [bcgov-c/platform-secops-netpol](https://github.com/bcgov-c/platform-secops-netpol). Please refer to that repository for more details if you have the required access. 

security/aporeto/docs/CustomPolicy.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-This tutorial will guide you through creating application identities for each of your deployable components (pods) within your OpenShift Container Platform (OCP) namespaces as well as building custom `NetworkSecurityPolicy` (NSP) based on these identities to secure communications between your components.
+This tutorial will guide you through creating application identities for each of your deployable components (pods) within your OpenShift Container Platform (OCP) namespaces as well as building custom application network security/access policy via `NetworkSecurityPolicy` (NSP) objects based on these identities to secure communications between your components.
 
 By the end of the document you will be able to create policy to manage:
 
@@ -20,7 +20,7 @@ __Application Identity__
 
 You build application identity by adding labels to the metadata portion of your OCP deployment manifests. For example, in the deployment manifest excerpt below the combination of labels build a unique application identity which can be referenced in the NSP to permit communication.
 
-Its worth noting that each deployment config should have at least one label that uniquely identifies it. In the example below this is accomplished using the `role=api` label; no other deployment will use this specific label. See the **Naming Convention** section below for best practices. 
+Its worth noting that each deployment config should have at least one label that uniquely identifies it. In the example below this is accomplished using the `role=api` label; no other deployment will use this specific label. See the **Application Identity Naming Convention** section below for best practices. 
 
 ```yaml
 - kind: DeploymentConfig
@@ -44,7 +44,7 @@ Its worth noting that each deployment config should have at least one label that
 * Add the `role=` label to each deployment config of your manifest to uniquely identify the pods.
 
 
-## Naming Convention
+## Application Identity Naming Convention
 
 The naming convention you use for labels that allow you to build your application identity should be no more complicated than necessary.
 
@@ -85,20 +85,20 @@ The `env` label will change based on the namespace the deployment targets and th
 * K.I.S - Keep It (your labels) Simple; don't try and outsmart yourself.
 * Where possible use the naming convention proposed here for uniformity across projects.
 
-## Policy
+## Custom Access Policies
 
-The policy below will provide most teams enough to get up and running in short order; Customize them with labels or template parameters as needed. If you find the sample policy below does not suite your needs contact platform services to help create more advanced policy.
+The access policies below will provide most teams enough to get up and running in short order. Customize them with labels or template parameters as needed. If you find the sample policy below does not suite your needs contact platform services to help create more advanced access policy.
 
 In the subsections below we'll use one or more tags to identify the source and destination systems. The relevance if `source` and `destination` is that the application identified in the `source` will be able to open a network connection to the application identified in `destination`; Once a connection is open then data is able to flow bidirectionally.
 
 | Field | Required | Description     |
 | ----------- |:--------:|:---------------|
-| name        | YES      | Use this field to uniquely identify policy. |
+| name        | YES      | Use this field to uniquely identify policy. Check out the [naming conventions](../architecture/design_decisions.md#policy-naming-conventions)  for custom network security policies. |
 | description | YES      | A brief description of what the policy does. |
 | source      | YES      | Tags used to identify the application that can initiate a network connection. |
 | destination | YES      | Tags used to identify the application that receives the network connection.
 
-See the `samples` folder accompanying these instructions for more information.
+See the [`samples` file](./sample/quickstart-nsp.yaml) accompanying these instructions for more information.
 
 ### Namespace to OCP API
 
@@ -108,7 +108,7 @@ The OCP has an internal API that your environment needs to communicate with to r
 apiVersion: secops.pathfinder.gov.bc.ca/v1alpha1
 kind: NetworkSecurityPolicy
 metadata:
-  name: pods-to-api
+  name: custom-pods-to-api-[APP_NAME]
 spec:
   description: |
     Allow pods to talk to the internal OCP api 
@@ -129,7 +129,7 @@ This sample policy is used to allow pods to communicate within a given namespace
 apiVersion: secops.pathfinder.gov.bc.ca/v1alpha1
 kind: NetworkSecurityPolicy
 metadata:
-  name: web2api-permit
+  name: custom-web2api-permit-[APP_NAME]
 spec:
   description: |
     allow the Web pod(s) to communicate to the API pod(s).
@@ -153,7 +153,7 @@ The sample below allows the Web pod(s) to accept connections to from the Interne
 kind: NetworkSecurityPolicy
 apiVersion: secops.pathfinder.gov.bc.ca/v1alpha1
 metadata:
-  name: external-ingress
+  name: custom-external-ingress-[APP_NAME]
 spec:
   description: |
     Allow the frontend (web) to receive connections from the Internet.
@@ -179,7 +179,7 @@ The sample below allows the API pod(s) to open connections to any system on the
 kind: NetworkSecurityPolicy
 apiVersion: secops.pathfinder.gov.bc.ca/v1alpha1
 metadata:
-  name: internal-egress
+  name: custom-internal-egress-[APP_NAME]
 spec:
   description: |
     Allow the backend (API) to open connections to the
@@ -202,7 +202,7 @@ The sample below allows the API pod(s) to open connections to a specific pod(s)
 kind: NetworkSecurityPolicy
 apiVersion: secops.pathfinder.gov.bc.ca/v1alpha1
 metadata:
-  name: ns2ns-comms
+  name: custom-ns2ns-comms-[APP_NAME]
 spec:
   description: |
     Allow the backend (API) to open connections to backend (API) pod(s)
@@ -236,7 +236,7 @@ This can be configured in a single NetworkSecurityPolicy object. Apply the follo
 apiVersion: secops.pathfinder.gov.bc.ca/v1alpha1
 kind: NetworkSecurityPolicy
 metadata:
-  name: allow-alpha-and-bravo-to-talk
+  name: custom-allow-alpha-and-bravo-to-talk-[APP_NAME]
 spec:
   description: |
     Allow all pods in alpha and bravo to communicate