// Copyright 2019 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
//
// This proto file includes the protocol buffers for communicating with the Safe
// Browsing Real Time API.

syntax = "proto2";

package safe_browsing;

import "components/enterprise/common/proto/connectors.proto";
import "components/safe_browsing/core/common/proto/csd.proto";

option optimize_for = LITE_RUNTIME;

message RTLookupRequest {
  // If applicable, URL submitted from Chrome.
  optional string url = 1;
  // Type of Lookup submitted by Chrome.
  enum LookupType {
    // Lookup type is not specified in request.
    LOOKUP_TYPE_UNSPECIFIED = 0;
    // Lookup type is navigation.
    NAVIGATION = 1;
    // Lookup type is download.
    DOWNLOAD = 2;
  }
  optional LookupType lookup_type = 2;
  // Mechanism to have different detection methods for different user
  // population later.
  optional ChromeUserPopulation population = 3;

  // Deprecated
  optional string DEPRECATED_scoped_oauth_token = 4 [deprecated = true];

  // The DM Token for Enterprise-enrolled devices (go/cbe-dmtoken). May contain
  // either a device or a profile DM token. The device DM token takes precedence
  // when both are present.
  optional string dm_token = 5;

  // DM token for managed profile.
  // For more information on DM tokens, see go/cbe-dmtoken
  optional string profile_dm_token = 11;

  // DM token for managed device.
  // For more information on DM tokens, see go/cbe-dmtoken
  optional string browser_dm_token = 12;

  // This field contains additional information about the browser and device or
  // profile, this information is used for security event reporting.
  // Only populated for Enterprise Protego requests.
  optional enterprise_connectors.ClientMetadata client_reporting_metadata = 14;

  // Email of the signed-in user that triggered the request, if available.
  // Only populated for enterprise requests.
  optional string email = 13;

  // |version| helps the Safe Browsing server understand what version of the
  // proto Chrome understands, and also what kinds of behaviours it supports.
  // It should be incremented when adding new fields and/or when making changes
  // to how existing fields may be interpreted.
  // Version 1:
  //   * Client supports caching with |COVERING_MATCH| verdicts.
  //   * Client supports the |os_type| field.
  //   * Client falls back to hash-based checks if there's a SAFE match in the
  //     cache.
  // Version 2:
  //   * Client supports referrer chains.
  // Version 3:
  //   * Client support the |report_type| and |frame_type| fields.
  // Version 4:
  //   * Client may include |referring_webapk| in |referring_app_info| field.
  optional int32 version = 6 [default = 0];

  // The operating system of the client.
  enum OSType {
    OS_TYPE_UNSPECIFIED = 0;
    OS_TYPE_ANDROID = 1;
    OS_TYPE_CHROME_OS = 2;
    // Deprecated: OS_TYPE_FUCHSIA = 3;
    OS_TYPE_IOS = 4;
    OS_TYPE_LINUX = 5;
    OS_TYPE_MAC = 6;
    OS_TYPE_WINDOWS = 7;
  }
  optional OSType os_type = 7;

  // If we can find the complete referrer chain, this field will contain URLs
  // transitions from landing referrer to landing page to current URL in reverse
  // chronological order, i.e. current URL comes first in this list, and landing
  // referrer comes last.
  repeated ReferrerChainEntry referrer_chain = 8;

  // Type of report sent.
  enum ReportType {
    REPORT_TYPE_UNSPECIFIED = 0;
    FULL_REPORT = 1;
    SAMPLED_REPORT = 2;
  }
  // Whether the ping sent to Safe Browsing is a normal (full request) ping or a
  // sample ping for URLs on the allow-list.
  optional ReportType report_type = 9;

  // Type of URL frame.
  enum FrameType {
    FRAME_TYPE_UNSPECIFIED = 0;
    MAIN_FRAME = 1;
    SUB_FRAME = 2;
  }
  // Whether the URL sent to Safe Browsing is mainframe URL or subframe URL.
  optional FrameType frame_type = 10;

  // The Android app that launched Chrome.
  optional ReferringAppInfo referring_app_info = 15;

  // Local IP addresses of the device. This is only used for enterprise
  // requests.
  repeated string local_ips = 16;
}

message RTLookupResponse {
  // Contains threat information including threat type, verdict type, cache
  // duration and cache expression on a matching url.
  message ThreatInfo {
    // Type of threat detected.
    enum ThreatType {
      // Unknown.
      THREAT_TYPE_UNSPECIFIED = 0;
      // URL leads to unintentional download of malware i.e. drive-by downloads.
      WEB_MALWARE = 1;
      // Social engineering threat type for internal use.
      SOCIAL_ENGINEERING = 3;
      // Unwanted software threat type.
      UNWANTED_SOFTWARE = 4;
      // Unclear Billing threat type
      UNCLEAR_BILLING = 5;
      // Enterprise-specific threat type for managed policy related verdicts.
      MANAGED_POLICY = 6;

      reserved 2;
    }
    optional ThreatType threat_type = 1;
    // TTL of the verdict in seconds.
    optional int64 cache_duration_sec = 2;

    // A host-suffix/path-prefix expression for caching the verdict
    // This field is only used by previous versions of Chrome(M81 Canary and
    // Dev) that only support "COVERING_MATCH". This field is deprecated in
    // favor of "cache_expression_using_match_type" below.
    optional string cache_expression = 3 [deprecated = true];

    // Type of verdicts issued by the server. Different levels of verdicts from
    // 1 to 100 can be added in future based on the confidence of the verdict.
    // 1 being confidently safe to 100 being confidently dangerous.
    enum VerdictType {
      VERDICT_TYPE_UNSPECIFIED = 0;
      SAFE = 1;
      SUSPICIOUS = 50;
      WARN = 75;
      DANGEROUS = 100;
    }
    optional VerdictType verdict_type = 4;

    enum CacheExpressionMatchType {
      MATCH_TYPE_UNSPECIFIED = 0;

      // The returned cache expression applies to all URLs covered by it. See
      // the following for how covering works:
      // https://developers.google.com/safe-browsing/v4/urls-hashing e.g.
      // "test.com/foo1" of type COVERING_MATCH will not apply to
      // "test.com/foo2" or "test.com/", but will apply to "test.com/foo1/bar2"
      // and "baz.test.com/foo1".
      COVERING_MATCH = 1;

      // The returned cache expression only applies to URLs with the same host
      // and path after canonicalization. e.g. "test.com/foo1" of type
      // EXACT_MATCH will not apply to "test.com/" or "test.com/foo1/bar2", but
      // will apply to "test.com/foo1"
      EXACT_MATCH = 2;
    }

    optional CacheExpressionMatchType cache_expression_match_type = 5;

    // The new cache expression. "cache_expression_match_type" indicates how
    // this expression should be used for matching on the client. If
    // “cache_expression_match_type” is not set, it means this expression is not
    // applicable for caching, and the entry should be ignored.
    optional string cache_expression_using_match_type = 6;

    // Contains information about the detected enterprise rule match. This is
    // only populated if ‘ThreatType’ is “MANAGED_POLICY”.
    optional MatchedUrlNavigationRule matched_url_navigation_rule = 7;
  }

  // Each matching url can have multiple threats detected, if the response
  // contains multiple threat_info messages, then they are in decreasing order
  // of severity so that the client could choose first applicable threat_info
  // as the most severe one.
  repeated ThreatInfo threat_info = 1;

  // When set, represents the realtime API asking the client side detection
  // module to send a ping regardless of the scoring found in CSD models.
  optional ClientSideDetectionType client_side_detection_type = 2;

  // The URL categories associated with the URL in the request. Only populated
  // for Enterprise Protego and only if categories were found for the URL.
  repeated string url_categories = 3;

  // The information of Llama trigger rules that triggered a CSD ping. Set only
  // if client_side_detection_type = FORCE_REQUEST.
  optional LlamaForcedTriggerInfo llama_forced_trigger_info = 4;
}

// mirrors google.protobuf.Timestamp
message Timestamp {
  // Represents seconds of UTC time since Unix epoch
  // 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to
  // 9999-12-31T23:59:59Z inclusive.
  optional int64 seconds = 1;

  // Non-negative fractions of a second at nanosecond resolution. Negative
  // second values with fractions must still have non-negative nanos values
  // that count forward in time. Must be from 0 to 999,999,999
  // inclusive.
  optional int32 nanos = 2;
}

// Contains information about a matched URL Filtering rule defined by
// enterprise policies.
message MatchedUrlNavigationRule {
  // The id of the matched rule that caused this verdict.
  optional string rule_id = 1;
  // The name (as defined in the admin console by the admin who defined this
  // rule) of the matched rule that caused this verdict.
  optional string rule_name = 2;
  // If the match was due to an URL category, it is found here.
  optional string matched_url_category = 3;

  // Action for matched rule not implemented.
  reserved 4;

  // This represents text segment in a custom message defined for DLP rule.
  // For eg: “Please learn more (here)[link] and (here)[link]"
  // is broken into 4 segments.
  message CustomRuleMessageSegment {
    // Required. Text to be displayed in this segment.
    optional string text = 1;

    // Optional. Link to external resource, such as a company's communication
    // policy. This is supposed to be hyperlink on text field above.
    optional string link = 2;
  }

  message CustomMessage {
    // Custom message provided by admin during rule creation. Contains text
    // only.
    optional string custom_message = 1 [deprecated = true];

    // learn more link provided by admin during rule creation. Contains a single
    // URL.
    optional string learn_more_link = 2 [deprecated = true];

    // Custom message containing <a> tags wrapping URLs. This is sanitized HTML
    // restricted to <a> tags with "href" attribute.
    optional string custom_message_with_links = 3 [deprecated = true];

    // Ordered list of text segments comprised of plain text and URLs. These
    // combined represent the custom rule message.
    repeated CustomRuleMessageSegment message_segments = 4;
  }
  // Contains custom interstitial message associated with this rule.
  optional CustomMessage custom_message = 5;

  message WatermarkMessage {
    // Custom message provided by admin during rule creation. Contains text
    // only.
    optional string watermark_message = 1;

    // Identifier for the user/device that triggered the watermark rule.
    optional string user_email = 2;
    optional string obfuscated_device_id = 3;

    // Triggered rule timestamp to be displayed in the watermark for easy admin
    // investigation.
    optional Timestamp timestamp = 4;
  }

  // Contains the watermarking message, provided by Admin during rule creation.
  // Also includes information about the user for whom the rule was triggered,
  // and the timestamp of the triggered rule event.
  optional WatermarkMessage watermark_message = 6;

  reserved 7;

  // Whether the matched rule need to block screenshots.
  optional bool block_screenshot = 8;

  message DataMaskingAction {
    optional string display_name = 1;

    // The type of masking to be applied. This is either "LIGHT", "HARD" or
    // "REDACTED", and is implemented using a string instead of an enum to
    // simplify compatibility when this proto field is converted to a JSON
    // object in Chrome for a JS extension API call.
    optional string mask_type = 2;

    // This is a regex pattern that will be used to match the URL.
    optional string pattern = 3;
  }

  // The set of data masking actions that should be applied to the URL due to
  // this rule match.
  repeated DataMaskingAction data_masking_actions = 9;
}