dependencies: initial external dependency policy. (#12952)

This will apply to all changes to external dependencies in future PRs.

Part of #10471

Signed-off-by: Harvey Tuch <[email protected]>

DEPENDENCY_POLICY.md

@@ -0,0 +1,103 @@
+# Envoy External Dependency Policy
+
+Envoy has an evolving policy on external dependencies, tracked at
+https://github.com/envoyproxy/envoy/issues/10471. This will become stricter over time, below we
+detail the policy as it currently applies.
+
+## External dependencies dashboard
+
+The list of external dependencies in Envoy with their current version is available at
+https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/security/external_deps
+
+## Declaring external dependencies
+
+In general, all external dependencies for the Envoy proxy binary build and test should be declared
+in either [bazel/repository_locations.bzl](bazel/repository_locations.bzl) or
+[api/bazel/repository_locations.bzl](api/bazel/repository_locations.bzl), unless listed under
+[policy exceptions](#policy-exceptions).
+
+An example entry for the `nghttp2` dependency is:
+
+```python
+com_github_nghttp2_nghttp2 = dict(
+    project_name = "Nghttp2",
+    project_url = "https://nghttp2.org",
+    version = "1.41.0",
+    sha256 = "eacc6f0f8543583ecd659faf0a3f906ed03826f1d4157b536b4b385fe47c5bb8",
+    strip_prefix = "nghttp2-{version}",
+    urls = ["https://github.com/nghttp2/nghttp2/releases/download/v{version}/nghttp2-{version}.tar.gz"],
+    use_category = ["dataplane"],
+    cpe = "cpe:2.3:a:nghttp2:nghttp2:*",
+),
+```
+
+Dependency declarations must:
+
+* Provide a meaningful project name and URL.
+* State the version in the `version` field. String interpolation should be used in `strip_prefix`
+  and `urls` to reference the version. If you need to reference version `X.Y.Z` as `X_Y_Z`, this
+  may appear in a string as `{underscore_version}`, similarly for `X-Y-Z` you can use
+  `{dash_version}`.
+* Versions should prefer release versions over master branch GitHub SHA tarballs. A comment is
+  necessary if the latter is used. This comment should contain the reason that a non-release
+  version is being used and the YYYY-MM-DD when the last update was performed.
+* Provide accurate entries for `use_category`. Please think carefully about whether there are data
+  or control plane implications of the dependency.
+* CPEs are compulsory for all dependencies that are not purely build/test.
+  [CPEs](https://en.wikipedia.org/wiki/Common_Platform_Enumeration) provide metadata that allow us
+  to correlate with related CVEs in dashboards and other tooling, and also provide a machine
+  consumable join key. You can consult the latest [CPE
+  dictionary](https://nvd.nist.gov/products/cpe) to find a CPE for a dependency.`"N/A"` should only
+  be used if no CPE for the project is available in the CPE database. CPEs should be _versionless_
+  with a `:*` suffix, since the version can be computed from `version`.
+
+When build or test code references Python modules, they should be imported via `pip3_import` in
+[bazel/repositories_extra.bzl](bazel/repositories_extra.bzl). Python modules should not be listed in
+`repository_locations.bzl` entries. `requirements.txt` files for Python dependencies must pin to
+exact versions, e.g. `PyYAML==5.3.1` and ideally also include a [SHA256
+checksum](https://davidwalsh.name/hashin).
+
+Pure developer tooling and documentation builds may reference Python via standalone
+`requirements.txt`, following the above policy.
+
+## New external dependencies
+
+* Any new dependency on the Envoy data or control plane that impacts Envoy core (i.e. is not
+  specific to a single non-core extension) must be cleared with the Envoy security team, please file
+  an issue and tag
+  [@envoyproxy/security-team](https://github.com/orgs/envoyproxy/teams/security-team). While policy
+  is still [evolving](robust_to_untrusted_downstream_and_upstream), criteria that will be used in
+  evaluation include:
+  * Does the project have release versions? How often do releases happen?
+  * Does the project have a security vulnerability disclosure process and contact details?
+  * Does the project have effective governance, e.g. multiple maintainers, a governance policy?
+  * Does the project have a code review culture? Are patches reviewed by independent maintainers
+    prior to merge?
+  * Does the project enable mandatory GitHub 2FA for contributors?
+  * Does the project have evidence of high test coverage, fuzzing, static analysis (e.g. CodeQL),
+    etc.?
+
+* Dependencies for extensions that are tagged as `robust_to_untrusted_downstream` or
+  `robust_to_untrusted_downstream_and_upstream` should be sensitive to the same set of concerns
+  as the core data plane.
+
+## Maintaining existing dependencies
+
+We rely on community volunteers to help track the latest versions of dependencies. On a best effort
+basis:
+
+* Core Envoy dependencies will be updated by the Envoy maintainers/security team.
+
+* Extension [CODEOWNERS](CODEOWNERS) should update extension specific dependencies.
+
+Where possible, we prefer the latest release version for external dependencies, rather than master
+branch GitHub SHA tarballs.
+
+## Policy exceptions
+
+The following dependencies are exempt from the policy:
+
+* Any developer-only facing tooling or the documentation build.
+
+* Transitive build time dependencies, e.g. Go projects vendored into
+  [protoc-gen-validate](https://github.com/envoyproxy/protoc-gen-validate).

EXTENSION_POLICY.md

@@ -33,6 +33,8 @@ The following procedure will be used when proposing new extensions for inclusion
   4. Any extension added via this process becomes a full part of the repository. This means that any
   API breaking changes in the core code will be automatically fixed as part of the normal PR process
   by other contributors.
+  5. Any new dependencies added for this extension must comply with
+  [DEPENDENCY_POLICY.md](DEPENDENCY_POLICY.md), please follow the steps detailed there.
 
 ## Removing existing extensions
 

GOVERNANCE.md

@@ -186,6 +186,11 @@ build confidence in consistent application of the API guidelines to PRs.
 Adding new [extensions](REPO_LAYOUT.md#sourceextensions-layout) has a dedicated policy. Please
 see [this](./EXTENSION_POLICY.md) document for more information.
 
+# Exernal dependency policy
+
+Adding new external dependencies has a dedicated policy. Please see [this](DEPENDENCY_POLICY.md)
+document for more information.
+
 # Conflict resolution and voting
 
 In general, we prefer that technical issues and maintainer membership are amicably worked out