Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

network-traffic-annotations

/network-traffic-annotations

Prowadzi przez pisanie i zarządzanie Network Traffic Annotations w Chromium przy dodawaniu lub zmianie kodu wykonującego żądania sieciowe.

Repozytorium
chromium ↗
Licencja
BSD-3-Clause
Ostatnia zmiana repozytorium
25.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 25.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

BSD-3-Clause, otwarta.

Co robi i kiedy

Prowadzi przez pisanie i zarządzanie Network Traffic Annotations w Chromium przy dodawaniu lub zmianie kodu wykonującego żądania sieciowe.

Oryginalny opis (EN)

Guide for writing and managing Network Traffic Annotations in Chromium. Use this skill when adding or updating code that makes network requests.

Jak działa

  1. Where to add
  2. Authoring Process
  3. Annotation Tag Content
  4. Template
  5. Running the Auditor
Sekcje z nagłówków SKILL.md, w oryginale · 187 linii, 873 słów
Podgląd SKILL.md
---
name: network-traffic-annotations
description: Guide for writing and managing Network Traffic Annotations in Chromium. Use this skill when adding or updating code that makes network requests.
---

# 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:

1. The origin of the user’s intent or internal requirement is stated.
2. The controls (settings or policies) to stop or limit the request are
   enforced.
3. The data being sent is specified.

## Authoring Process

When adding a network annotation, you MUST follow these steps in sequence:

1. Verify pre-conditions.
2. Give the user an overview of the process.
3. 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.
4. Explicitly ask the user to verify the accuracy of annotation's content.
5. Write the annotation based on the requirements you've gathered
6. Run the `auditor.py` script
7. 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_SERVICE` for Google endpoints
  - `WEBSITE` for a website the user is visiting
  - `OTHER` for any other endpoint
    - If you use `OTHER`, explain it in the `destination_other` string field.
- **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. `contacts` is a
  repeated field.
- **last_reviewed**: Date of last review in `YYYY-MM-DD` format. Use today's
  date, e.g. using the `date` command.

### Essential Policy Fields

- **cookies_allowed**: `YES` or `NO`.
- **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 { ... }` so `auditor.py` can parse them. You can find
  policy definitions in `components/policy/resources/templates/policies.yaml`
  and `components/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

```cpp
  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`.

```bash
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.py` locally.
- 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.

```xml
 <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.
Pliki w paczce (2)
  • OWNERS 1 KB
  • SKILL.md 6 KB

Wersje

W bazie nie ma innych skilli o nazwie network-traffic-annotations.

Migawka bazy z 13.11.2026 · wersja paczki 1896166732b2 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100android-test-batching
    Audytuje i stosuje adnotacje wsadowe i reguły AutoReset do testów Java w Chromium, przy optymalizacji czasu instrumentacji i wycieków stanu testów.
  • 100network-latency-tester
    Prawdopodobnie testuje opóźnienia sieciowe w ramach testów wydajnościowych i uruchamia się automatycznie przy pisaniu lub uruchamianiu testów.
  • 100network
    Podstawia odpowiedzi, przepisuje wychodzące żądania, blokuje adresy URL i nagrywa HAR przez chrome-use network route, np. do stubowania API lub przekierowania na staging.
  • 90histograms
    Zarządza metadanymi histogramów i enumów Chromium przy dodawaniu kodu logującego histogram lub aktualizacji histograms.xml i enums.xml.
  • 100electron-chromium-upgrade
    Prowadzi przy aktualizacji wersji Chromium w projekcie Electron: stosowanie i rozwiązywanie konfliktów patchy oraz analizę zmian w Chromium.
  • 98realbrowser
    Steruje lokalną przeglądarką Chrome lub Chromium: karty, zrzuty ekranu, logi konsoli i rejestrowanie ruchu sieciowego.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.