diff --git a/how-to/index.rst b/how-to/index.rst index ac28f42..087887b 100644 --- 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 new file mode 100644 index 0000000..6487d7f --- /dev/null +++ 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 `_ + diff --git a/how-to/security/checklist.rst b/how-to/security/checklist.rst new file mode 100644 index 0000000..427819e --- /dev/null +++ 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 new file mode 100644 index 0000000..49c7672 --- /dev/null +++ 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 `_ +* `OpenStack Security Guide `_ +* `Canonical OpenStack Docs `_ + diff --git a/how-to/security/hardening.rst b/how-to/security/hardening.rst new file mode 100644 index 0000000..10b56d7 --- /dev/null +++ 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 `_ +* :doc:`checklist` +* :doc:`authentication` + diff --git a/how-to/security/incident-response.rst b/how-to/security/incident-response.rst new file mode 100644 index 0000000..7ef6140 --- /dev/null +++ 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 new file mode 100644 index 0000000..5130ddd --- /dev/null +++ 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 new file mode 100644 index 0000000..4e4b3a6 --- /dev/null +++ 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 + diff --git a/how-to/security/logging-monitoring.rst b/how-to/security/logging-monitoring.rst new file mode 100644 index 0000000..76da2ff --- /dev/null +++ b/how-to/security/logging-monitoring.rst @@ -0,0 +1,63 @@ +================================= +Logging, Auditing, and Monitoring +================================= + +.. _security-logging: + +Comprehensive logging and monitoring provide traceability, compliance, +and rapid incident response. + +Centralised Logging +=================== + +* Aggregate logs via Loki, Elastic, or other secure collectors. +* Protect log transport using TLS. +* Enforce retention and access controls. +* Enable log integrity checks (e.g., hash chains or WORM storage). + +Keystone Authentication Middleware Logs +======================================= + +The Keystone auth middleware (``keystonemiddleware.auth_token``) records +token validation, user identification, and policy enforcement events. + +Example locations: + +- ``/var/log/keystone/keystone.log`` +- API service logs containing middleware messages (e.g., Nova API logs) + +Enable verbose logging for token validation if required for audits: + +.. code-block:: ini + + [keystone_authtoken] + http_request_debug = true + log_level = INFO + +Auditing +======== + +* Enable audit notifications in Keystone, Nova, and Neutron. +* Forward audit events to a SIEM or monitoring system. +* Retain logs per compliance (e.g. 90–180 days). + +Monitoring and Alerting +======================= + +* Monitor certificate expiry, failed logins, API latency, and service availability. +* Integrate with Prometheus or Canonical Observability Stack. +* Define thresholds and alert routing to the on-call team. + +Security Analytics +================== + +* Correlate Keystone authentication anomalies (e.g., multiple failed tokens). +* Detect large volume API bursts (potential abuse). +* Use dashboards for per-service security posture. + +References +========== + +* :doc:`authentication` +* `Keystonemiddleware Docs `_ + diff --git a/how-to/security/ports.rst b/how-to/security/ports.rst new file mode 100644 index 0000000..652ac10 --- /dev/null +++ b/how-to/security/ports.rst @@ -0,0 +1,29 @@ +============================= +Ports and Protocols Reference +============================= + +.. _security-ports: + +This reference lists default service ports for Canonical OpenStack (Sunbeam) deployments. +Use it to configure firewalls and validate exposed endpoints. + +Core Services +============= + +.. include:: includes/openstack-ports-full.rst + +Port Security Guidance +====================== + +* Allow inbound access only from trusted networks. +* Prefer TLS-enabled ports (e.g., 5671 instead of 5672). +* Disable HTTP on 80 when HTTPS (443) is enabled. +* Restrict SSH (22) to management or bastion hosts. +* Periodically scan with ``ss -tuln`` or ``nmap`` to confirm open ports. + +References +========== + +* :doc:`hardening` +* `OpenStack Firewall Reference `_ +