internal/engine/shac.proto

// Copyright 2023 The Shac 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 engine;

option go_package = "go.fuchsia.dev/shac-project/shac/internal/engine";

// Document is the root message being decoded in a shac.textproto.
message Document {
  // Minimum shac version that is required to run this check. This enables
  // printing a better error message. It is a semver string.
  string min_shac_version = 1;
  // When set to true, it is allowed to have checks that access the network.
  bool allow_network = 2;
  // Full list of all loaded package dependencies.
  Requirements requirements = 3;
  // Digests of all direct and indirect dependencies to confirm the code was not
  // modified.
  Sum sum = 4;
  // When set, refers to a local copy to use.
  string vendor_path = 5;
  // File paths to ignore/un-ignore. Syntax matches that of .gitignore. See
  // https://git-scm.com/docs/gitignore.
  repeated string ignore = 6;
  // Whether to allow checks write access to the SCM root directory.
  // TODO(olivernewman): Remove this option once named caches and pass-throughs
  // are implemented.
  bool writable_root = 7;
  repeated Var vars = 8;
}

// Var specifies a variable that may be passed into checks at runtime by the
// --var flag and accessed via `ctx.vars.get(name)`.
//
// Vars are intentionally limited in usefulness so they can only be used for
// passing through opaque configuration strings, not for controlling behavior,
// which would introduce the potential for divergence between environments.
message Var {
  // name is the name of the variable, as specified on the command line and as
  // passed into `ctx.vars.get()`.
  string name = 1;
  // desc is an optional description of the meaning of the variable.
  string description = 2;
  // default is the default value of the variable. It may be left unspecified,
  // in which case the default is the empty string.
  string default = 3;
}

// Requirements lists all the external dependencies, both direct and transitive
// (indirect).
message Requirements {
  // direct are packages referenced by the starlark code via a load() statement.
  repeated Dependency direct = 1;
  // indirect are packages referenced by direct dependencies or transitively.
  repeated Dependency indirect = 2;
}

// Dependency is a starlark package containing a api.star file that will be
// loaded and become available through a load("@...") statement.
message Dependency {
  // url is the URL to the resource without the schema, e.g.
  // "github.com/shac/generic-checks".
  string url = 1;
  // alias is an optional shorthand alias. This is how this is referenced to in
  // load() statements.
  string alias = 2;
  // version is the pinned version to use the dependency.
  string version = 3;
}

// Sum is the digest of known dependencies.
message Sum {
  repeated Known known = 1;
}

// Known is the multiple known digests of a single dependency.
message Known {
  string url = 1;
  repeated VersionDigest seen = 2;
}

// VersionDigest is a version:digest pair.
message VersionDigest {
  // version is one of the version referred to directly or transitively.
  string version = 1;
  // digest is the hash of the content of the dependency. It uses the same
  // hashing algorithm than go.sum. See https://golang.org/x/mod/sumdb/dirhash.
  string digest = 2;
}