tools/traffic_annotation/traffic_annotation.proto - chromium/src - Git at Google

 // 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/network_traffic_annotations.md" 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;

     // 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 {
     // 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.
       UNSPECIFIED = 0;
       // 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. 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.
       WEBSITE = 1;
       // A Google owned service, like SafeBrowsing, spellchecking, ...
       GOOGLE_OWNED_SERVICE = 2;
       // 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.
       UNSPECIFIED = 0;
       // 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 =
       2;
 };
	// 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/network_traffic_annotations.md" 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;

	// 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 {
	// 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.
	UNSPECIFIED = 0;
	// 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. 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.
	WEBSITE = 1;
	// A Google owned service, like SafeBrowsing, spellchecking, ...
	GOOGLE_OWNED_SERVICE = 2;
	// 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.
	UNSPECIFIED = 0;
	// 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 =
	2;
	};