Dependency Library Scan

FutureVuls has the capability to detect and manage vulnerabilities in application dependency libraries, as well as in OS packages.

There are several detection methods, each with different types of scannable vulnerabilities and detection performance, so it is recommended to try them out and select or combine them for detection.

The characteristics of each detection method are described in Scan Method Selection and Characteristics.

Lockfile Paste Scan

This is a method of scanning by pasting the contents of a Lockfile into a browser.

When a vulnerability affecting the registered Lockfile is disclosed, FutureVuls detects it and automatically registers a task and notifies the user. If the Lockfile contents are updated by upgrading the dependent library, please update the Lockfile contents from the FutureVuls screen. The status of detected tasks in FutureVuls is automatically updated to “patch_applied”.

The LockFiles that can be scanned by Paste Scan are as follows.

Please refer to Supported Environments for LockFiles and binaries that can be scanned.

Here’s how to register a Lockfile from the FutureVuls screen.

• Select a server and click Add on the LOCKFILE tab.

• Give the Lockfile a name, select the type, paste the contents of the Lockfile, and send.

• It will register the software and detect vulnerabilities at the next scan.

Scanning with Trivy by Specifying Paths on the Filesystem

aquasecurity/trivy is an OSS tool that can detect vulnerabilities in application dependency libraries. It automatically detects application dependency libraries stored in a specified directory and scans for vulnerabilities in them. FutureVuls incorporates the scan results from Trivy and enables vulnerability management of application libraries on FutureVuls.

Trivy performs vulnerability scans based on binaries such as Lock files and jar files for various languages. For details on the supported languages and package ecosystems, see the Filesystem and Rootfs columns of Trivy Supported languages.

There are two patterns available for container image scanning with Trivy:

• Install Trivy in a local environment and scan

• How to integrate into CI/CD pipeline

Scan locally with Trivy installation

Install Trivy on the local environment and upload the result of scanning application libraries to FutureVuls. With this method, two installation modes are available: normal and lightweight. The difference between them is as follows:

Scan new dependent libraries

If you want to scan a new application library and register it with FutureVuls, follow these steps:

1. Open the dialog box by clicking the Add server button in the Server tab and select Scan a library on the file system
2. Select the scanner token and enter the absolute path of the target directory for scanning.
   • If you do not specify a path, the root directory will be automatically specified, and all application libraries on the file system will be the target of scanning.
3. If you are in a proxy environment, enter the proxy server to pass through.
4. If you are using the lightweight version, check the switch bar.
5. Copy and paste the command displayed at the bottom of the screen, and execute it in the local environment where the target application library is managed.
6. Confirm that the scanned directory is added to the server tab of the target group in FutureVuls
   • In the case of normal scan, it will be reflected in FutureVuls in 5 to 10 minuts.

• If you want to perform a scan immediately after installation, please run the following command:
  • /opt/vuls-trivy-saas/vuls-trivy-saas.sh &> /opt/vuls-trivy-saas/vuls-trivy.log

Registration is complete with the above steps. In the normal version, the scanner starts automatically once a day, scans the target directory, and reflects it in FutureVuls.

In the normal version, several scan options are available.

If the scan result is not reflected, please refer to here.

Update configuration information of registered libraries

• Update vulnerability information based on the configuration information already registered

If you want to update vulnerability information based on the configuration information of the application library already registered in FutureVuls, please perform a manual scan from FutureVuls.

• Reflect changes in application library configuration information in FutureVuls

If there are any changes in the dependent libraries you have registered, please reflect them in FutureVuls according to the following procedure.

• For the normal version:
  • The scanner starts automatically once a day and scans the image, so no operation is required.
  • If you want to start the scanner immediately, please run the following command as the root or vuls-trivy-saas user:
    • /opt/vuls-trivy-saas/vuls-trivy-saas.sh &> /opt/vuls-trivy-saas/vuls-trivy.log
• For the lightweight version:
  1. Click the target server in the server tab to open the server detail page.
  2. Click the Update Configuration button to open the dialog.
  3. Select the scanner token and enter the absolute path of the scan target directory.
  4. If you are using a proxy environment, enter the proxy server you pass through.
  5. Copy the command displayed at the bottom of the screen, paste and run it in the local environment that manages the target application library.

How to incorporate into CI/CD pipelines

Integrate Trivy into your CI/CD pipeline and upload the scanned result of the application library to FutureVuls. This document describes how to do it with GitHub Actions. Here’s the sample YAML file for GitHub Actions.

• Environment variables used in the sample

• If updating the configuration information of a library already managed on FutureVuls, specify the UUID of the target library as VULS_SAAS_UUID.

Scan using the script file for scanning.

name: FutureVuls Docker Image Scan
on:
  push
defaults:
  run:
      shell: bash
jobs:
  docker-test:
    name: FutureVuls Docker Image Scan
    env:
      VULS_SAAS_GROUPID: ${{ secrets.VULS_SAAS_GROUPID }}
      VULS_SAAS_TOKEN: ${{ secrets.VULS_SAAS_TOKEN }}
      TARGET_LIBRARY: "/aaa/bbb"
      VULS_SAAS_UUID: "xxxxxxxx"
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: cached scan db
      uses: actions/cache@v3
      with:
        path: vulndb/
        key: trivy-vulndb
    - name: scan and upload
      env: 
      run: 
        curl -s https://installer.vuls.biz/vuls-trivy-light.sh | \
        VULS_SAAS_GROUPID="${env.VULS_SAAS_GROUPID}" \
        VULS_SAAS_TOKEN="${env.VULS_SAAS_TOKEN}" \
        TARGET_LIBRARY="${env.TARGET_LIBRARY}" \
        bash -s inst

How to automatically update Lockfile when pushing using GitHub Actions

This explains how to use futurevuls/fvuls-lockfile-uploader to check if the Lockfile has been updated when git push is executed, and to update the registered Lockfile via REST API only when the Lockfile has been updated.

In the following example, it is executed only when ./go.sum or ./web/yarn.lock is changed and pushed to the release branch.

The following environment variables in the sample should be set using Encrypted Secrets.

on:
  push:
    ## https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#onpushpull_requestpaths
    paths:
      - 'go.sum'
      - 'web/yarn.lock'
    branches:
      - release

name: Check lockfiles
jobs:
  build:
    env:
      FVULS_SERVER_UUID: ${{ secrets.FVULS_SERVER_UUID }}
      FVULS_TOKEN: ${{ secrets.FVULS_TOKEN }}
    name: Upload lockfile
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Upload go.sum
        uses: futurevuls/fvuls-lockfile-uploader@v1
        with:
          repoName: ${{ github.repository }}
          path: './go.sum'
      - name: Upload web/yarn.lock
        uses: futurevuls/fvuls-lockfile-uploader@v1
        with:
          repoName: ${{ github.repository }}
          path: './web/yarn.lock'

Scanning Libraries on Remote Repository with Trivy

By integrating with trivy repository scan, you can detect vulnerabilities in language libraries on GitHub/GitLab and manage them on FutureVuls. This allows you to use library scans even if the library file to be scanned is not present in the local environment where trivy is installed.

For details on supported languages and package ecosystems, see the Repository column of Trivy Supported languages.

Scanning Methods

Registering for the First Time

• Install the following three tools according to your work environment

Install Command Samples

curl -s https://api.github.com/repos/aquasecurity/trivy/releases/latest | \
grep "browser_download_url.*_Linux-64bit.tar.gz" | \
cut -d : -f 2-3 | \
xargs wget
tar zxvf trivy_*.tar.gz

curl -s https://api.github.com/repos/future-architect/vuls/releases/latest | \
grep "browser_download_url.*trivy-to-vuls.*_linux_amd64.tar.gz" | \
cut -d : -f 2-3 | \
xargs wget
tar zxvf trivy-to-vuls*.tar.gz

curl -s https://api.github.com/repos/future-architect/vuls/releases/latest | \
grep "browser_download_url.*future-vuls.*_linux_amd64.tar.gz" | \
cut -d : -f 2-3 | \
xargs wget
tar zxvf future-vuls*.tar.gz

curl -s https://api.github.com/repos/aquasecurity/trivy/releases/latest | \
grep "browser_download_url.*_macOS-ARM64.tar.gz" | \
cut -d : -f 2-3 | \
xargs wget
tar zxvf trivy_*.tar.gz

curl -s https://api.github.com/repos/future-architect/vuls/releases/latest | \
grep "browser_download_url.*trivy-to-vuls.*_darwin_arm64.tar.gz" | \
cut -d : -f 2-3 | \
xargs wget
tar zxvf trivy-to-vuls*.tar.gz

curl -s https://api.github.com/repos/future-architect/vuls/releases/latest | \
grep "browser_download_url.*future-vuls.*_darwin_arm64.tar.gz" | \
cut -d : -f 2-3 | \
xargs wget
tar zxvf future-vuls*.tar.gz

• Set up environmental Variables

export FVULS_GROUP_ID=xxx
export FVULS_TOKEN=xxx
export FVULS_SERVER_UUID=`uuidgen`
export REPOSITORY_URL=https://xxx.xxxxx/xxx
# If you are using a proxy, you need to set the proxy server to go through
export https_proxy=http://name:pass@proxy:port

# Change variables to set up per scan targetting repositories
export GITHUB_TOKEN=xxxxxxxx
export GITLAB_TOKEN=xxxxxxxx

• Scan the repository and upload it to FutureVuls

./trivy repo -q -f json --list-all-pkgs ${REPOSITORY_URL} | \
./trivy-to-vuls parse --stdin | \
./future-vuls upload --stdin --url https://auth.vuls.biz/one-time-auth --group-id ${FVULS_GROUP_ID} --token ${FVULS_TOKEN}  --uuid ${FVULS_SERVER_UUID}

When you open FutureVuls, you can see that a new server has been registered and a vulnerability in a language library has been detected.

Updating library files

If you want to update a library that has already been registered, set the UUID of the target server in the environment variable FVULS_SERVER_UUID, and then scan and upload.

# Skip installation of trivy, trivy-to-vuls, and future-vuls

export FVULS_GROUP_ID=xxx
export FVULS_TOKEN=xxx
export FVULS_SERVER_UUID=xxx
export REPOSITORY_URL=https://xxx.xxxxx/xxx

# Select the variable to set depending on the repository to be scanned
export GITHUB_TOKEN=xxxxxxxx
export GITLAB_TOKEN=xxxxxxxx

./trivy repo -q -f json -o ./results.json --list-all-pkgs ${REPOSITORY_URL}
./trivy-to-vuls parse ./ -f result.json | \
./future-vuls upload --stdin --url https://auth.vuls.biz/one-time-auth --group-id ${FVULS_GROUP_ID} --token ${FVULS_TOKEN}  --uuid ${FVULS_SERVER_UUID}

Scanning with a Lockfile using Vuls Scanner

This method scans for vulnerabilities in dependent libraries by specifying the Lockfile or binary path that is located on the server.

Refer to Supported environments for a list of Lockfiles and binaries that can be scanned.

This function supports both local and remote scan modes.

Vuls Local Scan Mode Operation

Specify the path of the Lockfile to be scanned in config.toml. The Lockfile at the specified path is parsed during scan to obtain the list of dependent libraries.

Vuls Remote Scan Mode Operation

Specify the path of the Lockfile on the target server to be scanned in config.toml. The Lockfile at the specified path on the remote server is parsed using SSH during scan to obtain the list of dependent libraries.

Configuration

Specify the path of the Lockfile in /opt/vuls-saas/config.toml.

[servers]

[servers.sample]
user = "vuls-saas"
host = "localhost"
port = "local"
lockfiles = [
  "/home/user/lockfiles/package-lock.json",
  "/home/user/lockfiles/Gemfile.lock",
  "/home/user/lockfiles/yarn.lock"
]

Automatic scanning of LockFiles and Jars in findLockDir on the target server can be enabled by specifying findLock = true and findLockDirs in config.toml.

[servers]

[servers.sample]
user = "vuls-saas"
host = "localhost"
port = "local"
findLock = true 
findLockDirs = [
  "/path/to/prject/lib",
  "/path/to/prject2/lib",
]

• The scanned packages are displayed in the software and task menus, just like the OS packages.

GitHub Security Alerts Integration

GitHub Security Alerts is a feature of GitHub that scans for vulnerabilities in the dependency libraries listed in the Lockfile of a repository. In FutureVuls, you can integrate with GitHub via API to import the vulnerabilities detected by GitHub.

Even if you do not manage the source code in GitHub, you can detect vulnerabilities by managing only the Lockfile in GitHub.

Please refer to GitHub:Supported package ecosystems for the supported languages and types.

Registering CPEs from the FutureVuls screen

This is a method to register CPEs from the FutureVuls screen and scan for vulnerabilities in libraries. The information sources for scanning using CPEs are NVD and JVN, so vulnerabilities in libraries not registered in NVD or JVN cannot be detected. Also, you need to register the libraries that the target library depends on, so it is usually better to adopt other methods.