diff --git a/CHANGELOG.md b/CHANGELOG.md index 310c14a69..67203bf8e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,7 @@ # Changelog +## [0.2.0] TBD after release (see ROADMAP.md for details) + ## [0.1.0] - 2022-10-31 ### Added @@ -8,4 +10,3 @@ First POC. ### Changed ### Security - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f9b55e253..f4632198b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,10 +6,10 @@ efficient. Anyone may contribute to a project in the Galadriel repository that t * Abide by the SPIFFE [code of conduct](https://github.com/spiffe/spiffe/blob/main/CODE-OF-CONDUCT.md) * Can certify the clauses in the [Developer Certificate of Origin](https://github.com/spiffe/spiffe/blob/main/DCO) -To get started: +## Getting started -* First, [README](/README.md) to become familiar with how the Galadriel Project is managed -* Make sure you're familiar with our [Coding Conventions](#conventions) when appropriate +* First, [README](/README.md) to become familiar with how the Galadriel Project is managed. +* Make sure you're familiar with our [Coding Conventions](#coding-conventions-a-nameconventionsa). ## Sending a pull request @@ -18,17 +18,19 @@ To get started: 3. Update the docs, if necessary 4. Ensure your branch is based on the latest commit in `main` 5. Ensure all tests pass (see project docs for more information) -6. Make sure your commit messages contain a `Signed-off-by: ` line (see `git-commit --signoff`) to certify the [DCO](/DCO) +6. Make sure your commit messages contain a `Signed-off-by: ` line (see `git-commit --signoff`) to + certify the [DCO](/DCO) 7. Make sure your all your commits are GPG-signed 8. Open a [pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/) against the upstream `main` branch -All changes to Galadriel project must be code reviewed in a pull request (this goes for everyone, even those who have merge rights). +All changes to Galadriel project must be code reviewed in a pull request (this goes for everyone, even those who have +merge rights). ## After your pull request is submitted Pull requests are approved according to the process described in our [governance -policies](/GOVERNANCE.md). At least two other contributors must approve the pull request. +policies](/GOVERNANCE.md). At least one maintainer must approve the pull request. Once your pull request is submitted, it's your responsibility to: @@ -39,14 +41,20 @@ Following approval, the pull request will be merged by the submitter of the pull ## Coding Conventions -Coding conventions will follow the [SPIFFE project conventions](https://github.com/spiffe/spiffe/blob/main/CONTRIBUTING.md#coding-conventions-). +Coding conventions will follow +the [SPIFFE project conventions](https://github.com/spiffe/spiffe/blob/main/CONTRIBUTING.md#coding-conventions-). -#### Third-party code +## Datastore Contributions + +For more detailed information on working with the Datastore, including structure, migrations, schema changes, and more, +please review the [Datastore README](pkg/server/db/README.md). + +## Third-party code When third-party code must be included, all licenses must be preserved. This includes modified third-party code and excerpts, as well. -#### Repositories and Licenses +## Repositories and Licenses All repositories under this project should include: @@ -54,4 +62,6 @@ All repositories under this project should include: * A `LICENSE` file with the Apache 2.0 license * A [CODEOWNERS](https://help.github.com/articles/about-codeowners/) file listing the maintainers -All code projects should use the [Apache License version 2.0](https://www.apache.org/licenses/LICENSE-2.0), and all documentation repositories should use the [Creative Commons License version 4.0](https://creativecommons.org/licenses/by/4.0/legalcode). +All code projects should use the [Apache License version 2.0](https://www.apache.org/licenses/LICENSE-2.0), and all +documentation repositories should use +the [Creative Commons License version 4.0](https://creativecommons.org/licenses/by/4.0/legalcode). diff --git a/GOVERNANCE.md b/GOVERNANCE.md index bf0a22168..c5f98e727 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,23 +1,33 @@ -## Project Roles +## Roles within the Galadriel Project ### Users -These are individuals who -- Want to learn more about the Galadriel Project; -- Are existing users of Galadriel and its tools who wish to follow the project's progress. +Users are individuals who: + +- Are interested in learning more about the Galadriel Project; +- Are existing users of Galadriel and its tools, wanting to stay updated on the project's progress. ### Contributors -These are individuals who wish to contribute code or ideas to Galadriel. Contributors submit code and ideas through GitHub issues or by creating pull requests. +Contributors are individuals who have a desire to contribute to Galadriel. They provide contributions in the form of +code or innovative ideas. Contributions are typically made through GitHub issues or by creating pull requests. ### Maintainers -These are individuals who can approve submitted pull requests to be merged into the primary codebase. The project requires pull requests to be approved by at least two (2) maintainers. Once approved, a pull request can be merged by maintainers. A list of the current maintainers can be found in the [Codeowners](./CODEOWNERS) file. +Maintainers are individuals with the authority to approve pull requests for merging into the primary codebase. To +maintain the quality and integrity of the code, the Galadriel Project requires at least one maintainer to approve a +pull request before it can be merged. The list of current maintainers is available in the [Codeowners](./CODEOWNERS) +file. ## Change Review Process -**All changes must be submitted as a GitHub Pull Request (PR)** +**All changes must be submitted via GitHub Pull Request (PR)** + +The submitter of a pull request bears the responsibility of addressing any feedback received. While the pull request is +open, it is also the submitter's responsibility to ensure that the proposed change is always in a mergeable state. For +guidelines on submitting a pull request for approval, please refer to the [Contributor's Guide](/CONTRIBUTING.md). -The submitter of a pull request is responsible for responding to any feedback. While it remains open, the submitter is also responsible for ensuring the change is always in a state where it can be merged. Guidelines for submitting a pull request for approval can be found [here](/CONTRIBUTING.md). +**All changes must garner approval from at least one Maintainer** -**All changes must be approved by at least two (2) Maintainers** +Each proposed change must be approved by at least one maintainer before it can be merged into the primary codebase. +This ensures that the code is thoroughly reviewed and maintains the high standards set by the Galadriel Project. diff --git a/README.md b/README.md index 7ea7420af..5ee548a42 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # Galadriel + [![CodeQL](https://github.com/HewlettPackard/galadriel/actions/workflows/codeql.yml/badge.svg)](https://github.com/HewlettPackard/galadriel/actions/workflows/codeql.yml) [![PR Build](https://github.com/HewlettPackard/galadriel/actions/workflows/pr_build.yml/badge.svg)](https://github.com/HewlettPackard/galadriel/actions/workflows/pr_build.yml) [![Scorecards supply-chain security](https://github.com/HewlettPackard/galadriel/actions/workflows/scorecards.yml/badge.svg)](https://github.com/HewlettPackard/galadriel/actions/workflows/scorecards.yml) @@ -6,42 +7,62 @@ --- -Project Galadriel, or just Galadriel, is an open source project that enables scalable and easy configuration of Federation relationships among SPIRE Servers. It works as a central hub for managing and auditing Federation relationships. +Project Galadriel is an open-source project that streamlines the configuration of Federation relationships among SPIRE +Servers and manages the secure exchange of Trust Bundles based on the registered and approved relationships. It +functions as a central hub for the management and auditing of these Federation relationships. + +### What is Galadriel? + +- **Alternative approach to SPIRE Federation**: Galadriel is built on top of SPIRE APIs to streamline the management of + foreign Trust Bundles. +- **Federation at scale**: Galadriel simplifies the configuration of multiple SPIRE Server federations while + prioritizing security. +- **Central hub**: Galadriel provides a centralized platform where federation relationships can be defined and audited. -### What Galadriel IS? -- **Alternative approach to SPIRE Federation**: it's built on top of SPIRE APIs to facilitate foreign Trust Bundles management. -- **Multi-tenant**: multiple organizations can leverage the same Galadriel deployment, while ensuring data and operations isolation. -- **Federation at scale**: configuring multiple SPIRE Server federation should be easy and secure by default, that is Galadriel's main focus. -- **Central hub**: it's a central place where federation relationships can be defined and audited. +### What Galadriel is not? -### What Galadriel IS NOT? -- **A replacement of SPIRE/SPIFFE Federation**: it doesn't replace SPIRE Federation, it leverages what's already built in there. -- **A SPIRE plugin**: it's deployed as a separate component, not as a SPIRE plugin. +- **A replacement for SPIRE/SPIFFE Federation**: Galadriel does not replace SPIRE Federation, instead, it leverages + existing SPIRE capabilities. +- **A SPIRE plugin**: Galadriel is deployed as a standalone component, not as a SPIRE plugin. --- -## Get started +## Getting Started -- Learn how to run the Proof of Concept (v0.1.0) [here](https://github.com/HewlettPackard/galadriel/blob/v0.1.0/doc/INSTRUCTIONS.md) -- [Configuration and CLI Usage instructions](./doc/USAGE.md) +- **TBD** -## Contribute +## Contributing -Project Galadriel is an open source project under the [Apache 2 license](./LICENSE), and as such, any kind of contribution is welcome, being documentation, new features, bugfixing, issues, etc. Check out our [Contributing guidelines](./CONTRIBUTING.md) to learn how we manage contributions, and the [Governance policy](./GOVERNANCE.md) to learn about the different roles in the project. +Project Galadriel is an open-source project under the [Apache 2 license](./LICENSE). We welcome any form of +contribution, whether it's documentation, new features, bug fixes, or issues. Check out +our [Contributing guidelines](./CONTRIBUTING.md) to learn about our contribution management, and +the [Governance policy](./GOVERNANCE.md) to understand the various roles within the project. ## Roadmap -Project Galadriel has currently reached the Proof of Concept milestone ([v0.1.0](https://github.com/HewlettPackard/galadriel/blob/v0.1.0/doc/INSTRUCTIONS.md)). Refer to the [Roadmap](./ROADMAP.md) to learn what's next. +Project Galadriel has currently reached the Proof of Concept +milestone ([v0.1.0](https://github.com/HewlettPackard/galadriel/blob/v0.1.0/doc/INSTRUCTIONS.md)). Refer to +the [Roadmap](./ROADMAP.md) to learn about our future plans. -## Want to know more? +## Want to Know More? -### Design document -Please feel free to check out our [Design Document](https://docs.google.com/document/d/1nkiJV4PAV8Wx1oNvx4CT3IDtDRvUFSL8/edit?usp=sharing&ouid=106690422347586185642&rtpof=true&sd=true), where you can find more information about the architecture and future plans for Galadriel. Comments and suggestions are welcome and highly appreciated. +### Design Document + +Feel free to explore +our [Design Document](https://docs.google.com/document/d/1nkiJV4PAV8Wx1oNvx4CT3IDtDRvUFSL8/edit?usp=sharing&ouid=106690422347586185642&rtpof=true&sd=true), +which provides more information about Galadriel's architecture and future plans. Your comments and suggestions are +welcome and highly appreciated. ### Community Presentations & Blog Posts -- SPIRE Bridge: an Alternative Approach to SPIFFE Federation - [Juliano Fantozzi](https://github.com/jufantozzi), [Maximiliano Churichi](https://github.com/mchurichi) / SPIFFE Community Day Fall 2022 (October 2022) / [video](https://www.youtube.com/watch?v=pHdOm4MdPHE), [slides](https://docs.google.com/presentation/d/1Cox9MNeZA1bD2aktg2HTMjcgGn_6Rbb0/edit?usp=sharing&ouid=106690422347586185642&rtpof=true&sd=true), [demo](https://github.com/HewlettPackard/galadriel/tree/v0.1.0/demos) -- Galadriel - A SPIRE Federation Alternative - [William Barrera Fuentes](https://github.com/wibarre) / HPE Developer Community (October 2022) / [blog post](https://developer.hpe.com/blog/galadriel-a-spire-federation-alternative/) -## Found a security issue? +- SPIRE Bridge: an Alternative Approach to SPIFFE + Federation - [Juliano Fantozzi](https://github.com/jufantozzi), [Maximiliano Churichi](https://github.com/mchurichi) / + SPIFFE Community Day Fall 2022 (October + 2022) / [video](https://www.youtube.com/watch?v=pHdOm4MdPHE), [slides](https://docs.google.com/presentation/d/1Cox9MNeZA1bD2aktg2HTMjcgGn_6Rbb0/edit?usp=sharing&ouid=106690422347586185642&rtpof=true&sd=true), [demo](https://github.com/HewlettPackard/galadriel/tree/v0.1.0/demos) +- Galadriel - A SPIRE Federation Alternative - [William Barrera Fuentes](https://github.com/wibarre) / HPE Developer + Community (October 2022) / [blog post](https://developer.hpe.com/blog/galadriel-a-spire-federation-alternative/) + +## Encountered a Security Issue? -Please refer to the [Security policy](./SECURITY.md) to learn more about security updates and reporting potential vulnerabilities. +Please refer to our [Security policy](./SECURITY.md) for more information about security updates and how to report +potential vulnerabilities. diff --git a/ROADMAP.md b/ROADMAP.md index a7b246189..818a8f493 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,29 +1,33 @@ # Roadmap -## Milestones +## Recently Completed -### Proof of Concept (PoC) -- **Status**: Completed ([v0.1.0](https://github.com/HewlettPackard/galadriel/tree/v0.1.0/)) -- **Goal**: Exercise concepts about trust bundle exchange based on relationships. It will corroborate the feasibility of having a Harvester agent as a medium to manage federated relationships in SPIRE servers, the Server as a middle hub for exchange, and the relationship as a control for the exchange.  -- **Result**: - - Server runs, and stores bundles and defined relationships in an ephemeral storage system. - - Server exposes local APIs for admins to register new members, generate access tokens for them, and define bidirectional 1:1 relationships. - - Server exposes public authenticated APIs for Harvesters. - - Harvester uses Server-generated access tokens to communicate with the Server. - - Harvester communicates with the SPIRE Server to fetch its bundle and to set foreign bundles. - - Harvester sends its collocated SPIRE bundle, and fetches and keeps in sync foreign bundles based on the defined relationships. +- APIs for Server and Harvester defined through Open API spec. +- TLS enabled between Galadriel Server and Harvesters, using a disk-based upstream CA that the Server uses to sign its + certificate. +- Secure Harvester introduction using a single-use join token. +- Harvester authentication using JWT issued by the Server, which are rotated. The JWT is issued by the Server using + either an in-memory KeyManager or a disk-based KeyManager for generating the private keys. +- Bundle signing and verification using a disk-based Signer and Verifier implementation. +- Added support for SQLite and Postgres. +- Simple implementation of the Federation Relationship approval flow. +- Federated bundle synchronization across Harvesters based on configured and approved relationships. + +## Near-Term and Medium-Term + +- Support for SPIRE running in high-availability (HA) mode. +- Support for Galadriel Server in high-availability (HA) mode. +- Support for other upstream CAs for TLS certificates. +- Support for other Key Management Systems (KMS) for the private keys used for JWT issuing. +- Support for relationship consent signing. +- Support for other bundle signers and verifiers, e.g., using Sigstore. +- Telemetry, health checkers, alerts, and API versioning. -### Minimum Viable Product (MVP) -- **Status**: In Progress -- **Goal**: Have a minimal product for early evaluation, that is is API based, and implements the security and core principles identified in the [Design Document](https://docs.google.com/document/d/1nkiJV4PAV8Wx1oNvx4CT3IDtDRvUFSL8/edit?usp=sharing&ouid=106690422347586185642&rtpof=true&sd=true). -- **Result**: - - Server and Harvester APIs are well defined and documented. - - Harvester is securely introduced to the Server. - - One or more production-ready database systems are available to be used as backend storage. - - Multiple organizations can share the same Galadriel Server instance without data leak risks. - - Trust bundles are cryptographically signed and verified end-to-end. - - Galadriel supports SPIRE in an HA topology. - - Server and Harvester can be configured to emit metrics to an open telemetry standard. - - Harvester admins explicitly approve or deny memberships. - - Components and flows are thoroughly and continuously tested and exercised. - - There are deployment options for bare metal and Kubernetes. +## Long-Term + +### Initial Proof of Concept (PoC) + +- **Status**: Completed ([v0.1.0](https://github.com/HewlettPackard/galadriel/tree/v0.1.0/)) +- **Goal**: Exercise concepts about trust bundle exchange based on relationships. This stage corroborates the + feasibility of having a Harvester agent as a medium to manage federated relationships in SPIRE servers, the Server as + a central hub for exchange, and the relationship as a control for the exchange. diff --git a/dev/request_data/bundle_post.json b/dev/request_data/bundle_post.json deleted file mode 100644 index 282bc6e04..000000000 --- a/dev/request_data/bundle_post.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "state": { - "trust_domain": "td1", - "trust_bundle": "d2VsbCwgaGVsbG8gaGFuZHNvbWUgOj4=", - "bundle_digest": "d2VsbCwgaGVsbG8gaGFuZHNvbWUgOj4=" - } -} diff --git a/dev/request_data/bundle_sync.json b/dev/request_data/bundle_sync.json deleted file mode 100644 index 18215abf9..000000000 --- a/dev/request_data/bundle_sync.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "state": { - "td2": "rJYNLNt7SjfQBrJ/6vO5mrtuedic1hYdwvGoXqtAQiI=" - } -} diff --git a/pkg/server/db/README.md b/pkg/server/db/README.md index fad6dacc0..2b39376f2 100644 --- a/pkg/server/db/README.md +++ b/pkg/server/db/README.md @@ -1,28 +1,36 @@ -# Datastore code +# Datastore -Type-safe code from SQL is generated using [sqlc](https://github.com/kyleconroy/sqlc). +The Galadriel project supports two datastore engines: SQLite and Postgres. The Datastore handles all database +interactions. This document outlines the procedures for generating type-safe code, handling migrations, and changing the +database schema. -`sqlc` is configured through the file [sqlc.yalm](sqlc.yaml). +## SQL Code Generation -When there is a change in the schema or in the queries, the DB code should be re-generated: +We use [sqlc](https://github.com/kyleconroy/sqlc) to generate type-safe Go code for SQL queries. Sqlc configurations are +defined in the [sqlc.yaml](sqlc.yaml) file. -``` +Whenever there are changes to the schema or queries, run the following command to regenerate the Go code: + +```shell make generate-sql-code ``` -This regenerates the files `models.go`, `db.go`, `querier.go`, and files ending in `.sql.go`. +This command regenerates the `models.gen.go`, `db.gen.go`, `querier.gen.go`, and the `.sql.go` files. + +**Note:** Remember to commit these regenerated files. -**These files should be committed.** +## Database Migrations -# Migrations +Database migrations are managed with [golang-migrate](https://github.com/golang-migrate/migrate). -Migrations are done using [golang-migrate](https://github.com/golang-migrate/migrate). +During the creation of a new Datastore object using the `NewDatastore` method, the schema version is verified, and any +necessary migrations are applied. -When a new Datastore object is created using the NewDatastore method, the schema version is verified and -migrations are applied if needed. +## Changing the Database Schema -# Change the DB schema +Following the initial release of Galadriel, any changes to the DB schema must be handled through new files in +the [postgres migrations](postgres/migrations) and [sqlite3 migrations](sqlite/migrations) folders. Also, the queries in +the [postgres queries](postgres/queries) and [sqlite queries](sqlite/queries) should be updated accordingly. -Once there was an initial release of Galadriel, changes in the DB schema should be added through new files -in the [migrations](postgres/migrations) folder and the queries in the [queries](postgres/queries) should be updated. -For SQLite, the files are in the [sqlite](sqlite) folder. \ No newline at end of file +To reflect the current schema version supported by Galadriel and to ensure automatic migration, remember to increment +the `currentDBVersion` constant.