Merge "Security Planning shall support customer expectations"

doc/source/.vscode/settings.json

@@ -1,3 +1,4 @@
 {
-    "restructuredtext.confPath": ""
+    "restructuredtext.confPath": "",
+    "esbonio.sphinx.confDir": ""
 }

doc/source/planning/kubernetes/container-security-df8a251ec03f.rst

@@ -0,0 +1,128 @@
+.. _container-security-df8a251ec03f:
+
+===========================
+Container Security Planning
+===========================
+
+The following container security best practices are recommended as part of your
+network security planning. 
+
+Restrict Direct (SSH) Access to Kubernetes Nodes
+------------------------------------------------
+
+To reduce the risk of unauthorized access to host resources, only system
+administrators should be allowed SSH access to |prod| nodes. Non-system admin
+users should be restricted to helm and kubectl for remote access.
+
+Use Role-based Access Control (RBAC)
+------------------------------------
+
+Define RBAC policies to exercise strict control over permissions granted to
+non-admin users. Restrict non-admin users to the minimum level of privileges. 
+
+Use Namespaces
+--------------
+
+Use Namespaces to partition application resources into logical groups to allow
+the creation of RBAC policies to managing access to these resources as a whole.
+
+Use Network Policies
+--------------------
+
+Use network policies to restrict pod-to-pod traffic to approved profiles.
+
+Segregate Sensitive Workloads
+-----------------------------
+
+Use a combination of node taints and pod toleration to ensure that pods do not
+get scheduled onto inappropriate nodes.
+
+For sole-tenant nodes, use node selectors to segregate applications from
+tenants on different worker nodes to minimize container-escape scope to
+applications of the sole-tenant.
+
+Define Resource Quotas and Resource Limits Policies
+---------------------------------------------------
+
+Do not allow the configuration of resource-unbounded containers as this puts
+the system at risk of Denial-of-Service or “noisy neighbor” scenarios.
+
+Specify Minimal-Required Security Context for Pods
+--------------------------------------------------
+
+Explicitly specify the minimal-required security context for pods, containers
+and volumes through pod security policies, for example: 
+
+-   runAsNonRoot
+
+-   Capabilities
+
+-   readOnlyRootFilesystem
+
+---------------
+Kata Containers
+---------------
+
+Kata containers are an optional capability on |prod| that provide a secure
+container runtime with lightweight virtual machines that feel and perform like
+containers, but provide stronger workload isolation. For improved performance
+wrt isolation, Kata containers leverages hardware-enforced isotation with
+virtualization VT extensions.   
+
+For more information, see :ref:`starlingx-kubernetes-user-tutorials-overview`.
+
+---------------------
+Pod Security Policies
+---------------------
+
+Pod security policies provide a cluster-level resource that controls the use
+of security-sensitive aspects of Pod security. PodSecurityPolicies (PSP) define
+different levels of access to security-sensitive aspects of the pod. RBAC
+[Cluster]Roles can then be created for these PSPs, with RBAC
+[Cluster]RoleBindings of these roles to a ‘subject’ (i.e. users, groups,
+serviceaccounts, etc.). 
+
+The following considerations apply to PodSecurityPolicies (PSPs): 
+
+-   includes enabling or disabling options such as running as root, access to
+    host filesystem, access to host networking, etc.
+
+-   are disabled by default  
+
+-   can be enable by the System Administor via **system service-parameter-add
+    kubernetes kube_apiserver admission_plugins=PodSecurityPolicy**
+
+|prod| provides default PSP and RBAC definitions to simplify initial
+usage:
+
+-   Define a ‘restrictive’ and ‘privileged’ PSP, and corresponding
+    representative RBAC Roles
+
+-   Define initial RBAC RoleBindings for these roles such that:
+
+    -    cluster-admin can still perform anything / anywhere
+
+    -    authenticated users can only perform a restricted set of
+         security-sensitive options on Pods and only in namespaces the user
+         is allowed to access
+    
+Administrator can then: 
+
+-    create other custom PodSecurityPolicies and associated RBAC Roles
+
+-    create [Cluster]RoleBindings to the appropriate ‘subjects’.
+
+
+------------------------------------
+Container Image Signature Validation 
+------------------------------------
+
+The Portieris admission controller allows you to enforce image security polices
+to:
+
+-   enforce trust pinning and blocks creation of resources that use untrusted
+    images
+
+-   access trusted data in Notary server corresponding to the image
+
+For more information about Portieris, including installation instructions, see :ref:'portieris-overview'.

doc/source/planning/kubernetes/index-planning-kub-913bd621ac0f.rst

@@ -8,9 +8,9 @@
       :start-after: kub-begin
       :end-before: kub-end
 
-************
+------------
 Introduction
-************
+------------
 
 .. toctree::
    :maxdepth: 1
@@ -96,7 +96,47 @@ Security planning
 .. toctree::
    :maxdepth: 1
 
-   security-planning-uefi-secure-boot-planning
+   infrastructure-security
+   container-security-df8a251ec03f
+
+Security hardening Guidelines
+*****************************
+
+.. toctree::
+   :maxdepth: 1
+
+   security-hardening-intro
+
+Recommended Security Features with a Minimal Performance Impact
+---------------------------------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   uefi-secure-boot
+
+Secure System Accounts
+----------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   local-linux-account-for-sysadmin
+   local-and-ldap-linux-user-accounts
+   starlingx-accounts
+   web-administration-login-timeout
+   ssh-and-console-login-timeout
+   system-account-password-rules
+
+Security Features
+-----------------
+
+.. toctree::
+   :maxdepth: 1
+
+   secure-https-external-connectivity
+   security-hardening-firewall-options
+   isolate-starlingx-internal-cloud-management-network
 
 **********************************
 Installation and resource planning

doc/source/planning/kubernetes/infrastructure-security.rst

@@ -0,0 +1,189 @@
+
+.. qzw1552672165570
+.. _infrastructure_security:
+
+=======================
+Infrastructure Security
+=======================
+
+A key aspect of planning your installation and configuration is addressing
+infrastructure security. By planning your configuration to include industry
+standard best practices prior to deployment, you can reduce the risk of
+security and compliance issues.
+
+---------------------------------------
+|prod| Infrastructure Security Features
+---------------------------------------
+
+The security features listed below are available with |prod| and should be
+included in your infrastructure security planning.
+
+-    Regular CVE scanning and fixing of |prod| Platform’s CentOS Kernel and RPM
+     Packages
+         
+-   UEFI Secure Boot on |prod| Hosts
+
+    -    Signed boot loaders, initramfs, kernel and kernel modules
+
+    -    Signed in formal builds with |prod| private key on |prod| secure
+         signing server
+
+    -    Validated by board-specific UEFI Secure Boot Firmware
+
+    For more information, see :ref:`Kubernetes_UEFI_Secure_Boot_Planning`
+    
+-   Signed ISOs and Patches/Updates
+
+    -    Signed in formal builds with |prod| private key on |prod| secure
+         signing server
+
+    -    Public key built into ISO and patch signature validation code
+
+    -    Signatures checked on load import and update import commands
+
+-   Authentication and Authorization on all interfaces of:
+
+    -    SSH / Local Console (local LDAP)
+    
+         -    Linux User/Group Permissions
+ 
+         -    Linux sudo
+ 
+    -    |prod| REST APIs/CLIs (Keystone - local DB)
+    
+         -    Keystone Roles - admin, member
+ 
+    -    Kubernetes APIs/CLIs (Service Accounts and Remote LDAP / Windows
+         Active Directory via OIDC/DEX)
+
+         -    K8S RBAC Policies
+
+    -    |prod| Dashboard Webserver (Keystone - Local DB)
+
+         -    Keystone Roles - admin, member
+
+    -    Local Docker Registry (Keystone - Local DB)
+
+         - Keystone - admin, non-admin user
+
+-   HTTPS Support for all external Platform endpoints including:
+
+    -    System, Kubernetes, local docker registry REST APIs
+
+    -    Platform Dashboard Webserver
+
+    -   Certificate Management for K8S Certificates
+        
+        -    Bootstrap configured K8S Root CA Certificates (auto-generated or
+             user-specified)
+
+        -    Cron Jobs for renewing K8S server & client Certificates
+            
+        -    Procedure for updating K8S Root CA Certificate
+
+    -   Certificate Management for HTTPS Platform endpoints  (StarlingX APIs,
+        Registry, OIDC, …) including use of Cert-Manager for install and
+        auto-renewal of Certificates
+
+
+    -   Trusted CA Management for local client-side certificate validation
+
+    -   Alarming of soon-to-expired and expired Certificates
+
+    -   ‘show-certs.sh’ for displaying status and residual time for all
+        certificates.
+
+-   Secure (HTTPS) Platform management network communication in Distributed
+    Cloud providing secure management network connectivity between the system
+    controller and subclouds with auto-renewal of certificates
+
+-   OAM / API Firewall includes default firewall rules automatically applied
+    and customer modifiable through Calico network policies
+
+-   Helm v3 support including the removal of the default use of Helmv2/Tiller
+    (insecure)
+     
+-   Secure User Management including:
+
+    -    User Password Complexity enforcement
+
+    -    User forced log out on idle activity
+
+    -    User temporary lock out on N consecutive authentication failures
+
+-   Audit logs for operator commands and authentication events
+
+    -    Shell commands (on SSH / Local Console)
+
+    -    StarlingX REST APIs / CLIs
+
+    -    All logs can be sent to external Log Server using Wind River Analytics
+         application
+
+-   Linux Auditd support for running on all hosts with configurable rules
+
+-   OpenScap Modules included in Host ISO
+
+-   Security Services for Hosted Applications including:
+
+    -    Cert Manager support including integration of the cert-manager project
+         to automate the management and issuance of TLS certificates from
+         various issuing sources (e.g. interface with external CA for
+         certificate signing, auto-renewal of certificates)
+
+    -   Secure secret management and storage  (Hashicorp Vault) with the
+        integration of upstream Hashicorp Vault project and Support Vault
+        general secret management for hosted applications
+
+.. _Kubernetes_UEFI_Secure_Boot_Planning:
+
+------------------------------------
+Kubernetes UEFI Secure Boot Planning
+------------------------------------
+
+|UEFI| Secure Boot Planning allows you to authenticate modules before they are
+allowed to execute.
+
+The initial installation of |prod| should be done in |UEFI| mode if you plan on
+using the secure boot feature in the future.
+
+The |prod| secure boot certificate can be found in the |prod| ISO, on the EFI
+bootable FAT filesystem. The file is in the directory /CERTS. You must add this
+certificate database to the motherboard's |UEFI| certificate database. How to
+add this certificate to the database is determined by the |UEFI| implementation
+provided by the motherboard manufacturer.
+
+You may need to work with your hardware vendor to have the certificate
+installed.
+
+There is an option in the |UEFI| setup utility that allows a user to browse to
+a file containing a certificate to be loaded in the authorized database. This
+option may be hidden in the |UEFI| setup utility unless |UEFI| mode is enabled,
+and secure boot is enabled.
+
+Many motherboards ship with Microsoft secure boot certificates pre-programmed
+in the |UEFI| certificate database. These certificates may be required to boot
+|UEFI| drivers for video cards, |RAID| controllers, or |NICs| \(for example,
+the |PXE| boot software for a |NIC| may have been signed by a Microsoft
+certificate\). While certificates can be removed from the certificate database
+\(this is |UEFI| implementation specific\) it may be required that you keep the
+Microsoft certificates to allow for complete system operation.
+
+Mixed combinations of secure boot and non-secure boot nodes are supported. For
+example, a controller node may secure boot, while a worker node may not. Secure
+boot must be enabled in the |UEFI| firmware of each node for that node to be
+protected by secure boot.
+
+.. _security-planning-uefi-secure-boot-planning-ul-h4z-lzg-bjb:
+
+-   Secure Boot is supported in |UEFI| installations only. It is not used when
+    booting |prod| as a legacy boot target.
+
+-   |prod| does not currently support switching from legacy to |UEFI| mode
+    after a system has been installed. Doing so requires a reinstall of the
+    system. This means that upgrading from a legacy install to a secure boot
+    install \(|UEFI|\) is not supported.
+
+-   When upgrading a |prod| system from a version that did not support secure
+    boot to a version that does, do not enable secure boot in |UEFI| firmware
+    until the upgrade is complete.

doc/source/planning/kubernetes/security-planning-uefi-secure-boot-planning.rst

@@ -1,54 +0,0 @@
-
-.. qzw1552672165570
-.. _security-planning-uefi-secure-boot-planning:
-
-====================================
-Kubernetes UEFI Secure Boot Planning
-====================================
-
-|UEFI| Secure Boot Planning allows you to authenticate modules before they are
-allowed to execute.
-
-The initial installation of |prod| should be done in |UEFI| mode if you plan on
-using the secure boot feature in the future.
-
-The |prod| secure boot certificate can be found in the |prod| ISO, on the EFI
-bootable FAT filesystem. The file is in the directory /CERTS. You must add this
-certificate database to the motherboard's |UEFI| certificate database. How to
-add this certificate to the database is determined by the |UEFI| implementation
-provided by the motherboard manufacturer.
-
-You may need to work with your hardware vendor to have the certificate
-installed.
-
-There is an option in the |UEFI| setup utility that allows a user to browse to
-a file containing a certificate to be loaded in the authorized database. This
-option may be hidden in the |UEFI| setup utility unless |UEFI| mode is enabled,
-and secure boot is enabled.
-
-Many motherboards ship with Microsoft secure boot certificates pre-programmed
-in the |UEFI| certificate database. These certificates may be required to boot
-|UEFI| drivers for video cards, |RAID| controllers, or |NICs| \(for example,
-the |PXE| boot software for a |NIC| may have been signed by a Microsoft
-certificate\). While certificates can be removed from the certificate database
-\(this is |UEFI| implementation specific\) it may be required that you keep the
-Microsoft certificates to allow for complete system operation.
-
-Mixed combinations of secure boot and non-secure boot nodes are supported. For
-example, a controller node may secure boot, while a worker node may not. Secure
-boot must be enabled in the |UEFI| firmware of each node for that node to be
-protected by secure boot.
-
-.. _security-planning-uefi-secure-boot-planning-ul-h4z-lzg-bjb:
-
--   Secure Boot is supported in |UEFI| installations only. It is not used when
-    booting |prod| as a legacy boot target.
-
--   |prod| does not currently support switching from legacy to |UEFI| mode
-    after a system has been installed. Doing so requires a reinstall of the
-    system. This means that upgrading from a legacy install to a secure boot
-    install \(|UEFI|\) is not supported.
-
--   When upgrading a |prod| system from a version that did not support secure
-    boot to a version that does, do not enable secure boot in |UEFI| firmware
-    until the upgrade is complete.

doc/source/planning/openstack/uefi-secure-boot-planning.rst

@@ -8,5 +8,4 @@ UEFI Secure Boot Planning
 
 You may want to plan for utilizing the supported |UEFI| secure boot feature.
 
-See :ref:`Kubernetes UEFI Secure Boot Planning
+See :ref:`infrastructure_security` for details.
-<security-planning-uefi-secure-boot-planning>` for details.

doc/source/security/kubernetes/index-security-kub-81153c1254c3.rst

@@ -224,46 +224,6 @@ Security Feature Configuration for Spectre and Meltdown
 
    security-feature-configuration-for-spectre-and-meltdown
 
-*****************************
-Security Hardening Guidelines
-*****************************
-
-.. toctree::
-   :maxdepth: 1
-
-   security-hardening-intro
-
-Recommended Security Features with a Minimal Performance Impact
-***************************************************************
-
-.. toctree::
-   :maxdepth: 1
-
-   uefi-secure-boot
-
-Secure System Accounts
-**********************
-
-.. toctree::
-   :maxdepth: 1
-
-   local-linux-account-for-sysadmin
-   local-and-ldap-linux-user-accounts
-   starlingx-accounts
-   web-administration-login-timeout
-   ssh-and-console-login-timeout
-   system-account-password-rules
-
-Security Features
-*****************
-
-.. toctree::
-   :maxdepth: 1
-
-   secure-https-external-connectivity
-   security-hardening-firewall-options
-   isolate-starlingx-internal-cloud-management-network
-
 ************************
 Deprecated Functionality
 ************************