|
| 1 | + .. Licensed to the Apache Software Foundation (ASF) under one |
| 2 | + or more contributor license agreements. See the NOTICE file |
| 3 | + distributed with this work for additional information |
| 4 | + regarding copyright ownership. The ASF licenses this file |
| 5 | + to you under the Apache License, Version 2.0 (the |
| 6 | + "License"); you may not use this file except in compliance |
| 7 | + with the License. You may obtain a copy of the License at |
| 8 | +
|
| 9 | + .. http://www.apache.org/licenses/LICENSE-2.0 |
| 10 | +
|
| 11 | + .. Unless required by applicable law or agreed to in writing, |
| 12 | + software distributed under the License is distributed on an |
| 13 | + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 14 | + KIND, either express or implied. See the License for the |
| 15 | + specific language governing permissions and limitations |
| 16 | + under the License. |
| 17 | +
|
| 18 | +Vulnerabilities in 3rd party dependencies |
| 19 | +========================================= |
| 20 | + |
| 21 | +How users should treat 3rd-party dependencies with known CVEs |
| 22 | +------------------------------------------------------------- |
| 23 | + |
| 24 | +Apache Airflow has a rather large number of dependencies, and we invest a lot of effort to keep Airflow updated |
| 25 | +to latest versions of those dependencies. We have automation, that checks for new versions of dependencies, |
| 26 | +and attempts to upgrade and test them automatically, we also have security scans that indicate if we have |
| 27 | +minimum versions of dependencies, that are not vulnerable to known, important, exploitable CVEs. Every |
| 28 | +version of Airflow has a set of constraints - i.e. latest tested versions of dependencies, that |
| 29 | +are passing our tests and that we know allow to install Airflow and it's providers together. |
| 30 | + |
| 31 | +However - due to sometimes complex dependency trees and sometimes conflicting requirements, we are not |
| 32 | +always able to upgrade and test dependencies to the latest versions. Sometimes we can only upgrade to newer |
| 33 | +versions of dependencies in the "development" branch - i.e. for the next "MINOR" version of Airflow, |
| 34 | +and we are not able to backport those upgrades to the latest released "MINOR" version of Airflow. |
| 35 | + |
| 36 | +This means that sometimes we have to keep older versions of dependencies in the latest released "MINOR" |
| 37 | +version of Airflow, even if those versions are vulnerable to some CVEs. Since Airflow is a volunteer-driven |
| 38 | +project, we do not provide any guarantees that we will upgrade to dependencies that are CVE-free. |
| 39 | + |
| 40 | +Contrary to a common belief, the presence of a CVE in a 3rd-party dependency does not automatically mean |
| 41 | +that Airflow or your deployment - and we do not accept reports and issues stating that we **should upgrade** |
| 42 | +those because they have a known CVE. We need to have a proof that the CVE is exploitable in Airflow |
| 43 | +and that it can be used to attack Airflow or your deployment and such proofs should be responsibly |
| 44 | +disclosed to us, in private, following our `Security policy <https://github.com/apache/airflow/security/policy>`_. |
| 45 | +If you have such proof, please share it with us and we will do our best to upgrade the dependency |
| 46 | +to a non-vulnerable version as soon as possible and back-port it to latest released minor version, |
| 47 | +following our :doc:`releasing_security_patches` policy. We expect our commercial users who need to fulfill |
| 48 | +their obligation to manage and disclose CVEs in their environment to invest time and effort into |
| 49 | +responsible disclosure, and investment of their security teams if they think Airflow is vulnerable to |
| 50 | +third-party CVEs. |
| 51 | + |
| 52 | +This general approach is described in the `Apache Software Foundation's approach <https://security.apache.org/report-dependency/>`_. |
| 53 | +This document provides more detailed instructions that are specific to Apache Airflow. |
| 54 | + |
| 55 | +Constraints in released airflow versions |
| 56 | +---------------------------------------- |
| 57 | + |
| 58 | +The constraints we publish for released versions of Airflow are the latest tested versions of dependencies, |
| 59 | +that we know worked with Airflow at the time of release. However, in many cases, if there are newer versions |
| 60 | +of those dependencies released later, they have a chance to work with Airflow as well, as we usually do not |
| 61 | +upper-bind those dependencies and you should be able to test and upgrade to newer versions even if the |
| 62 | +constraint files have an earlier version of the dependency. |
| 63 | + |
| 64 | +We almost never (except in very exceptional cases which do not allow users to use constraints to install |
| 65 | +airflow) update those constraint files after specific version of Airflow is released, and we do not re-publish |
| 66 | +Airflow reference container images with updated dependencies, so users are on their own to update selected |
| 67 | +dependencies if they want to, and test if they work with Airflow. What you can do in case your scans |
| 68 | +show some CVEs that you need to update is described in :ref:`docker-stack:fixing-image-at-release-time`. |
| 69 | + |
| 70 | +The easiest way to get latest, CVE-free dependencies is to upgrade to the latest released version |
| 71 | +of Airflow and keep doing it frequently as we release, this will make it overall easier for the users |
| 72 | +to handle the upgrade process when they do it incrementally and more often, rather than jump a number |
| 73 | +of versions at once. |
| 74 | + |
| 75 | +What you do if you detect a CVE in a 3rd-party dependency |
| 76 | +--------------------------------------------------------- |
| 77 | + |
| 78 | +There is a chance that you are using some scans that will show you CVE in a 3rd-party dependency that is |
| 79 | +used by Airflow and you would like to get rid of those. There are a few things you can do in such case: |
| 80 | + |
| 81 | +* First of all - resist an urge to open a public issue - especially if you have no idea if Airflow and your |
| 82 | + deployment is impacted. Such issues will be usually closed with reference to this document and you |
| 83 | + will be expected to follow it. |
| 84 | + |
| 85 | +* Check if you can upgrade yourself to the newer version of dependency that is not vulnerable to the CVE, and |
| 86 | + test if it works with Airflow. If it does, you can use it in your deployment even if the constraints for |
| 87 | + your version of Airflow show an older version of the dependency. Feel free to start a public discussion (in |
| 88 | + `GitHub Discussions <https://github.com/apache/airflow/discussions>`_ ) in "Show and Tell" section where |
| 89 | + you will share it with others and encourage them to do the same if you successfully tested and upgraded the |
| 90 | + dependency. That helps other community members to be more confident about upgrading and might make them |
| 91 | + aware of some of 3rd-party vulnerabilities that they were not aware of. |
| 92 | + |
| 93 | +* In case your version of Airflow or some of it's providers, prevent you from upgrading to a non-vulnerable version of the |
| 94 | + dependency, you can see if latest versions of Airflow or providers removed any limitations - you can check |
| 95 | + constraint files and :doc:`sbom` we publish for all Airflow versions (industry-standard way of capturing |
| 96 | + inventory of dependencies). If you see that you can upgrade, upgrade - ideally - to latest versions of |
| 97 | + Airflow and providers, but if you cannot - upgrade to the latest version that allows you to upgrade the |
| 98 | + dependency to a non-vulnerable version. Again, if you successfully do it, please share your experience in |
| 99 | + GitHub Discussions. |
| 100 | + |
| 101 | +* Check if the dependency that you have problem with is already upgraded in the ``main`` branch of Airflow - |
| 102 | + `Main constraints <https://github.com/apache/airflow/tree/constraints-main>`_. If it is, this means that |
| 103 | + the dependency will be upgraded in the next "MINOR" version of Airflow, and you can prepare for the upgrade |
| 104 | + by testing the "main" branch with the newer version of the dependency, participate in the release candidate. |
| 105 | + testing that is announced at airflow Dev list (see `Community page <https://airflow.apache.org/community/>`_ |
| 106 | + for instructions on how you can subscribe. Helping to test such release candidates and testing upgrade |
| 107 | + process is by far the fastest way to speed up the process of releasing the next "MINOR" version of Airflow |
| 108 | + with the non-vulnerable version of the dependency. Also contributing to such release in general is a |
| 109 | + great way to give back to the community and help it to grow and speed up such release process. Also |
| 110 | + check related changes and see if the change that allowed it is already back-ported to the latest released |
| 111 | + "MINOR" version of Airflow and planned for the next "PATCHLEVEL" release (such PR will have future |
| 112 | + "PATCHLEVEL" version assigned as milestone, and the dependency should be upgraded in the constraints file |
| 113 | + for that version (For example 3.1.* versions has latest constraint files in the |
| 114 | + `3-1 constraints <https://github.com/apache/airflow/tree/constraints-3-1>`_ ). |
| 115 | + |
| 116 | +* If such dependency change is not yet back-ported to the latest released "MINOR" version of Airflow, but you want |
| 117 | + to help with it - we recommend you to open PR to the ``v3-N-test`` branch - it can usually be done following |
| 118 | + the cherry-pick process described in the |
| 119 | + `Developer documentation <https://github.com/apache/airflow/blob/main/dev/README_AIRFLOW3_DEV.md#merging-prs-targeted-for-airflow-3x>`_ |
| 120 | + Note, that we never back-port things to older "MINOR" versions of Airflow, so if the commit is not |
| 121 | + back-ported to the latest released "MINOR" version of Airflow, it will not be back-ported to any |
| 122 | + older "MINOR" version of Airflow. |
| 123 | + |
| 124 | +* If you really want to upgrade to a non-vulnerable version of the dependency and cannot provide a Proof Of |
| 125 | + Concept showing that Airflow is affected, and you cannot see it in latest versions of Airflow - you can |
| 126 | + attempt to investigate the issue yourself and prepare a PR that will allow airflow to upgrade to the |
| 127 | + new dependency. Avoid mentioning that the reason for the upgrade is a CVE, as we do not want to have public |
| 128 | + discussions about CVEs that are not proven to be exploitable in Airflow. Instead, you can just say that you |
| 129 | + want to upgrade to a newer version of the dependency and you want to share it with others in case |
| 130 | + they want to do the same. This can be a contribution to Airflow or to the dependency or even to other |
| 131 | + dependencies. Airflow contributors have a good tool that checks why specific dependency cannot be upgraded |
| 132 | + and it provides a ``uv`` resolution track that you can analyse to understand which dependencies are |
| 133 | + blocking the upgrade, you can start GitHub Discussions showing output of the tool and asking for help from |
| 134 | + maintainers to explain you what needs to be done. |
| 135 | + |
| 136 | + This is how to run the tool (you need to have ``uv`` installed, you can install it with ``pip install uv``): |
| 137 | + |
| 138 | + .. code-block:: bash |
| 139 | +
|
| 140 | + git clone git@github.com:apache/airflow.git |
| 141 | + uv tool install -e ./dev/breeze --force |
| 142 | + breeze release-management constraints-version-check --python 3.10 --package PACKAGE_NAME --explain-why |
| 143 | +
|
| 144 | + Fragment of example output of such tool is shown below - indicating that ``apache-beam`` blocks upgrade of |
| 145 | + ``grpcio`` package to version 1.56.0: |
| 146 | + |
| 147 | + .. image:: ../img/checking_dependencies.png |
| 148 | + :align: center |
| 149 | + :alt: Output of uv tool for ``grpcio`` package upgradability status |
| 150 | + |
| 151 | + Output of that tool is quite technical and is provided by the ``uv`` tool but it shows all the conflicts |
| 152 | + that are preventing the upgrade of the dependency and it can be a good starting point to understand what needs |
| 153 | + to be done to allow the upgrade. Sharing the output in GitHub Discussions can be a good way to get help |
| 154 | + from maintainers and other contributors to understand what needs to be done. |
| 155 | + |
| 156 | +* When you have proofs that Airflow is impacted by the CVE (you need to understand what the issue is about and |
| 157 | + understand how it can be exploited in Airflow and your deployment), you should prepare a Proof Of Concept (PoC) |
| 158 | + showing how the CVE can be exploited, and share it with us in private, following our |
| 159 | + `Security policy <https://github.com/apache/airflow/security/policy>`_. |
0 commit comments