r2c-internal-project-depends-on

This Semgrep rules key allows specifying third-party dependencies along with the semver (semantic version) range that should trigger the rule. The r2c-internal-project-depends-on filters the rule unless one of the children is matched by a lockfile.

We welcome external contributors to try out the key, but keep in mind there's no expectation of stability across releases yet. The API and behavior of this feature is subject to change.

In the rules.yaml, specify r2c-internal-project-depends-on key either as a dependency, or a sequence of dependencies with depends-on-either key (see the example below).

A dependency consists of three keys:

namespace: The package registry where the third-party dependency is found.
package: The name of the third-party dependency as it appears in the lockfile.
version: A semantic version range. Uses Python packaging specifiers which support almost all NPM operators, except for ^.

So a r2c-internal-project-depends-on key will either look like this:

r2c-internal-project-depends-on:
  namespace: ...
  package: ...
  version: ...

Or it can have the following layout with depends-on-either:

r2c-internal-project-depends-on:
  depends-on-either:
    - namespace: ...
      package: ...
      version: ...
    - namespace: ...
      package: ...
      version: ...
    ...

Example

Here is an example r2c-internal-project-depends-on rule that searches for a known vulnerable version of the AWS CLI from April 2017, but only reports the vulnerability if the s3 module (where the vulnerability is located) is actually used:

rules:
- id: vulnerable-awscli-apr-2017
  severity: WARNING
  pattern-either:
  - pattern: boto3.resource('s3', ...)
  - pattern: boto3.client('s3', ...)
  r2c-internal-project-depends-on:
    namespace: pypi
    package: awscli
    version: "<= 1.11.82"
  message: this version of awscli is subject to a directory traversal vulnerability in the s3 module
  languages: [python]

Findings of r2c-internal-project-depends-on

Findings produced by rules with the r2c-internal-project-depends-on can be of two types: reachable and nonreachable.

A reachable finding is one with both a dependency match and a pattern match: a vulnerable dependency was found and the vulnerable part of the dependency (according to the patterns in the rule) is used somewhere in the code.
An unreachable finding is one with only a dependency match. Reachable findings are reported as coming from the code that was pattern matched. Unreachable findings are reported as coming from the lockfile that was dependency matched. For both types of findings, Semgrep specifies whether they are unreachable or reachable along with all matched dependencies, in the extra field of Semgrep's JSON output, using the dependency_match_only and dependency_matches fields, respectively.

A finding is only considered reachable if the file containing the pattern match actually depends on the dependencies in the lockfile containing the dependency match. A file depends on a lockfile if it is the nearest lockfile going up the directory tree.