docs(hosting): document security best practices and incident response

.gitbook.yaml

@@ -1,4 +1,5 @@
 redirects:
+    guides/hosting/installation-updates/security-plugin.html: guides/hosting/installation-updates/security-best-practices/security-plugin.html
     guides/hosting/configurations/shopware/staging.html: guides/hosting/installation-updates/creating-a-staging-instance.html
     developers-guide/plugin-guidelines/: https://developers.shopware.com/developers-guide/plugin-guidelines/
     guides/plugins/apps/platform-sh-template.html: guides/plugins/apps/app-base-guide.html
@@ -263,4 +264,3 @@ redirects:
     guides/installation/start-developing.html: guides/development/start-developing.html
     concepts/translations/: concepts/framework/translations/
     guides/hosting/installation-updates/deployments/deployment-helper.html: guides/hosting/installation-updates/deployments/deployment-helper/index.html
-

.wordlist.txt

@@ -291,6 +291,7 @@ CustomerRecoveryAware
 CustomerRecoveryStorer
 CustomerStorer
 CustomerTagRule
+Cyberattack
 CycloneDX
 DAL
 DBAL
@@ -1276,6 +1277,7 @@ bPlatform
 bRestApi
 bServiceExtension
 bTemplateExtension
+backdoors
 backend
 backends
 backface

guides/hosting/installation-updates/cluster-setup.md

@@ -108,10 +108,10 @@
 
 ### Security plugin
 
-For obtaining security fixes, without version upgrades, we provide a dedicated Security plugin.
-It is compatible with all Shopware versions, and the included fixes only activate on versions that are affected. In cluster setups, install it through Composer so all application servers receive the same code.
+Keep a compatible version of the Security Plugin installed, activated, and up to date, even when Shopware itself is fully updated.
+In cluster setups, install it through Composer so all application servers receive the same code.
 
-<PageRef page="security-plugin" />
+<PageRef page="security-best-practices/security-plugin" />
 
 ### Update of composer dependencies
 

guides/hosting/installation-updates/performing-updates.md

@@ -8,7 +8,10 @@ nav:
 
 ## When to update
 
-Shopware releases updates every month. It's not necessary to update every month, but you should always install the latest security patches through the [Security Plugin](https://store.shopware.com/en/swag136939272659f/shopware-6-security-plugin.html) or update Shopware itself to the latest version. To check if your Shopware version still gets security updates, you can check the [Shopware Release Cycle](https://developer.shopware.com/release-notes/).
+Shopware releases updates every month.
+Always apply security updates promptly and keep your Shopware version within [security support](https://developer.shopware.com/release-notes/#release-calendar).
+For self-hosted shops, keep the [Security Plugin](security-best-practices/security-plugin.md) installed, activated, and up to date, even when Shopware itself is fully updated.
+See [Security Best Practices](security-best-practices/index.md) for additional guidance.
 
 Generally speaking, the maintenance effort is the same whether you wait a long period or update more regularly. Our recommendation is to update from every major version to the next major version, and stay on a minor version for a longer period of time if you don't need any new features or encounter issues with the used version.
 

guides/hosting/installation-updates/security-best-practices/incident-response.md

@@ -0,0 +1,77 @@
+---
+nav:
+  title: Responding to a Cyberattack
+  position: 20
+
+---
+
+# Responding to a Cyberattack
+
+As soon as you suspect an attack is in progress, stop public traffic to the affected shop and isolate the affected systems.
+Work with your hosting provider to block access at the firewall or load balancer, including access to the Administration and APIs.
+Do not rely on the storefront maintenance page alone to contain an attack.
+
+## Get help and preserve evidence
+
+If you suspect an attack, contact your hosting provider and agency first for help with containment, investigation, and recovery.
+Shopware offers dedicated support options for security incidents, including for Community Edition users without a support subscription.
+Contact [Shopware Support](https://support.shopware.com/create-ticket) to discuss the assistance available for your situation.
+You do not need to wait until your investigation is complete.
+
+Preserve logs and forensic snapshots before deleting files, restarting services, or restoring backups.
+Record when you first noticed the attack and the actions you take.
+Do not delay containment while collecting evidence.
+
+## Investigate the entry point and impact
+
+Establish what happened, including:
+
+- How and when the attacker first entered the system, for example through a vulnerability or stolen credentials.
+- What level of access they gained, including Administration access, database access, or the ability to execute code on the server.
+- What they did with that access, including changes to files, configuration, accounts, orders, or payment flows, and access to or theft of customer data.
+- Whether other systems or connected services were affected.
+
+Look for anything that could give the attacker persistent access, such as backdoors, modified plugins, scheduled tasks, additional administrator accounts, or newly created integration credentials.
+The absence of obvious changes or log entries does not establish that the system is clean.
+
+AI agents can be particularly helpful for analysing large volumes of logs, identifying suspicious patterns, and reconstructing the attack timeline.
+Validate their findings against the original evidence and redact secrets and customer data before sending logs to an external service.
+
+## Remove attacker access and recover
+
+Once you understand the entry point, the access gained, and the attacker's actions, remove unauthorized access and reverse the malicious changes.
+Fix the weakness or compromised account that allowed the attack; removing a backdoor without closing the entry point leaves the shop exposed.
+
+::: warning
+If you suspect remote code execution, assume the entire affected system is compromised.
+Deleting visible backdoors or installing a security update is not enough to restore trust.
+The safe recovery path is to rebuild affected systems from trusted images and restore a verified backup from before the earliest suspected compromise.
+Check that the backup is clean: the attack may have started before you first noticed it.
+:::
+
+Apply the required security fixes to Shopware, extensions, dependencies, and infrastructure before making the recovered shop publicly accessible.
+
+## Rotate secrets before reopening
+
+From a trusted device and in the recovered environment, rotate credentials and secrets the attacker may have accessed.
+These can include Shopware administrator and integration credentials, database passwords, app secrets, hosting credentials, and keys for external services.
+Invalidate existing sessions and tokens.
+Make sure restoring a backup does not reintroduce compromised credentials or unauthorized accounts.
+
+Restore public traffic only after the entry point is closed, persistent access has been removed, recovery and credential changes are complete, and the shop has been tested.
+Monitor for signs of renewed attacker activity after reopening.
+
+## Check legal obligations promptly
+
+Especially if customer data may have been affected, consult a legal advisor promptly about your obligations, including possible notifications to affected customers, data protection authorities, or other relevant authorities.
+Reporting deadlines may apply before the investigation is complete; do not wait until recovery is finished to seek advice.
+For personal data breaches under the GDPR, see the [European Data Protection Board's guidance](https://www.edpb.europa.eu/sme/assess-the-risks/data-breaches_en).
+
+## Share your findings with Shopware
+
+Reach out to [Shopware Support](https://support.shopware.com/create-ticket) after the incident as well, even if you did not contact us during the active attack.
+Share the affected versions, timeline, entry point, access gained, attacker actions, and recovery measures as far as you have established them.
+This information helps us improve protections and keep the whole Shopware ecosystem safe.
+
+If you discover a previously unknown vulnerability, report it through our [security reporting page](https://www.shopware.com/en/contact/security-reporting/).
+Use private support or security-reporting channels for incident details, and avoid sending unnecessary customer data or secrets.

guides/hosting/installation-updates/security-best-practices/index.md

@@ -0,0 +1,70 @@
+---
+nav:
+  title: Security Best Practices
+  position: 25
+
+---
+
+# Security Best Practices
+
+This guide describes recommended security practices and how responsibilities differ by hosting model.
+For a more detailed list of Shopware's security mechanisms and how to configure them, see the [security reference](../../../../resources/references/security.md).
+If you suspect an attack, follow the [incident response guide](incident-response.md) immediately.
+
+## Understand your responsibilities
+
+With **Shopware SaaS**, Shopware operates and secures the platform and its infrastructure, including automatically applying platform updates and security patches.
+You do not need to manage servers or install the Security Plugin yourself.
+
+With **[Shopware PaaS Native](../../../../products/paas/shopware/index.md)**, Shopware manages the underlying infrastructure, including servers, networking, managed databases, and platform backups.
+A [web application firewall](../../../../products/paas/shopware/cdn/security-features.md) is enabled and configured by default.
+You or your agency remain responsible for the application: testing and deploying [Shopware updates](../../../../products/paas/shopware/guides/update-shopware.md), Security Plugin and other extension updates, Composer dependency updates, and security fixes to your custom code.
+Managed infrastructure and a firewall do not replace these application updates.
+
+In both models, you remain responsible for your configuration, access and user management, and the security of external apps and integrations you operate or connect.
+See section 29.2 of the [Shopware terms and conditions](https://www.shopware.com/en/gtc/) for the responsibility boundary.
+For **self-hosted installations**, you or your hosting provider also manage infrastructure security.
+
+The application update and extension recommendations below apply to self-hosted and PaaS Native shops.
+Infrastructure maintenance applies to the services you operate yourself.
+
+## Stay on a supported Shopware version
+
+Run a Shopware version that is still receiving security updates.
+Check the [release calendar](https://developer.shopware.com/release-notes/#release-calendar) to see which versions are supported and how security fixes are delivered.
+If your Shopware version is approaching its end of life, plan and complete an upgrade to a supported version before security support ends.
+Apply security updates promptly and keep your extensions and Composer dependencies up to date.
+
+## Keep the Security Plugin installed
+
+Always keep a compatible version of the Security Plugin installed, activated, and up to date, even when Shopware itself is fully updated.
+Having the plugin in place makes it easier to apply the next security update without waiting for a complete platform update.
+The plugin does not replace regular Shopware updates or extend security support for versions that have reached their end of life.
+
+See the [Security Plugin](security-plugin.md) guide for compatibility, installation, and details about the fixes it provides.
+
+## Keep your infrastructure supported
+
+For infrastructure you operate yourself, run supported versions of your operating system, PHP, database, web server, search engine, and cache or message queue services.
+Apply their vendors' security updates and check the [recommended stack and supported versions](../../index.md#recommended-stack-and-supported-versions) for compatibility with Shopware.
+
+Use PHP 8.4 or later on a compatible Shopware release, and keep it updated to the latest patch version of a supported PHP branch.
+PHP 8.4 introduced [driver-specific PDO SQL parsers](https://wiki.php.net/rfc/pdo_driver_specific_parsers), which protect against some [SQL injection techniques caused by parsing mismatches in older PHP versions](https://www.slcyber.io/research/a-novel-technique-for-sql-injection-in-pdos-prepared-statements).
+This is an additional protection layer and does not replace security fixes in Shopware or its extensions.
+On PaaS Native, select supported, compatible PHP and database versions in your [application configuration](../../../../products/paas/shopware/fundamentals/application-yaml.md) and deploy the change.
+
+## Manage extensions through deployments
+
+Consider disabling runtime extension management in production and managing extensions solely through Composer and a separate build and deployment process.
+On PaaS Native, runtime extension management is already disabled; extensions must be managed through Composer and deployments, as described in the [PaaS Native FAQ](../../../../products/paas/shopware/faq.md).
+
+Runtime plugin installation allows PHP code to be added to the running shop.
+An attacker who gains access to an account with extension installation privileges can use this capability to execute malicious code on the shop server.
+Disabling runtime extension management reduces this route from account compromise to remote code execution.
+
+As an additional benefit, managing extensions through deployments makes it easier to test new plugins and plugin updates in staging and catch compatibility issues before they affect your production shop.
+
+See [Extension Management](../extension-management.md) for the Composer workflow and the configuration to make the Administration's Extension Manager read-only.
+
+Use this deployment process for Security Plugin updates as well, and treat relevant security releases as urgent.
+Test and deploy them as soon as possible; do not wait for the next routine feature release or maintenance window.

guides/hosting/installation-updates/security-plugin.md → guides/hosting/installation-updates/security-best-practices/security-plugin.md

@@ -1,15 +1,22 @@
 ---
 nav:
   title: Security Plugin
-  position: 25
+  position: 10
 
 ---
 
 # Security Plugin
 
 The [Shopware 6 Security Plugin](https://store.shopware.com/en/swag136939272659f/shopware-6-security-plugin.html) (`SwagPlatformSecurity`) backports security fixes to existing Shopware installations. It allows you to close known security vulnerabilities with a simple plugin update, without upgrading Shopware itself. The plugin is free and maintained by Shopware.
 
-The plugin does not replace regular Shopware updates. It is meant to bridge the time until you can perform a proper update or to keep installations secure that cannot be updated immediately. Security issues in third-party dependencies such as Symfony or Twig are not covered by the plugin and still require a dependency or Shopware update — see [Third-party dependencies](#third-party-dependencies).
+For self-hosted and PaaS Native shops, always keep a compatible version of the plugin installed, activated, and up to date, even when Shopware itself is fully updated.
+Having the plugin in place makes it easier to apply the next security update promptly.
+Apply relevant plugin updates as soon as possible rather than waiting for a routine maintenance window.
+
+The plugin does not replace regular Shopware updates or extend support for versions that have reached their end of life.
+Your Shopware version must still receive security support; check the [release calendar](https://developer.shopware.com/release-notes/#release-calendar) for the currently supported versions.
+Additional hardening and broader security improvements are delivered in regular Shopware releases and are usually not backported through the plugin.
+Security issues in third-party dependencies such as Symfony or Twig are not covered by the plugin and still require a dependency or Shopware update — see [Third-party dependencies](#third-party-dependencies).
 
 ## Compatibility
 
@@ -22,7 +29,8 @@ The following table shows which plugin version covers each major Shopware versio
 | 2.x            | 6.5.x             | ✔️         |
 | 1.x            | 6.4.x             | ❌         |
 
-Within a plugin version, every fix declares the Shopware version range it applies to. A fix is only loaded when your Shopware version is affected: if your version already contains the official patch or is older than the first affected version, the fix stays inactive automatically. Installing the plugin on a fully patched installation is therefore safe. It simply does nothing until a new vulnerability is published.
+Within a plugin version, every fix declares the Shopware version range it applies to.
+A fix is only loaded when your Shopware version is affected: if your version already contains the official patch or is older than the first affected version, the fix stays inactive automatically.
 
 ## Installation
 
@@ -32,7 +40,7 @@ Install and activate the extension named "Shopware 6 Security Plugin" through th
 
 ### Through Composer
 
-For deployments built through CI or running on multiple application servers, install the plugin as a Composer dependency through the [Shopware Composer Registry](extension-management.md), so all nodes receive the same code:
+For deployments built through CI or running on multiple application servers, install the plugin as a Composer dependency through the [Shopware Composer Registry](../extension-management.md), so all nodes receive the same code:
 
 ```bash
 composer require store.shopware.com/swagplatformsecurity

resources/references/security.md

@@ -92,7 +92,7 @@ SameSite prevents the browser from sending cookies along with cross-site request
 
 ## Security plugin
 
-Obtaining security fixes without version upgrades is possible through the [Security plugin](../../guides/hosting/installation-updates/cluster-setup.md#security-plugin).
+For self-hosted shops, keep the [Security Plugin](../../guides/hosting/installation-updates/security-best-practices/security-plugin.md) installed, activated, and up to date, even when Shopware itself is fully updated.
 
 ## Storefront IP Whitelisting
 
@@ -102,6 +102,8 @@ To enable access even during maintenance mode, IP addresses can be added to [Sto
 
 SQL injection allows an attacker to execute new or modify existing SQL statements to access information that they are not allowed to access. Shopware primarily uses our own [Data Abstraction Layer](../../concepts/framework/data-abstraction-layer.md), which does not expose SQL directly, so most SQL injection attack vectors are prevented. Whenever direct SQL is being used, the [best practices from Doctrine DBAL](https://www.doctrine-project.org/projects/doctrine-dbal/en/current/reference/security.html) are followed to ensure proper escaping of user input.
 
+Use PHP 8.4 or later on a compatible Shopware release, as its [driver-specific PDO SQL parsers](https://wiki.php.net/rfc/pdo_driver_specific_parsers) help prevent some SQL injection cases.
+
 ## Exposing underlying technology
 
 Some features intentionally expose the underlying technology upon which they are built. For example, the underlying Twig templating system is exposed when the user provides mail templates, SEO URL templates, or Product Export templates. Similarly, direct CSS access is exposed over the theme configuration.