Insufficient Rekor Log Entry Data Documentation for Non-Expert Users

[jspeed-meyers]

Description

While trying to build a dashboard that displays statistics about the public Rekor transparency log data (similar to @SantiagoTorres's 1,000,000 entries blog post) I experienced some friction in trying to understand each type of log entry, the associated data fields, and the necessary transformations for parsing the values contained in the data field. I think my difficulty stems from my newness to the sigstore project and a lack of documentation aimed at non-expert users. To be clear, the schema definitions are helpful, but they do not resolve all my difficulties.

Here's an example of an abridged in-toto entry and my related friction points.

{
  "Attestation": "eyJ…9fX0=",
  "AttestationType": "",
  "Body": {
    "IntotoObj": {
      "content": {
        "hash": {
          "algorithm": "sha256",
          "value": "2e1ec1db6adf042073bce010721a02624eab7a870c8236ec9704f4495cdc4fa4"
        }
      },
      "publicKey": "LS0…Cg=="
    }
  },
  "LogIndex": 533407,
  "IntegratedTime": 1629355901,
  "UUID": "e5d5d1835e5ccbb9dac77fc7565ed5e5e5880facd6d025058c6710da9df419cd",
  "LogID": "c0d23d6ad406973f9559f3ba2d1ca01f84147d8ffc5b8445c224f98b9591801d"
}

Friction point 1: What is an Attestation and what is an AttestationType? I'm familiar with the notion of an attestation from the in-toto project but I'm not sure what values to expect in either field and what they mean. When I search the documentation (either in the pluggable types GH section on in toto or the Rekor official documentation on pluggable types) I don't find an explanation.

Friction point 2: How do I decode the value in the Attestation field? Is there documentation on how to decode this value? I couldn't find it again.

These types of friction points recurred for at least several of the other types.

I should mention that I think that this friction point is at least indirectly related to the issue that @vaikas experienced in issue #646. After a discussion with Ville, it seems that he was unable to determine via the documentation the procedure used for indexing an in toto attestation.

Proposal

I was first curious to get feedback from the sigstore community about if (A) this is a problem others have experienced [it seemed at least a little similar to friction log created by @haydentherapper] and (B) whether this friction is worth reducing. I realize there are many priorities for the sigstore community.

I would be glad to add documentation related to solving the documentation friction points I described above. I would start with one PR related to only the in-toto type and, if that was seen as useful, proceed to the other types one by one.

@lukehinds, @bobcallaway, @dlorenc, @n3wscott, @nsmith5

[dlorenc]

I was first curious to get feedback from the sigstore community about if (A) this is a problem others have experienced [it seemed at least a little similar to friction log created by @haydentherapper] and (B) whether this friction is worth reducing. I realize there are many priorities for the sigstore community.

I would be glad to add documentation related to solving the documentation friction points I described above. I would start with one PR related to only the in-toto type and, if that was seen as useful, proceed to the other types one by one.

We should definitely document this and provide some samples!

[vaikas]

Sorry for the tardy reply here :( I was trying to find a way to provide more context in a sensible way, but this is the best I can do after noodling. I think there are few layers here, and I didn't want to confuse the issue anymore, but here goes :)

I think there are few different documentation points, for example, the end user who is trying to figure out how to inspect Rekor entries as well as search for Rekor entries. Once you find an entry, what the schema is, and so forth. One small example that confused me, is that getting an entry from Rekor has a URL to a Type:

{"_type":"https://in-toto.io/Statement/v0.1",... <snip>

But this link doesn't work, it's also all over the place in in-toto github, for example here: https://github.com/in-toto/attestation/blob/main/spec/predicates/link.md so maybe it's not expected to work. But it created confusion for me, and not necessarily related to Rekor whatsoever.

In addition to documenting for each of the Types what is the definition, I think for each type we should also document how can you search for it. This was the trouble that I was facing as I was trying to write some tests to ensure the indexing was working properly. I started with a very easy example that I was hoping then to generalize into all the existing types, but I put that aside cause I couldn't figure things out and other things became a higher priority. It is toes un-reusable as is (only supports the hashedrekord), but hopefully reflects the point of what I was trying to achieve:
https://github.com/vaikas/sigstore-scaffolding/blob/main/cmd/rekor/checktree/main.go#L101

The tests mentioned above could/should probably use the rekor-cli tool instead of the above hacky bits (I was trying to learn).

To @dlorenc point about examples, I was personally hoping we could get to a place where for each existing type (and for any new type introduced), there would be a canonical example and we would run E2E tests by adding it to Rekor and then running searches for them to ensure that things are being properly indexed. This is not only for the end user (though, having canonical even types would be helpful), but also for folks introducing new types by having a nice test framework.

In particular with the recent amazing work done to introduce sharding, I think those kinds of tests would give us higher confidence in being able to create new Trillian trees and ensure that all the things that end up in the index end up the right way. If you read this far, you get a gold star.

[nsmith5]

In regards to

A) is this a problems other have experienced?

Yeah absolutely. I ended up ignoring the attestation fields in rekor-sidekick for the time being and found it a little difficult to get information on the Body structure as well. In the end I passed the burden on to the end user and they need to go learn about the structure (perhaps by trail and error like me) and write policy accordingly.

[jspeed-meyers]

Thank @nsmith5, @vaikas, and @dlorenc! So on my TODO list for this week is:

• Create an initial documentation example of a type for the in-toto type.

I'll workshop this around this week and if I get positive feedback, I'll put in a PR and open it up. @ville, I'll do my best to include documentation for the in-toto type that addresses the "how can you search for it" point you raised.

[jspeed-meyers]

Next up:

• Submit PR with documentation related to Alpine type. Will come next week.

[jspeed-meyers]

Next up:

• Submit PR with with documentation related to Rekord type.

[hanyuwang1993]

New to in-toto and Rekor. I am struggling to upload the link file generated by running in-toto-run cli to Rekor. Can you also add documentation on this? Thanks a lot!

[jspeed-meyers]

@hanyuwang1993, probably! I haven't done this myself, but I can and will look into it. If you could provide additional technical details (what commands you ran, with what order, with what results) that would help me create this documentation. Tagging @ltagliaferri because of her interest in the sigstore docs. Also tagging @SantiagoTorres because of his expertise in in-toto.

[SantiagoTorres]

@hanyuwang1993 haven't tried this in a bit myself, so happy to help troubleshoot and fix anything if needed!

[hanyuwang1993]

@jspeed-meyers @SantiagoTorres thank you guys so much for you swift response. Let me summarise the issue i have faced.

I am currently exploring in-toto + Rekor stack. Basically i am trying to generate signed metadata for each supply chain step ( e.g. git checkout code, run unit test) using in-toto cli (https://in-toto.readthedocs.io/en/latest/command-line-tools/in-toto-run.html)

in-toto-run <named arguments> [optional arguments] \
	 -- <command> [args]

The output of previous step is link file, you can find the specs here https://github.com/in-toto/docs/blob/master/in-toto-spec.md#44-file-formats-namekeyid-prefixlink

After generating .link file, I want to leverage on Rekor transparency log to store this signed metadata. i saw In-Toto Attestations is listed as supported types here , so i i tried with the command

 rekor-cli upload --rekor_server https://rekor.sigstore.dev --artifact git-metadata.a0a78898.link  --type intoto -public-key mykey.pub

but it gave this error

[POST /api/v1/log/entries][400] createLogEntryBadRequest  &{Code:400 Message:Error processing entry: Accepted signatures do not match threshold, Found: 0, Expected 1}

I am very new to Rekor and in-toto, want to ask two questions:

1. Does link file generated by in-toto cli follow in-toto attestation schema which is supported by Rekor?
2. If not, how should i convert the link meta to schema that can be consumed by Rekor? or do i need to add a new type by myself following the steps on https://docs.sigstore.dev/rekor/pluggable-types ?

Hope i have made problem clear. Let me know if you need any more clarifications! Thank you :)

[jspeed-meyers]

@hanyuwang1993, this is helpful context. Personally I'll need to do some investigation; I haven't used the in-toto-run before, including in conjunction with Rekor.

My initial hypothesis is related to the end of the error: Accepted signatures do not match threshold, Found: 0, Expected 1 - It seems like Rekor was looking for a signature and didn't find one. @SantiagoTorres, at first impression, what do you think?

Pinging @znewman01 in case this rings a bell with him.

[znewman01]

@hanyuwang1993 thanks for reporting! This looks like a separate issue so let's debug in #706.

[SantiagoTorres]

@jspeed-meyers I'm realizing it's probably trying to validate a DSSE envelope for the old style metablock sig. I think we can definitely fix this on the in-toto side ...

Thanks for reporting, @hanyuwang1993!

[jspeed-meyers]

Closing this issue because I think Lisa Tagliaferri will do better work on Sigstore docs than I can, and she has begun to devote attention to this.