doc(cli): bundle description and examples. (#134)

* doc(cli): bundle description and examples.

* feat(ruleset): enable rego engine for ruleset.

* doc(changelog): update changelog.

* doc(cli): update cli documentation.

CHANGELOG.md

@@ -4,15 +4,51 @@
 
 FEATURES:
 
+* cli:
+  * `darwin-amd64` and `darwin-arm64` are code signed and notarized using an
+    Apple Developer ID certificate to allow harp execution on Silicon M1 based
+    computers. [#134](https://github.com/elastic/harp/pull/134)
+
+* cli/transform:
+  * `compress`/`decompress` commands for various algorithms. [#117](github.com/elastic/harp/pull/117)
+  * `hash`/`multihash` command for various hashing algorithms. [#117](github.com/elastic/harp/pull/117)
+  * `encode`/`decode` command for various encoding strategies [#117](github.com/elastic/harp/pull/117)
+
+* bundle/ruleset:
+  * enable `rego` language for RuleSet constraint engine. [#134](https://github.com/elastic/harp/pull/134)
+
+* sdk/api:
+  * support `user_data` for `Bundle`, `Package`, `SecretChain` to store custom
+    arbitrary data during pipeline execution. [#134](https://github.com/elastic/harp/pull/134)
+
 * sdk/value:
   * `encoding` reader / writer factory. [#117](github.com/elastic/harp/pull/117)
   * `compression` reader/writer factory. [#117](github.com/elastic/harp/pull/117)
   * `hash` writer factory. [#117](github.com/elastic/harp/pull/117)
 
-* cli/transform:
-  * `compress`/`decompress` commands for various algorithms [#117](github.com/elastic/harp/pull/117)
-  * `hash`/`multihash` command for various hashing algorithms. [#117](github.com/elastic/harp/pull/117)
-  * `encode`/`decode` command for various encoding strategies [#117](github.com/elastic/harp/pull/117)
+CHANGES:
+
+* go:
+  * FIPS artifact build process is disabled.
+
+* git:
+  * the tag `cmd/harp/vX.XX` will never be produced.
+
+* ci:
+  * `dependabot` setup to monitor and automate dependency updates.
+  * the release pipeline has been completely redesigned to use goreleaser.
+  * SLSA `provenance` is temporary disabled due to a lack of the multiplatform support
+    for the used action.
+
+DIST:
+
+* build/ci:
+  * SHA256 fingerprint is provided per artifact.
+  * SBOM is embedded in the artifact archive.
+
+* build/gha:
+  * [zntrio/harp-installer](https://github.com/zntrio/harp-installer) github action
+    could be used to set up harp during your github action pipelines.
 
 ## 0.2.7
 

api/proto/harp/bundle/v1/bundle.proto

@@ -28,6 +28,7 @@ option objc_class_prefix = "SBX";
 option php_namespace = "harp\\Bundle\\V1";
 
 import "harp/bundle/v1/template.proto";
+import "google/protobuf/any.proto";
 import "google/protobuf/wrappers.proto";
 
 // Bundle is a concrete secret bundle.
@@ -48,6 +49,8 @@ message Bundle {
   google.protobuf.BytesValue values = 6;
   // Merkle Tree root
   bytes merkle_tree_root = 7;
+  // User data storage
+  map<string, google.protobuf.Any> user_data = 99;
 }
 
 // Package is a secret organizational unit.
@@ -64,6 +67,8 @@ message Package {
   SecretChain secrets = 4;
   // SecretChain versions
   map<fixed32, SecretChain> versions = 5;
+  // User data storage
+  map<string, google.protobuf.Any> user_data = 99;
 }
 
 // SecretChain describe a secret version chain.
@@ -84,6 +89,8 @@ message SecretChain {
   google.protobuf.UInt32Value next_version = 6;
   // Locked buffer when encryption is enabled
   google.protobuf.BytesValue locked = 7;
+  // User data storage
+  map<string, google.protobuf.Any> user_data = 99;
 }
 
 // KV contains the key, the value and the type of the value.

api/proto/harp/bundle/v1/ruleset.proto

@@ -65,6 +65,10 @@ message Rule {
   string description = 2;
   // REQUIRED. Rule path matcher filter.
   string path = 3;
-  // REAQUIRED. Constraint collection.
+  // OPTIONAL. CEL Constraint collection.
   repeated string constraints = 4;
+  // OPTIONAL. Rego policy.
+  string rego = 5;
+  // OPTIONAL. Rego policy file.
+  string rego_file = 6;
 }

build/mage/golang/import.go

@@ -30,7 +30,7 @@ func Import() error {
 	color.Cyan("## Process imports")
 
 	for pth := range CollectedGoFiles {
-		args := []string{"-w", "-local", "github.com/elastic/harp"}
+		args := []string{"write", "-s", "Standard", "-s", "Default", "-s", "Prefix(github.com/elastic)"}
 		args = append(args, pth)
 
 		if err := sh.RunV("gci", args...); err != nil {

cmd/harp/internal/cmd/bundle_decrypt.go

@@ -39,9 +39,44 @@ type bundleDecryptParams struct {
 var bundleDecryptCmd = func() *cobra.Command {
 	params := &bundleDecryptParams{}
 
+	longDesc := cmdutil.LongDesc(`
+	Decrypt a bundle content.
+
+	For confidentiality purpose, bundle package value can be encrypted before
+	the container sealing. It offers confidentiality properties so that the
+	final consumer must know an additional decryption key to be allowed to
+	read the package value.
+
+	All package properties (name, labels, annotations) remain a clear-text
+	message. Only package values (secret K/V) is encrypted.
+
+	In order to decrypt the package value, harp uses the value encryption
+	transformers. The required key must be provided in a format understandable
+	by the encryption transformer factory.
+
+	This act as in-transit/in-use encryption.
+	`)
+
+	examples := cmdutil.Examples(`
+	# Decrypt a bundle from STDIN and produce output to STDOUT
+	harp bundle decrypt --key <transformer key>
+
+	# Decrypt a bundle from STDIN using multiple transformer keys
+	harp bundle decrypt --key <transformer key 1> --key <transformer key 2>
+
+	# Decrypt a bundle from STDIN and ignore secrets which could not be decrypted
+	# with given transformer key (partial decryption / authorization by key)
+	harp bundle decrypt --skip-not-decryptable --key <transformer-key>
+
+	# Decrypt a bundle from STDIN and produce output to a file
+	harp bundle decrypt --key <transformer key> --out decrypted.bundle
+	`)
+
 	cmd := &cobra.Command{
-		Use:   "decrypt",
-		Short: "Decrypt secret values",
+		Use:     "decrypt",
+		Short:   "Decrypt secret values",
+		Long:    longDesc,
+		Example: examples,
 		Run: func(cmd *cobra.Command, args []string) {
 			// Initialize logger and context
 			ctx, cancel := cmdutil.Context(cmd.Context(), "harp-bundle-decrypt", conf.Debug.Enable, conf.Instrumentation.Logs.Level)

cmd/harp/internal/cmd/bundle_diff.go

@@ -31,14 +31,30 @@ type bundleDiffParams struct {
 	sourcePath      string
 	destinationPath string
 	generatePatch   bool
+	outputPath      string
 }
 
 var bundleDiffCmd = func() *cobra.Command {
 	params := &bundleDiffParams{}
 
+	longDesc := cmdutil.LongDesc(`
+	Compute Bundle object differences.
+
+	Useful to debug a BundlePatch application and watch for a Bundle alteration.
+	`)
+
+	examples := cmdutil.Examples(`
+	# Diff a bundle from STD and a file based one
+	harp bundle diff --old - --new rotated.bundle
+
+	# Generate a BundlePatch from differences
+	harp bundle diff --old - --new rotated.bundle --patch --out rotation.yaml`)
+
 	cmd := &cobra.Command{
-		Use:   "diff",
-		Short: "Display container differences",
+		Use:     "diff",
+		Short:   "Display bundle differences",
+		Long:    longDesc,
+		Example: examples,
 		Run: func(cmd *cobra.Command, args []string) {
 			// Initialize logger and context
 			ctx, cancel := cmdutil.Context(cmd.Context(), "harp-bundle-diff", conf.Debug.Enable, conf.Instrumentation.Logs.Level)
@@ -48,7 +64,7 @@ var bundleDiffCmd = func() *cobra.Command {
 			t := &bundle.DiffTask{
 				SourceReader:      cmdutil.FileReader(params.sourcePath),
 				DestinationReader: cmdutil.FileReader(params.destinationPath),
-				OutputWriter:      cmdutil.StdoutWriter(),
+				OutputWriter:      cmdutil.FileWriter(params.outputPath),
 				GeneratePatch:     params.generatePatch,
 			}
 
@@ -61,8 +77,10 @@ var bundleDiffCmd = func() *cobra.Command {
 
 	// Parameters
 	cmd.Flags().StringVar(&params.sourcePath, "old", "", "Container path ('-' for stdin or filename)")
+	log.CheckErr("unable to mark 'old' flag as required.", cmd.MarkFlagRequired("old"))
 	cmd.Flags().StringVar(&params.destinationPath, "new", "", "Container path ('-' for stdin or filename)")
-	log.CheckErr("unable to mark 'dst' flag as required.", cmd.MarkFlagRequired("dst"))
+	log.CheckErr("unable to mark 'new' flag as required.", cmd.MarkFlagRequired("new"))
+	cmd.Flags().StringVar(&params.outputPath, "out", "-", "Output ('-' for stdout or filename)")
 	cmd.Flags().BoolVar(&params.generatePatch, "patch", false, "Output as a bundle patch")
 
 	return cmd

cmd/harp/internal/cmd/bundle_dump.go

@@ -39,9 +39,41 @@ type bundleDumpParams struct {
 var bundleDumpCmd = func() *cobra.Command {
 	params := &bundleDumpParams{}
 
+	longDesc := cmdutil.LongDesc(`
+	Inspect a Bundle object.
+
+	Harp Bundles is a structure designed to hold additional properties associated
+	to a path (package name) and values (secrets). For your pipeline usages, you
+	can store annotations, labels and user data which can be consumed and/or
+	produced during the secret management pipeline execution.
+
+	The Bundle object specification can be consulted here -	https://ela.st/harp-spec-bundle
+	`)
+
+	examples := cmdutil.Examples(`
+	# Dump a JSON representation of a Bundle object from STDIN
+	harp bundle dump
+
+	# Dump a JSON map containing package name as key and associated secret kv
+	harp bundle dump --data-only
+
+	# Dump a JSON map containing package name as key and associated metadata
+	harp bundle dump --metadata-only
+
+	# Dump all package paths as a list (useful for xargs usage)
+	harp bundle dump --path-only
+
+	# Dump a Bundle using a JMEFilter query
+	harp bundle dump --query <jmesfilter query>
+
+	# Dump a bundle content excluding the template used to generate
+	harp bundle dump --skip-template`)
+
 	cmd := &cobra.Command{
-		Use:   "dump",
-		Short: "Dump as JSON",
+		Use:     "dump",
+		Short:   "Dump as JSON",
+		Long:    longDesc,
+		Example: examples,
 		Run: func(cmd *cobra.Command, args []string) {
 			// Initialize logger and context
 			ctx, cancel := cmdutil.Context(cmd.Context(), "harp-bundle-dump", conf.Debug.Enable, conf.Instrumentation.Logs.Level)