Consider adding support for 'tag' controls

[TomHennen]

As a proof of concept that we can check that the repo restricts the update/removal of tags.

Bonus, update provenance & vsas when tags (and branches?) are created.

[TomHennen]

If it works well enough we could/should including this requirement within SLSA Source Track generally.

[TomHennen]

It looks like this collection of controls for a tag ruleset does the trick:

  "rules": [
    {
      "type": "deletion"
    },
    {
      "type": "non_fast_forward"
    },
    {
      "type": "update"
    }
  ],

[TomHennen]

While the tool does check to see if tag immutability is enabled there's more to do.

I think we need:

1. To issue some sort of 'provenance' when tags are created. As with (the perhaps too generically named) source provenance we should record the actor, tag ref, repo, and time. We should probably also record tag controls (the controls in 'source provenance' cover branch stuff which doesn't make sense for tags). Right now that would basically just be if immutability is enabled or not.
2. We should create a Source VSA for the commit and include the tag ref in it. Perhaps in a source_tags field next to source_branches?
3. We'll need to fill out verifiedLevels in the VSA. I think we should do that by finding existing VSAs for the commit in question, picking one of them (how?), and copying the values from its verifiedLevels field into the new VSA.
4. We should only include or exclude the IMMUTABLE_TAGS value if the repo currently has that control enabled and it meets existing policy w.r.t. to time.

Questions:

1. Should the VSA we produce include the refs from prior VSAs? It might be nice to have a single VSA that includes all the refs. It's also harder. Especially if we're dealing with multiple. We'd open up questions like what to do with the old VSAs (we still want them! their other metadata might be interesting).
2. How should we deal with multiple VSAs when deciding on the verifiedLevels for a new one?

[TomHennen]

We should only include or exclude the IMMUTABLE_TAGS value if the repo currently has that control enabled and it meets existing policy w.r.t. to time.

In this comment @arewm suggests we not issue a VSA at all if we think tags might have been rewritten.

I'd suggest a perhaps subtler approach.

In this current implementation IMMUTABLE_TAGS is distinct from the SLSA level. I'd suggest something like:

1. If they have the GitHub control enabled, but don't have immutable_tags set in their policy, don't include IMMUTABLE_TAGS in the VSA.
2. If they have the GitHub control enabled, they have immutable_tags set in their policy, and the GitHub control has been enabled at least as long as the time since the policy went into force, include IMMUTABLE_TAGS in the VSA.
3. If they don't have the GitHub control enabled, and they don't have immutable_tags set in their policy, don't include IMMUTABLE_TAGS in the VSA.
4. If they don't have the GitHub control enabled (or the time doesn't match) but they do have immutable_tags set in the policy, then don't emit a VSA and treat it like we would a branch policy failure.

[arewm]

Thanks for those scenarios. After thinking about it more, maybe we should always push VSAs for tags which is what I think you were getting at except for the last bullet?

Are these VSAs stored in Rekor? How do we handle the case:

• A VSA is generated with IMMUTABLE_TAGS
• The control is disabled allowing tags to be modified
• A previously immutable tag is deleted
• The control is re-enabled restricting tags
• The tag is pushed again

What happens if the tag is pushed again? Would we be able to query for multiple VSAs that exist for this tag (and therefore have proof of non-immutability)? Does the behavior change if the tag is moved instead of deleted after removing the restriction?

Would it be possible to produce a VSA on a tag-deletion event as well if we are depending on multiple VSAs being present to indicate an invalidation of the immutable tag policy?

[TomHennen]

Thanks for those scenarios. After thinking about it more, maybe we should always push VSAs for tags which is what I think you were getting at except for the last bullet?

Are these VSAs stored in Rekor?

I think they might wind up there based on using Sigstore to sign them, but I don't think its required.

Instead the PoC stores the attestations as git notes in the repo itself. That's where it expects to find things.

How do we handle the case:

• A VSA is generated with IMMUTABLE_TAGS
• The control is disabled allowing tags to be modified
• A previously immutable tag is deleted
• The control is re-enabled restricting tags
• The tag is pushed again

This is the point of the policy which stored and managed in an independent repo.

In the case you describe the policy evaluation would fail and no VSA would be issued since GitHub would report that the control has only been enabled since T+1 when the policy requires it to have been enabled no later than T.

E.g. this time is checked against the time GitHub says the control was enabled.

So for them to do what you describe and get a VSA they'd have to send a PR that updates their public policy, which amounts to saying that they've only just enabled SLSA. That gives people an opportunity to look a bit more closely at what they're doing. There might be some strengthening we could do here, but I think the big point is that they can't do as you describe in private and by themselves.

What happens if the tag is pushed again? Would we be able to query for multiple VSAs that exist for this tag (and therefore have proof of non-immutability)? Does the behavior change if the tag is moved instead of deleted after removing the restriction?

Would it be possible to produce a VSA on a tag-deletion event as well if we are depending on multiple VSAs being present to indicate an invalidation of the immutable tag policy?

We're basically trusting GitHub's control here. If they turn it off they're allowed to do stuff, but they won't get a VSA for it.

There's also discussion of changing the name to TAG_HYGIENE and not immutability to better reflect that there are cases that aren't covered.

[TomHennen]

Update:

#150 added a basic checktag command that enables tag controls, tag provenance, and VSAs for tags.

The provenance doesn't currently include the actor that pushed the tag because the GH activity API doesn't give it to us (that's how we get it for source provenance). However we might be able to get this data from the command line when the workflow runs from github.triggering_actor. Since the workflow runs under our control it should still all be 'fine' (but it will be easier to mess up).

[TomHennen]

I was able to get the actor added based on data we get in the workflow.

I think the only remaining work is to define how this control operates in the design (and requirements mapping).

[TomHennen]

#160 added information about how this works to the docs.
#169 made it a requirement at L2+ (to match the current spec).