diff --git a/README.md b/README.md index f7d081db..029d1271 100644 --- a/README.md +++ b/README.md @@ -2,27 +2,13 @@ [![Go Reference](https://pkg.go.dev/badge/github.com/jetstack/jetstack-secure.svg)](https://pkg.go.dev/github.com/jetstack/jetstack-secure) [![Go Report Card](https://goreportcard.com/badge/github.com/jetstack/jetstack-secure)](https://goreportcard.com/report/github.com/jetstack/jetstack-secure) -![Jetstack Secure](./docs/images/js.png) - -[Jetstack Secure](https://www.jetstack.io/jetstack-secure/) manages your machine identities across Cloud Native Kubernetes and OpenShift environments and builds a detailed view of the enterprise security posture. - -This repo contains the open source in-cluster agent of Jetstack Secure, that sends data to the [Jetstack Secure -SaaS](https://platform.jetstack.io). - -> **Wondering about Preflight?** Preflight was the name for the project that was the foundation for the Jetstack Secure platform. It was a tool to perform configuration checks on a Kubernetes cluster using OPA's REGO policy. We decided to incorporate that functionality as part of the Jetstack Secure SaaS service, making this component a basic agent. You can find the old Preflight Check functionality in the git history ( tagged as `preflight-local-check` and you also check [this documentation](https://github.com/jetstack/jetstack-secure/blob/preflight-local-check/docs/check.md). +"The agent" manages your machine identities across Cloud Native Kubernetes and OpenShift environments and builds a detailed view of the enterprise security posture. ## Installation Please [review the documentation](https://platform.jetstack.io/documentation/installation/agent) for the agent before getting started. -The released container images are cryptographically signed by -[`cosign`](https://github.com/sigstore/cosign), with -[SLSA provenance](https://slsa.dev/provenance/v0.2) and a -[CycloneDX SBOM](https://cyclonedx.org/) attached. For instructions on how to -verify those signatures and attachments, refer to -[this guide](docs/guides/cosign). - ## Local Execution To build and run a version from master: diff --git a/docs/datagatherers/aks.md b/docs/datagatherers/aks.md deleted file mode 100644 index b1982642..00000000 --- a/docs/datagatherers/aks.md +++ /dev/null @@ -1,36 +0,0 @@ -# AKS Data Gatherer - -The AKS *data gatherer* fetches information about a cluster from the Azure -Kubernetes Service API. - -## Data - -Preflight collects data about clusters. The fields included here can be found -[here](https://docs.microsoft.com/en-us/rest/api/aks/managedclusters/get). - -## Configuration - -To use the AKS data gatherer add an `aks` entry to the `data-gatherers` -configuration. For example: - -``` -data-gatherers: -- kind: "aks" - name: "aks" - config: - resource-group: example - cluster-name: my-aks-cluster - credentials-path: /tmp/credentials.json -``` - -The `aks` configuration contains the following fields: - -- `resource-group`: The Azure resource group where the cluster is located. -- `cluster-name`: The name of your AKS cluster. -- `credentials`: The path to a file containing credentials for Azure APIs. - -## Permissions - -You must [create](https://docs.microsoft.com/en-us/azure/aks/kubernetes-service-principal#manually-create-a-service-principal) -a Service Principal and [link](https://docs.microsoft.com/en-us/azure/aks/kubernetes-service-principal#specify-a-service-principal-for-an-aks-cluster) -a it to your AKS cluster. diff --git a/docs/datagatherers/eks.md b/docs/datagatherers/eks.md deleted file mode 100644 index 6da10add..00000000 --- a/docs/datagatherers/eks.md +++ /dev/null @@ -1,46 +0,0 @@ -# EKS Data Gatherer - -The EKS *data gatherer* fetches information about a cluster from the AWS -Elastic Kubernetes Service API. - -## Data - -Preflight collects data about clusters. The fields included here can be found -[here](https://docs.aws.amazon.com/eks/latest/APIReference/API_Cluster.html). - -## Configuration - -To use the EKS data gatherer add an `eks` entry to the `data-gatherers` -configuration. For example: - -``` -data-gatherers: -- kind: "eks" - name: "eks" - config: - cluster-name: my-eks-cluster -``` - -The `eks` configuration contains the following fields: - -- `cluster-name`: The name of your EKS cluster. - -## Permissions - -Example Policy: - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "eks:DescribeCluster", - "eks:ListClusters" - ], - "Resource": "arn:aws:eks:*:111122223333:cluster/*" - } - ] -} -``` diff --git a/docs/datagatherers/gke.md b/docs/datagatherers/gke.md deleted file mode 100644 index 18d1668d..00000000 --- a/docs/datagatherers/gke.md +++ /dev/null @@ -1,111 +0,0 @@ -# GKE Data Gatherer - -The GKE *data gatherer* fetches information about a cluster from the Google -Kubernetes Engine API. - -## Data - -The output of the GKE data gatherer follows the format described in the -[GKE API reference](https://cloud.google.com/kubernetes-engine/docs/reference/rest/v1beta1/projects.locations.clusters#Cluster) -and the [Go Docs](https://godoc.org/google.golang.org/api/container/v1#Cluster). - -It's comparable to the output from: - -```bash -gcloud container clusters describe my-cluster --format=json -``` - -## Configuration - -To use the GKE data gatherer add a `gke` entry to the `data-gatherers` -configuration. For example: - -``` -data-gatherers: -- kind: "gke" - name: "gke" - config: - # Path to a file containing the credentials. If empty, it will try to use - # the SDK defaults (explained below) - # credentials-path: /tmp/credentials.json - cluster: - project: my-gcp-project - location: us-central1-a - name: my-gke-cluster -``` - -The `gke` configuration contains the following fields: - -- `credentials-path`: *optional* The path to a file containing credentials for - your cluster. -- `cluster` - - `name`: The name of your GKE cluster. - - `project`: The ID of your Google Cloud Platform project. - - `location`: The compute zone or region where your cluster is running. - -## Permissions - -If a `credentials-path` file is not specified, Preflight will attempt to use -Application Default Credentials or the metadata API (as per Google SDK default). - -If Preflight is running locally and the `gcloud` command is installed and -configured, just run `gcloud auth application-default login` to set up -Application Default Credentials. - -The `credentials` file path is useful if you want to configure a separate -service account for Preflight to use to fetch GKE data. - -The user and service account must have the correct [IAM -Roles](https://cloud.google.com/kubernetes-engine/docs/how-to/iam). -Specifically it must have the `container.clusters.get` permission. This can be -given with the _Kubernetes Engine Cluster Viewer_ role -(`roles/container.clusterViewer`). - -### Sample Terraform Configuration - -This can be used to create a GCP service account called `preflight` which is -then bound to a custom role of the same name with the minimum required -permissions. - - -```hcl -terraform { - required_version = "~> 0.12" -} - -variable "project_id" { - type = string - description = "The ID of the project where the cluster Preflight is going to check is." -} - -# https://www.terraform.io/docs/providers/google/index.html -provider "google" { - version = "2.5.1" - project = var.project_id -} - -# https://www.terraform.io/docs/providers/google/r/google_service_account.html -resource "google_service_account" "preflight_agent_service_account" { - project = var.project_id - account_id = "preflight-agent" - display_name = "Service account for Preflight Agent" -} - -# https://www.terraform.io/docs/providers/google/r/google_project_iam_custom_role.html -resource "google_project_iam_member" "preflight_agent_cluster_viewer" { - project = var.project_id - role = "roles/container.clusterViewer" # allows getting of credentials, all other permissions handled in k8s RBAC - member = "serviceAccount:${google_service_account.preflight_agent_service_account.email}" -} - -# if using workload identity in GKE, use the following binding to allow the -# agent to use the service account -resource "google_service_account_iam_binding" "preflight_agent_workload_identity" { - service_account_id = google_service_account.preflight_agent_service_account.name - role = "roles/iam.workloadIdentityUser" - members = ["serviceAccount:${var.project_id}.svc.id.goog[preflight/agent]"] -} -``` - -An annotation specifing the gcp service account must be added to the agent's k8s service account -`iam.gke.io/gcp-service-account=@` diff --git a/docs/guides/cosign/guide.md b/docs/guides/cosign/guide.md deleted file mode 100644 index faafc430..00000000 --- a/docs/guides/cosign/guide.md +++ /dev/null @@ -1,93 +0,0 @@ -# Cosign - -> Note: the ['keyless' signing feature](https://github.com/sigstore/cosign/blob/main/KEYLESS.md) -> of `cosign` used here is currently classified as 'experimental' - -The jetstack-secure agent container image is signed using -[`cosign`](https://github.com/sigstore/cosign). - -An attestation is attached which satisfies the requirements of -[SLSA 1](https://slsa.dev/spec/v0.1/requirements) and a -[CycloneDX Software Bill of Materials](https://cyclonedx.org/) is also provided -that details the dependencies of the image. - -This document outlines how to verify the signature, attestation and download -the SBOM with the `cosign` CLI. - -## Signature - -To verify the container image signature: - -1. Ensure `cosign` is installed -2. Configure the signature repository and enable experimental features: - -``` -export COSIGN_REPOSITORY=ghcr.io/jetstack/jetstack-secure/cosign -export COSIGN_EXPERIMENTAL=1 -``` - -3. Verify the image - -``` -cosign verify --cert-oidc-issuer https://token.actions.githubusercontent.com quay.io/jetstack/preflight:latest -``` - -If the container was properly signed then the command should exit successfully. - -The `Subject` in the output should be -`https://github.com/jetstack/jetstack-secure/.github/workflows/release-master.yaml@`, -where `` is either the `master` branch or a release tag, i.e: - -- `refs/heads/master` -- `refs/tags/v0.1.35` - -## SLSA Provenance Attestation - -To verify and view the SLSA provenance attestation: - -1. Ensure `cosign` is installed -2. Configure the signature repository and enable experimental features: - -``` -export COSIGN_REPOSITORY=ghcr.io/jetstack/jetstack-secure/cosign -export COSIGN_EXPERIMENTAL=1 -``` - -3. Verify and decode the attestation payload: - -``` -cosign verify-attestation --cert-oidc-issuer https://token.actions.githubusercontent.com quay.io/jetstack/preflight:latest | tail -n 1 | jq -r .payload | base64 -d | jq -r . -``` - -## Software Bill of Materials (SBOM) - -To verify and download the SBOM: - -1. Ensure `cosign` is installed -2. Configure the signature repository and enable experimental features: - -``` -export COSIGN_REPOSITORY=ghcr.io/jetstack/jetstack-secure/cosign -export COSIGN_EXPERIMENTAL=1 -``` - -3. Verify the SBOM - -``` -cosign verify --attachment sbom --cert-oidc-issuer https://token.actions.githubusercontent.com quay.io/jetstack/preflight:latest -``` - -If the SBOM was properly signed then the command should exit successfully. - -The `Subject` in the output should be -`https://github.com/jetstack/jetstack-secure/.github/workflows/release-master.yaml@`, -where `` is either the `master` branch or a release tag, i.e: - -- `refs/heads/master` -- `refs/tags/v0.1.35` - -4. Download the SBOM - -``` -cosign download sbom quay.io/jetstack/preflight:latest > bom.xml -``` diff --git a/docs/guides/gke_local/guide.md b/docs/guides/gke_local/guide.md deleted file mode 100644 index 55bcf2aa..00000000 --- a/docs/guides/gke_local/guide.md +++ /dev/null @@ -1,105 +0,0 @@ -# How to run Preflight with the GKE package - -This doc guides you on how to run preflight-agent locally to scan a GKE installation. - -As a result, you will get a new cluster in your Preflight account showing reports with the GKE package. - -It executes the agent locally because this guide is intented to be an interative demonstration, but the agent could be installed in-cluster as well. Take a look at the [GKE data-gatherer manual](../../datagatherers/gke.md) for further details on how to configure authentication in that scenario. - -## Requisites - -- A GKE cluster. -- The `gcloud` CLI tool working locally on your computer. -- `gcloud` is logged in to an account with permissions to read cluster and GKE state in the project where your cluster is running. -- You have already run `gcloud container clusters get-credentials [cluster] ...` to configure your kubeconfig. - -## Get the preflight cli - -Go to [the releases page](https://github.com/jetstack/preflight/releases) and download the binary of the latest stable release for your platform (`v0.1.15` at the moment of writing this). - -![release](./img/release.png) - -For instance: - -``` -curl -L https://github.com/jetstack/preflight/releases/download/v0.1.15/preflight-linux-amd64 > preflight -chmod +x ./preflight -``` - -Then run this to make sure you downloaded the right thing: - -``` -./preflight version -``` - -## Access Preflight - -> At the moment, Preflight is in private beta. If you are interested, please [email us](mailto:preflight-maintainers@jetstack.io?subject=Preflight%20Beta%20Access) and we will grant to access to the beta program. - -If you have an account, you will have an access token. - -Enter [preflight.jetstack.io/login](https://preflight.jetstack.io/login) and access with your token. - -You will be presented with the list of cluster in your organization. - -## Add a new cluster and start agent - -Click in "Add Cluster". - -Choose a name for your cluster (e.g. `my-gke-cluster`) and click the accept button. - -Then you will be presented with instructions to install the agent in a cluster. - -Since you are going to run the agent locally instead of installing it in a cluster, you must copy the agent token and craft a config file manually. - -You can extract the agent token from the installation command, as shown in the picture. - -![token](./img/select_token.png) - -Then you can use this snipped as template for your configuration file and replace the agent token where it corresponds. - -Also, change `cluster.project`, `cluster.location`, `cluster.name` accordingly so they point to your GKE cluster (`gcloud container clusters list` if you don't remember those values.). - -If you don't specify `credentials`, it will try to use _Gcloud Application Default Credentials_. You can run `gcloud auth application-default login` to make sure your _Application Default Credentials_ are configured. - -```yaml -# config.yaml - -schedule: "* * * *" -token: "" -endpoint: - protocol: https - host: "preflight.jetstack.io" - path: "/api/v1/datareadings" -data-gatherers: -- kind: "gke" - name: "gke" - config: - cluster: - project: my-gcp-project - location: us-central1-a - name: my-gke-cluster - # Path to a file containing the credentials. If empty, it will try to use - # the SDK defaults - # credentials: /tmp/credentials.json -``` - -Save the file as `config.yaml`. - -Now you can run the Preflight agent: - -``` -./preflight agent -c ./config.yaml -``` - -You should see in the log that it is sending data to the server periodically. - -If you go back to the add cluster wizard and click "The agent it ready" - -![ready](./img/ready.png) - -## See reports - -If you go to the clusters view, you will see the new cluster is there: - -![cluster](./img/cluster.png) diff --git a/docs/guides/gke_local/img/cluster.png b/docs/guides/gke_local/img/cluster.png deleted file mode 100644 index f22d5ef9..00000000 Binary files a/docs/guides/gke_local/img/cluster.png and /dev/null differ diff --git a/docs/guides/gke_local/img/ready.png b/docs/guides/gke_local/img/ready.png deleted file mode 100644 index f6f9a4d9..00000000 Binary files a/docs/guides/gke_local/img/ready.png and /dev/null differ diff --git a/docs/guides/gke_local/img/release.png b/docs/guides/gke_local/img/release.png deleted file mode 100644 index f5f369a3..00000000 Binary files a/docs/guides/gke_local/img/release.png and /dev/null differ diff --git a/docs/guides/gke_local/img/select_token.png b/docs/guides/gke_local/img/select_token.png deleted file mode 100644 index 8a2e6fa8..00000000 Binary files a/docs/guides/gke_local/img/select_token.png and /dev/null differ diff --git a/docs/images/azblob_keys.png b/docs/images/azblob_keys.png deleted file mode 100644 index 8d11f55c..00000000 Binary files a/docs/images/azblob_keys.png and /dev/null differ diff --git a/docs/images/js.png b/docs/images/js.png deleted file mode 100644 index 83796565..00000000 Binary files a/docs/images/js.png and /dev/null differ diff --git a/docs/images/preflight_package.png b/docs/images/preflight_package.png deleted file mode 100644 index 6e7024f4..00000000 Binary files a/docs/images/preflight_package.png and /dev/null differ