Analyze dependency for behaviors

{{< details >}}

• Tier: Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
• Status: Experiment

{{< /details >}}

Libbehave is an experimental feature that scans your dependencies during merge request pipelines to identify newly added libraries and their potentially risky behaviors. While traditional dependency scanning looks for known vulnerabilities, Libbehave gives insight into what features and behaviors your dependencies exhibit.

Each feature detected by Libbehave is assigned a "riskiness" score of either:

• Informational: No risk, but may assist in cataloguing features of a dependency (for example, uses JSON).
• Low: Small risk, can highlight a dependency is doing a security sensitive action such as using encryption.
• Medium: Moderate level of risk, can be used to interact with the file system or read environment variables where sensitive data may be stored or accessed.
• High: Highest level of risk, these behaviors are commonly abused in security vulnerabilities such as executing OS commands or dynamically evaluating code.

Features that Libbehave detects include:

• Executing OS commands
• Executing dynamic code (eval)
• Reading/writing files
• Opening network sockets
• Reading/expanding archives (ZIP/tar/Gzip)
• Interacting with external services by using HTTP clients, Redis, Elastic Cache, Relational Management Database (RMDB) servers, SSH, Git
• Serializing data in various formats: XML, YAML, MessagePack, Protocol Buffers, JSON, and language-specific formats
• Templating
• Popular frameworks
• Upload/download of files

For demos of Libbehave for each supported package manager type, see our Libbehave demo projects.

Supported languages and package managers

The following languages and package managers are supported by Libbehave:

• C# (NuGet)
  • Reads Directory.Build.props files (replacing property values if found)
  • Reads *.deps.json files
  • Reads **/*.dll and **/*.exe files
• Go
  • Reads go.mod files
• Java (Maven)
  • Reads pom.xml files (replacing property values if found)
  • Reads **/gradle.lockfile* files
• JavaScript/TypeScript (npmjs)
  • Reads **/package-lock.json files
  • Reads **/yarn.lock files
  • Reads **/pnpm-lock.yaml files
• Python (pypi)
  • Reads **/*requirements*.txt files
  • Reads **/poetry.lock files
  • Reads **/Pipfile.lock files
  • Reads **/setup.py files
  • Reads packages in egg or wheel installation directories:
    • Reads **/*dist-info/METADATA, **/*egg-info/PKG-INFO, **/*DIST-INFO/METADATA, and **/*EGG-INFO/PKG-INFO files
• PHP (Composer/Packagist)
  • Reads **/installed.json files
  • Reads **/composer.lock files
  • Reads **/php/.registry/.channel.*/*.reg" files
• Ruby (RubyGems)
  • Reads **/Gemfile.lock files
  • Reads **/specifications/**/*.gemspec files
  • Reads **/*.gemspec files

The previous files are analyzed for new dependencies only if the files have been modified in the source branch.

Enable Libbehave

Prerequisites:

• The Developer, Maintainer, or Owner role for the project.
• Pipeline is part of an active merge request pipeline that has a defined source and target Git branch.
• Project includes one of the supported languages.
• Project is adding new dependencies to the source or feature branch.

To enable Libbehave:

1. In the top bar, select Search or go to and find your project.

2. Select Code > Repository.

3. Select the .gitlab-ci.yml file.

4. Select Edit > Edit single file.

5. Add the Libbehave CI/CD components:

   yamlCopy

   include:
     - component: $CI_SERVER_FQDN/security-products/experiments/libbehave/[email protected]
       inputs:
         stage: test
   

6. Select Commit changes.

This configuration creates a new job called libbehave-experiment in the test stage.

Configure merge request comments

To configure merge request comments for Libbehave, configure a project access token.

Prerequisites:

• The Maintainer or Owner role for the project.
• Libbehave enabled for the project.

To configure merge request comments:

1. In the top bar, select Search or go to and find your project.

2. Select Settings > Access tokens.

3. Select Add new token and complete the fields:

   • Token name: Enter a name, for example, libbehave-bot.
   • Role: Select Guest.
   • Select scopes: Select the API checkbox.

4. Select Create project access token.

   Copy the project access token to your clipboard. It's required in the next step.

5. Select Settings > CI/CD.

6. Expand Variables.

7. Select Add variable and complete the fields:

   • Key: Enter BEHAVE_TOKEN.
   • Value: Paste the project access token.
   • Visibility: Select Masked.
   • Flags: Clear the Protect variable checkbox.

8. Select Add variable.

The CI/CD component automatically uses the BEHAVE_TOKEN so you do not need to specify it in the component inputs.

[!note] Merge request comments appear only when the source branch is either a protected branch or when the Protect variable option is unchecked for the BEHAVE_TOKEN variable.

Available CI/CD inputs and variables

You can use CI/CD variables to customize the CI component of Libbehave.

The following variables configure the behavior of how Libbehave runs.

The following flags are available, but are untested and should be left at their default values:

Because all variables have not been tested, you may find some that work and others that do not. If you need one that does not work, submitting a feature request or contributing to the code to enable it to be used.

Dependency detection and analysis

Libbehave analyzes and reports findings on any newly added dependencies and is meant to run in merge request pipelines. That means if your merge request does not include any new dependencies, then Libbehave returns zero results.

Detection works differently, depending on the language and package manager used. By default, those supported package managers have their package manager related files parsed to identify which dependencies are being added. This information is gathered and then used to call out to the respective package manager API to download the identified package's artifacts.

After they're downloaded, the dependencies are extracted and analyzed using static analysis methods based on Semgrep, with a configured set of checks.

In the case of Java and C#, an additional step is taken to decompile the binary artifacts prior to running static analysis.

Known issues

Each language has its own known issues.

All package files such as Gemfile.lock and requirements.txt must provide explicit versions. Version ranges are not supported.

C#

• Property or variable replacement in .props or .csproj files do not account for nested project files. It replaces any variable that matches a global set of extracted variables and their values.
• Decompiles downloaded dependencies, so source to line translation may not be 1:1.
• Libbehave decompiles all .NET versions that exist in a NuGet package. This may be optimized in the future.
  • For example, some dependencies will package multiple DLLs in a single archive targeting different framework versions (example: net20/Some.dll, net45/Some.dll).

Java

• Does not support inheritance for pom.xml files.
• Only supports Maven and not custom JFrog or other artifact repositories.
• Decompiles downloaded dependencies, so source to line translation may not be 1:1.

Python

• Attempt to download source packages from PyPI for analysis. If there is no source package, Libbehave downloads the first available bdist_wheel package which may not match the target OS.

Output

Libbehave produces the following output:

• Job summary: The summary of findings are output directly into the CI/CD output job console for a quick view of which features a dependency detected.
• MR comment summary: The summary of findings are output as a merge request comment note for easier review. This requires an access token to be configured to give the job access to write to the MR note section.
• HTML artifact: An HTML artifact that contains a searchable set of libraries and identified features as well as the exact lines of code that triggered the finding.

Job summary

The job summary requires no extra configuration and will always be presented after a successful analysis.

Example of what the Job Summary output looks like:

# Job output #

[=== libbehave: New packages detected ===]
🔺 4 new packages have been detected in this MR.
[= java - open-vulnerability-clients 6.1.7 =]
The https://mvnrepository.com/artifact/io.github.jeremylong/open-vulnerability-clients package was found to exhibit the following behaviors:
    - 🟧 GzipReadArchive (Risk: Medium)
-----------------
[= java - jdiagnostics 1.0.7 =]
The https://mvnrepository.com/artifact/org.anarres.jdiagnostics/jdiagnostics package was found to exhibit the following behaviors:
    - 🟥 CryptoMD5 (Risk: High)
    - 🟧 WriteFile (Risk: Medium)
    - 🟧 ReadFile (Risk: Medium)
    - 🟧 ReadEnvVars (Risk: Medium)
-----------------
[= java - commons-dbcp2 2.12.0 =]
The https://mvnrepository.com/artifact/org.apache.commons/commons-dbcp2 package was found to exhibit the following behaviors:
    - 🟥 JavaObjectSerialization (Risk: High)
    - 🟧 Passwords (Risk: Medium)
-----------------
[= java - jmockit 1.49 =]
The https://mvnrepository.com/artifact/org.jmockit/jmockit package was found to exhibit the following behaviors:
    - 🟥 JavaObjectSerialization (Risk: High)
    - 🟧 WriteFile (Risk: Medium)
    - 🟧 ReadFile (Risk: Medium)
    - 🟨 CryptoRAND (Risk: Low)
-----------------

MR comment summary

The MR comment summary output requires an access token with Guest level access be created for the project that the Libbehave component has been configured for. The access token should then be configured for the project. Because feature branches are not protected by default, ensure the Protect variable setting is cleared. Otherwise the Libbehave job cannot read the access token's value.

HTML artifact

The HTML artifact will appear in your jobs artifacts output (behaveout/gl-libbehave.html) and should be accessible in your job artifact downloads.

Offline environment (not supported)

Libbehave does not work in offline environments as it pulls down dependencies directly from the various package managers.

Troubleshooting

Job is not run

If the Libbehave job is not run, ensure your project is configured to run merge request pipelines.

Merge request comment is not being added

This is usually due to the BEHAVE_TOKEN not being set. Ensure the access token has Guest level access and the Protect variable option is unchecked in the Settings > CI/CD variables settings.

Error: {401 Permission Denied}

This is usually due to the BEHAVE_TOKEN not containing the correct value. Ensure the access token has Guest level access.