From 405a64dddda09e4ff96c65dd6fe4fd0944f98eef Mon Sep 17 00:00:00 2001 From: Tom Meadows Date: Thu, 16 May 2024 21:19:38 +0100 Subject: [PATCH] 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 --- docgen/docs.go | 49 +++++++++++++++++++++++++++- docgen/verify.sh | 4 +++ docs/attestors/aws.md | 3 +- docs/attestors/command-run.md | 3 +- docs/attestors/environment.md | 3 +- docs/attestors/gcp-iit.md | 3 +- docs/attestors/git.md | 3 +- docs/attestors/github.md | 3 +- docs/attestors/gitlab.md | 3 +- docs/attestors/jwt.md | 3 +- docs/attestors/link.md | 3 +- docs/attestors/material.md | 3 +- docs/attestors/maven.md | 3 +- docs/attestors/oci.md | 3 +- docs/attestors/policyverify.md | 3 +- docs/attestors/product.md | 3 +- docs/attestors/sarif.md | 3 +- docs/attestors/slsa.md | 3 +- docs/concepts/collection.md | 58 ++++++++++++++++++++++++++++++++++ 19 files changed, 142 insertions(+), 17 deletions(-) create mode 100644 docs/concepts/collection.md diff --git a/docgen/docs.go b/docgen/docs.go index 80a1c0a1..9ebcea51 100644 --- a/docgen/docs.go +++ b/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) + } } diff --git a/docgen/verify.sh b/docgen/verify.sh index 0d7874e7..d3f443d9 100755 --- a/docgen/verify.sh +++ b/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" diff --git a/docs/attestors/aws.md b/docs/attestors/aws.md index 92e4e873..2b2fe647 100644 --- a/docs/attestors/aws.md +++ b/docs/attestors/aws.md @@ -112,4 +112,5 @@ GovCloud regions. ] } } -}``` +} +``` diff --git a/docs/attestors/command-run.md b/docs/attestors/command-run.md index 8f76500e..6e9b7e4b 100644 --- a/docs/attestors/command-run.md +++ b/docs/attestors/command-run.md @@ -94,4 +94,5 @@ Linux operating systems and is considered experimental. ] } } -}``` +} +``` diff --git a/docs/attestors/environment.md b/docs/attestors/environment.md index 30503db7..3e5d0625 100644 --- a/docs/attestors/environment.md +++ b/docs/attestors/environment.md @@ -37,4 +37,5 @@ so take care to not leak secrets stored in environment variables. ] } } -}``` +} +``` diff --git a/docs/attestors/gcp-iit.md b/docs/attestors/gcp-iit.md index ba228bc3..04918bde 100644 --- a/docs/attestors/gcp-iit.md +++ b/docs/attestors/gcp-iit.md @@ -573,4 +573,5 @@ against Google's JWKS ([JSON Web Key Set](https://auth0.com/docs/secure/tokens/j ] } } -}``` +} +``` diff --git a/docs/attestors/git.md b/docs/attestors/git.md index af5922b2..2904b85c 100644 --- a/docs/attestors/git.md +++ b/docs/attestors/git.md @@ -140,4 +140,5 @@ The attestor returns the SHA1 ([Secure Hash Algorithm 1](https://en.wikipedia.or ] } } -}``` +} +``` diff --git a/docs/attestors/github.md b/docs/attestors/github.md index 1da80a3b..3e18e1ca 100644 --- a/docs/attestors/github.md +++ b/docs/attestors/github.md @@ -560,4 +560,5 @@ The [Github](https://github.com/about) Attestor records information about the [G ] } } -}``` +} +``` diff --git a/docs/attestors/gitlab.md b/docs/attestors/gitlab.md index f6c289e7..a8b6fafe 100644 --- a/docs/attestors/gitlab.md +++ b/docs/attestors/gitlab.md @@ -575,4 +575,5 @@ instance's JWKS ([JSON Web Key Set](https://auth0.com/docs/secure/tokens/json-we ] } } -}``` +} +``` diff --git a/docs/attestors/jwt.md b/docs/attestors/jwt.md index c14e0604..d395d828 100644 --- a/docs/attestors/jwt.md +++ b/docs/attestors/jwt.md @@ -500,4 +500,5 @@ claims of the JWT. The JWK that was used to verify the JWT is also recorded. ] } } -}``` +} +``` diff --git a/docs/attestors/link.md b/docs/attestors/link.md index 9ed13e23..faf3b87d 100644 --- a/docs/attestors/link.md +++ b/docs/attestors/link.md @@ -90,4 +90,5 @@ The Link Attestor generates an [in-toto Link attestation](https://in-toto.readth ] } } -}``` +} +``` diff --git a/docs/attestors/material.md b/docs/attestors/material.md index be2abddf..6938530b 100644 --- a/docs/attestors/material.md +++ b/docs/attestors/material.md @@ -29,4 +29,5 @@ of all files before any changes are made by a command. "required": [ "Materials" ] -}``` +} +``` diff --git a/docs/attestors/maven.md b/docs/attestors/maven.md index 43018732..97204f05 100644 --- a/docs/attestors/maven.md +++ b/docs/attestors/maven.md @@ -71,4 +71,5 @@ The [Maven](https://maven.apache.org/) Attestor records project and dependency i ] } } -}``` +} +``` diff --git a/docs/attestors/oci.md b/docs/attestors/oci.md index 0c70c096..edb19f29 100644 --- a/docs/attestors/oci.md +++ b/docs/attestors/oci.md @@ -97,4 +97,5 @@ attestation. ] } } -}``` +} +``` diff --git a/docs/attestors/policyverify.md b/docs/attestors/policyverify.md index b22b65f5..e90f67b9 100644 --- a/docs/attestors/policyverify.md +++ b/docs/attestors/policyverify.md @@ -77,4 +77,5 @@ The Policy Verify Attestor generates a [verification summary attestation](https: ] } } -}``` +} +``` diff --git a/docs/attestors/product.md b/docs/attestors/product.md index afb4acd2..a16d19da 100644 --- a/docs/attestors/product.md +++ b/docs/attestors/product.md @@ -47,4 +47,5 @@ All subjects are reported as subjects. "required": [ "Products" ] -}``` +} +``` diff --git a/docs/attestors/sarif.md b/docs/attestors/sarif.md index 75216656..ee1acfa7 100644 --- a/docs/attestors/sarif.md +++ b/docs/attestors/sarif.md @@ -788,4 +788,5 @@ The Sarif attestor records the contents of any [products](./product.md) that are ] } } -}``` +} +``` diff --git a/docs/attestors/slsa.md b/docs/attestors/slsa.md index 7e60b36b..3e025df1 100644 --- a/docs/attestors/slsa.md +++ b/docs/attestors/slsa.md @@ -162,4 +162,5 @@ The SLSA Attestor generates a [SLSA Provenance](https://slsa.dev/spec/v1.0/prove ] } } -}``` +} +``` diff --git a/docs/concepts/collection.md b/docs/concepts/collection.md new file mode 100644 index 00000000..79b73c66 --- /dev/null +++ b/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" + ] + } + } +} +```