Add draft material about capturing file accesses

Signed-off-by: Aditya Sirish <[email protected]>

spec/predicates/runtime-trace.md

@@ -32,7 +32,7 @@ The schema of the attestation type is the core part of the document. It defines
       "id": "<URI>"
     },
     “build”: {
-        “BuilderId”: “<URI>”,
+        “builderId”: “<URI>”,
         “type”: “<URI>”,
         “event”: “<STRING>”,
     },
@@ -48,6 +48,9 @@ The schema of the attestation type is the core part of the document. It defines
       "process": [
          { /* object */ }
       ],
+      "fileAccess": [
+        { /* object */ }
+      ],
     },
     "metadata": {
       "buildStartedOn": "<TIMESTAMP>",
@@ -77,19 +80,19 @@ Identifies the specific monitor instance used to trace the runtime.
 
 URI indicating the monitor’s identity.
 
-`builder` _object_, _required_
+`build` _object_, _required_
 
 Feedback required: Should this predicate be scoped to runtime traces of builds only or generalize to runtime traces of any activity?
 
-`builder.id` _string (URI)_, _required_
+`builder.builderId` _string (URI)_, _required_
 
 URI indicating the builder’s identity. Ex: GitLab Runner ID
 
-`builder.type` _string (TypeURI)_, _required_
+`build.type` _string (TypeURI)_, _required_
 
 URI indicating the type of build performed.
 
-`builder.event` _string_, _required_
+`build.event` _string_, _required_
 
 String identifying the specific job or task associated with the attestation.
 
@@ -113,6 +116,14 @@ Feedback required: Should different types of monitors (process vs network for ex
 
 `monitorLog.network` _list_, _optional_
 
+`monitorLog.fileAccess` _list_, _optional_
+
+Record of files accessed during the build process. A complete list of _materials_ can be derived from this information. Each entry in this list is expected to record the path of the file and one or more digests of the file. This field is a list rather than a key value map because a single file may be used multiple times during the build process. Further, some files that are accessed may _change_ during the build process, and so, different entries may have different digests.
+
+While this predicate can be used to log file accesses, the actual technique used to capture the file access event has some implications. If a synchronous monitor, for example one that uses `ptrace` to trace the file access system calls, is used, then the build process can be paused while the file's digest is calculated and stored. However, asynchronous monitors such as those using eBPF cannot pause the build process before the file is actually used. Therefore, they cannot make as strong guarantees about the digests of the files accessed. Verifiers using runtime trace attestations for file accesses must careful about what guarantees they are actually getting based on how the build process was monitored.
+
+Feedback required: There were discussions about including a field for "materials" derived from file accesses. Should it be within monitorLog?
+
 `metadata` _object_, _optional_
 
 Other properties of the monitoring event.