// 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.
syntax = "proto3";
package traffic_annotation;
option optimize_for = LITE_RUNTIME;
import "chrome_settings.proto";
import "chrome_device_policy.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;
// __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;
// A proxy that will forward the traffic to a google owned service.
PROXIED_GOOGLE_OWNED_SERVICE = 4;
// 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;
// Data that is meant to be visible internally, example point of contacts,
// should be placed inside internal field.
// This field should not be used in any external reports.
message Internal {
// Point-of-contact for questions, issues, or bugs related to
// this network request.
message Contact {
oneof contact_type {
// Email of a team or individual owner
string email = 1;
// OWNERS file within the chromium codebase
string owners = 2;
}
}
repeated Contact contacts = 1;
}
Internal internal = 7;
// Types of user data sent in this network request
message UserData {
enum UserDataType {
// Placeholder, do not use this value.
UNSPECIFIED = 0;
// Any token that identifies an account or
// requests resources on behalf of a particular user.
// Example: OAuth2 token.
ACCESS_TOKEN = 1;
ADDRESS = 2;
ANDROID_ID = 3;
AGE = 4;
// When a request could contain any arbitrary data,
// to include personal data. Helpful to provide more
// specifics in the description.
ARBITRARY_DATA = 5;
BIRTH_DATE = 6;
CREDENTIALS = 7;
CREDIT_CARD_DATA = 8;
DEVICE_ID = 9;
EMAIL = 10;
FILE_DATA = 11;
GAIA_ID = 12;
GENDER = 13;
GOVERNMENT_ID = 14;
IMAGE = 15;
// Request contains information about the user's location, separate
// from what can be inferred from the IP address.
LOCATION = 17;
NAME = 19;
PHONE = 20;
// Any data synced from a profile like History,
// Bookmarks, Autofill, etc.
PROFILE_DATA = 21;
// Any URL which reveals personal data or information
// about a user's browsing habits, like the URL of a
// website they're visiting/have visited before.
SENSITIVE_URL = 22;
// Any data originating from user input, regardless of the specific form
// (e.g. text fields, search queries, etc.).
USER_CONTENT = 26;
USERNAME = 27;
// Data originating from the content of the current webpage.
WEB_CONTENT = 28;
// Hardware or OS information like Manufacturer, Model, etc.
HW_OS_INFO = 29;
// If a request sends sensitive data/PII that doesn't fall in the
// categories above, use `OTHER` and provide more details in the `data`
// field.
//
// Can be combined with other data types. e.g. the following is valid:
// user_data {
// type: ACCESS_TOKEN
// type: OTHER
// }
OTHER = 999;
// `user_data::type` is mandatory in annotations. Use `NONE` if the
// request doesn't send user data. For instance: fetching a static
// resource from the public web, using a hard-coded URL.
NONE = 1000;
}
repeated UserDataType type = 1;
}
UserData user_data = 8;
// Date when this annotation was last reviewed
// in YYYY-MM-DD format.
string last_reviewed = 9;
}
TrafficSemantics semantics = 3;
// Next tag: 8
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 non-device enterprise
// policy.
// see out/Debug/gen/components/policy/proto/chrome_settings.proto
repeated enterprise_management.ChromeSettingsProto chrome_policy = 4;
// Policy configuration(s) that disable or limit this network request.
// This would be a text serialized protobuf of any device enterprise
// policy. See components/policy/proto/chrome_device_policy.proto.
repeated enterprise_management.ChromeDeviceSettingsProto
chrome_device_policy = 7;
// Justification for not having a policy that disables this feature.
string policy_exception_justification = 5;
// TODO(b/254273300): add deprecated_policies tag in auditor.py
repeated string deprecated_policies = 6;
}
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;
};
Codebase Browser
chromium