Protobuf for Traffic Annotation and first use by a URLFetcher.

tools/traffic_annotation/traffic_annotation.proto

+// Copyright 2017 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 traffic_annotation;
+
+import "components/policy/cloud_policy_full_runtime.proto";
+
+// Describes a specific kind of network traffic based on a fine-grained
+// semantic classification of all network traffic generated by Chrome.
+// Used for auditing purposes.
+message NetworkTrafficAnnotation {
+  // This is a globally unique identifier that must stay unchanged while the
+  // network request carries the same semantic meaning. If the network request
+  // gets a new meaning, this ID needs to be changed.
+  // The purpose of this ID is to give humans a chance to reference
+  // NetworkTrafficAnnotations externally even when those change a little bit
+  // (e.g. adding a new piece of data that is sent along with a network
+  // request).
+  // IDs of one component should have a shared prefix so that sorting all
+  // NetworkTrafficAnnotations by unique_id groups those that belong to the same
+  // component together.
+  // For example:
+  //   "spellchecker_lookup"
+  string unique_id = 1;
+
+  // Encapsulates information about the code location that generates this kind
+  // of network traffic.
+  message TrafficSource {
+    // File name where the network request is triggered.
+    // This is typically filled by the extractor and does not need to be
+    // specified in the source code. For manual whitelisting this needs to be
+    // specified.
+    string file = 1;
+
+    // Function name where the network request is instantiated.
+    // This is typically filled by the extractor and does not need to be
+    // specified in the source code. For manual whitelisting this needs to be
+    // specified.
+    string function = 2;
+
+    // __LINE__ in file, where the AuditPolicy object is instantiated.
+    // This is typically filled by the extractor and does not need to be
+    // specified in the source code.
+    // For whitelisted network requests in third_party/ that cannot be properly
+    // annotated in the source code, this attribute is empty.
+    int32 line = 3;
+
+    // For whitelisted network requests in third_party/ that cannot be properly
+    // annotated in the source code, this distinguishes between the first,
+    // second, ... annotated call.
+    // For annotations in the source code, this is not used because the line
+    // attribute uniquely identifies the network request.
+    int32 call_number = 4;
+  }
+
+  TrafficSource source = 2;
+
+  // Meta information about the network request.
+  message TrafficSemantics {
+    // Justification for an empty AuditPolicy policy.
+    // Typically this can be either a TODO or a hint that the annotation is
+    // made upstream in the code. For example, if net::URLFetcher::Create() has
+    // an annotation, the net::TCPClientSocket() that is used by the URLFetcher
+    // does not need to be annotated as well.
+    string empty_policy_justification = 1;
+
+    // What component triggers the request. The components should be human
+    // readable and don’t need to reflect the components/ directory. Avoid
+    // abbreviations.
+    // Examples: spellchecker, component updater, website
+    string sender = 2;
+
+    // Plaintext description of the network request in language that is
+    // understandable by admins (ideally also users). Please avoid acronyms.
+    // Please describe the feature and the feature's value proposition as well.
+    // Examples:
+    // - Google Chrome can provide smarter spell-checking by sending text you
+    //   type into the browser to Google's servers, allowing you to use the same
+    //   spell-checking technology used by Google products, such as Docs.
+    //   If the feature is enabled, Chrome will send the entire contents of text
+    //   fields as you type in them to Google along with the browser’s default
+    //   language. Google returns a list of suggested spellings, which will be
+    //   displayed in the context menu.
+    // - A network request that comes from web content (a page the user visits)
+    string description = 3;
+
+    // What triggered the network request. Use a textual description. This
+    // should be a human readable string.
+    // For things that are clearly part of the website (resource load, form
+    // submission, fetch by a service worker,...), you *may* just put “website”
+    // here.
+    string trigger = 4;
+
+    // What nature of data is being sent. This should be a human readable
+    // string. Any user data and/or PII should be pointed out.
+    // Examples: “log files from /var/...”, “statistics about foobar”, “the
+    // signature of a form of a website”, “installed extensions and their
+    // version”, “a word on a website the user tapped on”
+    string data = 5;
+
+    enum Destination {
+      // A website the user visits or interacts with. The distinction from a
+      // google owned service can be difficult when the user navigates to
+      // google.com or searches with the omnibar. Therefore follow the following
+      // guideline: If the source code has hardcoded that the request goes to
+      // Google (e.g. for ZeroSuggest), use GOOGLE_OWNED_SERVICE. If the request
+      // can go to other domains and is perceived as a part of a website rather
+      // than a native browser feature, use WEBSITE. In other cases use OTHER.
+      WEBSITE = 0;
+      // A Google owned service, like SafeBrowsing, spellchecking, ...
+      GOOGLE_OWNED_SERVICE = 1;
+      // Other endpoints, e.g. a service hosting a PAC script. In case of doubt,
+      // use this category. We will audit it in the future to see whether we
+      // need more categories.
+      OTHER = 1000;
+    }
+    Destination destination = 6;
+
+    // Human readable description in case the destination points to OTHER.
+    string destination_other = 7;
+  }
+
+  TrafficSemantics semantics = 3;
+
+  message TrafficPolicy {
+    // Whether cookies/channel IDs/... can be sent or saved (use true if at
+    // least one is correct).
+    bool cookies_allowed = 1;
+
+    // If a request sends or stores cookies/channel IDs/... (i.e. if
+    // cookies_allowed is true), we want to know which cookie store is being
+    // used. The answer to this question can typically be derived from the
+    // URLRequestContext that is being used.
+    // The three most common cases will be:
+    // - If cookies_allowed is false, leave this field unset.
+    // - If the profile's default URLRequestContext is being used (e.g. from
+    //   Profile::GetRequestContext()), this means that the user's normal
+    //   cookies are sent. In this case, put "user" here.
+    // - If the system URLRequestContext is being used (for example via
+    //   io_thread()->system_url_request_context_getter()), put "system" here.
+    // Otherwise, please explain (e.g. SafeBrowsing uses a separate cookie
+    // store).
+    string cookies_store = 2;
+
+    // Human readable description of how to enable/disable a feature that
+    // triggers this network request by a user. Use “NA”, if no such setting
+    // exists (e.g. “Disable ‘Use a web service to help resolve spelling
+    // errors.’ in Chrome’s settings under Advanced”).
+    string setting = 3;
+
+    // Example policy configuration that disables this network request.
+    // This would be a text serialized protobuf of any enterprise policy.
+    // see out/Debug/gen/components/policy/cloud_policy.proto
+    repeated enterprise_management.CloudPolicySettings policy = 4;
+
+    // Justification for not having a policy that disables this feature.
+    string policy_exception_justification = 5;
+  }
+
+  TrafficPolicy policy = 4;
+};
+
+// NetworkTrafficAnnotations that were extracted from the source code.
+message ExtractedNetworkTrafficAnnotation {
+  repeated NetworkTrafficAnnotation network_traffic_annotation = 1;
+};
+
+// NetworkTrafficAnnotations that had to go into a whitelist file because the
+// source code could not be annotated (e.g. because it is in a third-party
+// library).
+message WhitelistedNetworkTrafficAnnotations {
+  repeated NetworkTrafficAnnotation network_traffic_annotation = 1;
+};
+
+// All NetworkTrafficAnnotations from a Chromium configuration.
+message NetworkTrafficAnnotations {
+  ExtractedNetworkTrafficAnnotation extracted_network_traffic_annotations = 1;
+  WhitelistedNetworkTrafficAnnotations whitelisted_network_traffic_annotations =
+      2;
+};