From 34c4252900cfd9533447f074b2aa76628b97ef7c Mon Sep 17 00:00:00 2001 From: Michael Peters Date: Tue, 22 Mar 2022 15:46:56 -0400 Subject: [PATCH] Multiple AllowLists per Target Signed-off-by: Michael Peters --- 68-multi-allowlists.md | 144 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 68-multi-allowlists.md diff --git a/68-multi-allowlists.md b/68-multi-allowlists.md new file mode 100644 index 0000000..be48ce8 --- /dev/null +++ b/68-multi-allowlists.md @@ -0,0 +1,144 @@ +# enhancement-68: Multiple AllowLists per Target + + +- [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) + + +## 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.