blob: 65bc32b1e80b798a421dca83c22f4e955fd09501 [file] [log] [blame]
// 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;
// chrome_settings_full_runtime.proto is a version of the following proto
// without lite runtime optimization:
// out/Debug/gen/components/policy/proto/chrome_settings.proto
import "chrome_settings_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. Please refer to
// "/docs/" for users guide.
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;
// __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 {
// What component triggers the request. The components should be human
// readable and don’t need to reflect the components/ directory. Avoid
// abbreviations.
// Examples: Online Spellcheck, Safe Browsing, WebView.
string sender = 1;
// 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 = 2;
// 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 = 3;
// 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 = 4;
enum Destination {
// Do not use this value. It's just a placeholder for default value.
// A website the user visits or interacts with. The distinction from a
// google owned service can be difficult when the user navigates to
// 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. Use LOCAL if the request is
// processed locally and does not go to network, otherwise use OTHER. If
// OTHER is used, please add plain text description in 'destination_other'
// tag.
// A Google owned service, like SafeBrowsing, spellchecking, ...
// Does not go to the network and just fetches a resource locally.
LOCAL = 3;
// 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 = 5;
// Human readable description in case the destination points to OTHER.
string destination_other = 6;
TrafficSemantics semantics = 3;
message TrafficPolicy {
enum CookiesAllowed {
// Do not use this value. It's just a placeholder for default value.
// Cookies are never used.
NO = 1;
// Cookies/channel IDs/... can be sent or saved (use if at least one is
// correct).
YES = 2;
CookiesAllowed 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 (e.g. “Disable ‘Use a web service
// to help resolve spelling errors.’ in settings under Advanced”).
string setting = 3;
// Policy configuration(s) that disable or limit this network request.
// This would be a text serialized protobuf of any enterprise policy.
// see out/Debug/gen/components/policy/proto/chrome_settings.proto
repeated enterprise_management.ChromeSettingsProto chrome_policy = 4;
// Justification for not having a policy that disables this feature.
string policy_exception_justification = 5;
TrafficPolicy policy = 4;
// Human readable extra comments, if required.
string comments = 5;
// 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 =