docs: edit of all witness docs

bilzinho · colek42 · commit 97ca6e20966c · 2022-05-10T11:30:40.000-05:00
diff --git a/cmd/witness/options/key.go b/cmd/witness/options/key.go
@@ -29,7 +29,7 @@ type KeyOptions struct {
 func (ko *KeyOptions) AddFlags(cmd *cobra.Command) {
 	cmd.Flags().StringVarP(&ko.KeyPath, "key", "k", "", "Path to the signing key")
 	cmd.Flags().StringVar(&ko.CertPath, "certificate", "", "Path to the signing key's certificate")
-	cmd.Flags().StringSliceVarP(&ko.IntermediatePaths, "intermediates", "i", []string{}, "Intermediates that link trust back to a root in the policy")
+	cmd.Flags().StringSliceVarP(&ko.IntermediatePaths, "intermediates", "i", []string{}, "Intermediates that link trust back to a root of trust in the policy")
 	cmd.Flags().StringVar(&ko.SpiffePath, "spiffe-socket", "", "Path to the SPIFFE Workload API socket")
 	cmd.Flags().StringVar(&ko.FulcioURL, "fulcio", "", "Fulcio address to sign with")
 	cmd.Flags().StringVar(&ko.OIDCIssuer, "fulcio-oidc-issuer", "", "OIDC issuer to use for authentication")
diff --git a/cmd/witness/options/run.go b/cmd/witness/options/run.go
@@ -28,10 +28,10 @@ type RunOptions struct {
 
 func (ro *RunOptions) AddFlags(cmd *cobra.Command) {
 	ro.KeyOptions.AddFlags(cmd)
-	cmd.Flags().StringVarP(&ro.WorkingDir, "workingdir", "d", "", "Directory that commands will be run from")
+	cmd.Flags().StringVarP(&ro.WorkingDir, "workingdir", "d", "", "Directory from which commands will run")
 	cmd.Flags().StringSliceVarP(&ro.Attestations, "attestations", "a", []string{"environment", "git"}, "Attestations to record")
-	cmd.Flags().StringVarP(&ro.OutFilePath, "outfile", "o", "", "File to write signed data.  Defaults to stdout")
+	cmd.Flags().StringVarP(&ro.OutFilePath, "outfile", "o", "", "File to which to write signed data.  Defaults to stdout")
 	cmd.Flags().StringVarP(&ro.StepName, "step", "s", "", "Name of the step being run")
 	cmd.Flags().StringVarP(&ro.RekorServer, "rekor-server", "r", "", "Rekor server to store attestations")
-	cmd.Flags().BoolVar(&ro.Tracing, "trace", false, "enable tracing for the command")
+	cmd.Flags().BoolVar(&ro.Tracing, "trace", false, "Enable tracing for the command")
 }
diff --git a/cmd/witness/options/verify.go b/cmd/witness/options/verify.go
@@ -31,6 +31,6 @@ func (vo *VerifyOptions) AddFlags(cmd *cobra.Command) {
 	cmd.Flags().StringSliceVarP(&vo.AttestationFilePaths, "attestations", "a", []string{}, "Attestation files to test against the policy")
 	cmd.Flags().StringVarP(&vo.PolicyFilePath, "policy", "p", "", "Path to the policy to verify")
 	cmd.Flags().StringVarP(&vo.ArtifactFilePath, "artifactfile", "f", "", "Path to the artifact to verify")
-	cmd.Flags().StringVarP(&vo.RekorServer, "rekor-server", "r", "", "Rekor server to fetch attestations from")
+	cmd.Flags().StringVarP(&vo.RekorServer, "rekor-server", "r", "", "Rekor server from which to fetch attestations")
 	cmd.Flags().StringSliceVarP(&vo.CAPaths, "policy-ca", "", []string{}, "Paths to CA certificates to use for verifying the policy")
 }
diff --git a/docs/attestors/aws-iid.md b/docs/attestors/aws-iid.md
@@ -1,16 +1,16 @@
 # AWS Instance Identity Attestor
 
-The AWS Instance Identity Attestor communicates with the AWS Instance Metadata to collect
-information about the instance Witness is being executed on. The documents signature is
+The AWS (Amazon Web Services) Instance Identity Attestor communicates with the AWS Instance Metadata to collect
+information about the AWS instance Witness on which executing. The document signature is
 verified with the AWS RSA public certificate available [here](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/verify-signature.html).
-This currently does not work for the Hong Kong, Bahrain, Cape Town, Milan, China, or
+This verification method currently does not work for the Hong Kong, Bahrain, Cape Town, Milan, China, or
 GovCloud regions.
 
 ## Subjects
 
 | Subject | Description |
 | ------- | ----------- |
-| `instanceid` | The ID of the instance Witness was executed on |
+| `instanceid` | The ID of the AWS instance where Witness was executed |
 | `accountid` | ID of the account that owns the AWS instance |
-| `imageid` | ID of the AMI the instance was running at time of execution |
-| `privateip` | IP of the instance at time of execution |
+| `imageid` | ID of the AMI ([Amazon Machine Image](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html)) the instance was running at time of execution |
+| `privateip` | IP address of the instance at time of execution |
diff --git a/docs/attestors/commandrun.md b/docs/attestors/commandrun.md
@@ -1,7 +1,8 @@
 # Command Attestor
 
-The command attestor collects information about a command that witness executes and observes.
-The command's arguments, exit code, stdout, and stderr will be collected and added to the attestation.
+The Command Attestor collects information about a command that TestifySec Witness executes and observes.
+The command arguments, exit code, stdout, and stderr will be collected and added to the attestation.
+
 Witness can optionally trace the command which will record all subprocesses started by the parent process
-as well as all files opened by all processes. Please note that tracing is currently only supported on
-Linux operating systems and is considered experimental for now.
+as well as all files opened by all processes. Please note that tracing is currently supported only on
+Linux operating systems and is considered experimental.
diff --git a/docs/attestors/environment.md b/docs/attestors/environment.md
@@ -1,5 +1,5 @@
-# Environment
+# Environment Attestor
 
-The environment attestor records the OS, hostname, username, and all environment variables set
-of witness at execution time.  There is currently no way to block specific environment variables
-so please take care to not leak secrets stored in environment variables.
+The Environment Attestor records the OS, hostname, username, and all environment variables set
+by TestifySec Witness at execution time.  Currently there is no means to block specific environment variables
+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
@@ -1,15 +1,15 @@
 # GCP Instance Identity Attestor
 
-The GCP Instance Identity Attestor communicates with the GCP metadata server to collect information
-about the instance Witness is being exected on. The instance identity JWT's signature is validated
-against Google's JWKS to ensure authenticity.
+The [Google Cloud Platform](https://console.cloud.google.com/getting-started?supportedpurview=project) (GCP) Instance Identity Attestor communicates with the [GCP metadata server](https://cloud.google.com/appengine/docs/standard/java/accessing-instance-metadata) to collect information
+about the instance on which TestifySec Witness is being exected. The instance identity JSON Web Token signature is validated
+against Google's JWKS ([JSON Web Key Set](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets)) to ensure authenticity.
 
 ## Subjects
 
 | Subject | Description |
 | ------- | ----------- |
-| `instanceid` | ID of the Google Compute instance Witness was executed on |
-| `instancename` | Name of the Compute instance Witness was executed on |
-| `projectid` | The ID of the project that the instance belonged to |
-| `projectnumber` | Number of the project that the instance belonged to |
-| `clusteruid` | UID of the cluster if the execution enviornment was a GKE clister |
+| `instanceid` | ID of the Google Compute instance on which Witness was executed |
+| `instancename` | Name of the Compute instance on which Witness was executed |
+| `projectid` | The ID of the project to which the instance belonged |
+| `projectnumber` | Number of the project to which the instance belonged |
+| `clusteruid` | UID of the cluster if the execution environment was a [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine) (GKE) cluster |
diff --git a/docs/attestors/git.md b/docs/attestors/git.md
@@ -1,9 +1,9 @@
 # Git Attestor
 
-The Git attestor records the current state of the objects in the git repository, including untracked objects.
+The Git Attestor records the current state of the objects in the git repository, including untracked objects.
 Both staged and unstaged states are recorded.
 
 
 ## Subjects
 
-The attestor returns the SHA1 git commit hash as a subject.
+The attestor returns the SHA1 ([Secure Hash Algorithm 1](https://en.wikipedia.org/wiki/SHA-1)) git commit hash as a subject.
diff --git a/docs/attestors/gitlab.md b/docs/attestors/gitlab.md
@@ -1,13 +1,13 @@
-# Gitlab Attestor
+# GitLab Attestor
 
-The Gitlab attestor records information about the Gitlab CI/CD job execution that
-Witness was run in. Witness verifies the JWT provided in `CI_JOB_JWT` against the
-instance's JWKS to ensure authenticity at execution time.
+The [GitLab](https://about.gitlab.com/) Attestor records information about the GitLab CI/CD job execution in which
+TestifySec Witness was run. Witness verifies the JWT ([JSON Web Token](https://en.wikipedia.org/wiki/JSON_Web_Token)) provided in `CI_JOB_JWT` against the
+instance's JWKS ([JSON Web Key Set](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets)) to ensure authenticity at execution time.
 
 ## Subjects
 
 | Subject | Description |
 | ------- | ----------- |
-| `pipelineurl` | Url of the CI/CD pipeline that this job belonged to |
-| `joburl` | Url of the CI/CD job that this attestor describes |
-| `projecturl` | Url of the project that owns the CI/CD pipeline and job |
+| `pipelineurl` | URL of the CI/CD pipeline to which this job belonged  |
+| `joburl` | URL of the CI/CD job that this attestor describes |
+| `projecturl` | URL of the project that owns the CI/CD pipeline and job |
diff --git a/docs/attestors/jwt.md b/docs/attestors/jwt.md
@@ -1,4 +1,4 @@
 # JWT Attestor
 
-The JWT attestor verifies a JWT against a JWKS and records information about the
+The JWT ([JSON Web Token](https://en.wikipedia.org/wiki/JSON_Web_Token)) Attestor verifies a JWT against a JWKS ([JSON Web Key Set](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets)) and records information about the
 claims of the JWT.  The JWK that was used to verify the JWT is also recorded.
diff --git a/docs/attestors/material.md b/docs/attestors/material.md
@@ -1,5 +1,5 @@
 # Material Attestor
 
-The material attestor records the digests of all files in the working directory of Witness
-at exection time, but before any command is run.  This gives information about the state
+The Material Attestor records the digests of all files in the working directory of TestifySec Witness
+at exection time, but before any command is run.  This recording provides information about the state
 of all files before any changes are made by a command.
diff --git a/docs/attestors/maven.md b/docs/attestors/maven.md
@@ -1,10 +1,10 @@
 # Maven Attestor
 
-The Maven attestor records project and dependency information from a provided pom.xml.
+The [Maven](https://maven.apache.org/) Attestor records project and dependency information from a provided pom.xml ([Maven Project Object Model](https://maven.apache.org/guides/introduction/introduction-to-the-pom.html)).
 
 ## Subjects
 
 | Subject | Description |
 | ------- | ----------- |
-| `project:group/artifact@version` | The group, artifact, and version of the project that the pom.xml belongs to |
+| `project:group/artifact@version` | The group, artifact, and version of the project to which the pom.xml belongs |
 | `dependency:group/artifact@version` | The group, artifact, and verion of each dependency in the pom.xml |
diff --git a/docs/attestors/oci.md b/docs/attestors/oci.md
@@ -1,7 +1,7 @@
 # OCI Attestor
 
-The OCI attestor records information about a provided OCI image stored on disk as a tarball.
-Information about the image's tags, layers, and manifest are collected and reported in this
+The OCI Attestor records information about a provided [Open Container Initiative](https://opencontainers.org/) (OCI) image stored on disk as a tarball.
+Information about the image tags, layers, and manifest are collected and reported in this
 attestation.
 
 ## Subjects
diff --git a/docs/attestors/product.md b/docs/attestors/product.md
@@ -1,7 +1,7 @@
 # Product Attestor
 
-The product attestor looks at any materials recorded before a command was run and records all
-products of the command. Digests and mime tyeps of any changed or created files are recorded as products.
+The Product Attestor examines materials recorded before a command was run and records all
+products in the command. Digests and MIME types of any changed or created files are recorded as products.
 
 ## Subjects
 
diff --git a/docs/config.md b/docs/config.md
@@ -1,6 +1,6 @@
 ## Witness Configuration
 
-Witness looks for the configuration file `.witness.yaml` in the current directory.
+TestifySec Witness looks for the configuration file `.witness.yaml` in the current directory.
 
 Any values in the configuration file will be overridden by the command line arguments.
 
@@ -29,4 +29,4 @@ verify:
     attestations: stringSlice
     publickey: string
     policy: string
-```
+```
diff --git a/docs/policy.md b/docs/policy.md
diff --git a/docs/witness_run.md b/docs/witness_run.md
diff --git a/docs/witness_sign.md b/docs/witness_sign.md
diff --git a/docs/witness_verify.md b/docs/witness_verify.md

Original file line number	Diff line number	Diff line change
`@@ -31,6 +31,6 @@ func (vo VerifyOptions) AddFlags(cmd cobra.Command) {`
`31`	`31`	`cmd.Flags().StringSliceVarP(&vo.AttestationFilePaths, "attestations", "a", []string{}, "Attestation files to test against the policy")`
`32`	`32`	`cmd.Flags().StringVarP(&vo.PolicyFilePath, "policy", "p", "", "Path to the policy to verify")`
`33`	`33`	`cmd.Flags().StringVarP(&vo.ArtifactFilePath, "artifactfile", "f", "", "Path to the artifact to verify")`
`34`		`- cmd.Flags().StringVarP(&vo.RekorServer, "rekor-server", "r", "", "Rekor server to fetch attestations from")`
	`34`	`+ cmd.Flags().StringVarP(&vo.RekorServer, "rekor-server", "r", "", "Rekor server from which to fetch attestations")`
`35`	`35`	`cmd.Flags().StringSliceVarP(&vo.CAPaths, "policy-ca", "", []string{}, "Paths to CA certificates to use for verifying the policy")`
`36`	`36`	`}`