From 0e92680875385fcd16f1a9285f69d0005ee97320 Mon Sep 17 00:00:00 2001 From: Zach Stone Date: Thu, 16 Jul 2026 15:57:59 -0700 Subject: [PATCH 1/3] chore: update security platform docs for staleness --- .../overview/security/platform-security/index.md | 12 +++++------- .../tutorials/security/policy-enforcement/index.md | 4 ++-- 2 files changed, 7 insertions(+), 9 deletions(-) diff --git a/src/content/overview/security/platform-security/index.md b/src/content/overview/security/platform-security/index.md index e8f160fe42..3b9d7f7f69 100644 --- a/src/content/overview/security/platform-security/index.md +++ b/src/content/overview/security/platform-security/index.md @@ -15,7 +15,7 @@ user_questions: - How do I enforce admission policies in my cluster? - What can I do to keep my clusters secure? - What security services and tools does Giant Swarm offer? -last_review_date: 2026-06-22 +last_review_date: 2026-07-16 owner: - https://github.com/orgs/giantswarm/teams/team-shield --- @@ -33,7 +33,6 @@ The stack consists of multiple distinct components which are independently insta | CIS Benchmarks | Trivy Operator | In Catalog | [Trivy Operator][trivy-operator-app] | | Cloud Security Posture | Evaluating | Planned | | | Runtime Anomalies | Falco | In Catalog | [Falco][falco-app] | -| In-Cluster Registry | Harbor | In Catalog | [Harbor][harbor-app] | | Log Alerting | Supported by both Falco and our [managed Observability Bundle][observability-bundle] offering. | In Catalog | [Loki][loki-app] / [Falco][falco-app] | | Log Shipping + Storage | Supported by our [managed Loki][loki-app] offering. | In Catalog | [Loki][loki-app] | | Advanced Network Capabilities* | Supported by our managed Connectivity Bundle offering. | In Catalog | [Cilium][cilium-app] | @@ -47,9 +46,9 @@ A high-level overview of each component is included below. Please refer to the G ## Trivy -Trivy is a vulnerability scanner created by [Aqua Security][trivy-upstream]. It can be run as a command-line tool (for example, in a CI/CD pipeline) or as a Kubernetes operator, which we deploy from our [Trivy App][trivy-app]. When running as an operator, Trivy can be used as the scanning backend for a Harbor container registry, and as the scanner used by Trivy Operator. +Trivy is a vulnerability scanner created by [Aqua Security][trivy-upstream]. It can be run as a command-line tool (for example, in a CI/CD pipeline) or as a Kubernetes operator, which we deploy from our [Trivy App][trivy-app]. When running in-cluster, it acts as the scanning backend used by Trivy Operator. -Within our managed security stack, Trivy is deployed in-cluster as the backend for Trivy Operator and Harbor (if in use). We also recommend customers enable vulnerability scanning in their CI/CD pipelines and include support for that integration as part of our managed offering. +Within our managed security stack, Trivy is deployed in-cluster as the backend for Trivy Operator. We also recommend customers enable vulnerability scanning in their CI/CD pipelines and include support for that integration as part of our managed offering. ## Trivy Operator @@ -124,7 +123,7 @@ Report: ... ``` -Kubernetes CIS benchmark reports can similarly be retrieved with `$ kubectl get ciskubebenchreport -A` and `kubectl describe`. +Kubernetes CIS and NSA compliance reports can similarly be retrieved with `$ kubectl get clustercompliancereport` and `kubectl describe`. The underlying host and infrastructure checks that feed these compliance reports are stored in `InfraAssessmentReport` and `ClusterInfraAssessmentReport` resources. ### Reporting and monitoring @@ -162,7 +161,7 @@ replex-k8s-agent polr-ns-replex-k8s-agent 9 0 0 0 0 Simply `kubectl get -o yaml` a report to see detailed information about the policies in place, plus any recorded violations. Reports can also be visualized through the included web UI by port forwarding it to your local machine: ```bash -$ kubectl port-forward service/kyverno-ui 8080:8080 -n +$ kubectl port-forward service/kyverno-policy-reporter-ui 8080:8080 -n Forwarding from 127.0.0.1:8080 -> 8080 Forwarding from [::1]:8080 -> 8080 ... @@ -182,7 +181,6 @@ We include Falco in our managed security stack as a detection mechanism for mali [cilium-app]: https://github.com/giantswarm/cilium-app/ [falco-app]: https://github.com/giantswarm/falco-app [falco-upstream]: https://github.com/falcosecurity/falco -[harbor-app]: https://github.com/giantswarm/harbor-app [kube-bench]: https://github.com/aquasecurity/kube-bench [kyverno-app]: https://github.com/giantswarm/kyverno-app [kyverno-upstream]: https://github.com/kyverno/kyverno/ diff --git a/src/content/tutorials/security/policy-enforcement/index.md b/src/content/tutorials/security/policy-enforcement/index.md index 0e230204c6..9c076769d3 100644 --- a/src/content/tutorials/security/policy-enforcement/index.md +++ b/src/content/tutorials/security/policy-enforcement/index.md @@ -18,7 +18,7 @@ user_questions: - How can I run a container as a certain user? - How can I run a container as privileged? - Why is my container lacking permission to use a persistent volume? -last_review_date: 2026-07-02 +last_review_date: 2026-07-16 mermaid: true layout: single owner: @@ -1132,7 +1132,7 @@ There are different ways to structure a `PolicyException`, and your cluster admi Giant Swarm currently suggests a "PolicyException per workload" approach, which looks like this: ```yaml -apiVersion: kyverno.io/v2beta1 +apiVersion: kyverno.io/v2 kind: PolicyException metadata: name: my-workload-exceptions From 9ab5d93f5ff6d9767cc12b4b2b7445d97dc18205 Mon Sep 17 00:00:00 2001 From: Zach Stone Date: Thu, 16 Jul 2026 16:30:22 -0700 Subject: [PATCH 2/3] gs polex touchups --- .../security/platform-security/index.md | 7 +++++-- .../tutorials/security/policy-api/index.md | 6 +++++- .../security/policy-enforcement/index.md | 20 +++++++++++++++++++ 3 files changed, 30 insertions(+), 3 deletions(-) diff --git a/src/content/overview/security/platform-security/index.md b/src/content/overview/security/platform-security/index.md index 3b9d7f7f69..1a17746d7c 100644 --- a/src/content/overview/security/platform-security/index.md +++ b/src/content/overview/security/platform-security/index.md @@ -11,7 +11,7 @@ aliases: user_questions: - How do I view and manage vulnerabilities in my cluster? - What UI options are there for vulnerability and policy reports? - - What is included in the Security Bundle? + - Which components make up the Giant Swarm security platform? - How do I enforce admission policies in my cluster? - What can I do to keep my clusters secure? - What security services and tools does Giant Swarm offer? @@ -171,6 +171,8 @@ Open your browser to `localhost:8080` to view the reports. More detailed information about the use of Kyverno for Pod Security Standards (PSS) policy enforcement, including exception management is available in our separate [policy enforcement documentation][policy-enforcement]. +Giant Swarm manages the lifecycle of these policies and their exceptions with additional components, including the `kyverno-policy-operator` and the `exception-recommender`. These are exposed through our [Policy API][policy-api], which lets you declare policy intent without managing the underlying Kyverno resources directly. + ## Falco Falco is a [CNCF project][falco-upstream] originally created by Sysdig which enables rule-based detection of runtime anomalies in a container or on a host Node. Falco watches Linux system calls (syscalls) for events matching a predefined set of suspicious or malicious activities. Examples include reading a sensitive file or executing a shell inside a container. @@ -179,6 +181,7 @@ We include Falco in our managed security stack as a detection mechanism for mali [app-platform]: {{< relref "/overview/fleet-management/app-management" >}} [cilium-app]: https://github.com/giantswarm/cilium-app/ +[envoy-gateway-app]: https://github.com/giantswarm/envoy-gateway-app [falco-app]: https://github.com/giantswarm/falco-app [falco-upstream]: https://github.com/falcosecurity/falco [kube-bench]: https://github.com/aquasecurity/kube-bench @@ -186,6 +189,7 @@ We include Falco in our managed security stack as a detection mechanism for mali [kyverno-upstream]: https://github.com/kyverno/kyverno/ [lens-extension]: https://github.com/aquasecurity/trivy-operator-lens-extension [loki-app]: https://github.com/giantswarm/loki-app +[policy-api]: {{< relref "/tutorials/security/policy-api" >}} [policy-enforcement]: {{< relref "/tutorials/security/policy-enforcement" >}} [policy-reporter-upstream]: https://github.com/kyverno/policy-reporter [observability-bundle]: {{< relref "/overview/observability" >}} @@ -196,4 +200,3 @@ We include Falco in our managed security stack as a detection mechanism for mali [trivy-operator-app]: https://github.com/giantswarm/trivy-operator-app [trivy-operator-upstream]: https://github.com/aquasecurity/trivy-operator [vscode-trivy]: https://github.com/aquasecurity/trivy-vscode-extension -[envoy-gateway-app]: https://github.com/giantswarm/envoy-gateway-app diff --git a/src/content/tutorials/security/policy-api/index.md b/src/content/tutorials/security/policy-api/index.md index 357e28df23..0e73b1daeb 100644 --- a/src/content/tutorials/security/policy-api/index.md +++ b/src/content/tutorials/security/policy-api/index.md @@ -12,7 +12,7 @@ user_questions: - How can I exclude a workload from a Kyverno policy? - What security policies are enforced in my cluster? - What is the Policy API? -last_review_date: 2026-07-02 +last_review_date: 2026-07-16 owner: - https://github.com/orgs/giantswarm/teams/team-shield --- @@ -74,6 +74,10 @@ spec: Based on this exception, the Policy API controllers will generate additional resources and make configuration changes to any tools which enforce the listed policies. +#### PolicyExceptionDrafts + +Giant Swarm clusters can also suggest exceptions for you. The `exception-recommender` inspects policy reports and generates `PolicyExceptionDraft` resources containing suggestions for the exceptions a workload would need. A cluster administrator reviews a draft and, if appropriate, promotes it to a `PolicyException`. For the full workflow, see [generating exceptions automatically]({{< relref "/tutorials/security/policy-enforcement" >}}#generating-exceptions-automatically) on the policy enforcement page. + ### Motivation / historical note The Giant Swarm platform is built upon a number of independent tools, projects, and APIs supported by the CNCF and the surrounding Kubernetes ecosystem. diff --git a/src/content/tutorials/security/policy-enforcement/index.md b/src/content/tutorials/security/policy-enforcement/index.md index 9c076769d3..a4f7f22922 100644 --- a/src/content/tutorials/security/policy-enforcement/index.md +++ b/src/content/tutorials/security/policy-enforcement/index.md @@ -1077,6 +1077,12 @@ spec: {{% /details %}} +## Optional policies + +Beyond the Pod Security Standards enforced by default, Giant Swarm's [`kyverno-policies`](https://github.com/giantswarm/kyverno-policies) include additional policies that clusters can opt into. These cover a range of concerns related to security, governance, and best practices. + +These policies aren't enforced unless you enable them. Refer to the [`kyverno-policies` repository](https://github.com/giantswarm/kyverno-policies) for the full, current list. + ## Policy exceptions If a workload requires an exception, for example because it has a legitimate reason to run with a less secure configuration, the workload can be excluded from enforcement of a particular policy. @@ -1123,6 +1129,20 @@ Various `Policy` API components watch these resources and make the corresponding For policies which are enforced or audited by multiple distinct tools, a Giant Swarm `PolicyException` can be used to declaratively configure all of the underlying implementations simultaneously. +#### Generating exceptions automatically + +Working out exactly which policies a workload violates can be tedious. To reduce that toil, Giant Swarm offers the [`exception-recommender`](https://github.com/giantswarm/exception-recommender), which watches `PolicyReport`s for policy violations and drafts the exceptions a workload would need. + +For each affected workload, it creates a `PolicyExceptionDraft` ([`policy.giantswarm.io/v1alpha1`]({{< relref "/reference/platform-api/crd/policyexceptiondrafts.policy.giantswarm.io" >}})). A draft has no enforcement of its own, it only documents the exceptions a workload would need to pass admisison given the active policies and workload state. + +To turn a suggestion into a real exception: + +1. Review the generated `PolicyExceptionDraft` for the workload. +2. If the excepted access is acceptable, promote it to a Giant Swarm `PolicyException`. The draft uses the same schema, so this is mostly a matter of changing the resource kind. +3. The `kyverno-policy-operator` reconciles the `PolicyException` into the underlying Kyverno `PolicyException`, exactly as it does for exceptions you write by hand. + +This workflow keeps a human in the loop but eliminates the guesswork of writing the exception logic. The approval and deployment can be automated within existing security review processes. + ### Configuring exceptions with Kyverno Cluster administrators may prefer to manage exceptions themselves. In this case, it's necessary to create the underlying Kyverno policy exception directly. From 7b5878c03b0b76100d2fd20e1b3703db697814b9 Mon Sep 17 00:00:00 2001 From: Zach Stone Date: Thu, 16 Jul 2026 16:54:40 -0700 Subject: [PATCH 3/3] sharing secrets and other touchups --- src/content/overview/security/_index.md | 4 ++-- .../security/platform-security/index.md | 7 ++---- .../security/sharing-secrets/index.md | 24 ++++++++++++------- .../security/policy-enforcement/index.md | 2 +- 4 files changed, 20 insertions(+), 17 deletions(-) diff --git a/src/content/overview/security/_index.md b/src/content/overview/security/_index.md index 43a3da10e9..0d429a884d 100644 --- a/src/content/overview/security/_index.md +++ b/src/content/overview/security/_index.md @@ -6,7 +6,7 @@ menu: principal: parent: overview identifier: overview-security -last_review_date: 2025-07-02 +last_review_date: 2026-07-16 owner: - https://github.com/orgs/giantswarm/teams/team-shield --- @@ -37,7 +37,7 @@ Our platform leverages several cloud-native technologies to deliver these securi - **Falco**: An open-source runtime security project, Falco monitors your Kubernetes environment for runtime anomalies, providing real-time detection of suspicious activities. -- **Prometheus and Grafana**: Used for log alerting and monitoring, Prometheus collects and stores metrics, while Grafana provides a customizable dashboard for visualizing and setting up alerts based on these metrics. +- **Mimir, Loki, and Grafana**: Alloy collects metrics and logs to be stored by Mimir and Loki, respectively. Grafana provides customizable dashboards and alerting across both. - **Cilium**: Container networking plugin that provides advanced network capabilities, including DNS-based network policies and traffic encryption to secure communication within your clusters. diff --git a/src/content/overview/security/platform-security/index.md b/src/content/overview/security/platform-security/index.md index 1a17746d7c..219add9ac7 100644 --- a/src/content/overview/security/platform-security/index.md +++ b/src/content/overview/security/platform-security/index.md @@ -67,7 +67,6 @@ Scan data can be accessed: - using `kubectl` - from the Trivy Operator Grafana dashboard - directly in Prometheus -- using the [Trivy Operator extension for Lens][lens-extension] - using the [Trivy extension for VS Code][vscode-trivy] (for working with Trivy scans offline) #### Using kubectl @@ -144,7 +143,7 @@ Kyverno is a [CNCF project][kyverno-upstream] originally created by Nirmata whic As part of the security offering, Kyverno provides enforcement for PSS policies and image signing, plus custom policies provided by customers using the stack. -Policy violations are stored in `PolicyReport` CRs and exposed as Prometheus metrics via [policy-reporter][policy-reporter-upstream]. You can retrieve the reports via `kubectl`: +Policy violations are stored in `PolicyReport` CRs and exposed as Prometheus metrics via [policy-reporter][policy-reporter-upstream]. For large fleets, Kyverno can offload these reports from etcd into a dedicated `reports-server` (an aggregated API server backed by a database) to reduce etcd pressure; this is available but disabled by default. You can retrieve the reports via `kubectl`: ```bash $ kubectl get polr -A @@ -171,7 +170,7 @@ Open your browser to `localhost:8080` to view the reports. More detailed information about the use of Kyverno for Pod Security Standards (PSS) policy enforcement, including exception management is available in our separate [policy enforcement documentation][policy-enforcement]. -Giant Swarm manages the lifecycle of these policies and their exceptions with additional components, including the `kyverno-policy-operator` and the `exception-recommender`. These are exposed through our [Policy API][policy-api], which lets you declare policy intent without managing the underlying Kyverno resources directly. +Giant Swarm manages the lifecycle of these policies and their exceptions with additional components, including the `kyverno-policy-operator` and the `exception-recommender`. These are exposed through our [Policy API]({{< relref "/tutorials/security/policy-api" >}}), which lets you declare policy intent without managing the underlying Kyverno resources directly. ## Falco @@ -187,9 +186,7 @@ We include Falco in our managed security stack as a detection mechanism for mali [kube-bench]: https://github.com/aquasecurity/kube-bench [kyverno-app]: https://github.com/giantswarm/kyverno-app [kyverno-upstream]: https://github.com/kyverno/kyverno/ -[lens-extension]: https://github.com/aquasecurity/trivy-operator-lens-extension [loki-app]: https://github.com/giantswarm/loki-app -[policy-api]: {{< relref "/tutorials/security/policy-api" >}} [policy-enforcement]: {{< relref "/tutorials/security/policy-enforcement" >}} [policy-reporter-upstream]: https://github.com/kyverno/policy-reporter [observability-bundle]: {{< relref "/overview/observability" >}} diff --git a/src/content/overview/security/sharing-secrets/index.md b/src/content/overview/security/sharing-secrets/index.md index 7b016c1fb7..98714a7741 100644 --- a/src/content/overview/security/sharing-secrets/index.md +++ b/src/content/overview/security/sharing-secrets/index.md @@ -12,21 +12,27 @@ owner: user_questions: - How do I share a secret with Giant Swarm? - How do I share cloud provider credentials with Giant Swarm? -last_review_date: 2024-11-26 +last_review_date: 2026-07-16 --- -Getting started with Giant Swarm involves an initial setup that includes sharing some credentials with us. It can also happen that some other secrets need to be shared along our partnership, as customers progress in their cloud-native journey. Our goal is that customers can share secrets in the easiest and most secure ways: hence, in this page two different tools are presented for sharing secrets with us. +Getting started with Giant Swarm involves an initial setup that includes sharing some credentials with us, and other secrets may need to be shared as our partnership grows. Our goal is to make sharing secrets with us as easy and secure as possible. There are two ways to do it. -## Option #1: Using `Keybase` +## Use your own secure sharing method -The [`Keybase`](https://keybase.io/) project provides a secure messaging and file-sharing app that enjoys end-to-end encryption by means of public-key cryptography. In other words, every user has its own private-public key pair for sending messages securely. Since messages are encrypted using the recipient's public key, only the recipient can decrypt them as it's the only entity owning the private key needed for decryption. +We're happy to receive secrets through whatever secure sharing method you already use. Ask your Giant Swarm engineer, agree on a method that works for both sides, and confirm it before sending anything sensitive. -If `Keybase` is your tool of choice for sharing secrets with us, ask our engineer for their `Keybase` username, verify with them that everything is working, and share the secret securely with them. +One convenient command-line option is [`age`](https://github.com/FiloSottile/age), which can encrypt a file to the public keys attached to a GitHub profile. Ask your engineer for their GitHub username, then encrypt your secret to their keys: -## Option #2: Using `age` +```bash +curl https://github.com/.keys | age --recipients-file - my_secret.txt > my_secret.txt.age +``` -The [`age`](https://github.com/FiloSottile/age) project offers a simple command-line tool that allows for encrypting secrets easily and in a classic UNIX-style fashion. A lovely feature about `age` is the possibility to encrypt messages using the public keys associated with a `GitHub` profile. +Share the resulting `.age` file with the engineer, who can decrypt it with their private key. To decrypt a secret that's been shared with you, run: -If `age` is your tool of choice for sharing secrets with us, ask our engineer for their `GitHub` username, run a command such as `curl https://github.com/.keys | age --recipients-file - my_secret.txt > my_secret.txt.age` in your shell and share the `.age` file with the engineer. The engineer will be able to decrypt it using their private key. +```bash +age --decrypt -i -o my_secret.txt my_secret.txt.age +``` -In case you need to decrypt a secret shared with you, run a command such as `age --decrypt -i -o my_secret.txt my_secret.txt.age` in your shell. +## Let us create a 1Password share item + +Alternatively, we can create a [1Password](https://1password.com/) share item and send you a secure link to exchange the secret. Ask your Giant Swarm engineer to set one up. diff --git a/src/content/tutorials/security/policy-enforcement/index.md b/src/content/tutorials/security/policy-enforcement/index.md index a4f7f22922..bb7cba1e6b 100644 --- a/src/content/tutorials/security/policy-enforcement/index.md +++ b/src/content/tutorials/security/policy-enforcement/index.md @@ -1133,7 +1133,7 @@ For policies which are enforced or audited by multiple distinct tools, a Giant S Working out exactly which policies a workload violates can be tedious. To reduce that toil, Giant Swarm offers the [`exception-recommender`](https://github.com/giantswarm/exception-recommender), which watches `PolicyReport`s for policy violations and drafts the exceptions a workload would need. -For each affected workload, it creates a `PolicyExceptionDraft` ([`policy.giantswarm.io/v1alpha1`]({{< relref "/reference/platform-api/crd/policyexceptiondrafts.policy.giantswarm.io" >}})). A draft has no enforcement of its own, it only documents the exceptions a workload would need to pass admisison given the active policies and workload state. +For each affected workload, it creates a `PolicyExceptionDraft` ([`policy.giantswarm.io/v1alpha1`]({{< relref "/reference/platform-api/crd/policyexceptiondrafts.policy.giantswarm.io" >}})). A draft has no enforcement of its own, it only documents the exceptions a workload would need to pass admission given the active policies and workload state. To turn a suggestion into a real exception: