Skip to content

Commit 6d3f909

Browse files
puercopuerco
authored
Merge pull request #4 from openvex/attest
Add attestation spec
2 parents 8cb9154 + e58212a commit 6d3f909

File tree

1 file changed

+221
-0
lines changed

1 file changed

+221
-0
lines changed

‎ATTESTING.md

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
# Attesting OpenVEX Documents
2+
3+
## What is an Attestation?
4+
5+
An attestation is an assertion made about a piece of software. There are many
6+
kinds of attestations in use today such as provenance attestation defined by
7+
SLSA or those asserting to the results of vulnerability scans.
8+
9+
OpenVEX was conceived to be able to be embedded in
10+
[in-toto attestations](https://github.com/in-toto/attestation). The format defined
11+
by the in-toto project is composed of a number of subjects (the pieces of
12+
software the attestation is talking about) and a predicate that defines what is
13+
being said about the subjects.
14+
15+
[DIAGRAM]
16+
17+
Here is an example of an empty attestation
18+
19+
```json
20+
{
21+
"_type": "https://in-toto.io/Statement/v0.1",
22+
"predicateType": "",
23+
"subject": [],
24+
"predicate": {}
25+
}
26+
```
27+
28+
## Embedding and Inheritance
29+
30+
OpenVEX documents are designed to be embeddable in other formats. This is not a
31+
unique feature of OpenVEX: the VEX minimum elements define the notion of an
32+
"encapsulating format", a document that contains the VEX document and its
33+
statements. VEX also defines an inheritance model where the required data to
34+
complete VEX metadata cascades down from the encapsulating format to the
35+
document, to the statement. This allows VEX to leverage the capabilities of the
36+
encapsulating formats while defining a compatibility flow among implementations.
37+
38+
OpenVEX documents do not require an encapsulating document. Nevertheless, they
39+
were designed to be embeddable and they can be used as in-toto predicates. This
40+
lets software authors assert VEX data about a piece of software.
41+
42+
When embedding OpenVEX in attestations, the only field of data that "cascades"
43+
is the VEX statement's `product`, or `subject` in in-toto lingo.
44+
45+
### The VEX Product and the Attestation's Subject
46+
47+
In VEX, all statements apply to one or more products. A "product" in VEX is a
48+
loose term meaning any piece of software that can be listed in an SBOM. For a
49+
statement to be valid, it needs to have one or more statements. Here's an example
50+
of a VEX statement:
51+
52+
```json
53+
{
54+
"vulnerability": "CVE-2014-123456",
55+
"products": [
56+
"pkg:apk/distro/[email protected]?arch=armv7",
57+
"pkg:apk/distro/[email protected]?arch=x86_64"
58+
],
59+
"status": "fixed"
60+
}
61+
```
62+
63+
In the previous example, the statement specifies two packages of git (for armv7 and x86_64).
64+
65+
Attestations define their subjects natively. Following the VEX inheritance model
66+
the subjects in an attestation containing a VEX document will cascade down and
67+
become the VEX "product" of any statements that don't specify a subject.
68+
69+
Here is an example of an attestation with the same packages as subjects. Note that
70+
the predicate type is set to the OpenVEX context (the predicate contents have been
71+
removed for clarity):
72+
73+
```json
74+
{
75+
"_type": "https://in-toto.io/Statement/v0.1",
76+
"predicateType": "https://openvex.dev/ns",
77+
"subject": [
78+
{
79+
"name": "pkg:apk/distro/[email protected]?arch=armv7",
80+
"digest": {
81+
"sha256": "74634d9736a45ca9f6e1187e783492199e020f4a5c19d0b1abc2b604f894ac99"
82+
},
83+
},
84+
{
85+
"name": "pkg:apk/distro/[email protected]?arch=x86_64",
86+
"digest": {
87+
"sha256": "6bd98fe56e4d91439343d123d98522005874957ea1cb6075e75544d7753bd8d7"
88+
},
89+
}
90+
],
91+
"predicate": {
92+
// ...
93+
}
94+
}
95+
96+
```
97+
98+
When embedding OpenVEX inside an attestation, the subjects SHOULD move from the
99+
VEX statement product to the attestation subjects. This makes the attestation usable
100+
in systems that already know how to process them while still keeping the VEX metadata
101+
valid via the inheritance model. This is the complete attestation with the
102+
embedded OpenVEX document:
103+
104+
```json
105+
{
106+
"_type": "https://in-toto.io/Statement/v0.1",
107+
"predicateType": "text/vex",
108+
"subject": [
109+
{
110+
"name": "pkg:apk/distro/[email protected]?arch=armv7",
111+
"digest": {
112+
"sha256": "74634d9736a45ca9f6e1187e783492199e020f4a5c19d0b1abc2b604f894ac99"
113+
},
114+
},
115+
{
116+
"name": "pkg:apk/distro/[email protected]?arch=x86_64",
117+
"digest": {
118+
"sha256": "6bd98fe56e4d91439343d123d98522005874957ea1cb6075e75544d7753bd8d7"
119+
},
120+
}
121+
],
122+
"predicate": {
123+
"@context": "https://openvex.dev/ns",
124+
"@id": "https://openvex.dev/docs/example/vex-9fb3463de1b57",
125+
"author": "Wolfi J Inkinson",
126+
"role": "Security Researcher",
127+
"timestamp": "2023-01-08T18:02:03.647787998-06:00",
128+
"version": "1",
129+
"statements": [
130+
{
131+
"vulnerability": "CVE-2023-12345",
132+
"status": "fixed"
133+
}
134+
]
135+
}
136+
}
137+
```
138+
139+
Note in the finished example how the products in the statement have moved
140+
toward the attestation's subject section. This example assumes that the
141+
subjects' digests can be computed externally.
142+
143+
The product entries MAY remain in the VEX statement. In that case, they MUST
144+
be repeated and matched in the attestation subject section. An attestation SHOULD
145+
remain complete when composed with an OpenVEX predicate.
146+
147+
## Handling Product/Subject Granularity
148+
149+
An attestation's predicate is a singleton. It is a set of exactly one predicate
150+
that applies to any number of subjects. VEX, on the other hand, defines a document
151+
model that can host any number of statements, possibly with different subjects:
152+
153+
```json
154+
"statements": [
155+
{
156+
"vulnerability": "CVE-2014-123456",
157+
"products": [
158+
"pkg:apk/distro/[email protected]?arch=armv7"
159+
],
160+
"status": "fixed"
161+
},
162+
{
163+
"vulnerability": "CVE-2014-123456",
164+
"products": [
165+
"pkg:apk/distro/[email protected]?arch=x86_64"
166+
],
167+
"status": "under_investigation"
168+
},
169+
]
170+
```
171+
172+
The nature of the data models implies that an attestation can only refer to
173+
VEX statements that contain one or more of the `subject` entries in their product
174+
section. To attest the example above, an attestation can use any of the following
175+
subject structs:
176+
177+
```json
178+
"subject": {
179+
"pkg:apk/distro/[email protected]?arch=armv7"
180+
}
181+
```
182+
183+
```json
184+
"subject": {
185+
"pkg:apk/distro/[email protected]?arch=x86_64"
186+
}
187+
```
188+
189+
```json
190+
subject: {
191+
"pkg:apk/distro/[email protected]?arch=armv7",
192+
"pkg:apk/distro/[email protected]?arch=x86_64"
193+
}
194+
```
195+
196+
When an identifier is listed in the subject section, it signals any processor
197+
to look for data about it in the predicate. When looking at the VEX statements,
198+
the following rules define how statements are to be considered:
199+
200+
1. Any VEX statements that don't define products are considered to be attested.
201+
2. Any VEX statements listing products but not having the attestation's subjects
202+
in the product list are to be ignored.
203+
3. Any VEX statements including one of the attestation's subjects in its `product`
204+
section are to be considered only for that identifier and others that match.
205+
4. If a VEX statement lists one of the attestation's subjects in the product list
206+
but not another, it MUST be considered for the former but not for the latter.
207+
208+
## Digital Signatures
209+
210+
Attestations are meant to be digitally signed. While the signature envelope is
211+
not a part of the attestation or OpenVEX specifications, it should be noted that
212+
VEX recommends that the document `author` _SHOULD be cryptographically associated
213+
with the signature of the VEX document_. Signing an attestation SHOULD follow this
214+
convention and sign the attestation when possible using the same identity
215+
expressed in the author field. Since statements can originate from third parties
216+
exploring the same product, this may not be possible in all circumstances.
217+
218+
An identity signing an attestation containing VEX statements from third parties
219+
implies that the signer trusts those statements and has decided to include them
220+
in the VEX impact history.
221+

0 commit comments

Comments
 (0)