1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
|
# 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
```
## Testing Changes to auditor.py
Unit tests need to be run manually:
```
vpython3 tools/traffic_annotation/scripts/auditor/auditor_test.py
```
|
