diff --git a/README.md b/README.md index 5da4344..8966b75 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ The traditional credentials handling practices enforce a clear separation of concerns between application and infrastructure teams. However, Kubernetes centralized credentials through the ```secret``` and ```configmap``` API objects within ```etcd``` with an encryption layer. -More here [Security](docs/security.md) or with [Kubernetes Secrets Handbook](https://www.amazon.com/Kubernetes-Secrets-Handbook-production-grade-management/dp/180512322X) +More here [Security](docs/exposures.md) or with [Kubernetes Secrets Handbook](https://www.amazon.com/Kubernetes-Secrets-Handbook-production-grade-management/dp/180512322X) ## How? Kubernetes introduces a KMS plugin framework to support access to an external security (hardware or software) module and enable an envelope encryption practice. @@ -28,6 +28,18 @@ More here [Implementation](docs/architecture.md) * Delinea/Thycotic integration +## Additional collaterals + +### Code of Conduct +We believe in a space for everyone and we embrace the following [code of conduct](docs/code_of_conduct.md). + +### Contributing +The essence of open source is sharing and contributing to knowledge. The guidelines are available [here](docs/contributing.md). + +### Security +We take security and trust seriously. If you believe that you have found a security issue in this project, *please disclose responsibly the details by following the [security policy](docs/security.md). + + ## Origin of kleidi @@ -39,3 +51,4 @@ The origin is Greek, and the meaning is "key". (Source: [Wikipedia](https://en.w

+ diff --git a/CODE_OF_CONDUCT.MD b/docs/code_of_conduct.md similarity index 72% rename from CODE_OF_CONDUCT.MD rename to docs/code_of_conduct.md index 26487a3..cb5603d 100644 --- a/CODE_OF_CONDUCT.MD +++ b/docs/code_of_conduct.md @@ -2,4 +2,4 @@ We follow the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). -Please contact rom@beezy.dev to report an issue. \ No newline at end of file +Please contact git@beezy.dev to report an issue. \ No newline at end of file diff --git a/CONTRIBUTING.md b/docs/contributing.md similarity index 95% rename from CONTRIBUTING.md rename to docs/contributing.md index e91cd62..b3b1b5d 100644 --- a/CONTRIBUTING.md +++ b/docs/contributing.md @@ -5,7 +5,7 @@ Welcome! We are glad that you want to contribute to our project and make it as e If this is your first contribution to kleidi, we encourage you to walk through this guideline helping you to setup your dev environment, make a change, test it and open a pull request about it. ## Code of Conduct -The kleidi community is governed by our [Code of Conduct](https://github.com/beezy-dev/kleidi/blob/main/CODE_OF_CONDUCT.md). This includes but isn't limited to: kleidi GitHub repositories, Discussions, interaction on social media, conferences and meetups. +The kleidi community is governed by our [Code of Conduct](code_of_conduct.md). This includes but isn't limited to: kleidi GitHub repositories, Discussions, interaction on social media, conferences and meetups. ## License By contributing, you agree that your contributions will be licensed under its [Apache License 2.0](https://github.com/beezy/kleidi/blob/main/LICENSE). @@ -16,7 +16,7 @@ In short, when you submit code changes, your submissions are understood to be un We welcome many different types of contributions includings: * Answering questions on [GitHub Discussions](https://github.com/beezy-dev/kleidi/discussions) -* [Documentation](https://github.com/beezy-dev/kleidi/wiki) +* [Documentation](https://github.com/beezy-dev/kleidi) * Social Media, blog post, webinar * [Issue triage, new feature, bug fix](https://github.com/beezy-dev/kleidi/issues) * Build, CI/CD, QA help, release management @@ -39,7 +39,7 @@ unexpected behavior. Use one of the existing templates or follow some example li - what actually happens - any hint towards a possible root cause and fix -***NOTE: do not open a Security related bug or issue. We take security and users' trust seriously. If you believe you have found a security issue in kleidi, please responsibly disclose by following the [Security Policy](https://github.com/beezy-dev/kleidi/security/policy).*** +***NOTE: do not open a Security related bug or issue. We take security and users' trust seriously. If you believe you have found a security issue in kleidi, please responsibly disclose by following the [Security Policy](security.md).*** ## Find an Issue We use GitHub to host code, track issues and feature requests, as well as accept pull requests. As a start, we have labelled [good first issues](https://github.com/beezy-dev/kleidi/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) for new contributors and [help wanted](https://github.com/beezy-dev/kleidi/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) issues suitable for any contributor who isn't a core maintainer. @@ -107,7 +107,7 @@ When you submit your pull request, or you push new commits to it, our GitHub Act 1. If your commits does not content all the suggestions, please open an issue with the title ***Follow-On PR #00***. This will allow to pursue or not these suggestions if needed. -1. If your pull request will require a [Documentation](https://github.com/beezy-dev/kleidi/wiki) update, make sure to provide a +1. If your pull request will require a [Documentation](https://github.com/beezy-dev/kleidi) update, make sure to provide a a extract of what needs to be changed with the proposed changed. Best would be to clone the wiki and perform a parallel pull request. diff --git a/docs/exposures.md b/docs/exposures.md new file mode 100644 index 0000000..2226c68 --- /dev/null +++ b/docs/exposures.md @@ -0,0 +1,43 @@ +# kubernetes kms plugin + +## Physical/Virtual machine world +The entire IT organization is segmented into knowledge domains such as networking, storage, computing, and applications in the legacy world. +When an application team asks for a virtual machine: +* The VMware Team has its credentials, which the Linux team cannot access. +* The Linux team will configure, maintain, and support the operating system and not share their credentials with any other team. +* The application team will deploy their application, which might be connected to a database; the DBA will provide credentials. +This quick overview can be enriched with all other layers like storage, backup, networking, monitoring, etc. +None will cross-share their credentials. + +## Container platform world +Within Kubernetes, the states and configurations of every component, from computing to networking to applications and more, are stored within the ```etcd``` key-value datastore. + +Even if cloud-native applications can interact directly with a KMS provider like Vault, application and platform credentials are still stored within the cluster. This might also include the token to connect with the KMS provider. + +All data fields are encoded in base64 but not encrypted. + +## Security exposures + +The following diagram takes a 10,000-feet overview to explore the security exposures leading to a potential secret leaking/spilling: + +![kleidi security exposures](images/kledi-security_exposure.drawio.png) + +* The secret comes from an external source and needs to be injected. +* The base64 encoded secret will be ingested via the API server. +* If a Kubernetes KMS provider plugin exists, the API server encrypts the data field using an envelope encryption scheme. +* The secret and encrypted data filed will be stored within the ```etcd``` key-value datastore. +* The ```etcd``` key-value datastore file is saved on a local volume on the control plane node filesystem. + +What are the exposures: + +|Exposure | Risk | Mitigation | +|---------|------|------------| +|The secret comes from an external source. It requires a base64-encoded payload. | This transformation is a first-level exposure of the data field at file and console levels. | Work an injection mechanism from the password manager or KMS | +| A common mistake is committing the secret YAML definition to a Git repository. | The credentials are exposed for life and will need to be rotated. | Don't include any YAML manifest with sensitive data in a Git repository even for testing purposes. Using a tool like SOPS can help prevent such scenario | +| If no KMS provider plugin exists. | The API server stores the base64-encoded secret within the ```etcd``` key-value datastore. | Application secrets might benefit from an external KMS. Platform secrets will require a data encryption at rest option provided by Kubernetes. | +| If a KMS provider plugin exists. | The encryption Key or credentials to access the KMS or HSM are exposed in clear text. | Set up a mTLS authentication if possible. | +| The ```etcd``` key-value datastore is stored on the control plane filesystem. | The datastore file can be accessed if the node is compromised. | Encrypting the filesystem helps secure the datastore file from being read, except if the node has been compromised with root access. | +| The API server is the Kubernetes heart and soul. | If the appropriate RBAC or the API server is compromised, all protective measures will be useless since the API server will decrypt all sensitive data fields. | RBAC and masking the API server if possible | + +Thanks to Red Hat colleagues Francois Duthilleul and Frederic Herrmann for spending time analyzing the gaps. + diff --git a/docs/security.md b/docs/security.md index 2226c68..b6c2265 100644 --- a/docs/security.md +++ b/docs/security.md @@ -1,43 +1,33 @@ -# kubernetes kms plugin +# Security -## Physical/Virtual machine world -The entire IT organization is segmented into knowledge domains such as networking, storage, computing, and applications in the legacy world. -When an application team asks for a virtual machine: -* The VMware Team has its credentials, which the Linux team cannot access. -* The Linux team will configure, maintain, and support the operating system and not share their credentials with any other team. -* The application team will deploy their application, which might be connected to a database; the DBA will provide credentials. -This quick overview can be enriched with all other layers like storage, backup, networking, monitoring, etc. -None will cross-share their credentials. +## Reporting Potential Security Issues -## Container platform world -Within Kubernetes, the states and configurations of every component, from computing to networking to applications and more, are stored within the ```etcd``` key-value datastore. +If you have encountered a potential security vulnerability in this project, +please **report it to us at git@beezy.dev and not via an GitHub issue**. -Even if cloud-native applications can interact directly with a KMS provider like Vault, application and platform credentials are still stored within the cluster. This might also include the token to connect with the KMS provider. +We will work with you to verify the vulnerability, build a patch, validate +the fix, and finally issue a public report. -All data fields are encoded in base64 but not encrypted. +When reporting issues, please provide the following information: +- Component(s) affected +- A description indicating how to reproduce the issue +- A summary of the security vulnerability and impact -## Security exposures +We request that you contact us via the email address above and give the +project contributors a chance to resolve the vulnerability and issue a new +release prior to any public exposure; this helps protect the project's +users, and provides them with a chance to upgrade and/or update in order to +protect their applications. -The following diagram takes a 10,000-feet overview to explore the security exposures leading to a potential secret leaking/spilling: +## Policy -![kleidi security exposures](images/kledi-security_exposure.drawio.png) +If we verify a reported security vulnerability, our policy is: -* The secret comes from an external source and needs to be injected. -* The base64 encoded secret will be ingested via the API server. -* If a Kubernetes KMS provider plugin exists, the API server encrypts the data field using an envelope encryption scheme. -* The secret and encrypted data filed will be stored within the ```etcd``` key-value datastore. -* The ```etcd``` key-value datastore file is saved on a local volume on the control plane node filesystem. +- We will patch the current release branch, as well as the immediate prior minor + release branch. -What are the exposures: - -|Exposure | Risk | Mitigation | -|---------|------|------------| -|The secret comes from an external source. It requires a base64-encoded payload. | This transformation is a first-level exposure of the data field at file and console levels. | Work an injection mechanism from the password manager or KMS | -| A common mistake is committing the secret YAML definition to a Git repository. | The credentials are exposed for life and will need to be rotated. | Don't include any YAML manifest with sensitive data in a Git repository even for testing purposes. Using a tool like SOPS can help prevent such scenario | -| If no KMS provider plugin exists. | The API server stores the base64-encoded secret within the ```etcd``` key-value datastore. | Application secrets might benefit from an external KMS. Platform secrets will require a data encryption at rest option provided by Kubernetes. | -| If a KMS provider plugin exists. | The encryption Key or credentials to access the KMS or HSM are exposed in clear text. | Set up a mTLS authentication if possible. | -| The ```etcd``` key-value datastore is stored on the control plane filesystem. | The datastore file can be accessed if the node is compromised. | Encrypting the filesystem helps secure the datastore file from being read, except if the node has been compromised with root access. | -| The API server is the Kubernetes heart and soul. | If the appropriate RBAC or the API server is compromised, all protective measures will be useless since the API server will decrypt all sensitive data fields. | RBAC and masking the API server if possible | - -Thanks to Red Hat colleagues Francois Duthilleul and Frederic Herrmann for spending time analyzing the gaps. +- After patching the release branches, we will immediately issue new security + fix releases for each patched release branch. +- A security advisory will be released on the project GitHub repository detailing the + vulnerability, as well as recommendations for end-users to protect themselves.