plugin_service.proto

/*
 * Copyright 2022 Google LLC
 *
 * 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.
 */

// Model for the plugin RPC service protocol.
syntax = "proto3";

package tsunami.proto;

import "detection.proto";
import "network_service.proto";
import "plugin_representation.proto";
import "reconnaissance.proto";

option java_multiple_files = true;
option java_outer_classname = "PluginServiceProtos";
option java_package = "com.google.tsunami.proto";
option go_package = "github.com/google/tsunami-security-scanner/proto";

// Represents a run request with all matched plugins that will need to run
// as well as the target to run against.
message RunRequest {
  // Target of the plugins.
  TargetInfo target = 1;
  // All matched plugins that will need to run.
  repeated MatchedPlugin plugins = 2;
}

// Compact representation of RunRequest.
message RunCompactRequest {
  // Target of the plugins.
  TargetInfo target = 1;

  // Indexes in the following structure point to the services/plugins defined
  // below. (The order is safe, guaranteed by the proto specification: "The
  // order of the elements with respect to each other is preserved when parsing,
  // though the ordering with respect to other fields is lost.")
  message PluginNetworkServiceTarget {
    // The index of the plugin to run.
    uint32 plugin_index = 1;
    // The index of the network service to run against.
    uint32 service_index = 2;
  }
  // All network services that are targeted by some of the plugins.
  repeated NetworkService services = 2;
  // All plugins that should be executed during the run.
  repeated PluginDefinition plugins = 3;
  // The concrete map of plugin/network service pairs that should be scanned.
  repeated PluginNetworkServiceTarget scan_targets = 4;
}

// Represents the plugin needed to run by the language-specific server
// as well as all the matched network services for the plugin.
message MatchedPlugin {
  // All matched network services from the reconnaissance report.
  repeated NetworkService services = 1;
  // Plugin to run.
  PluginDefinition plugin = 2;
}

// Represents a run response with the only field being all DetectionReports
// generated by the language-specific server.
message RunResponse {
  DetectionReportList reports = 1;
}

// Represents a request to list all plugins from the requested server.
message ListPluginsRequest {}

// Represents a response containing a list of all plugins
// from the requested server.
message ListPluginsResponse {
  repeated PluginDefinition plugins = 1;

  // Plugin service can indicate here that it RunRequest should be compact
  // (compact_targets should be populated instead of MatchedPlugin plugins).
  bool want_compact_run_request = 2;
}

// Represents the plugin service, two RPCs for running plugins
// and listing plugins, respectively.
service PluginService {
  // Performs a run request to run all language plugins specified by the
  // request.
  rpc Run(RunRequest) returns (RunResponse) {}
  // Performs a run request to run all language plugins specified by the
  // compact representation of the request. This is useful, when hundreds of
  // plugins are to be run against many different NetworkServices.
  // The language server must set `want_compact_run_request` so that the
  // Tsunami CLI knows to invoke this method instead of `Run`.
  rpc RunCompact(RunCompactRequest) returns (RunResponse) {}
  // Sends a request to list all plugins from the respective language server.
  rpc ListPlugins(ListPluginsRequest) returns (ListPluginsResponse) {}
}