Skip to content

Latest commit

 

History

History
346 lines (265 loc) · 12.8 KB

109-consolidate_policy_tools.md

File metadata and controls

346 lines (265 loc) · 12.8 KB

enhancement-109: Consolidate policy generation tools

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

Keylime provides multiple policy generation and editting tools with separate functionalities located in different parts of the repository:

  • scripts/create_runtime_policy.sh
    • A shell script that measures all the files in the filesystem to generate a runtime policy as an allowlist
  • keylime/cmd/convert_runtime_policy.py
    • Converts a runtime policy from the legacy format (i.e. allowlist and excludelists) to the unified JSON format
  • keylime/cmd/create_policy.py
    • The main tool to create an manipulate policies in the unified JSON format.
  • keylime/cmd/sign_runtime_policy.py
    • Signs a runtime policy, generating a signed policy in the Dead Simple Signing Envelope (DSSE) format

These scripts are not fit for usage in production environment:

  • There is no consistency in their user interface
  • There is not enough documentation on their usage
  • Each script provides a different functionality, although all scripts are used for policy creation and editing
  • They are not located in a consistent location in the repository

The goal of this enhancement is to provide a single tool consolidating all the existing functionality from the scripts above adding consistent interface and documentation

Motivation

Creating the attestation policies is a requirement for the deployment of keylime, but the existing scripts are difficult to use. The main goal is to lower the difficulty of creating and editing policies.

Goals

  • Consolidate all the policy generation and editing tools provided in the repository in a single tool
  • Provide a consistent user interface for all the functionalities
  • Provide documentation for the policy generation tool

Non-Goals

  • Adding new functionalities to the consolidated policy generation tool is out of scope. The goal of this enhancement is only to consolidate the existing tools.

Proposal

The proposal is to create a single tool that will provide the functionality of the existing scripts. The necessary steps would be:

  • Design a consistent interface for the consolidated tool
  • Move all the functionality from the existing scripts into the new created tool following the interface design

User Stories (optional)

Story 1

  • The user consults the policy generation tool documentation
  • The user executes the policy generation tool to create a new policy file based on the measurements of the files in the file system
  • Using the same tool, the user can combine an allowlist and an excludelist to generate a new policy
  • Using the same tool, the user can sign the generated policy using a private key

Notes/Constraints/Caveats (optional)

If some functionality is considered insecure, useless, or the implementation is not possible, it can be excluded from the consolidated tool after obtaining approval from the community.

Risks and Mitigations

The existing tools should be kept for a grace period alongside the new tool.

Design Details

The interface of the new consolidated policy generation tool should be consistent, intuitive, and organized, meaning:

  • Use subcommands to separate functionalities
  • Use commonly used options for their usual purpose:
    • For example, --help or -h for help, -o for output, etc.
  • Similar parameters of different subcommands should be passed using similar options
    • For example, 2 subcommands that receive a key as input could use the same --key option or -k as short
  • Provide sane default values for optional parameters

The documentation should cover all the subcommands and options:

  • With helpful error messages, which may indicate next steps or clarify missing information
  • Ideally, with both concise and long versions
    • For example, a concise usage explanation with --help and a long usage explanation in manpages

A suggestion for the consolidation of the functionalities:

  • Rewrite the functionality provided by scripts/create_runtime_policy.sh in python
  • Move all the functionalities from the various scripts to the consolidated tool.

The output of the consolidated tool must be compatible with the current components code and should not require any change to the components.

Additional usability improvements can be added to the tool, such as:

  • Autocompleting of commands and/or options
  • Possibility to provide machine-friendly input
    • For example, accepting the options setting via a JSON input
  • Multiple levels of verbosity for the output

Test Plan

The code should be covered by unit tests included as part of the repository code and additional end-to-end tests added to the CI test suite (in https://github.com/RedHat-SP-Security/keylime-tests)

Upgrade / Downgrade Strategy

This enhancement should not affect components upgrading or downgrading as the intended use case is orthogonal to the components functionality.

Dependencie requirements

The addition of new dependencies should be minimized, and when needed, the addition should be properly justified and approved by the maintainers.

Drawbacks

No drawbacks were identified as during the grace period nothing would be removed from the repository

Alternatives

The alternative is to continue use the existing tools, with the option to try to improve their usability individually. The downside of this alternative is that the problem of having multiple tools with similar purpose will continue to affect the users.

Infrastructure Needed (optional)

No additional infrastructure should be needed.