docs: add security considerations

docs/docs/architecture/security-considerations.md

@@ -0,0 +1,56 @@
+# Security Considerations
+
+Contrast ensures application integrity and provides secure means of communication and bootstrapping (see [security benefits](../basics/security-benefits.md)).
+However, care must be taken when interacting with the outside of Contrast's confidential environment.
+This page presents some tips for writing secure applications and outlines the trust boundaries app developers need to know.
+
+## General recommendations
+
+### Authentication
+
+The application receives credentials from the Contrast Coordinator during initialization.
+This allows to authenticate towards peers and to verify credentials received from peers.
+The application should use the certificate bundle to authenticate incoming requests and be wary of unauthenticated requests or requests with a different root of trust (for example the internet PKI).
+
+The recommendation to authenticate not only applies to network traffic, but also to volumes, GPUs and other devices.
+Generally speaking, all information provided by the world outside the confidential VM should be treated with due scepticism, especially if it's not authenticated.
+Common cases where Kubernetes apps interact with external services include DNS, Kubernetes API clients and cloud storage endpoints.
+
+### Encryption
+
+Any external persistence should be encrypted with an authenticated cipher.
+This recommendation applies to block devices or filesystems mounted into the container, but also to cloud blob storage or external databases.
+
+## Contrast security guarantees
+
+If an application authenticates with a certificate signed by the Contrast Mesh CA of a given manifest, Contrast provides the following guarantees:
+
+1. The container images used by the app are the images specified in the resource definitions.
+2. The command line arguments of containers are exactly the arguments specified in the resource definitions.
+3. All environment variables are either specified in resource definitions, in the container image manifest or in a settings file for the Contrast CLI.
+4. The containers run in a confidential VM that matches the reference values in the manifest.
+5. The containers' root filesystems are mounted in encrypted memory.
+
+### Limitations inherent to policy checking
+
+Workload policies serve as workload identities.
+From the perspective of the Contrast Coordinator, all workloads that authenticate with the same policy are equal.
+Thus, it's not possible to disambiguate, for example, pods spawned from a deployment or to limit the amount of certificates issued per policy.
+
+Container image references from Kubernetes resource definitions are taken into account when generating the policy.
+A mutable reference may lead to policy failures or unverified image content, depending on the Contrast runtime.
+Reliability and security can only be ensured with a full image reference, including digest.
+The [`docker pull` documentation] explains pinned image references in detail.
+
+Policies can only verify what can be inferred at generation time.
+Some attributes of Kubernetes pods can't be predicted and thus can't be verified.
+Particularly the [downward API] contains many fields that are dynamic or depend on the host environment, rendering it unsafe for process environment or arguments.
+The same goes for `ConfigMap` and `Secret` resources, which can also be used to populate container fields.
+If the application requires such external information, it should be injected as a mount point and carefully inspected before use.
+
+Another type of dynamic content are persistent volumes.
+Any volumes mounted to the pod need to be scrutinized, and sensitive data must not be written to unprotected volumes.
+Ideally, a volume is mounted as a raw block device and authenticated encryption is added within the confidential container.
+
+[`docker pull` documentation]: https://docs.docker.com/reference/cli/docker/image/pull/#pull-an-image-by-digest-immutable-identifier
+[downward API]: https://kubernetes.io/docs/concepts/workloads/pods/downward-api/

docs/docs/deployment.md

@@ -56,6 +56,11 @@ kubectl apply -f https://github.com/edgelesssys/contrast/releases/latest/downloa
 Your Kubernetes resources need some modifications to run as Confidential Containers.
 This section guides you through the process and outlines the necessary changes.
 
+### Security review
+
+Contrast ensures integrity and confidentiality of the applications, but interactions with untrusted systems require the developers' attention.
+Review the [security considerations](architecture/security-considerations.md) and the [certificates](architecture/certificates.md) section for writing secure Contrast application.
+
 ### RuntimeClass
 
 Contrast will add annotations to your Kubernetes YAML files. If you want to keep the original files

docs/sidebars.js

@@ -129,6 +129,11 @@ const sidebars = {
  label: 'Certificate authority',
  id: 'architecture/certificates',
  },
+ {
+ type: 'doc',
+ label: 'Security considerations',
+ id: 'architecture/security-considerations',
+ },
  {
  type: 'doc',
  label: 'Observability',