recipes/recipes/windows_image_builder/actions.proto

// Copyright 2021 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto3";

package recipes.infra.windows_image_builder.actions;

import "recipes/infra/windows_image_builder/sources.proto";

// Refer to a specific offline customization action
message OfflineAction {
  // The name for a given offline customization, e.g. basic_network_setup.
  string name = 1;

  // List of actions to be performed for the customization.
  repeated Action actions = 2;
}

// Refer to a specific OnlineCustomization action
message OnlineAction {
  // The name for a given online customization, e.g. install_cygwin
  string name = 1;

  // List of actions to be performed for the customization
  repeated Action actions = 2;
}

message Action {
  oneof action{
    // Adds the given file to the image
    AddFile add_file = 1;
    // Installs a given file on the device
    AddWindowsPackage add_windows_package = 2;
    // Edit registry on offline windows image
    EditOfflineRegistry edit_offline_registry = 3;
    // Adds a driver to offline windows image
    AddWindowsDriver add_windows_driver = 4;
    // Executes a powershell expression
    PowershellExpr powershell_expr = 5;
  }

  // Timeout in seconds
  int32 timeout = 6;
}

// AddFile uses robocopy to copy the file to image mount dir. Due to the way
// robocopy works, dst needs to be a directory. This means the following
// behavior can be expected
// cipd_src:  Copy the contents of '<cipd>/<ref>/<package>/<platform>/'
//            to dst folder
// git_src:   Copy '<git>/<ref>/<src_file>' to dst folder
// gcs_src:   Copy '<gcs>/bucket/<src_file>' to dst folder
message AddFile {
  // The AddFile action's name, e.g. add_startnet
  string name = 1;

  // Src of the file to add
  sources.Src src = 2;

  // relative to root of mounted image, e.g. Windows\System32
  string dst = 3;
}

// Add-WindowsPackage calls the command by the same name in powershell. It adds
// the -PackagePath based on src, -Path based on context, -LogLevel and -LogPath
// by default. Other arguments can be optionally given by args.
message AddWindowsPackage {
  // The name for the step, e.g. add WinPE-WMI.cab
  string name = 1;
  // Src of the install file
  sources.Src src = 2;
  // Args for the install command
  repeated string args = 3;
}

message EditOfflineRegistry {
  // The EditOfflineRegistry action's name, e.g. add_startnet
  string name = 1;

  // relative to root of mounted image, e.g. Windows\System32\Config\software
  string reg_hive_file = 2;

  // relative to root of the mounted registry file, e.g. Microsoft\Windows Defender\Features
  string reg_key_path = 3;

  // The name of the registry key property you want to create\edit e.g. TamperProtection
  string property_name = 4;

  // The value of the registry key property you want to create\edit e.g. 0
  string property_value = 5;

  // The property_type of the registry property you want to create\edit e.g. DWord
  RegPropertyType property_type = 6;
}

// referenced from https://docs.microsoft.com/en-us/dotnet/api/microsoft.win32.registryvaluekind?view=net-5.0
enum RegPropertyType {
  Binary = 0;
  DWord = 1;
  ExpandString = 2;
  MultiString = 3;
  None = 4;
  QWord = 5;
  String = 6;
  Unknown =7;
}

// AddWindowsDriver calls the command by the same name in powershell. It adds
// the -Driver based on src and -Path based on context. -LogPath and -LogLevel
// are added by default. Other args can be optionally specified.
// https://docs.microsoft.com/en-us/powershell/module/dism/add-windowsdriver?view=windowsserver2019-ps
message AddWindowsDriver {
  // Name of the step to be run. Ex: install dell drivers
  string name = 1;

  // Src of the driver to be installed
  sources.Src src = 2;

  // Args for the install command. Ex: ['-Recurse', '-ForceUnsigned']
  repeated string args = 3;
}

// PowershellExpr executes the given expression in powershell. It is possible to
// use external artifacts. These are given by the `srcs` map. The key for the
// srcs is available as a powershell var. The flag continue_ctx determines if
// we should keep the context running after execution. Using this you can chain
// multiple expressions and if all of them have the flag set, all the
// expressions are executed in the same powershell session. If unset the
// powershell session is exited after the expression is executed.
message PowershellExpr {
  // Name of the step. This will be displayed in milo
  string name = 1;

  // map of artifacts to be downloaded. This will be available as a powershell
  // var for reference in the powershell expression. For example, if the srcs
  // contain `'example_py': Src(CIPDSrc(...))`. This will be available as a
  // powershell var `$example_py`.
  map<string, sources.Src> srcs = 2;

  // If set the session is kept alive after executing the expression.
  bool continue_ctx = 3;

  // List of return codes to treat as success. Default is [0].
  repeated int32 return_codes = 4;

  // List of file to be copied to milo. To be used to display logs in milo
  repeated string logs = 5;

  // Expression to be executed.
  string expr = 6;

  // timeout, if set will not throw error on timeout
  bool ignore_timeout = 7;
}