security: document threat model.

[htuch]

• Add an explicit threat model to the end user facing docs, link to this from SECURITY.md

• Switch all Envoy extensions to use a new macro envoy_cc_extension, mandating that extensions declare a security posture. Extensions can also optionally declare alpha or wip status.

• Tag all documentation sites with their well-known Envoy names.

• Introduce tooling to automagically populate a list of known trusted/untrusted extensions in the threat model docs.

• Generate API docs for extensions that depend on google.protobuf.Empty. This pattern is deprecated as per Per-extension empty message configs #8933, but we need these for tooling support meanwhile.

This work was motivated by oss-fuzz issue https://bugs.chromium.org/p/oss-fuzz/issues/detail?id=18370

Signed-off-by: Harvey Tuch htuch@google.com

[htuch]

@envoyproxy/security-team for consideration.

[mattklein123]

Awesome, LGTM w/ some small comments.

/wait

[mattklein123]

In general, +1 on this approach. With the bazel tagging can we feed that into the docs somehow? WDYT? Amazing stuff.

[repokitteh-read-only]

CC @envoyproxy/api-shepherds: Your approval is needed for changes made to api/.

🐱

Caused by: #8906 was synchronize by htuch.

see: more, trace.

[htuch]

This is now updated with the plumbing for generating docs from envoy_cc_extension attributes. I had an initial attempt at classifying the extension, some are still unknown, I think these would all benefit from additional eyes. Thanks.

[mattklein123]

Super amazing work. So amazing! Flushing out some comments now before I run to a meeting. Will look at the rendered docs later.

[mattklein123]

@lizan @PiotrSikora I think Istio uses this?

[mattklein123]

@htuch looking at the rendered docs can you alpha sort the output of each security posture section?

[mattklein123]

Some random notes from looking at the docs:

1. Is envoy.transport_sockets.alts really robust to downstream and upstream? How have we validated that?
2. kafka/xray show up on the threat model page with no links. Can they be excluded?
3. On the detailed page for each extension, can the thread model and production readiness level be somehow called out via an attention box or similar?
4. (Wish) on the threat model page, can it say something like "(alpha)" if an extension is alpha quality?
5. I think all the tracers need to be robust to downstream similar to loggers?

Amazing stuff.

/wait

[mattklein123]

I think this is used in production now? @lizan @qiwzhang? If so and this is still using alpha protos can we promote to non-alpha?

[htuch]

@marcomagdy @easy are you willing to call the X-ray and OpenCensus tracers (respectively) as hardened to edge traffic (i.e. untrusted downstreams)?

[htuch]

@mattklein123 re: the ALTS robustness, my assumption is that any transport socket is largely symmetrical, as (with some minor configuration differences usually) it can be dropped into downstream or upstream configuration.

[htuch]

@PiotrSikora @lizan @qiwzhang can you folks please address @mattklein123 's questions in the threads above? We'd like to land the threat modeling for Envoy.

[marcomagdy]

... are you willing to call the X-ray and OpenCensus tracers (respectively) as hardened to edge traffic (i.e. untrusted downstreams)?

@htuch I think that makes sense for X-Ray since it consumes HTTP headers only which have gone through Envoy's core already.
Let me know if I should be thinking of particular scenarios or attack vectors.

[mattklein123]

Awesome work, let's ship and iterate.