README and docs restructure (#362)

* starting proposed restructure Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * adding latest changes to README Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * fixed link to contributing md Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * made title title heading size Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * named the file wrong - doh Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * resizing headings at top Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * added spacing Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * a few more fixes Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * adding background section Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * removing bullet Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * final neatening Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * updated docs further - tutorial not working Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * adding demo gif Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * adding docusaurus stuff and more progress Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * saving progress, including docusaurus website Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * changing logo Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * adding snowfall Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * adding the concepts section Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * Adding the contributing.md from archivista (#327) * adding the contributing.md from archivista * dont need jq Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * Migrating go module (#328) * added all imports * fixing go sum * changing go-witness back for now, makes more sense --------- Co-authored-by: John Kjell <john@testifysec.com> Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * Migrating to the use of in-toto/go-witness module (#331) * added all imports * fixing go sum * changing go-witness back for now, makes more sense * moved witness to using new in-toto/go-witness module Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * adding change to test now following newer version of policy * running docgen as changes found from use of new module * pinning to v0.2.0 of archivista and go-witness Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> --------- Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> Signed-off-by: Tom Meadows <tom@tmlabs.co.uk> * Bumping Go version for goreleaser (#333) bumping go version for goreleaser Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * chore: bump actions/download-artifact from 3.0.2 to 4.0.0 (#335) Bumps [actions/download-artifact](https://github.com/actions/download-artifact) from 3.0.2 to 4.0.0. - [Release notes](https://github.com/actions/download-artifact/releases) - [Commits](actions/download-artifact@9bc31d5...7a1cd32) --- updated-dependencies: - dependency-name: actions/download-artifact dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * chore: bump github/codeql-action from 2.22.9 to 3.22.11 (#336) Bumps [github/codeql-action](https://github.com/github/codeql-action) from 2.22.9 to 3.22.11. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](github/codeql-action@c0d1daa...b374143) --- updated-dependencies: - dependency-name: github/codeql-action dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: John Kjell <john@testifysec.com> * chore: bump actions/upload-artifact from 3.1.3 to 4.0.0 (#337) Bumps [actions/upload-artifact](https://github.com/actions/upload-artifact) from 3.1.3 to 4.0.0. - [Release notes](https://github.com/actions/upload-artifact/releases) - [Commits](actions/upload-artifact@a8a3f3a...c7d193f) --- updated-dependencies: - dependency-name: actions/upload-artifact dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: John Kjell <john@testifysec.com> * chore: bump github/codeql-action from 3.22.11 to 3.22.12 (#343) Bumps [github/codeql-action](https://github.com/github/codeql-action) from 3.22.11 to 3.22.12. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](github/codeql-action@b374143...012739e) --- updated-dependencies: - dependency-name: github/codeql-action dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * chore: bump actions/download-artifact from 4.0.0 to 4.1.0 (#342) Bumps [actions/download-artifact](https://github.com/actions/download-artifact) from 4.0.0 to 4.1.0. - [Release notes](https://github.com/actions/download-artifact/releases) - [Commits](actions/download-artifact@7a1cd32...f44cd7b) --- updated-dependencies: - dependency-name: actions/download-artifact dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * moving config doc Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * adding latest changes Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * saving progress Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * adding keyless signing tutorial Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * doing images Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * fixing broken image Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * changing url Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * fixed images Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * updating docs and removing witness.md Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * Update go-git to resolve vulnerability (#346) * Update go-git to resolve vulnerability Signed-off-by: John Kjell <john@testifysec.com> * Update x/crypto Signed-off-by: John Kjell <john@testifysec.com> --------- Signed-off-by: John Kjell <john@testifysec.com> * chore: bump actions/dependency-review-action from 3.1.4 to 3.1.5 (#349) * Add FOSSA license scanning Signed-off-by: John Kjell <john@testifysec.com> * Add Security MD files an add FOSSA scan badge Signed-off-by: John Kjell <john@testifysec.com> Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * Pin dependencies and restrict permissions Signed-off-by: John Kjell <john@testifysec.com> * Add signing to goreleaser and Best Practices badge to readme. Signed-off-by: John Kjell <john@testifysec.com> Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * Add cosign install Signed-off-by: John Kjell <john@testifysec.com> * Update cloudflare/circl due to dependabot failure (#352) Signed-off-by: John Kjell <john@testifysec.com> * updated package json Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * chore: bump actions/cache from 3.3.2 to 3.3.3 (#355) Bumps [actions/cache](https://github.com/actions/cache) from 3.3.2 to 3.3.3. - [Release notes](https://github.com/actions/cache/releases) - [Changelog](https://github.com/actions/cache/blob/main/RELEASES.md) - [Commits](actions/cache@704facf...e12d46a) --- updated-dependencies: - dependency-name: actions/cache dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * chore: bump actions/upload-artifact from 4.0.0 to 4.1.0 (#356) Bumps [actions/upload-artifact](https://github.com/actions/upload-artifact) from 4.0.0 to 4.1.0. - [Release notes](https://github.com/actions/upload-artifact/releases) - [Commits](actions/upload-artifact@c7d193f...1eb3cb2) --- updated-dependencies: - dependency-name: actions/upload-artifact dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * chore: bump github/codeql-action from 3.22.12 to 3.23.0 (#357) Bumps [github/codeql-action](https://github.com/github/codeql-action) from 3.22.12 to 3.23.0. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](github/codeql-action@012739e...e5f05b8) --- updated-dependencies: - dependency-name: github/codeql-action dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * chore: bump actions/download-artifact from 4.1.0 to 4.1.1 (#358) Bumps [actions/download-artifact](https://github.com/actions/download-artifact) from 4.1.0 to 4.1.1. - [Release notes](https://github.com/actions/download-artifact/releases) - [Commits](actions/download-artifact@f44cd7b...6b208ae) --- updated-dependencies: - dependency-name: actions/download-artifact dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Initial attempt at PR and Issue templates (#351) * Initial attempt at PR and Issue templates Signed-off-by: John Kjell <john@testifysec.com> * Address some review feedback Signed-off-by: John Kjell <john@testifysec.com> --------- Signed-off-by: John Kjell <john@testifysec.com> Co-authored-by: Tom Meadows <tom@tmlabs.co.uk> * Checking attestors for duplicates (#361) * prevents duplicate attestors * adding tests * modified help for attestations flag --------- Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * removing witness website for now Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * editing image links Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * updating docgen Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * fixing docgen Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * addressing comments Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * fixing small issue with md Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> * fixed ellipsis Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> --------- Signed-off-by: chaosinthecrd <tom@tmlabs.co.uk> Signed-off-by: Tom Meadows <tom@tmlabs.co.uk> Signed-off-by: dependabot[bot] <support@github.com> Signed-off-by: John Kjell <john@testifysec.com> Co-authored-by: John Kjell <john@testifysec.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
in-toto · Jan 25, 2024 · b90f41b · b90f41b
1 parent 2b872a3
commit b90f41b
Show file tree

Hide file tree

Showing 23 changed files with 1,068 additions and 701 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -5,7 +5,6 @@ taking the time to contribute!
 
 Before starting, please take some time to familiarize yourself with the [Code of Conduct](CODE_OF_CONDUCT.md).
 
-
 ## Getting Started
 
 We welcome many different types of contributions and not all of them need a

diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
diff --git a/README.md b/README.md
diff --git a/docgen/docs.go b/docgen/docs.go
@@ -15,8 +15,10 @@
 package main
 
 import (
+	"bytes"
 	"flag"
-	"log"
+	"fmt"
+	"os"
 
 	"github.com/in-toto/witness/cmd"
 	"github.com/spf13/cobra/doc"
@@ -30,8 +32,27 @@ func init() {
 }
 
 func main() {
-	// Generate CLI docs
-	if err := doc.GenMarkdownTree(cmd.New(), directory); err != nil {
-		log.Fatalf("Error generating docs: %s", err)
+	mdContent := "# Witness CLI Reference\n\nThis is the reference for the Witness command line tool, generated by [Cobra](https://cobra.dev/).\n\n"
+	// Generate markdown content for all commands
+	for _, command := range cmd.New().Commands() {
+		// We are not generating docs for the completion command right now, as it doesn't render in Markdown correctly
+		if command.Use == "completion [bash|zsh|fish|powershell]" {
+			continue
+		}
+
+		buf := new(bytes.Buffer)
+		err := doc.GenMarkdown(command, buf)
+		if err != nil {
+			fmt.Println("Error generating markdown for command:", command.Use)
+			continue
+		}
+		mdContent += buf.String()
+	}
+
+	// Write the combined markdown content to a file
+	err := os.WriteFile(fmt.Sprintf("%s/commands.md", directory), []byte(mdContent), 0644)
+	if err != nil {
+		fmt.Println("Error writing to file:", err)
+		os.Exit(1)
 	}
 }
diff --git a/docgen/verify.sh b/docgen/verify.sh
@@ -19,7 +19,7 @@ set -e
 # Verify that generated Markdown docs are up-to-date.
 tmpdir=$(mktemp -d)
 tmpdir2=$(mktemp -d)
-cp docs/witness*.md "$tmpdir2/"
+cp docs/commands.md "$tmpdir2/"
 go run ./docgen --dir "$tmpdir"
 echo "###########################################"
 echo "If diffs are found, run: make docgen"

diff --git a/docs/about/how-witness-works.md b/docs/about/how-witness-works.md
@@ -0,0 +1,11 @@
+# How Witness Works
+
+### Signing
+Witness is able to observe your software development life-cycle (SDLC) by wrapping around commands executed within them. By passing any command to Witness as an argument, the tool is able to understand what was executed but also on what infrastructure, by what user or service account and more. The information that Witness gathers while the command is running is down to which [Attestors](docs/attestor.md) are used. Attestors are implementations of an interface that find and assert facts about the system Witness is running on (e.g., [AWS Attestor](docs/attestors/aws-iid.md)). Finally, Witness can compile this information into an [in-toto attestation](https://github.com/in-toto/attestation), place it in a [DSSE Envelope](https://github.com/secure-systems-lab/dsse) and sign that envelope with the key that was supplied by the user. 
+
+### Storing
+For storage, the Witness project can upload signed attestations to an [Archivista](https://github.com/in-toto/archivista) server, a graph and storage service for in-toto attestations. This enables the discovery and retrieval of attestations for verification of software artifacts.
+
+### Verifying
+Witness allows users to verify the attestations that they generate by providing the `witness verify` command. To achieve this, Witness uses a [policy file](./docs/policy.md) defined by the user to check for presence of the expected attestations and that they were signed by the appropriate functionaries (Public keys or roots of trust that are trusted to sign certain types of attestation). To verify the attestation body itself, Witness supports defining [OPA Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) policies inside the policy file. This allows users to ensure the facts asserted by the Attestors are reported expected.
+
diff --git a/docs/assets/demo.gif b/docs/assets/demo.gif
diff --git a/docs/assets/logo.png b/docs/assets/logo.png
diff --git a/docs/attestor.md b/docs/attestor.md
diff --git a/docs/commands.md b/docs/commands.md
@@ -0,0 +1,175 @@
+# Witness CLI Reference
+
+This is the reference for the Witness command line tool, generated by [Cobra](https://cobra.dev/).
+
+## witness run
+
+Runs the provided command and records attestations about the execution
+
+```
+witness run [cmd] [flags]
+```
+
+### Options
+
+```
+      --archivista-server string                      URL of the Archivista server to store or retrieve attestations (default "https://archivista.testifysec.io")
+  -a, --attestations strings                          Attestations to record ('product' and 'material' are always recorded) (default [environment,git])
+      --attestor-product-exclude-glob string          Pattern to use when recording products. Files that match this pattern will be excluded as subjects on the attestation.
+      --attestor-product-include-glob string          Pattern to use when recording products. Files that match this pattern will be included as subjects on the attestation. (default "*")
+      --enable-archivista                             Use Archivista to store or retrieve attestations
+      --hashes strings                                Hashes selected for digest calculation. Defaults to SHA256 (default [sha256])
+  -h, --help                                          help for run
+  -o, --outfile string                                File to which to write signed data.  Defaults to stdout
+      --signer-file-cert-path string                  Path to the file containing the certificate for the private key
+      --signer-file-intermediate-paths strings        Paths to files containing intermediates required to establish trust of the signer's certificate to a root
+  -k, --signer-file-key-path string                   Path to the file containing the private key
+      --signer-fulcio-oidc-client-id string           OIDC client ID to use for authentication
+      --signer-fulcio-oidc-issuer string              OIDC issuer to use for authentication
+      --signer-fulcio-oidc-redirect-url string        OIDC redirect URL (Optional). The default oidc-redirect-url is 'http://localhost:0/auth/callback'.
+      --signer-fulcio-token string                    Raw token string to use for authentication to fulcio (cannot be used in conjunction with --fulcio-token-path)
+      --signer-fulcio-token-path string               Path to the file containing a raw token to use for authentication to fulcio (cannot be used in conjunction with --fulcio-token)
+      --signer-fulcio-url string                      Fulcio address to sign with
+      --signer-spiffe-socket-path string              Path to the SPIFFE Workload API Socket
+      --signer-vault-altnames strings                 Alt names to use for the generated certificate. All alt names must be allowed by the vault role policy
+      --signer-vault-commonname string                Common name to use for the generated certificate. Must be allowed by the vault role policy
+      --signer-vault-namespace string                 Vault namespace to use
+      --signer-vault-pki-secrets-engine-path string   Path to the Vault PKI Secrets Engine to use (default "pki")
+      --signer-vault-role string                      Name of the Vault role to generate the certificate for
+      --signer-vault-token string                     Token to use to connect to Vault
+      --signer-vault-ttl duration                     Time to live for the generated certificate. Defaults to the vault role policy's configured TTL if not provided
+      --signer-vault-url string                       Base url of the Vault instance to connect to
+  -s, --step string                                   Name of the step being run
+      --timestamp-servers strings                     Timestamp Authority Servers to use when signing envelope
+      --trace                                         Enable tracing for the command
+  -d, --workingdir string                             Directory from which commands will run
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string      Path to the witness config file (default ".witness.yaml")
+  -l, --log-level string   Level of logging to output (debug, info, warn, error) (default "info")
+```
+
+### SEE ALSO
+
+* [witness](witness.md)	 - Collect and verify attestations about your build environments
+
+## witness sign
+
+Signs a file
+
+### Synopsis
+
+Signs a file with the provided key source and outputs the signed file to the specified destination
+
+```
+witness sign [file] [flags]
+```
+
+### Options
+
+```
+  -t, --datatype string                               The URI reference to the type of data being signed. Defaults to the Witness policy type (default "https://witness.testifysec.com/policy/v0.1")
+  -h, --help                                          help for sign
+  -f, --infile string                                 Witness policy file to sign
+  -o, --outfile string                                File to write signed data. Defaults to stdout
+      --signer-file-cert-path string                  Path to the file containing the certificate for the private key
+      --signer-file-intermediate-paths strings        Paths to files containing intermediates required to establish trust of the signer's certificate to a root
+  -k, --signer-file-key-path string                   Path to the file containing the private key
+      --signer-fulcio-oidc-client-id string           OIDC client ID to use for authentication
+      --signer-fulcio-oidc-issuer string              OIDC issuer to use for authentication
+      --signer-fulcio-oidc-redirect-url string        OIDC redirect URL (Optional). The default oidc-redirect-url is 'http://localhost:0/auth/callback'.
+      --signer-fulcio-token string                    Raw token string to use for authentication to fulcio (cannot be used in conjunction with --fulcio-token-path)
+      --signer-fulcio-token-path string               Path to the file containing a raw token to use for authentication to fulcio (cannot be used in conjunction with --fulcio-token)
+      --signer-fulcio-url string                      Fulcio address to sign with
+      --signer-spiffe-socket-path string              Path to the SPIFFE Workload API Socket
+      --signer-vault-altnames strings                 Alt names to use for the generated certificate. All alt names must be allowed by the vault role policy
+      --signer-vault-commonname string                Common name to use for the generated certificate. Must be allowed by the vault role policy
+      --signer-vault-namespace string                 Vault namespace to use
+      --signer-vault-pki-secrets-engine-path string   Path to the Vault PKI Secrets Engine to use (default "pki")
+      --signer-vault-role string                      Name of the Vault role to generate the certificate for
+      --signer-vault-token string                     Token to use to connect to Vault
+      --signer-vault-ttl duration                     Time to live for the generated certificate. Defaults to the vault role policy's configured TTL if not provided
+      --signer-vault-url string                       Base url of the Vault instance to connect to
+      --timestamp-servers strings                     Timestamp Authority Servers to use when signing envelope
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string      Path to the witness config file (default ".witness.yaml")
+  -l, --log-level string   Level of logging to output (debug, info, warn, error) (default "info")
+```
+
+### SEE ALSO
+
+* [witness](witness.md)	 - Collect and verify attestations about your build environments
+
+## witness verify
+
+Verifies a witness policy
+
+### Synopsis
+
+Verifies a policy provided key source and exits with code 0 if verification succeeds
+
+```
+witness verify [flags]
+```
+
+### Options
+
+```
+      --archivista-server string   URL of the Archivista server to store or retrieve attestations (default "https://archivista.testifysec.io")
+  -f, --artifactfile string        Path to the artifact to verify
+  -a, --attestations strings       Attestation files to test against the policy
+      --enable-archivista          Use Archivista to store or retrieve attestations
+  -h, --help                       help for verify
+  -p, --policy string              Path to the policy to verify
+      --policy-ca strings          Paths to CA certificates to use for verifying the policy
+  -k, --publickey string           Path to the policy signer's public key
+  -s, --subjects strings           Additional subjects to lookup attestations
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string      Path to the witness config file (default ".witness.yaml")
+  -l, --log-level string   Level of logging to output (debug, info, warn, error) (default "info")
+```
+
+### SEE ALSO
+
+* [witness](witness.md)	 - Collect and verify attestations about your build environments
+
+## witness version
+
+Prints out the witness version
+
+### Synopsis
+
+Prints out the witness version
+
+```
+witness version [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for version
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string      Path to the witness config file (default ".witness.yaml")
+  -l, --log-level string   Level of logging to output (debug, info, warn, error) (default "info")
+```
+
+### SEE ALSO
+
+* [witness](witness.md)	 - Collect and verify attestations about your build environments
+
diff --git a/docs/concepts/attestor.md b/docs/concepts/attestor.md
@@ -0,0 +1,27 @@
+# Attestors
+
+A Witness attestor is a programming interface that defines an object that can assert facts about a system and store those facts in a versioned schema. An attestor has a `Name`, `Type` and `RunType`. The `Type` is a versioned string corresponding to the JSON schema of the attestation. For example, the AWS attestor is defined as follows:
+```
+  Name    = "aws"
+  Type    = "https://witness.dev/attestations/aws/v0.1"
+  RunType = attestation.PreRunType
+```
+Attestation types are leveraged to ensure the correct version schema is used when we evaluate policy against these attestations.
+
+## Attestor Security Model
+
+Attestations are only as secure as the data that feeds them. Where possible cryptographic material should be validated, evidence of validation should be included in the attestation for out-of-band validation.
+
+Examples of cryptographic validation is found in the [GCP](https://github.com/testifysec/witness/tree/main/pkg/attestation/gcp-iit), [AWS](https://github.com/testifysec/witness/blob/main/pkg/attestation/aws-iid/aws-iid.go), and [GitLab](https://github.com/testifysec/witness/tree/main/pkg/attestation/gitlab) attestors.
+
+## Attestor Life Cycle
+
+- **Pre-material:** Pre-material attestors run before any other attestors. These attestors generally collect information about the environment.
+
+- **Material:** Material attestors run after any prematerial attestors and prior to any execute attestors. Generally these collect information about state that may change after any execute attestors, such as file hashes.
+
+- **Execute:**: Execute attestors run after any material attestors and generally record information about some command or process that is to be executed.
+
+- **Product:** Product attestors run after any execute attestors and generally record information about what changed during the execute lifecycle step, such as changed or created files.
+
+- **Post-product:** Post-product attestors run after product attestors and generally record some additional information about specific products, such as OCI image information from a saved image tarball.