diff --git a/docs/organizations/images/security-risk-management-transitive-chain.png b/docs/organizations/images/security-risk-management-transitive-chain.png new file mode 100644 index 0000000000..deb062baef Binary files /dev/null and b/docs/organizations/images/security-risk-management-transitive-chain.png differ diff --git a/docs/organizations/managing-security-and-risk.md b/docs/organizations/managing-security-and-risk.md index 4d273e845b..ae684f7a7d 100644 --- a/docs/organizations/managing-security-and-risk.md +++ b/docs/organizations/managing-security-and-risk.md @@ -585,6 +585,46 @@ You're also able to click any dependency to find out more information about it. The dependency overview page offers a quick bird's-eye view of that particular dependency. You'll be able to see all different versions that are being used, including which repository is using them, the oldest and most recent versions you're leveraging, as well as the highest criticality of security issues, the license 5 applied to any particular version of that dependency, and the [OSSF Scorecard](#ossf-scorecard) security assessment. +### Transitive dependencies {: id="transitive-dependencies"} + +A **transitive dependency** is a package your repository doesn't import directly — it's pulled in through another package you depend on. When a vulnerability lives in a transitive dependency, the package you need to upgrade is often *not* the vulnerable one itself, but an ancestor higher up the chain that has a patched release available. + +Codacy surfaces the full import chain for every finding caused by a transitive dependency, so you can see exactly which package to bump. + +#### Where you see it + +Open the **Findings** tab under **Security and risk management**. Findings caused by a transitive dependency are labelled **Transitive Dependency** in the header. + +![Security and risk management transitive dependency finding](images/security-risk-management-transitive-chain.png) + +When you expand a transitive finding, the import chain appears at the top of the finding card. It shows every hop from the first affected dependency down to the vulnerable package. + +#### Reading the chain + +The chain reads left to right: + +- **Transitive** — the icon and label that identifies this as a transitive dependency finding. +- **Intermediate segments** — the packages in the resolution path, connected by arrows (`→`). Each one is a dependency that pulls in the next. +- **Last segment** — the vulnerable package and version, shown in bold. +- **Fixed version** — when a patched release is available, a **Fixed version *x.x.x*** label appears at the end of the chain. This is the version to target when upgrading to resolve the vulnerability. + +For example: + +``` +Transitive → peft@0.11.1 → accelerate@0.31.0 → Torch@2.4.0 Fixed version 2.4.1 +``` + +In this example, `Torch@2.4.0` is the vulnerable package, and upgrading to the indicated fixed version resolves the vulnerability across this dependency path. + +#### When no fixed version is available + +If no patched release exists yet, the chain is shown without a **Fixed version** label. In that case the vulnerability cannot be resolved by a version bump alone; you may need to wait for an upstream fix, apply a workaround (such as explicitly setting the version of the transitive dependency), or accept the risk per your organization's policy. + +#### Limitations + +- The import chain is shown only for findings that come from dependency scanning. Findings from other scan types (container scanning, app scanning) do not show a chain. +- Each finding shows a single representative path. If a repository reaches the same vulnerable package through more than one chain, only one is displayed. + ### OSSF Scorecard {: id="ossf-scorecard"} The **OSSF Scorecard** feature provides additional security insights for your dependencies by displaying security assessment data from the Open Source Security Foundation (OSSF) Scorecard project.