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:

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 request’s content and reason.
|
||||
* `sender`: What component triggers the request. The components should be
|
||||
human readable and don’t 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 don’t have a compiled build directory), the code can be
|
||||
submitted to the trybot and the test on trybot will tell you the required
|
||||
|
Reference in New Issue
Block a user