| # 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 maintanance. 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 maintanance. |
| |
| # 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 platfroms. |
| 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. |
