Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

dependencies: initial external dependency policy. #12952

Merged
merged 5 commits into from
Sep 9, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 103 additions & 0 deletions DEPENDENCY_POLICY.md
Original file line number Diff line number Diff line change
@@ -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`.

htuch marked this conversation as resolved.
Show resolved Hide resolved
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:
htuch marked this conversation as resolved.
Show resolved Hide resolved

* Core Envoy dependencies will be updated by the Envoy maintainers/security team.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We really only update deps when needed for security reasons correct? Generally if someone wants an upgrade due to some shiny new feature they have done the work and we review. Are you suggesting we change that, or think it's worth clarifying?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we usually update dependencies continuously; @moderation has been responsible for a lot of this, see history at https://github.com/envoyproxy/envoy/commits/master/bazel/repository_locations.bzl.

There has been some high profile upgrades that were not really plausible to do mechanically as they required code changes, e.g. http-parser, but these are more the exception than rule.

I reckon it's better to try and stick with latest release version. The rationale for this is:

  • Many code improvements are made in projects that can impact security that fall below the threshold of CVE.
  • Many projects don't have long-term support branches, e.g. if we were talking Linux kernel, maybe it's fine to live on 4.0.x as you know this will have active support for a significant period of time.
  • For folks who operate monorepos (cough), other projects force dependencies to be brought forward in time.

The downside is we have more churn and less burn time for a given dependency version.


* 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).
2 changes: 2 additions & 0 deletions EXTENSION_POLICY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

htuch marked this conversation as resolved.
Show resolved Hide resolved
Expand Down
5 changes: 5 additions & 0 deletions GOVERNANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,11 @@ the maintainers per the voting process below.
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
Expand Down