Google Git
Sign in
chromium / chromium / src / refs/heads/main / . / tools / traffic_annotation / scripts / auditor
tree: 438e97c83714c1fb2fa4e23fc0983ac746b0c579 [path history] [tgz]
  1. __init__.py
  2. auditor.py
  3. auditor_test.py
  4. error.py
  5. hashes.py
  6. README.md
  7. util.py
tools/traffic_annotation/scripts/auditor/README.md

Network Traffic Annotation Auditor

This script runs extractor.py to extract Network Traffic Annotations from chromium source code, collects and summarizes its outputs, and performs tests and maintenance.

Please see docs/network_traffic_annotations.md for an introduction to network traffic annotations.

Before Running

Before running, you need to build the traffic_annotation_proto target, and pass the build path to the executable. For instance:

$ autoninja -C out/Debug traffic_annotation_proto
$ vpython3 ./tools/traffic_annotation/scripts/auditor/auditor.py --build-path=out/Debug

traffic_annotation_proto is a dependency of the chrome target, as well. So if you regularly use this build directory for development, you can probably skip the first step.

Usage

vpython3 ./tools/traffic_annotation/scripts/auditor/auditor.py [OPTIONS]... [path_filter]...

Extracts network traffic annotations from source files, tests them, and updates tools/traffic_annotation/summary/annotations.xml. If path filter(s) are specified, only those directories of the source will be analyzed. Run ./tools/traffic_annotation/scripts/auditor/auditor.py --help for options.

Example: vpython3 ./tools/traffic_annotation/scripts/auditor/auditor.py --build-path=out/Debug

Safe List

If there are files, paths, or specific functions that need to be exempted from all or some tests, they can be added to the safe_list.txt. The file is comma separated, specifying the safe lists based on ExceptionType in auditor.py.

Use * as wildcard for zero or more characters when specifying file paths.

Here are the exception types:

  • all: Files and paths in this category are exempted from all tests.
  • missing: Files and paths in this category can use the MISSING_TRAFFIC_ANNOTATION tag.
  • mutable_tag: Files and paths in this category can use the CreateMutableNetworkTrafficAnnotationTag() function.
  • test_annotation: Files and paths in this category can use the TRAFFIC_ANNOTATION_FOR_TESTS tag.
  • missing_new_fields: If none of internal::contacts::email, user_data::type and last_reviewed fields are populated then file and paths in this category are exempted getting validated.

hashes.py

In logs from chrome://net-export, there is a traffic_annotation field, which contains the *hash code of the network annotation. Since this hash code is not recorded in annotations.xml, it is non-trivial to map it to its annotation.

Running this scripts print a list of all annotations from annotations.xml, along with their hash codes. This makes it easier to look up the annotation.

vpython3 ./tools/traffic_annotation/scripts/auditor/hashes.py