Multiple AllowLists per Target

68-multi-allowlists.md

@@ -0,0 +1,144 @@
+# enhancement-68: Multiple AllowLists per Target
+
+<!-- toc -->
+- [Release Signoff Checklist](#release-signoff-checklist)
+- [Summary](#summary)
+- [Motivation](#motivation)
+  - [Goals](#goals)
+  - [Non-Goals](#non-goals)
+- [Proposal](#proposal)
+  - [User Stories (optional)](#user-stories-optional)
+    - [Story 1](#story-1)
+    - [Story 2](#story-2)
+  - [Notes/Constraints/Caveats (optional)](#notesconstraintscaveats-optional)
+  - [Risks and Mitigations](#risks-and-mitigations)
+- [Design Details](#design-details)
+  - [Test Plan](#test-plan)
+  - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
+- [Drawbacks](#drawbacks)
+- [Alternatives](#alternatives)
+- [Infrastructure Needed (optional)](#infrastructure-needed-optional)
+<!-- /toc -->
+
+## Release Signoff Checklist
+
+- [ ] Enhancement issue in release milestone, which links to pull request in [keylime/enhancements]
+- [ ] Core members have approved the issue with the label `implementable`
+- [ ] Design details are appropriately documented
+- [ ] Test plan is in place
+- [ ] User-facing documentation has been created in [keylime/keylime-docs]
+
+## Summary
+
+This enhancement proposes a way to allow Keylime to associate multiple
+allowlists with a monitoring target/host. This will allow various
+parts of an organization to automatically generate their allowlists
+and combine them as needed. This will build off of the alread existing
+infrastructure to manage allowlists by name and assign them to targets
+using `keylime_tenant`.
+
+## Motivation
+
+Currently there is a 1-to-1 relationship between allowlists and targets
+but that can make it difficult to manage in a real-world environment. In
+many production systems the list of valid files and measurements can have
+multiple sources. There can be a list for the base OS image which might be
+provided by the OS vendor (which itself might be multiple lists). There
+can also exist various CI/CD pipelines which create custom applications
+and thus a new list for each. At the same time, DevSecOps pipelines
+might update system configuration files and create a new allowlist for
+these. Trying to manage and combine all of these lists of files together
+into a single entity and apply them per-target using keylime tenant is
+difficult and non-transparent.
+
+We want to make this process simpler and easier to automate for more use
+cases. This will not only help Keylime users scale up their usage, but
+also increase adoption and make Keylime more attractive for downstream
+projects.
+
+### Goals
+
+* Allow users to add multiple allowlists to a target when it is created
+* Allow users to add an additional allowlist to an existing target
+
+### Non-Goals
+
+More extensive operations on the 1-to-many list won't be included such as removing a single allowlist from the list. For more complicated operations it would be better to just `delete` and then `add` a new target.
+
+## Proposal
+
+These are the proposed changes:
+
+* Change the DB relationship between `verifiermain` and `allowlist` to be 1-to-many
+* Allow multiple allowlists to be specified in the tenant's "add" command.
+* Add a new "append" command to the tenant
+
+### User Stories
+
+#### Story 1
+
+As a Fedora CoreOS user, I already know every package that could
+be present on my system based on my ostree version. I want to just
+tell Keylime where to find the list of file hashes for my specific
+version for my base OS. But then I want to provide a 2nd allowlist
+for my custom application that is generated by my CI/CD pipeline. As
+each new version of the application is built, a new keylime-formatted
+allowlist can be generated and added to keylime as named allowlist. Then
+`keylime_tenant` can be run to inform keylime that applicable targets
+have a new allowlist associated with them. Then when new versions of
+the application are deployed, keylime will validate and allow the new
+versions of the application.
+
+#### Story 2
+
+I have a mature automated process for generating my OS base image in a
+cloud environment. This process can also generate a keylime-formatted
+allowlist. After my base image has been deployed, my team uses
+Configuration Management tools (such as Ansible or Puppet) to
+configure the system based on it's desired role prior to application
+deployment. This CM pipeline will also generate keylime-formatted
+allowlists and upload them via `keylime_tenant`. Then when the host is
+added to the verifier, both allowlists can be referenced and the host
+will be monitored according to it's role.
+
+### Risks and Mitigations
+
+This is expanding on existing functionality and should be relatively risk-free
+
+## Design Details
+
+* Craft a DB migration adding a new table named `target_allowlist` which will reference `verifiermain` and `allowlist`.
+* Allow multiple `--allowlist`, `--allowlist-name` and `--allowlist-url` options to `keylime_tenant`'s "add" command
+    * Other allowlist options such as `--allowlist-checksum`, `--allowlist-sig`, etc, will need to be processed in-order. Meaning the first `--allowlist-checksum` will apply to the first `--allowlist` or `--allowlist-url` that is encountered.
+* Add a new `append` command to `keylime_tenant` to function similar to `add` but that appends allowlists to existing targets
+
+### Test Plan
+
+Addition unit and integration tests will be needed. Existing tests should
+continue to work as-is as any existing `keylime_tenant` usage will still
+be valid.
+
+### Upgrade / Downgrade Strategy
+
+Alembic migrations should handle all of the upgrade/downgrade
+work. Existing usage of the `keylime_tenant` command will continue to
+work as-is.
+
+## Drawbacks
+
+Changing from 1-to-1 to 1-to-many is inherently more complicated. But
+since it still allows 1-to-1 usage, existing users of keylime shouldn't
+notice any difference until they start using the new features.
+
+## Alternatives
+
+Currently the only alternative is to handle merging and combining
+allowlists yourself. Then you would need to either make each merged
+allowlist bespoke per-target, or use named allowlists with combined
+complicated names such as "OS-1.2.3-Role-X-App-Y" or something
+similar. The need still exists but there is no standard way to accomodate
+it without this feature.
+
+## Infrastructure Needed (optional)
+
+No additional infrastructure needed.