components/safe_browsing/content/common/safe_browsing.mojom

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

module safe_browsing.mojom;

import "components/safe_browsing/core/common/safe_browsing_url_checker.mojom";
import "mojo/public/mojom/base/file.mojom";
import "mojo/public/mojom/base/proto_wrapper.mojom";
import "mojo/public/mojom/base/shared_memory.mojom";
import "services/network/public/mojom/http_request_headers.mojom";
import "third_party/blink/public/mojom/tokens/tokens.mojom";
import "url/mojom/url.mojom";

// Provided by the browser and used by renderers to perform SafeBrowsing URL
// checks.
interface SafeBrowsing {
  // Queries SafeBrowsing whether |url| is safe to load, and creates a
  // SafeBrowsingUrlChecker interface.
  //
  // The check and (subsequent checks performed using SafeBrowsingUrlChecker)
  // checks against SafeBrowsing's Malware, Phishing, and UwS blocklists.
  //
  // `frame_token` is set when the request originates from the context of a
  // frame. Dedicated workers are associated with a frame context and will
  // have the value set. Service workers and shared workers are not associated
  // with a frame and will have it set to null.
  //
  // The SafeBrowsingUrlChecker interface should be used (and only used) for
  // subsequent checks of redirects, so that the server side could keep track of
  // the redirect chain. Disconnecting the checker interface cancels on-going
  // URL checks. Please note that in that case if the check started by this
  // method hasn't completed yet, it will also be canceled and the callback is
  // ran with |proceed == true| and |showed_interstitial == false| as if the URL
  // is safe.
  //
  // |proceed| indicates whether it is okay to proceed with loading the URL.
  // |showed_interstitial| indicates whether the SafeBrowsing interstitial page
  // has been shown to the user.
  CreateCheckerAndCheck(blink.mojom.LocalFrameToken? frame_token,
                        pending_receiver<SafeBrowsingUrlChecker> receiver,
                        url.mojom.Url url,
                        string method,
                        network.mojom.HttpRequestHeaders headers,
                        int32 load_flags,
                        bool has_user_gesture,
                        bool originated_from_service_worker)
      => (bool proceed, bool showed_interstitial);

  // Bind an additional pipe to this instance of the SafeBrowsing interface.
  Clone(pending_receiver<SafeBrowsing> receiver);
};

// Used to store the name and value of an HTML Element's attribute.
struct AttributeNameValue {
  string name;
  string value;
};

// A node is essentially a frame.
struct ThreatDOMDetailsNode {
  // A unique ID for this node, unique to the current Render Frame.
  int32 node_id;
  // URL of this resource. Can be empty.
  url.mojom.Url url;
  // If this resource was in the "src" attribute of a tag, this is the tagname
  // (eg "IFRAME"). Can be empty.
  string tag_name;
  // URL of the parent node. Can be empty.
  url.mojom.Url parent;
  // The unique ID of the parent node. Can be 0 if this is the top node.
  int32 parent_node_id;
  // Children of this node. Can be empty.
  array<url.mojom.Url> children;
  // The unique IDs of the child nodes. Can be empty if there are no children.
  array<int32> child_node_ids;
  // The node's attributes as a collection of name-value pairs.
  array<AttributeNameValue> attributes;
  // If this node represents a frame or iframe, then this field is set to the
  // FrameToken of the local or remote frame in this renderer process that is
  // responsible for rendering the contents of this frame (to handle OOPIFs).
  blink.mojom.FrameToken? child_frame_token;
  // This field holds inline JavaScript content and remotely hosted scripts.
  string inner_html;
};

interface ThreatReporter {
  // Client-side detection message sent from the browser to the renderer.
  // Request a DOM tree when a safe browsing interstitial is shown.
  // Renderer returns part of the DOM to be used in a threat report.
  GetThreatDOMDetails() => (array<ThreatDOMDetailsNode> nodes);
};

// Enum representing possible outcomes of the renderer-side classification.
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
enum PhishingDetectorResult {
  // The feature collection succeeded.
  SUCCESS = 0,

  // The classifier either did not exist, or was not ready.
  CLASSIFIER_NOT_READY = 1,

  // Another classification was requesting, cancelling this one.
  CANCELLED = 2,

  // The last recorded transition was a forward/back in history. Since the
  // classifier previously ran on this URL, it did not run again.
  FORWARD_BACK_TRANSITION = 3,

  // The classifier returned an invalid score because the model is
  // misconfigured.
  INVALID_SCORE = 4,

  // Invalid URL request came in that is not HTTP/HTTPS or GET requests.
  INVALID_URL_FORMAT_REQUEST = 5,

  // WebDocumentLoader failed to load.
  INVALID_DOCUMENT_LOADER = 6,

  // URL feature extraction has failed.
  URL_FEATURE_EXTRACTION_FAILED = 7,

  // DOM feature extraction failed.
  DOM_EXTRACTION_FAILED = 8,

  // Term feature extraction failed.
  TERM_EXTRACTION_FAILED = 9,

  // Visual extraction failed.
  VISUAL_EXTRACTION_FAILED = 10,
};

enum ClientSideDetectionType {
  // Send a CSD request regardless of the client side model's score values.
  kForceRequest,
  // Either the local DOM or visual model triggered.
  kTriggerModels,
  // A Notification prompt triggered.
  kNotificationPermissionPrompt,
  // Keyboard lock request triggered.
  kKeyboardLock,
  // Pointer lock request triggered.
  kPointerLock,
  // Vibration API request triggered.
  kVibrationApi,
  // Fullscreen API request triggered.
  kFullscreen,
  // Password protection request triggered.
  kPasswordProtection,
  // Clipboard copy API request triggered.
  kClipboardCopyApi,
  // Credit card form was detected.
  kCreditCardForm,
  // Image embedding matched.
  kImageEmbeddingMatch,
};

// Interface for starting phishing classification. This is scoped to a
// particular RenderFrame.
[EnableIf=full_safe_browsing]
interface PhishingDetector {
  // Tells the renderer to begin phishing detection for the given toplevel URL
  // which it has started loading. Returns the serialized request proto and a
  // `result` enum to indicate failure. If the URL is phishing the `request`
  // ClientPhishingRequest will have `is_phishing()` set to true. The
  // `request_type` correlates to the phishing detection request type from the
  // browser process and is only used for logging on the renderer.
  StartPhishingDetection(
    url.mojom.Url url, ClientSideDetectionType request_type)
      => (PhishingDetectorResult result,
          mojo_base.mojom.ProtoWrapper? request);
};

// Interface for setting a phishing model. This is scoped to an entire
// RenderProcess.
[EnableIf=full_safe_browsing]
interface PhishingModelSetter {
  // A classification model for client-side phishing detection in addition to
  // the image embedding model. This call sends the model and the image
  // embedding model from browser process to the renderer process. The image
  // embedding model is converted from a TfLite file to a string in the browser
  // process to be used to create an ImageEmbedder in the renderer process. This
  // function call should only be called for Enhanced Safe Browsing enabled
  // users who will allow the ImageEmbedding output as part of the CSD-Phishing
  // ping to be sent to CSPP for better model training. All else is the same as
  // the SetPhishingFlatBufferModel function.
  SetImageEmbeddingAndPhishingFlatBufferModel(
      mojo_base.mojom.ReadOnlySharedMemoryRegion region,
      mojo_base.mojom.ReadOnlyFile? tflite_model,
      mojo_base.mojom.ReadOnlyFile? image_embedding_model);

  // The image embedding model is a complementary model that is used with the
  // classification process, and this function will attach the model to an
  // already existing model object in the renderer process if the versions
  // match.
  AttachImageEmbeddingModel(
      mojo_base.mojom.ReadOnlyFile? image_embedding_model);

  // A classification model for client-side phishing detection. This call sends
  // the model from the browser process to the renderer process. The model is
  // sent as a safe_browsing::ClientSideModel flatbuffer string in a
  // ReadOnlySharedMemoryRegion to client-side phishing detection on the
  // renderer process. An invalid region is used to disable classification. The
  // |tflite_model| is a file handle with contents a TfLite model, which is used
  // to classify the appearance of pages.
  SetPhishingFlatBufferModel(
      mojo_base.mojom.ReadOnlySharedMemoryRegion region,
      mojo_base.mojom.ReadOnlyFile? tflite_model);

  // When OptimizationGuide server sends a null model, this signals there is a
  // bad model on disk. Calling this function clears the current Scorer object
  // in the renderer so that classification isn't used with the bad model.
  ClearScorer();

  // This is used in tests to ensure that the model has been set before sending
  // IPCs to start classification.
  SetTestObserver(pending_remote<PhishingModelSetterTestObserver>? observer)
      => ();
};

// This is used in tests to ensure that the model has been set before sending
// IPCs to start classification.
interface PhishingModelSetterTestObserver {
  // Called whenever the phishing model has changed.
  PhishingModelUpdated();
};

// Enum representing possible outcomes of the renderer-side image embedding
// process. These values are persisted to logs. Entries should not be renumbered
// and numeric values should never be reused.
enum PhishingImageEmbeddingResult {
  // The feature collection succeeded.
  kSuccess,
  // The image embedder either did not exist, or was not ready.
  kImageEmbedderNotReady,
  // Another image embedding was requesting, cancelling this one.
  kCancelled,
  // last recorded transition was a forward/back in history. Since the
  // image embedder previously ran on this URL, it did not run again.
  kForwardBackTransition,
  // the image embedder process failed
  kFailed,
};

// Interface for starting image embedding. This is scoped to a
// particular RenderFrame.
[EnableIf=full_safe_browsing]
interface PhishingImageEmbedderDetector {
  // Tells the renderer to begin image embedding. This should only happen if the
  // user is subscribed to ESB, and the verdict is phishy or LLAMA force trigger
  // the CSPP ping. The return objects are Image Embedding process result and a
  // ImageFeatureEmbedding object declared in csd.proto
  StartImageEmbedding(url.mojom.Url url)
      => (PhishingImageEmbeddingResult result,
          mojo_base.mojom.ProtoWrapper? image_embedding_request);
};

// Enum representing protocol type of a web request.
enum WebRequestProtocolType {
  kHttpHttps = 0,
  kWebSocket = 1,
};

// Enum representing contact initiator type of an extension web request.
enum WebRequestContactInitiatorType {
  kExtension = 0,
  kContentScript = 1,
};

// Interface to send extension web request data from the renderer to the
// browser.
interface ExtensionWebRequestReporter {
  // Send the url contacted and connect protocol type from an extension web
  // request.
  //
  // |origin_extension_id| is the id of the extension that initiated the web
  // request. Only safe to use for telemetry purposes. Untrustworthy to use
  // otherwise.
  // |telemetry_url| indictates the host contacted. Only safe to use for
  // telemetry purposes. Untrustworthy to use otherwise.
  SendWebRequestData(string origin_extension_id,
                     url.mojom.Url telemetry_url,
                     WebRequestProtocolType protocol_type,
                     WebRequestContactInitiatorType contact_initiator_type);

  // Bind an additional pipe to this instance of the ExtensionWebRequestReporter
  // interface.
  Clone(pending_receiver<ExtensionWebRequestReporter> receiver);
};