tree: 332d52b0a1eae994d905c488a611e8a4e239a9ab [path history] [tgz]
  1. auditor/
  2. bin/
  3. scripts/
  4. summary/
  5. .gitignore
  6. DEPS
  7. OWNERS
  8. README.md
  9. sample_traffic_annotation.cc
  10. traffic_annotation.proto
tools/traffic_annotation/README.md

Network Traffic Annotations

Network traffic annotations provide transparency and auditability for the data that Chrome sends to the network. For an introduction, please see docs/network_traffic_annotations.md. This folder provides tools to ensure that every operation in the code base that requires annotation, is annotated, and annotations are sound and complete.

Traffic Annotation Auditor

This is the main executable for all the tests. It runs Traffic Annotation Extractor clang tool to check the repository, extract annotations, and perform required tests and maintenance. See more details in tools/traffic_annotation/auditor/README.md.

Traffic Annotation Extractor

Traffic Annotation Auditor uses this clang tool (located in tools\clang\traffic_annotation_extractor) to parse the code and extract required data for testing and maintenance.

Building the Checkers

We do not want every developer to have to build clang tool and auditor, and so we store pre-built binaries in a Google Cloud Storage bucket and retrieve them via gclient hooks. The binaries are in tools/traffic_annotation/bin/[platform] folder. To roll new versions of the binaries, please see tools/traffic_annotation/bin/README.md.

Automatic Annotation Tests

Network traffic annotations are tested in commit queue using tools/traffic_annotation/scripts/check_annotations.py. This test is currently run on Linux and Windows trybots, but may expand in future to other platforms. To perform this test fast enough for a trybot and to avoid spamming the commit queue if an unexpected general failure happens (see next item), trybot tests are run in error resilient mode and only on the changed files. A more complete test runs on an FYI bot using tools/traffic_annotation/scripts/traffic_annotation_auditor_tests.py and alerts if tests are not running as expected.

Emergency Brake

In the event that clang changes something that requires the tool to be rebuilt (or for some other reason the tests don‘t work correctly), please disable the trybot test by setting the TEST_IS_ENABLED flag to False in tools/traffic_annotation/scripts/check_annotations.py, and file a bug and cc the people listed in OWNERS; they’ll be on the hook to rebuild and re-enable the test.

Annotations Summary

tools/traffic_annotation/summary/annotations.xml keeps an up to date summary of all annotations in the repository. This file is automatically updated by Traffic Annotation Auditor.