Adding collection concept to docs and fixing code snippet formatting …

…in md (#445)

* adding collection concept and fixing code snippet formatting in md

---------

Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk>

docgen/docs.go

@@ -24,6 +24,7 @@ import (
 	"strings"
 
 	"github.com/in-toto/witness/cmd"
+	"github.com/invopop/jsonschema"
 	"github.com/spf13/cobra/doc"
 
 	_ "github.com/in-toto/go-witness"
@@ -82,7 +83,7 @@ func main() {
 			os.Exit(1)
 		}
 
-		schemaContent := "## Schema" + "\n```json\n" + indented.String() + "```\n"
+		schemaContent := "## Schema" + "\n```json\n" + indented.String() + "\n```\n"
 		err = os.WriteFile(fmt.Sprintf("%s/attestors/%s.json", directory, att.Name()), []byte(indented.String()+"\n "), 0644)
 		if err != nil {
 			fmt.Println("Error writing to file:", err)
@@ -122,4 +123,50 @@ func main() {
 		log.Printf("Schema for %s written to %s/attestors/%s.md\n", att.Name(), directory, att.Name())
 
 	}
+
+	log.Println("Generating schema for the Witness Collection")
+	coll := jsonschema.Reflect(attestation.Collection{})
+	schemaJson, err := coll.MarshalJSON()
+	if err != nil {
+		fmt.Println("Error marshalling JSON schema:", err)
+		os.Exit(1)
+	}
+	var indented bytes.Buffer
+	err = json.Indent(&indented, schemaJson, "", "  ")
+	if err != nil {
+		fmt.Println("Error marshalling JSON schema:", err)
+		os.Exit(1)
+	}
+	schemaContent := "## Schema" + "\n```json\n" + indented.String() + "\n```\n"
+	f, err := os.ReadFile(fmt.Sprintf("%s/concepts/collection.md", directory))
+	if err != nil {
+		fmt.Println("Error reading file:", err)
+		os.Exit(1)
+	}
+
+	// Find the index of "## Schema" string
+	index := strings.Index(string(f), "## Schema")
+	if index == -1 {
+		f = append(f, schemaContent...)
+
+		err = os.WriteFile(fmt.Sprintf("%s/concepts/collection.md", directory), f, 0644)
+		if err != nil {
+			fmt.Println("Error writing to file:", err)
+			os.Exit(1)
+		}
+	} else {
+
+		// Truncate the content to remove everything after "## Schema"
+		f = f[:index]
+
+		f = append(f, schemaContent...)
+
+		err = os.WriteFile(fmt.Sprintf("%s/concepts/collection.md", directory), f, 0644)
+		if err != nil {
+			fmt.Println("Error writing to file:", err)
+			os.Exit(1)
+		}
+
+		log.Printf("Schema for collection written to %s/concepts/collection.md\n", directory)
+	}
 }

docgen/verify.sh

@@ -22,8 +22,12 @@ tmpdir2=$(mktemp -d)
 cp docs/commands.md "$tmpdir2/"
 mkdir "$tmpdir2/attestors"
 mkdir "$tmpdir/attestors"
+mkdir "$tmpdir2/concepts"
+mkdir "$tmpdir/concepts"
 cp docs/attestors/* "$tmpdir2/attestors/"
 cp docs/attestors/*.md "$tmpdir/attestors/"
+cp docs/concepts/collection.md "$tmpdir2/concepts/"
+cp docs/concepts/collection.md "$tmpdir/concepts/"
 go run ./docgen --dir "$tmpdir"
 echo "###########################################"
 echo "If diffs are found, run: make docgen"

docs/attestors/aws.md

@@ -112,4 +112,5 @@ GovCloud regions.
       ]
     }
   }
-}```
+}
+```

docs/attestors/command-run.md

@@ -94,4 +94,5 @@ Linux operating systems and is considered experimental.
       ]
     }
   }
-}```
+}
+```

docs/attestors/environment.md

@@ -37,4 +37,5 @@ so take care to not leak secrets stored in environment variables.
       ]
     }
   }
-}```
+}
+```

docs/attestors/gcp-iit.md

@@ -573,4 +573,5 @@ against Google's JWKS ([JSON Web Key Set](https://auth0.com/docs/secure/tokens/j
       ]
     }
   }
-}```
+}
+```

docs/attestors/git.md

@@ -140,4 +140,5 @@ The attestor returns the SHA1 ([Secure Hash Algorithm 1](https://en.wikipedia.or
       ]
     }
   }
-}```
+}
+```

docs/attestors/github.md

@@ -560,4 +560,5 @@ The [Github](https://github.com/about) Attestor records information about the [G
       ]
     }
   }
-}```
+}
+```

docs/attestors/gitlab.md

@@ -575,4 +575,5 @@ instance's JWKS ([JSON Web Key Set](https://auth0.com/docs/secure/tokens/json-we
       ]
     }
   }
-}```
+}
+```

docs/attestors/jwt.md

@@ -500,4 +500,5 @@ claims of the JWT.  The JWK that was used to verify the JWT is also recorded.
       ]
     }
   }
-}```
+}
+```

docs/attestors/link.md

@@ -90,4 +90,5 @@ The Link Attestor generates an [in-toto Link attestation](https://in-toto.readth
       ]
     }
   }
-}```
+}
+```

docs/attestors/material.md

@@ -29,4 +29,5 @@ of all files before any changes are made by a command.
   "required": [
     "Materials"
   ]
-}```
+}
+```

docs/attestors/maven.md

@@ -71,4 +71,5 @@ The [Maven](https://maven.apache.org/) Attestor records project and dependency i
       ]
     }
   }
-}```
+}
+```

docs/attestors/oci.md

@@ -97,4 +97,5 @@ attestation.
       ]
     }
   }
-}```
+}
+```

docs/attestors/policyverify.md

@@ -77,4 +77,5 @@ The Policy Verify Attestor generates a [verification summary attestation](https:
       ]
     }
   }
-}```
+}
+```

docs/attestors/product.md

@@ -47,4 +47,5 @@ All subjects are reported as subjects.
   "required": [
     "Products"
   ]
-}```
+}
+```

docs/attestors/sarif.md

@@ -788,4 +788,5 @@ The Sarif attestor records the contents of any [products](./product.md) that are
       ]
     }
   }
-}```
+}
+```

docs/attestors/slsa.md

@@ -162,4 +162,5 @@ The SLSA Attestor generates a [SLSA Provenance](https://slsa.dev/spec/v1.0/prove
       ]
     }
   }
-}```
+}
+```

docs/concepts/collection.md

@@ -0,0 +1,58 @@
+# Collection
+
+Witness enables users to generate a wide variety of attestation predicates (arbitrary metadata about a subject artifact, with a type-specific schema) through the use of attestors. For each `witness run`, multiple attestors can be specified and therefore multiple predicates can be
+generated as an output. Witness correlates each `run` invocation to a "step" in an artifacts supply-chain lifecycle (the name of which is determine by the `--step` flag). Witness therefore needs a way of bundling these predicates together to form a complete representation of that specific step, but also to avoid the repeated process of signing multiple statements. The `Collection` object is a predicate type that achieves this.
+
+## Schema
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/in-toto/go-witness/attestation/collection",
+  "$ref": "#/$defs/Collection",
+  "$defs": {
+    "Collection": {
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "attestations": {
+          "items": {
+            "$ref": "#/$defs/CollectionAttestation"
+          },
+          "type": "array"
+        }
+      },
+      "additionalProperties": false,
+      "type": "object",
+      "required": [
+        "name",
+        "attestations"
+      ]
+    },
+    "CollectionAttestation": {
+      "properties": {
+        "type": {
+          "type": "string"
+        },
+        "attestation": true,
+        "starttime": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "endtime": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      "additionalProperties": false,
+      "type": "object",
+      "required": [
+        "type",
+        "attestation",
+        "starttime",
+        "endtime"
+      ]
+    }
+  }
+}
+```