Network Traffic Annotations
Developmentnetwork-traffic-annotationsNetwork Traffic Annotations is an Agent Skill for development published in the chromium/chromium repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Guide for writing and managing Network Traffic Annotations in Chromium. Use this skill when adding or updating code that makes network requests.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/chromium/chromium/blob/HEAD/agents/skills/network-traffic-annotations/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/network-traffic-annotations, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Network Traffic Annotations
Network traffic annotations provide transparency into Chrome’s network communication by documenting the intent, payload, and control mechanisms of each network request.
Where to add
Add annotations at the most rational point of origin for a request. This is typically where:
- The origin of the user’s intent or internal requirement is stated.
- The controls (settings or policies) to stop or limit the request are enforced.
- The data being sent is specified.
Authoring Process
When adding a network annotation, you MUST follow these steps in sequence:
- Verify pre-conditions.
- Give the user an overview of the process.
- Gather requirements: start by reading the .cc file. Anything you're not sure of, ask the user explicitly and directly. You MUST ask the user for anything you're not sure of.
- Explicitly ask the user to verify the accuracy of annotation's content.
- Write the annotation based on the requirements you've gathered
- Run the
auditor.pyscript - Ask the user to review the contents one last time before they upload it for review.
Annotation Tag Content
Each annotation is defined using
net::DefineNetworkTrafficAnnotation("unique_id", R"(...)"). The second
argument is a text-encoded NetworkTrafficAnnotation protobuffer, as defined in
chrome/browser/privacy/traffic_annotation.proto.
To determine the annotation's contents, start by reading the source code of the file the annotation is in. If you need more information, or you are unsure what to enter for a particular field, you MUST ask the user for more information before proceeding.
Essential Semantics Fields
- sender: The component or feature triggering the request (e.g., "Safe Browsing").
- description: Plaintext explanation of the request and its value proposition. This is meant for a technical audience, but not Chrome/Chromium developers. Avoid obscure or internal code names.
- trigger: The specific user action that triggers the request.
- user_data: The nature of the data being sent (use enums from
chrome/browser/privacy/traffic_annotation.proto). - destination:
GOOGLE_OWNED_SERVICEfor Google endpointsWEBSITEfor a website the user is visitingOTHERfor any other endpoint- If you use
OTHER, explain it in thedestination_otherstring field.
- If you use
- contacts: A list of emails for points-of-contact (individuals, or a team
alias). You MUST ask the user which email they want to use.
contactsis a repeated field. - last_reviewed: Date of last review in
YYYY-MM-DDformat. Use today's date, e.g. using thedatecommand.
Essential Policy Fields
- cookies_allowed:
YESorNO. - setting: How a user can enable/disable the feature in settings. If there is no setting, explain why.
- chrome_policy: The enterprise policy that disables this request, and what
value to use to disable the request. Recently-added policies may need to be
wrapped in
subProto1 { ... }soauditor.pycan parse them. You can find policy definitions incomponents/policy/resources/templates/policies.yamlandcomponents/policy/resources/templates/policy_definitions/. - policy_exception_justification: If no enterprise policy exists to disable this request, explain why.
The traffic annotation MUST contain either chrome_policy or
policy_exception_justification, but not both.
Template
constexpr net::NetworkTrafficAnnotationTag traffic_annotation =
net::DefineNetworkTrafficAnnotation("...", R"(
semantics {
sender: "..."
description: "..."
trigger: "..."
destination: WEBSITE/GOOGLE_OWNED_SERVICE/OTHER
data: "..."
user_data {
type: ...
}
last_reviewed: "YYYY-MM-DD"
internal {
contacts {
email: "..."
}
contacts {
email: "..."
}
}
}
policy {
cookies_allowed: NO/YES
setting: "..."
chrome_policy {
[POLICY_NAME] {
[POLICY_NAME]: ...
}
}
policy_exception_justification: "..."
}
)");
Running the Auditor
After adding or updating an annotation, you MUST verify it using the
auditor.py script. Explain to the user what you're about to do, and why you're
doing it.
2. Build Chrome
You MUST ask the user which directory to use as the build path before proceeding.
Ensure you have a fresh build of the chrome target. For instance with
autoninja -C out/<build_path> chrome, replacing out/<build_path> with the
build path.
3. Run the Auditor
Use the same build_path where you just built chrome.
vpython3 tools/traffic_annotation/scripts/auditor/auditor.py --build-path=out/<build_path>
Pre-conditions
The auditor.py script cannot run under these conditions. If any of these
conditions are true, auditor.py will fail with an explanation of why. If any
of these are tru, you MUST abort immediately and inform the user:
- You are not running inside a Git repository.
- You are not running on Linux or Windows.
If you abort, the user has two options:
- Patch their change into a Git repository (on Linux/Windows), so they can run
auditor.pylocally. - Upload their CL to Gerrit, and do a CQ dry run.
Inform the user of their options, and don't do anything else.
4. Update Summary Files
The auditor will inform you if you need to update
tools/traffic_annotation/summary/annotations.xml or grouping.xml.
5. Update Platform List
For new annotations, auditor.py creates an entry in annotations.xml. The
entry is populated with a "default" list of target platforms, which may or may
not be accurate.
<item id="..." ... os_list="linux,windows,android,chromeos" ... />
Update os_list to match the actual list of target platforms. It should be
based on BUILD.gn files; or, if you can't figure it out from BUILD.gn files, ask
the user directly.
The only valid platforms for os_list are:
- linux
- windows
- chromeos
- android
macOS and iOS are not a valid platforms in this context. If the user mentions macOS or iOS, just ignore it.