0

Update docs/network_traffic_annotations.md

Updates docs/network_traffic_annotations.md

Bug: 656607
Change-Id: Ib9381a89f0458bbb99134a976ea96fdad12a3959
Reviewed-on: https://chromium-review.googlesource.com/966222
Commit-Queue: Ramin Halavati <rhalavati@chromium.org>
Reviewed-by: Martin Šrámek <msramek@chromium.org>
Cr-Commit-Position: refs/heads/master@{#548687}
This commit is contained in:
Ramin Halavati
2018-04-06 05:44:38 +00:00
committed by Commit Bot
parent 118ff98495
commit 6c1526e363

@ -13,8 +13,8 @@ provide the following answers:
* What is the intent behind each network request?
* What user data is sent in the request, and where does it go?
Besides these requirements, the following information helps Enterprise admins
and help desk:
Besides these requirements, the following information helps users, admins, and
help desk:
* How can a network communication be stopped or controlled?
* What are the traces of the communication on the client?
@ -60,17 +60,19 @@ into one connection, like when a socket merges several data frames and sends
them together, or a device location is requested by different components, and
just one network request is made to fetch it. In these cases, the merge point
can ensure that all received requests are properly annotated and just pass one
of them to the downstream step.
of them to the downstream step. It can also pass a local annotation stating that
it is a merged request on behalf of other requests of type X, which were ensured
to all have annotations.
This decision is driven from the fact that we do not need to transmit the
annotation metadata in runtime and enforced annotation arguments are just to
ensure that the request is annotated somewhere upstream.
## Coverage
Network traffic annotations are currently enforced on all url requests in
Windows and Linux, and are expanding to sockets and native API functions in
2017,Q4 - 2018,Q1.
Currently there is no plan to expand the task to other platforms.
Network traffic annotations are currently enforced on all url requests and
socket writes, except for the code which is not compiled on Windows or Linux.
This effort may expand to ChromeOS in future and currently there is no plan to
expand it to other platforms.
## Network Traffic Annotation Tag
@ -97,7 +99,7 @@ Each network traffic annotation should specify the following items:
network requests content and reason.
* `sender`: What component triggers the request. The components should be
human readable and dont need to reflect the components/ directory. Avoid
abbreviations.
abbreviations, and use a common value for all annotations in one component.
* `description`: Plaintext description of the network request in language
that is understandable by admins (ideally also users). Please avoid
acronyms and describe the feature and the feature's value proposition as
@ -284,31 +286,38 @@ change list. These checks include:
* Unique ids are unique, through history (even if an annotation gets deprecated,
its unique id cannot be reused to keep the stats sound).
To do these tests, traffic_annotation_auditor binary runs over the whole
repository and using a clang tool, checks if all above items are correct.
Running the `traffic_annotation_auditor` requires exiting a compiled build
directory and can be done with the following syntax.
`tools/traffic_annotation/bin/[linux64/windows32/mac]/traffic_annotation_auditor
### Presubmit tests
To perform tests prior to submit, one can use traffic_annotation_auditor binary.
It runs over the whole repository and using a clang tool, checks if all above
items are correct.
Running the `traffic_annotation_auditor` requires having a COMPLETE compiled
build directory and can be done with the following syntax.
`tools/traffic_annotation/bin/[linux64/win32]/traffic_annotation_auditor
--build-path=[out/Default]`
If you are running the auditor on Windows, please refer to extra instructions in
`tools/traffic_annotation/auditor/README.md`.
The latest executable of `traffic_annotation_auditor` for supported platforms
can be found in `tools/traffic_annotation/bin/[platform]`.
As this test is slow, it is not a mandatory step of the presubmit checks on
clients, and one can run it manually. The test is done on trybots as a commit
queue step.
clients, and one can run it manually.
### Waterfall tests
Two commit queue trybots test traffic annotations on changed files using the
scripts in `tools/traffic_annotation/scripts`. To run these tests faster and to
avoid spamming the commit queue if an unforeseen error has happed in downstream
scripts or tools, they are run in error resilient mode, only on changed files,
and using heuristics to decide which files to process.
An FYI bot runs more detailed tests on the whole repository and with different
switches, to make sure that the heuristics that trybot tests use and the limited
scope of tests have not neglected any issues.
## Annotations Review
Network traffic annotations require review by privacy, enterprise, and legal
teams. To shorten the process of review, only privacy review is a blocking step
and review by the other two teams will be done after code submission.
Privacy reviews are enforced through keeping a summary of annotations in
`tools/traffic_annotation/summary/annotations.xml`, which is owned by privacy
team. Once a new annotation is added, one is updated, or deleted, this file
Network traffic annotations require review before landing in code and this is
enforced through keeping a summary of annotations in
`tools/traffic_annotation/summary/annotations.xml`.
Once a new annotation is added, one is updated, or deleted, this file
should also be updated. To update the file automatically, one can run
`traffic_annotation_auditor` as specified in above step. But if it is not
`traffic_annotation_auditor` as specified in presubmit tests. But if it is not
possible to do so (e.g., if you are changing the code from an unsupported
platform or you dont have a compiled build directory), the code can be
submitted to the trybot and the test on trybot will tell you the required