witness
witness copied to clipboard
in-toto
Attestors need far better documentation for a new user
I'm a very new user trying to get to grips with Witness.
The main readme.md says :
> - The `-a {attestor}` flag allows you to define which attestors run
> - ex. `-a maven -a was -a gitlab` would be used for a maven build running on a GitLab runner on GCP.
This is confusing. I can see how maven maps to maven But how does "was" or "gitlab" map to GCP or GitLab ?
Assuming this is just a typo and it should be "-a aws" and "runner on AWS", I continue.
## What is a witness attestor?
...
Each 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
OK, so lets find that definition in this repository's code. Searching for the URL (without the v0.1 in case the README is out of date) from the Type in the example reveals only the mention in the README.
Where do those definitions go? They aren't YAML or JSON like all the config files mentioned...
So, do I need to define my own attestors? Apparently not because I can run witness with -a aws and it attempts to gather AWS info. If those Name/Type/RunType values are not in your code and I don't need to set them, why are they in the documentation?? How do I as a user benefit from that section?
But I'd like to understand what the attestor is doing because something is not working. I'd like to look at the code for it. So I go to the witness.dev URL in the Type field. And get a 401 error.
So IF I do need to define my own attestors, what URL should I use for the "Type" value? If that page is just giving a 401, is the Type a URL? If it isn't why does it look like one?
There is a link a bit further down in the "Security Model" section to examples of the attestors. Maybe that has the source of the attestor I am looking for...
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.
And EACH of those links takes me to a 404 error.
A bit further down, there is a list of "Pre Run Attestors" with links that work. That take me to the documentation for the attestor. Which has no source code or real explanation of how it works or what it actually does.
eg GitLab (or gitlab?) docs say that it verifies the CI_JOB_JWT against the instances JWKS without explaining how it tries to access the /.well-known/jwks.json to get the JWKS. Does it use the CI_JOB_TOKEN or some other auth?
Finally when I use the gitlab attestor, I get an error :
level=error msg="failed to run attestors: square/go-jose: unsupported key type/format"
Which key? Which type/format?
Hi, @max-allan-surevine
We definitely appreciate the feedback and agree that the documentation needs a bunch of love and is not currently in an acceptable state for new users. It is something we are looking to improve in the short term and I'm sorry you've had a frustrating experience.
This is confusing. I can see how maven maps to maven But how does "was" or "gitlab" map to GCP or GitLab ?
The sentence you're talking about here is indeed confusing and I'm also unsure of it's meaning. It seems as though there was an editing/typo mistake here that didn't get caught in review.
If those Name/Type/RunType values are not in your code and I don't need to set them, why are they in the documentation?? How do I as a user benefit from that section?
I can see your point here. The Name/Type/RunType are values in the code but they are more oriented toward the developer of an attestation, not a user of Witness. I think a core issue here is our ReadMe is blending documentation oriented toward developers and users and doesn't provide a cohesive experience for either role.
But I'd like to understand what the attestor is doing because something is not working. I'd like to look at the code for it. So I go to the witness.dev URL in the Type field. And get a 401 error.
The plan is to have attestor specific documentation and schema information live at these URLs but unfortunately that does not currently exist. Currently the URL is being used more as an identifier during the creation and parsing of an attestation collection, but again this goes back to the issue of incomplete and incohesive documentation.
I think this has been exacerbated by a recent migration of our library code to a separate repo at https://github.com/testifysec/go-witness
Again, sorry for the poor experience. Improving the docs and experience as a whole is a priority for us so we very much appreciate the feedback
Aha, now I found the attestor code I was looking for in the split repo! If I ever figure it out and have the time I might make a PR with some changes in. Thanks!
@mikhailswift , would you like issues with the attestors raised on the new repo or this one?
After reviewing the code I think that it uses a static location for the JWKS. https://github.com/testifysec/go-witness/blob/main/attestation/gitlab/gitlab.go#L31
We're using self hosted GitLab, so that won't work. There is a CI_SERVER_URL which you can use to build the JWKS location. (And presumably want to record that value so that I can't override the server URL in my build job and validate the JWKS against my own instance.)
For attestor issues go-witness is the best place :). We will definitely want to modify that to use CI_SERVER_URL instead.
The gitlab jwks url issue has been patched with https://github.com/testifysec/go-witness/pull/3
witness v0.1.10 with this included will be available shortly
I've had a similar experience to @max-allan-surevine when getting started with Witness. I was also wondering where the attestor code was.
Perhaps a note up top of the README would help?
NOTE: the attestor code has been split into repo https://github.com/testifysec/go-witness
Something like that would prevent a lot of head scratching for new users and devs alike
We have a PR to update the readme with the note about the go-witness library. I am going to close this issue due to the lack of specific tasks remaining. Please feel free to open another issue if there is some documentation you would like us to improve
