canonical · wolsen · Oct 15, 2025
diff --git a/how-to/index.rst b/how-to/index.rst
@@ -40,3 +40,12 @@ Troubleshooting
    :maxdepth: 2
 
    troubleshooting/index
+
+Security
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   security/index
+
diff --git a/how-to/security/authentication.rst b/how-to/security/authentication.rst
@@ -0,0 +1,66 @@
+================================
+Authentication and Authorization
+================================
+
+.. _security-authentication:
+
+This guide focuses on identity management, Fernet tokens, and service credentials.
+
+Keystone Overview
+=================
+
+Keystone provides authentication, authorization, and service discovery for OpenStack.  
+Sunbeam configures Keystone automatically and registers service users via Juju.
+
+Key Concepts
+------------
+
+* **Domains**: logical boundaries for users and projects.
+* **Projects**: map to tenants or teams.
+* **Roles**: define permissions; assign to users per project or domain.
+
+Example commands:
+
+.. code-block:: bash
+
+   openstack user create --domain default --project demo demo-user
+   openstack role add --project demo --user demo-user member
+
+Fernet Token Management
+=======================
+
+Sunbeam supports only Fernet tokens for authentication.  
+These are lightweight, stateless, and cryptographically signed.
+
+* Keys are distributed and rotated via Juju secrets.
+* Default rotation interval: 30–90 days.
+* Rotation command (for reference):
+
+.. code-block:: bash
+
+   juju run keystone/leader "keystone-manage fernet_rotate"
+
+Juju Secrets and Service Authentication
+=======================================
+
+All inter-service credentials (e.g., Nova→Keystone, Neutron→RabbitMQ) are exchanged using **Juju secrets**.
+
+* Secrets are encrypted and versioned automatically.
+* They can be revoked, refreshed, and audited.
+* Avoid storing credentials in plain charm config.
+
+Federated Identity (Optional)
+=============================
+
+Keystone supports SAML or OIDC federation for SSO.
+
+* Validate IdP metadata signatures.
+* Map external attributes carefully to local roles.
+* Restrict project scopes for federated users.
+
+References
+==========
+
+* :doc:`logging-monitoring`
+* `Keystone Security Guide <https://docs.openstack.org/keystone/latest/admin/>`_
+
diff --git a/how-to/security/checklist.rst b/how-to/security/checklist.rst
@@ -0,0 +1,55 @@
+============================
+Security Hardening Checklist
+============================
+
+.. _security-checklist:
+
+This checklist summarises key items to verify for a secure OpenStack Sunbeam environment.  
+For detailed procedures, refer to :doc:`hardening`.
+
+Infrastructure and OS
+=====================
+
+- [ ] Ubuntu LTS with all updates applied
+- [ ] Minimal package set installed
+- [ ] AppArmor/SELinux enabled
+- [ ] SSH key-based access only
+- [ ] Auditd configured and active
+
+Networking
+==========
+
+- [ ] Management and tenant networks isolated
+- [ ] Firewalls restrict only required ports (see :doc:`ports`)
+- [ ] TLS configured on all APIs
+- [ ] Neutron security groups enforced
+
+Identity and Access
+===================
+
+- [ ] Keystone users and roles follow least privilege
+- [ ] Fernet keys rotated regularly
+- [ ] Juju secrets verified and limited to intended services
+
+Storage and Secrets
+===================
+
+- [ ] Encrypted Cinder volumes and Glance backends
+- [ ] Secrets rotated and securely backed up
+- [ ] Vault or Juju secret audit logs enabled
+
+Monitoring and Response
+=======================
+
+- [ ] Centralised logs with TLS transport
+- [ ] Alerts for failed auth and certificate expiry
+- [ ] Backup and restore tested quarterly
+- [ ] Incident response procedures documented
+
+References
+==========
+
+* :doc:`hardening`
+* :doc:`logging-monitoring`
+* :doc:`incident-response`
+
diff --git a/how-to/security/compliance.rst b/how-to/security/compliance.rst
@@ -0,0 +1,34 @@
+=========================
+Compliance and References
+=========================
+
+.. _security-compliance:
+
+This section maps Canonical OpenStack (Sunbeam) security practices 
+to common frameworks and provides further reading.
+
+CIS and Ubuntu Baselines
+========================
+
+Ubuntu security baselines align with CIS Benchmarks for Linux hosts.  
+Operators can use `CIS-CAT` or `OpenSCAP` to validate compliance.
+
+FIPS 140-3 and Cryptography
+===========================
+
+OpenStack services rely on system OpenSSL libraries; 
+Ubuntu FIPS builds can be used where certification is required.
+
+ISO / SOC2 Alignment
+====================
+
+Canonical infrastructure guidance supports traceability and 
+auditability suitable for ISO 27001 or SOC2 environments.
+
+Canonical Security Resources
+============================
+
+* `Ubuntu Pro and Livepatch <https://ubuntu.com/pro>`_
+* `OpenStack Security Guide <https://docs.openstack.org/security-guide/>`_
+* `Canonical OpenStack Docs <https://canonical-openstack.readthedocs-hosted.com>`_
+
diff --git a/how-to/security/hardening.rst b/how-to/security/hardening.rst
@@ -0,0 +1,60 @@
+=========================
+Hardening Guide
+=========================
+
+.. _security-hardening:
+
+This guide describes steps to secure a Canonical OpenStack (Sunbeam) deployment before 
+and after it is installed.
+
+Pre-Deployment Hardening
+========================
+
+* Use minimal Ubuntu LTS images.
+* Apply all security updates and enable unattended-upgrades.
+* Disable password logins, allow SSH key-based access only.
+* Enable AppArmor or SELinux.
+* Configure firewall rules before deployment.
+* Verify Juju controller TLS certificates.
+
+Network and Service Isolation
+=============================
+
+* Isolate management, API, tenant, and storage traffic.
+* Limit inbound ports (see :doc:`ports`).
+* Restrict inter-service communication using TLS.
+* Use separate networks or VLANs for control plane and data plane.
+* Apply security groups for tenant isolation.
+
+Juju and Secrets
+================
+
+* Use Juju secrets for all credential exchanges between charms.
+* Rotate secrets periodically and revoke unused ones.
+* Restrict Juju controller access to trusted admins only.
+* Store Juju controller backups encrypted and offline.
+
+Host and Container Security
+===========================
+
+* Remove unused packages and services.
+* Enforce least-privilege for system daemons.
+* Enable kernel hardening (ASLR, NX bit, StackProtector).
+* Use minimal container images; enforce read-only rootfs and drop privileges.
+* Audit container profiles periodically.
+
+Runtime Practices
+=================
+
+* Keep packages patched via unattended-upgrades or Canonical Livepatch.
+* Rotate Fernet keys every 30–90 days.
+* Enable log forwarding and auditing (see :doc:`logging-monitoring`).
+* Perform quarterly security scans and reviews.
+
+References
+==========
+
+* `Ubuntu Security <https://ubuntu.com/security>`_
+* :doc:`checklist`
+* :doc:`authentication`
+
diff --git a/how-to/security/incident-response.rst b/how-to/security/incident-response.rst
@@ -0,0 +1,48 @@
+==============================
+Incident Response and Recovery
+==============================
+
+.. _security-incident-response:
+
+Preparation and planning are key to responding effectively to security incidents.
+
+Preparation
+===========
+
+* Define roles and responsibilities.
+* Maintain offline copies of Fernet keys, certificates, and Juju backups.
+* Document contact paths and escalation procedures.
+
+Detection
+=========
+
+* Review logs for anomalies and failed authentication bursts.
+* Use monitoring alerts for token abuse or service instability.
+
+Containment
+===========
+
+* Revoke or rotate compromised secrets with Juju.
+* Rotate Fernet keys on Keystone leader.
+* Restrict network access to affected services.
+
+Eradication and Recovery
+========================
+
+* Rebuild compromised hosts from trusted images.
+* Re-deploy charms to refresh configurations.
+* Validate service health post-recovery.
+
+Post-Incident Review
+====================
+
+* Document root cause and mitigation.
+* Apply lessons learned to hardening and configuration.
+* Update :doc:`checklist` and incident runbooks.
+
+References
+==========
+
+* :doc:`logging-monitoring`
+* :doc:`hardening`
+
diff --git a/how-to/security/includes/openstack-ports-full.rst b/how-to/security/includes/openstack-ports-full.rst
@@ -0,0 +1,68 @@
+Ports Used by OpenStack Services (Extended List)
+================================================
+
+Below is a more comprehensive list of default ports used by various OpenStack services (API endpoints, agents, data plane) based largely on the upstream “Firewalls and default ports” documentation. :contentReference[oaicite:0]{index=0}  
+Operators should verify actual port bindings (some can be customized) and only open what is strictly required.
+
+.. note::
+   Ports may differ in your deployment (e.g. TLS vs non-TLS, custom overrides). Always check configuration in your charms, Juju relations, and service charmed layers.
+
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| Service / Component              | Port(s) / Protocol     | Notes                                                               |
++==================================+========================+=====================================================================+
+| Keystone (Identity)              | 5000 TCP               | Public / internal API endpoint                                      |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| Glance (Image)                   | 9292 TCP               | Image service API                                                   |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| Nova (Compute API)               | 8774 TCP               | Compute API                                                         |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| Nova metadata service            | 8775 TCP               | Metadata service (VM metadata)                                      |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| VNC / console proxy              | 5900-5999 TCP          | VM console ports                                                    |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| Nova noVNC proxy                 | 6080 TCP               | Browser-based console access                                        |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| HTML5 console proxy              | 6082 TCP               | Alternative console proxy                                           |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| Placement API                    | 8003 TCP               | Placement service                                                   |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| Heat (Orchestration)             | 8004 TCP               | Heat API                                                            |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| Heat CloudFormation API          | 8000 TCP               | Heat CFN API                                                        |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| Heat CloudWatch API              | 8003 TCP               | Heat CloudWatch-compatible API                                      |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| Cinder (Block Storage)           | 8776 TCP               | Block Storage API                                                   |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| Manila (Shared FS)               | 8786 TCP               | Manila share API                                                    |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| Neutron (Networking)             | 9696 TCP               | Neutron API                                                         |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| Octavia (Load Balancer)          | 9876 TCP               | Octavia API / control                                               |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| Barbican (Key Manager)           | 9311 TCP               | Secret / key storage API                                            |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| Ironic (Bare Metal)              | 6385 TCP               | Ironic API – bare metal provisioning                                |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| Designate (DNS)                  | 9001 TCP               | DNS API                                                             |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| CloudKitty (Rating / Billing)    | 8889 TCP               | CloudKitty API                                                      |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| Aodh (Alarming)                  | 8042 TCP               | Alarm / notification API                                            |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| Magnum (Container orchestration) | 9511 TCP               | Magnum API / orchestration                                          |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| MySQL                            | 3306 TCP               | Database backend (TLS enabled where possible)                       |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| RabbitMQ (AMQP / AMQPS)          | | 5671 TCP (TLS)       | Message bus for inter-service communication                         |
+|                                  | | 5672 TCP (non-TLS)   |                                                                     |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| HTTP / Dashboard Horizon         | 80 TCP                 | If Horizon is exposed insecurely                                    |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| HTTPS / Dashboard Horizon        | 443 TCP                | Recommended for dashboard / APIs                                    |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| iSCSI target for Cinder          | 3260 TCP               | Required when using iSCSI-backed Cinder volumes                     |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+| NVMe-oF target for Cinder        | 4420 TCP               | If using NVMe-over-Fabrics for block storage                        |
++----------------------------------+------------------------+---------------------------------------------------------------------+
+
diff --git a/how-to/security/index.rst b/how-to/security/index.rst
@@ -0,0 +1,49 @@
+======================
+Security Overview
+======================
+
+.. _security-index:
+
+The Canonical OpenStack (Sunbeam) security documentation provides guidance for securing 
+your deployment from initial planning through day-to-day operations.
+
+This collection of guides covers host hardening, authentication and authorization, 
+secure secrets handling, port and network reference, logging and auditing, and incident response.
+
+Security Philosophy
+===================
+
+Canonical OpenStack is built on Ubuntu, leveraging its long-term security maintenance, 
+kernel livepatching, and strict package provenance. Sunbeam adds automation and 
+secure defaults via Juju, reducing operator error and improving repeatability.
+
+Security objectives include:
+
+* Protect confidentiality, integrity, and availability of infrastructure and tenant workloads.
+* Reduce attack surface across control plane and data plane.
+* Enforce cryptographic integrity for authentication and data in transit.
+* Enable secure, automated secret management with Juju.
+* Provide auditable and traceable change and access history.
+
+Defense Layers
+==============
+
+Security is achieved through layered defenses:
+
+1. **Host layer:** Ubuntu security, kernel hardening, AppArmor.
+2. **Deployment layer:** Juju relations, secrets, and automation.
+3. **Service layer:** OpenStack APIs, Keystone authentication, Fernet tokens.
+4. **Network layer:** Segmented management, storage, and tenant networks.
+5. **Operational layer:** Logging, auditing, and patching discipline.
+
+.. toctree::
+   :maxdepth: 2
+
+   hardening
+   checklist
+   ports
+   authentication
+   logging-monitoring
+   incident-response
+   compliance
+