add documentation for Marketplace security features

docs/manuals/marketplace/overview.md

@@ -7,8 +7,6 @@ description: How to use the Upbound Marketplace to discover Crossplane providers
   packages.
 ---
 
-# Overview
-
 [Upbound Marketplace][upbound-marketplace] simplifies your control plane journey
 with the largest registry for storing, managing, and sharing control plane
 extensions. It integrates seamlessly with Upbound's control plane project
@@ -38,6 +36,7 @@ Key features of the Upbound Marketplace include:
 - Unlimited public repositories
 - Private repositories
 - API docs
+- Image vulnerability and provenance data
 
 ## Verified publishers
 

docs/manuals/marketplace/security-features.md

@@ -0,0 +1,131 @@
+---
+title: Package Security Features
+sidebar_position: 3
+description: Navigating security features of Official Packages in the Upbound Marketplace
+---
+<!-- vale write-good.Passive = NO -->
+Official Packages are curated, tested Crossplane extensions hardened for
+enterprise production security requirements. The Upbound Marketplace provides
+several features for platform and security engineering teams to view, configure,
+and interact with these security artifacts.
+<!-- vale write-good.Passive = YES -->
+
+## Package vulnerabilities
+
+The Upbound Marketplace enables security teams to perform faster risk
+assessments without any image pulls or scans.
+
+### Vulnerability summaries
+
+<!-- vale gitlab.Uppercase = NO -->
+The version selector on an Official package listing displays a summary view of
+the most recent CVE counts by CVSS 3.0 severity class. This view provides an
+immediate visual indicator for spotting high-risk tags and choosing the best
+image for a deployment.
+<!-- vale gitlab.Uppercase = YES -->
+
+![image][summary]
+<!-- vale Microsoft.HeadingAcronyms = NO -->
+### CVE details
+
+Clicking a scanned version displays a Vulnerabilities tab and shows a table of
+the image's CVEs.
+
+![image][table]
+
+You can expand each CVE row to display details like:
+
+- severity, affected package name and version range, and available fix versions
+- links to official CVE references for multiple advisories
+- detailed description of the vulnerability and potential exploits
+- known exploits, if available
+
+![image][cve-detail]
+
+With these summary and detail views, users can make informed upgrade decisions
+and configure automation that use this data to gate or approve deployments.
+
+## Supply chain transparency
+
+The Upbound Marketplace also exposes the key supply chain metadata you need to
+verify image integrity and traceability.
+
+<!-- vale gitlab.Uppercase = NO -->
+### Provenance and SLSA attestations
+<!-- vale gitlab.Uppercase = YES -->
+
+The Upbound Marketplace surfaces [SLSA] provenance attestations for official
+packages produced by Upbound's build workflows. These are generated using
+[Sigstore] tooling and are immutable records of when, how, and by what process a
+package was built.
+
+To independently verify signatures and provenance, users can download the
+attestation and run the generated `cosign` commands in the `Provenance` tab of
+an official package.
+
+![image][cosign-verify]
+
+Cluster administrators can also configure Crossplane to verify signatures and attestations with an `ImageConfig`, rejecting pulls
+of any image that fail verification. Learn more about [configuring signature verification].
+
+### SBOM visibility
+
+Each official package also includes a simplified, human-readable SBOM directly
+in the Marketplace, allowing you to browse and filter its included packages and
+dependencies.
+
+For deeper inspection or automation, you can download the full SPDX-formatted
+SBOM and use it with external tools.
+
+![image][sbom]
+
+## FAQ
+<!-- vale Microsoft.HeadingAcronyms = YES -->
+
+<details>
+
+    <summary>How often are Official images scanned?</summary>
+
+    Official images are scanned twice a week with updated vulnerability databases. Minor versions first published within the last 6 months are eligible.
+
+</details>
+
+<details>
+
+    <summary>Why aren't all images scanned?</summary>
+
+    Currently, image vulnerabiltiy scans are only conducted on Official packages. The Upbound Marketplace does not have full visibility into the build processes of all images it receives, which can negatively impact the accuracy and precision of a scan artifact.
+
+</details>
+
+<details>
+
+    <summary>My personal scanner shows a discrepancy with the Marketplace. What is the scope of a vulnerability scan?</summary>
+
+    The data displayed in the Marketplace focuses on package-level vulnerabiltiies by analyizing the contents of the final image filesystem. This would exclude detection of issues in a Dockerfile or build instructions such as running as `root` or privilege escalation vectors.
+
+    Vulnerability matches against specific filesystem paths may also be filtered from the view. Currently, the Terraform binary used
+    in `provider-terraform` does not have its matches shown in the Marketplace, as the provider must pin to a `1.5.x` version indefinitely
+    due to [licensing] restrictions.
+
+</details>
+
+<details>
+
+    <summary>How do I know that the vulnerability scan or SBOM were produced by Upbound?</summary>
+
+    The vulnerability report and SBOM are embedded as signed attestations, meaning the build system signs a statement describing
+    these artifacts and their relation to the package. This signature provides cryptographic assurance that the attestations were 
+    produced by Upbound's build pipeline and have not been tampered with in transit.
+
+</details>
+
+[summary]: /img/marketplace-cve-summary.png
+[table]: /img/marketplace-cve-table.png
+[cve-detail]: /img/marketplace-cve-detail.png
+[Sigstore]: https://www.sigstore.dev/
+[cosign-verify]: /img/marketplace-cosign-commands.png
+[configuring signature verification]: /manuals/packages/providers/signature-verification
+[sbom]: /img/marketplace-simple-sbom.png
+[licensing]: https://www.hashicorp.com/en/license-faq
+[SLSA]: https://slsa.dev/

docs/manuals/spaces/howtos/self-hosted/deployment-reqs.md

@@ -58,10 +58,13 @@ rightsized the memory available in your Spaces cluster.
 <!-- vale gitlab.SentenceLength = YES -->
 
 :::important
-Be careful not to conflate `managed resource` with `custom resource definition`. The former is an "instance" of an external resource in Crossplane, while the latter defines the API schema of that resource.
+Be careful not to conflate `managed resource` with `custom resource definition`.
+The former is an "instance" of an external resource in Crossplane, while the
+latter defines the API schema of that resource. 
 :::
 
-It's estimated that each custom resource definition consumes ~3 MB of memory. The calculation is:
+It's estimated that each custom resource definition consumes ~3 MB of memory.
+The calculation is:
 
 ```bash
 number_of_managed_resources_defined_in_provider x 3 MB = memory_required
@@ -80,18 +83,23 @@ total memory: 429 MB
 In this scenario, you should budget ~430 MB of memory for provider usage on this control plane.
 
 :::tip
-Do this calculation for each provider you plan to install on your control plane. Then do this calculation for each control plane you plan to run in your Space.
+Do this calculation for each provider you plan to install on your control plane.
+Then do this calculation for each control plane you plan to run in your Space.
 :::
 
 
 #### Total memory usage
 
-Add the memory usage from the previous sections. Given the preceding examples, they result in a recommendation to budget ~1 GB memory for each control plane you plan to run in the Space.
+Add the memory usage from the previous sections. Given the preceding examples,
+they result in a recommendation to budget ~1 GB memory for each control plane
+you plan to run in the Space.
 
 :::important
 
 The 1 GB recommendation is an example.
-You should input your own provider requirements to arrive at a final number for your own deployment.
+You should input your own provider requirements to arrive at a final number for
+your own deployment.
+
 :::
 
 ### CPU considerations

utils/vale/styles/Upbound/spelling-exceptions.txt

@@ -113,6 +113,7 @@ shortcode
 shortcodes
 SharedSecretStore
 SharedExternalSecret
+Sigstore
 SLAs
 stdin
 stdout