From fea4a2c7a13c38ce2c9fbbe5a7004fd4a8f8ac75 Mon Sep 17 00:00:00 2001 From: Aditya Sirish Date: Fri, 11 Nov 2022 15:54:25 -0500 Subject: [PATCH] Add draft material about capturing file accesses Signed-off-by: Aditya Sirish --- spec/predicates/runtime-trace.md | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/spec/predicates/runtime-trace.md b/spec/predicates/runtime-trace.md index 024df9c9..9d78be8a 100644 --- a/spec/predicates/runtime-trace.md +++ b/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": "" }, “build”: { - “BuilderId”: “”, + “builderId”: “”, “type”: “”, “event”: “”, }, @@ -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": "", @@ -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.