visor/pkg/sentry/seccheck/points/sentry.proto

// Copyright 2022 The gVisor Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package gvisor.sentry;

import "pkg/sentry/seccheck/points/common.proto";

// CloneInfo contains information used by the Clone checkpoint.
message CloneInfo {
  gvisor.common.ContextData context_data = 1;

  // created_thread_id is the thread's ID in the root PID namespace.
  int32 created_thread_id = 3;

  int32 created_thread_group_id = 4;

  // created_thread_start_time_ns is the thread's CLOCK_REALTIME start time.
  int64 created_thread_start_time_ns = 5;

  // flags are equivalent to the flags passed to clone(2).
  uint64 flags = 6;
}

// ExecveInfo contains information used by the Execve checkpoint.
message ExecveInfo {
  gvisor.common.ContextData context_data = 1;

  // BinaryPath is the resolved filesystem path to the executable binary file in
  // the mount namespace in which it was opened. Unlike Execfn (which preserves
  // the original string passed to execve(2)), BinaryPath reflects symlink and
  // interpreter script resolution.
  string binary_path = 2;

  // Argv is the new process image's argument vector.
  repeated string argv = 3;

  // Env is the new process image's environment variables.
  repeated string env = 4;

  // BinaryMode is the executable binary file's mode.
  uint32 binary_mode = 5;

  uint32 binary_uid = 6;
  uint32 binary_gid = 7;

  // BinarySha256 is the SHA-256 hash of the executable binary file.
  //
  // Note that this requires reading the entire file into memory, which is
  // likely to be extremely slow.
  bytes binary_sha256 = 8;

  // BinarySha1 is the SHA-1 hash of the executable binary file.
  bytes binary_sha1 = 16;

  // BinaryOverlayfsUpper indicates whether the executable binary exists on the
  // upper layer of the overlay filesystem.
  //
  // Note that this only indicates presence on the upper layer, NOT that the
  // file exists *only* on the upper layer. Specifically,
  // binary_overlayfs_upper=true alone does not mean the file was copied up from
  // a lower layer (e.g., it could have been created or downloaded directly on
  // the upper layer).
  bool binary_overlayfs_upper = 9;

  // BinaryOverlayfsLower indicates whether the executable binary exists on the
  // lower layer of the overlay filesystem.
  //
  // Note that this only indicates presence on the lower layer, NOT that the
  // file exists *only* on the lower layer. Specifically,
  // binary_overlayfs_lower=true alone does not mean the file is unmodified
  // (e.g., if binary_overlayfs_upper=true also, the file was modified and
  // copied up to the upper layer).
  bool binary_overlayfs_lower = 15;

  // BinaryIno is the virtualized inode number of the executable binary file.
  uint64 binary_ino = 10;

  // BinaryCtime is the ctime of the executable binary file.
  gvisor.common.Timespec binary_ctime = 11;

  // BinarySize is the size of the executable binary file in bytes.
  int64 binary_size = 18;

  // BinaryNlink is the number of hard links to the executable binary file.
  uint32 binary_nlink = 19;

  // BinaryInMemfd is true if the executable binary file is in a memfd
  // (anonymous shmem/tmpfs file created via memfd_create).
  bool binary_in_memfd = 20;

  // Standard input, output, and error file descriptor info.
  gvisor.common.FdInfo stdin = 12;
  gvisor.common.FdInfo stdout = 13;
  gvisor.common.FdInfo stderr = 14;

  // Execfn is the exact pathname string passed to execve(2) (used for
  // AT_EXECFN). Unlike BinaryPath, this preserves the original relative or
  // unresolved path argument before symlink or interpreter script resolution.
  string execfn = 17;

  // PipeProcInfo contains lightweight process information of a sibling process
  // connected via pipe on stdin/stdout.
  PipeProcInfo pipe_input_proc = 21;
  PipeProcInfo pipe_output_proc = 22;
}

// PipeProcInfo contains lightweight process information of a sibling process
// connected via pipe.
//
// Only ContextData is provided here so that trace consumers can uniquely
// correlate the sibling process via thread_group_id and
// thread_group_start_time_ns without passing repetitive strings over the wire.
message PipeProcInfo {
  gvisor.common.ContextData context_data = 1;
}

message ExitNotifyParentInfo {
  gvisor.common.ContextData context_data = 1;

  // ExitStatus is the exiting thread group's exit status, as reported
  // by wait*().
  int32 exit_status = 2;
}

message TaskExit {
  gvisor.common.ContextData context_data = 1;

  // ExitStatus is the exiting thread group's exit status, as reported
  // by wait*().
  int32 exit_status = 2;
}

message MmapInfo {
  gvisor.common.ContextData context_data = 1;

  // MappedPath is the path of the file backing the memory mapping, if any.
  string mapped_path = 2;

  // MappedIno is the inode number of the backing file.
  uint64 mapped_ino = 3;

  // MappedMode is the file mode (permissions and type) of the backing file.
  uint32 mapped_mode = 4;

  // MappedUid is the user ID of the owner of the backing file.
  uint32 mapped_uid = 5;

  // MappedGid is the group ID of the owner of the backing file.
  uint32 mapped_gid = 6;

  // IsInitialMmap indicates whether this mapping corresponds to the task's
  // initial executable file.
  bool is_initial_mmap = 7;

  // MappedCtime is the ctime of the backing file.
  gvisor.common.Timespec mapped_ctime = 8;

  // OverlayfsUpper indicates whether the mapped file exists on the upper layer
  // of the overlay filesystem.
  //
  // Note that this only indicates presence on the upper layer, NOT that the
  // file exists *only* on the upper layer. Specifically,
  // overlayfs_upper=true alone does not mean the file was copied up from
  // a lower layer (e.g., it could have been created or downloaded directly on
  // the upper layer).
  bool overlayfs_upper = 9;

  // OverlayfsLower indicates whether the mapped file exists on the lower layer
  // of the overlay filesystem.
  //
  // Note that this only indicates presence on the lower layer, NOT that the
  // file exists *only* on the lower layer. Specifically,
  // overlayfs_lower=true alone does not mean the file is unmodified
  // (e.g., if overlayfs_upper=true also, the file was modified and
  // copied up to the upper layer).
  bool overlayfs_lower = 10;
}