use_cases.md 5.14 KB
Newer Older
Tom Hennen's avatar
Tom Hennen committed
1
2
# Use Cases

Tom Hennen's avatar
Tom Hennen committed
3
4
These are some of the use cases for SLSA.  Of these the first use case (a developer checking
their own packages prior to publishing) is the most ready for adoption as it does not require
5
6
interactions with any other party.

Tom Hennen's avatar
Tom Hennen committed
7
## Developer publishing a software package
Tom Hennen's avatar
Tom Hennen committed
8

Tom Hennen's avatar
Tom Hennen committed
9
A developer, BarInc, has the following goals in applying SLSA:
Tom Hennen's avatar
Tom Hennen committed
10

Tom Hennen's avatar
Tom Hennen committed
11
12
1.  Protect their users from malicious changes to the BarImage container image.
2.  Protect their reputation, which would be harmed, if BarImage were compromised.
Tom Hennen's avatar
Tom Hennen committed
13
3.  Access to metadata for auditing and ad-hoc analysis.
Tom Hennen's avatar
Tom Hennen committed
14

15
BarInc can acheive these goals when publishing the container image by:
Tom Hennen's avatar
Tom Hennen committed
16

Tom Hennen's avatar
Tom Hennen committed
17
18
1.  Upgrading their source control systems to meet higher SLSA levels.
2.  Upgrading their build system to meet higher SLSA levels.
Tom Hennen's avatar
Tom Hennen committed
19
3.  Ensuring BarImage **MUST** go through a secure control-point in order to be published.
Tom Hennen's avatar
Tom Hennen committed
20
4.  Having the control-point check the candidate BarImage against its provenance, checking:
Tom Hennen's avatar
Tom Hennen committed
21
    1.  That the expected builder created it.
Tom Hennen's avatar
Tom Hennen committed
22
23
24
25
    2.  That the builder meets some minimum SLSA level.
    3.  That the source repos listed in the provenance meet some minimum SLSA level.
    4.  That the build entry point listed in the provenance is what they expect.
    5.  (TBD) That the binary dependencies listed in the provenance meet some minimum SLSA level.
26
5.  Only publishing the container image if all the checks in #4 pass.
Tom Hennen's avatar
Tom Hennen committed
27
6.  Storing the provenance and all other attestations for future reference.
Tom Hennen's avatar
Tom Hennen committed
28

29
30
31
32
33
34
35
This approach allows BarInc to acheive their goals without requiring any changes from their users
or from their distribution channels.  It doesn't, however, protect their users from a published
BarImage from being tampered with after publication (though there may be other ways to address
those concerns, such as code-signing after verification, and time-of-use verification).

## Developer using third party software packages

Tom Hennen's avatar
Tom Hennen committed
36
37
38
39
A developer using BarImage wants to ensure it hasn't been tampered with before using it.

They could do this by:

Tom Hennen's avatar
Tom Hennen committed
40
41
42
43
1.  Requesting BarInc to publish the [in-toto Provenance] and any additional attestations (such
    as [source control attestations]) for BarImage each time it is released.
2.  Requesting BarInc to publish the public keys its builder uses to sign the attestations.
    -   (TBD) [Determine how to convey these keys].
Tom Hennen's avatar
Tom Hennen committed
44
45
3.  Requesting BarInc to confirm what SLSA level their builder and source control system meet.
    -   In the future there may be an accredidation body that confirm this _for_ BarInc.
Tom Hennen's avatar
Tom Hennen committed
46
4.  Determining what policy to apply to BarImages.
Tom Hennen's avatar
Tom Hennen committed
47
48
49
    -   They could create this policy on first use based on the data provided in the in-toto Provenance.
        Any significant deviations (e.g. builder changed, source repo changed) would cause failure. OR
    -   BarInc could _publish_ a suggested policy for users of BarImage on their website.
Tom Hennen's avatar
Tom Hennen committed
50
51
52
5.  Establishing a secure control-point that any uses of BarImage must pass through in order to be used.
    -   E.g. On import to a local Docker registry.
6.  Having the control-point check the candidate BarImage against its provenance, checking it against the
Tom Hennen's avatar
Tom Hennen committed
53
    policy from #4.
Tom Hennen's avatar
Tom Hennen committed
54
7.  Only importing the container image if all the checks in #6 pass.
Tom Hennen's avatar
Tom Hennen committed
55

56
57
58
This approach protects the developer without having to rely on any trust in intermediate package
repositories.

Tom Hennen's avatar
Tom Hennen committed
59
60
## Package Repository accepting a software package

61
62
63
64
65
A Package Repository (e.g. Docker Hub) wants to protect their users from malicious changes to the
container images uploaded to the repo.

They could do this by:

Tom Hennen's avatar
Tom Hennen committed
66
67
68
1.  Requesting publishers of containers to publish the [in-toto Provenance] and any additional
    attestations (such as [source control attestations]) each time a new image is pushed to the
    repository.
69
70
    -   (TBD) Where to store this provenance?
2.  Requesting publishers to publish the public keys it's builder uses to sign the attestations.
Tom Hennen's avatar
Tom Hennen committed
71
    -   (TBD) [Determine how to convey these keys]
72
73
3.  Requesting publishers to confirm what SLSA level their builder and source control system meet.
    -   In the future there may be an accredidation body that confirm this _for_ the publishers.
Tom Hennen's avatar
Tom Hennen committed
74
4.  Determining what policy to apply to published images.
75
76
77
78
79
80
81
    -   They could create this policy on first use based on the data provided in the in-toto Provenance.
        Any significant deviations (e.g. builder changed, source repo changed) would cause a push
        failure. OR
    -   The Package Repository could have publishers configure their specific policy as a part of their
        repo.
        -   The Package Repository could make these policies publicly readable by users of the repo.
        -   (TBD) How to securely update these policies.
Tom Hennen's avatar
Tom Hennen committed
82
83
5.  Checking new containers against the policy from #4.
6.  Preventing container images that fail the check in #5 from being made public.
84
85
86

This approach could protect users of protected repos from malicious tampering without requring all
users to do their own policy checks of each image they consume.
Tom Hennen's avatar
Tom Hennen committed
87
88
89
90

[Determine how to convey these keys]: https://github.com/slsa-framework/slsa/issues/101
[in-toto Provenance]: https://github.com/in-toto/attestation/blob/main/spec/predicates/provenance.md
[source control attestations]: https://github.com/in-toto/attestation/issues/47