Tooling for refreshing timestamp and snapshot metadata

[doanac]

I've really enjoyed experimenting with this tooling. One point of friction I'm hitting is with keeping my timestamp and snapshot metadata up-to-date. It's possible now with a certain amount of scripting and JSON parsing. However, I think it would help people trying to automate the handling of these 2 files if there was a helper to manage it.

I'd be happy to help, but wanted to gauge your interest in something like this first. My super simple hack right now was simply adding something like this to repo.go:

func (r *Repo) RefreshExpires(snapshotExpires, timestampExpires time.Time) error {
	ss, err := r.snapshot()
	if err != nil {
		return err
	}
	ts, err := r.timestamp()
	if err != nil {
		return err
	}
	changed := false
	if ss.Expires.Before(snapshotExpires) {
		if err = r.Snapshot(); err != nil {
			return err
		}
		changed = true
	}
	if changed || ts.Expires.Before(timestampExpires) {
		if err = r.Timestamp(); err != nil {
			return err
		}
		changed = true
	}
	if changed {
		err = r.Commit()
	}
	return err
}

and then I added a simple CLI sub-command to call that with a "expires within the hour" default threshold.

Is this of interested, or maybe y'all have a different idea in mind?

[trishankatdatadog]

Great idea! @asraa and @haydentherapper may be interested...

[asraa]

This should already be possible though? Could you explain why this works over manually running the command for snapshot and timestamp? Is it because you only want to re-sign if it changed?

tuf snapshot --expires DAY
tuf timestamp --expires DAY
tuf commit
``

[doanac]

Is it because you only want to re-sign if it changed?

Correct. I was experimenting with an idea where I could host TUF metadata inside a Github repository. Then have a github action that keeps the timestamp and snapshot metadata up-to-date. Having a simple wrapper command like the one I've described here, make automation much easier to achieve.

[asraa]

I was experimenting with an idea where I could host TUF metadata inside a Github repository.

Nice! Yeah! I have a snapshot and timestamp action here, https://github.com/sigstore/root-signing/blob/main/.github/workflows/snapshot-timestamp.yml

link me to your repo, I'd love to see it!

Maybe you could commit your expirations to a file, and when that file changes, it can trigger the workflow. I plan to do exactly this with creating a TUF repo metadata config here sigstore/root-signing#98

[znewman01]

I agree with @asraa that I'd prefer to keep the CLI to fewer, more composable commands. I'm not opposed to convenience wrappers for common workflows, but I'd like to first think about what general functionality the CLI could provide that would make this easy.

Would the following be "easy enough to script" that you wouldn't want this convenience wrapper?

• Add a tuf status command that has support for "is valid at the given time"

So then we have:

$ tuf status snapshot --valid-on=$(date -d '+1 hour') || (tuf snapshot && tuf  timestamp)
$ tuf status timestamp --valid-on=$(date -d '+1 hour') || tuf timestamp
$ tuf commit  # this should only commit if something changed

We could bikeshed things like --valid-on=+1h, the format that --valid-on takes, etc.

I could be convinced that this is a common enough pattern that tuf refresh would be worthwhile, but even then I would prefer to provide an expressive enough CLI that slight variations on this workflow are easy to express in bash. (Almost like the git "plumbing and porcelain" philosophy).

[doanac]

i like the status idea better because the "refresh" approach still kind of hides what may or may-not happen (i.e. did it "commit" or not).

[asraa]

I love the status idea! We have a root status command implemented in sigstore/sigstore. I would love to use a status implemented here.

[doanac]

I've been playing with this idea some and am starting to like it. Here's the rough idea I've come up with:
doanac@864086d

I can do a PR if that seems sensible.

[znewman01]

Thanks for pulling that together! It looks good to me for the most part.

There's a few minor things I'd like addressed before merging:

1. More docs, especially w/r/t "exit status will be 1 if expired, 0 otherwise". Folding the example from the commit message into the command docs would be nice as well.

2. --expires flag name is a little confusing to me—when I see tuf status --expires 2022-07-12T00:00:00 snapshot, it's not obvious from that invocation what the command asking. I want to be mindful and avoid bikeshedding too much though, so I could be persuaded here. Other options might include:

   • tuf status --valid-at=<date> (what I suggested above). I'm not attached to this, but I think it does a better job of
   • tuf status --is-unexpired-at=<date>
   • tuf is-valid --date=<date> snapshot
   • tuf query --valid-at=<date>: this could perhaps be expanded in the future, which might be nice—it could get rid of most of the need for jq in simple situations.

   If any of those seem clearer to you (both @doanac and @asraa), we can roll with that; other variants accepted as well. Otherwise let's just go with what you have.

3. (nitpick) I see you're manually checking that --expires is set. I think go-docopt has support for required flags so that might be unnecessary? If you can't make this work after a couple minutes, don't bother.

4. You're checking "metadata.expires < expiresOn"; should it be "<="? That's more consistent with my reading of the TUF spec.

5. (nitpick) Maybe rename RoleStatus to something like CheckRoleUnexpired?

[doanac]

I think these are good suggestions. I like tuf status --valid-at=<date>. I'll clean things up more and produce PR.