Setting Up Reachability Analysis#

You run reachability analysis by running the script vuls-reach-light.sh in your CI. The script downloads the reachability analysis program vuls-reach, analyzes the source code for each lockfile you specify, and uploads the results to FutureVuls.

For an overview of this feature and important notes, see "Reachability Analysis (Beta)".

Prerequisites#

Preparation in FutureVuls#

Your organization is on the CSIRT Plan. On other plans, the upload of analysis results is rejected
The group token used for the upload has the API permission "Read, Update" or "Read, Update, Group Settings" (see "Creating a FutureVuls API Token"). Group tokens with the API permission "Read Only", group set tokens, and organization tokens cannot be used
The Go application to analyze is already registered as an application on a server in FutureVuls. You register applications with a scan, lockfile registration, or SBOM import
If your organization restricts access by IP address (see "Registering Accessible IP Addresses"), the source IP address of your CI is allowed. The upload of analysis results uses the FutureVuls API, so unlike the upload of scan results, it is subject to the IP address restriction

Reachability analysis does not register new applications. Register the application with a scan or another method first, and then give its ID (applicationId) to the script.

CI Execution Environment#

Item	Requirements
OS / CPU	Linux on x86_64 or aarch64
Commands	`bash`, `curl`, `tar`, and the Go toolchain (the `go` command must be on `PATH`) `jq` and `file` are optional
Source code	The source code of the Go module to analyze is checked out `go.sum` contains all required entries (update it with `go mod tidy` or a similar command). If entries are missing, the analysis fails The dependency modules can be fetched (if you use private modules, you need the same settings as for `go build`)
Network	The runner can connect to `installer.vuls.biz` (download of the script and `vuls-reach`), `rest.vuls.biz` (upload of the analysis results), and `vuln.go.dev` (the Go vulnerability database) To download dependency modules and Go toolchains that are not in the module cache, the runner can connect to the destinations set by your Go settings (`GOPROXY`, `GOSUMDB`). By default, these are the Go module proxy (`proxy.golang.org`) and, for modules that the proxy does not have, their repositories (such as GitHub)

Step 1. Check the Server UUID and the applicationId#

You give the script the ID of the application to register the analysis results to (applicationId), and the server UUID of the server that the application belongs to.

For how to check the server UUID, see "How to get UUID".

Check the applicationId in one of the following ways:

Get it with GET /v1/lockfiles of the FutureVuls API
- Run it with the server ID of the target server in filterServerID (see "How to get serverID")
- If you specify the lockfile path (the registered name) in filterPath, only that application is returned. It must match the registered name exactly, including whether it has a leading /
- In lockfiles of the response, the id of the element for the application to analyze is the applicationId. path is the registered name of the application
- For applications registered by a scan or lockfile registration, select the element whose path matches the path of the go.mod or go.sum to analyze
- For SBOM applications, path has the form <name> | <SBOM UUID>. Select the element for the Go application (such as a binary) to analyze. Specify the pair of its ID and the path of the go.mod or go.sum of the Go module in the source code
- If nothing is returned, remove filterPath and look for the application in the list. By default, 20 elements are returned per request. Use limit (up to 1000) and page to specify the range to get
Check it in the FutureVuls console
- On the Server tab, select the target server, and then select the application to analyze on the "Application" tab
- The number after # in the title at the top of the third pane (for example, applicationLibrary #123456) is the applicationId

curl -s -G -H 'accept: application/json' -H 'Authorization: <API token>' \
  --data-urlencode 'filterServerID=<server ID>' \
  --data-urlencode 'filterPath=<lockfile path>' \
  'https://rest.vuls.biz/v1/lockfiles'

Step 2. Set the Environment Variables#

The script reads the following environment variables.

Environment variable	Description	Required
`VULS_SAAS_TOKEN`	A group token with the API permission "Read, Update" or higher	✅
`VULS_SERVER_UUID`	The server UUID of the server that the target application belongs to	✅
`VULS_REACH_TARGETS`	The list of analysis targets. Write `<applicationId>:<lockfile path>` entries separated by `,` or line breaks Example: `123456:services/api/go.mod,123457:tools/cli/go.mod`	✅
`VULS_SAAS_PROXY`	The proxy server (example: `http://proxy.example.com:8080`). The script sets this value to `http_proxy` and `https_proxy`, so the traffic of `vuls-reach` and the Go command also goes through the proxy It does not apply to the download of the script itself (the `curl` in Step 3). Use the proxy settings of your CI (such as `https_proxy`) for it

Managing the token

With VULS_SAAS_TOKEN, anyone can perform update operations of the FutureVuls API on the specified group. Keep it in the encrypted store of your CI (such as GitHub Actions secrets), and do not leave it in plain text in CI logs or repositories.

How to Write VULS_REACH_TARGETS#

Write the lockfile path relative to the directory where you run the script (usually the root of the repository checked out in CI), and make it match the registered name of the application (see below). Use an absolute path only for an application registered with the same absolute path (for example, /opt/app/go.mod registered by an agent scan)
The lockfile name must be go.mod or go.sum. The script analyzes the directory that contains the lockfile
Write one entry for each Go module. You cannot write the same applicationId more than once
The lockfile path cannot contain a comma (,)

The lockfile path must match the registration of the application.

For applications registered by methods other than SBOM import, the lockfile path must match the registered name (path of GET /v1/lockfiles). A leading / or ./ is ignored
For an application registered with an absolute path on a server (example: /opt/app/go.mod), put the lockfile at opt/app/go.mod (the path without the leading /) relative to the directory where you run the script, or at the absolute path /opt/app/go.mod on the CI host, and specify that path
For SBOM applications, the lockfile path of the first upload is recorded. Specify the same path after that
Among SBOM applications, Go application (its path in GET /v1/lockfiles is Go application | <SBOM UUID>) cannot be analyzed. This application groups Go packages whose path is unknown, so it can contain the dependency libraries of more than one program

Before the analysis starts, the script writes each pair of applicationId and lockfile to the log. FutureVuls cannot always detect a wrong pair, so check the log on the first run.

Step 3. Add the Script to Your CI#

Download the script, and then run it.

curl -fsSL -o vuls-reach-light.sh https://installer.vuls.biz/vuls-reach-light.sh
bash vuls-reach-light.sh scan

Do not pipe the output of curl into bash

If you run the script as curl ... | bash, bash receives empty input when the download fails, and exits with exit code 0. In this case, CI is treated as successful although no analysis or upload is done.

Example for GitHub Actions#

This example analyzes reachability in the same pipeline after the dependency library scan (see "Integrating Application Library Scanning into CI/CD").

name: FutureVuls library scan and reachability analysis
on:
  push:
    branches:
      - main
permissions:
  contents: read
jobs:
  futurevuls:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
        with:
          go-version-file: go.mod
      - name: Scan libraries
        env:
          VULS_SAAS_GROUPID: ${{ secrets.VULS_SAAS_GROUPID }}
          VULS_SAAS_TOKEN: ${{ secrets.VULS_SCAN_TOKEN }}
          TARGET_LIBRARY: ${{ github.workspace }}
          VULS_SAAS_UUID: ${{ secrets.VULS_SERVER_UUID }}
        run: |
          curl -fsSL -o vuls-trivy-light.sh https://installer.vuls.biz/vuls-trivy-light.sh
          bash vuls-trivy-light.sh inst
      - name: Wait for the scan result to be imported
        # The wait time is based on typical import times. Adjust it for your environment
        run: sleep 180
      - name: Reachability analysis
        env:
          VULS_SAAS_TOKEN: ${{ secrets.VULS_REACH_TOKEN }}
          VULS_SERVER_UUID: ${{ secrets.VULS_SERVER_UUID }}
          VULS_REACH_TARGETS: "123456:go.mod"
        run: |
          curl -fsSL -o vuls-reach-light.sh https://installer.vuls.biz/vuls-reach-light.sh
          bash vuls-reach-light.sh scan

Set a group token with the scan permission in VULS_SCAN_TOKEN, and a group token with the API permission "Read, Update" or higher in VULS_REACH_TOKEN. If one token has both permissions, you can use the same token
Replace 123456 in VULS_REACH_TARGETS with the applicationId you checked in Step 1
On the first run, check the applicationId after the scan registers the application, and then set VULS_REACH_TARGETS
FutureVuls imports the scan results asynchronously after the scan step ends. Because of this, wait briefly before you run the reachability analysis. If the wait is too short, the upload can fail (for example, with the error レポートの行がこのアプリケーションの検知済みパッケージと 1 件も一致しません。…, which means that no row of the report matches the detected packages of the application). When FutureVuls is busy, the import can take longer. In that case, run the reachability analysis again. Even if it fails, the next run recovers

Checking the Result of the Run#

When the upload of the analysis results succeeds, the following message is written to the CI log.

Task list, CSV exports, and the task list API can take several minutes to reflect the result (task detail is updated immediately)

Task Details is updated immediately after the upload. The task list, the CSV report, and the task list of the FutureVuls API take some time to reflect the result. For how to read the results, see "Reading the Results".

Operational Notes#

The script downloads the latest vuls-reach on each run. You cannot specify the version of vuls-reach
Run reachability analysis after the scan, and wait briefly so that the scan results are imported first. Right after you upgrade a dependency library, the upload can fail until the scan detects the new version. Even if it fails, the previous analysis results remain, and the next run recovers
If the script runs at the same time as the import of scan results for the same server or the periodic scan of the Amazon Inspector integration (once a day), the upload can fail temporarily. Schedule your CI so that it does not overlap with them
In the following cases, the application is deleted or registered again with a new ID, and the analysis results up to that point are also deleted. Check the new applicationId, and update VULS_REACH_TARGETS
- Deleting and registering the application again
- Deleting and registering the SBOM again
- Moving or renaming the lockfile in the repository, for an application registered by a scan
- Renaming an application registered by a scan in the console or with the FutureVuls API. The next scan registers an application with the original name and a new ID, and deletes the renamed application
- An SBOM update or an Amazon Inspector SBOM import no longer contains the application. For an Amazon Inspector SBOM import, this includes the case where another image in the same ECR repository (such as another tag) is imported
An SBOM application stays bound to the lockfile path used when you first upload reachability analysis results. If you move the lockfile in the repository, the ID does not change, but uploads with the new path fail (lockfile の指定がアプリケーションと一致しません。…). Updating the SBOM does not change the path. See "If You Move an SBOM Application's Lockfile"
An application whose lockfile content is registered in FutureVuls, such as an application added by lockfile registration, keeps its ID and analysis results when you rename it. If you move the lockfile in the repository, rename the application to the new path. After you rename it, change the lockfile path in VULS_REACH_TARGETS to the new name

If You Move an SBOM Application's Lockfile#

First, arrange the lockfile and the source code to analyze in CI so that they are accessible at the same paths as in the first analysis. Set VULS_REACH_TARGETS to the lockfile path used for the first upload and the existing applicationId, then run the analysis again.

If you need to use a new path, you can delete and import the SBOM again for a manually imported application SBOM. Deleting the SBOM also deletes its applications and their analysis results. After importing it again, set VULS_REACH_TARGETS to the new applicationId and the new lockfile path.

You cannot delete a server SBOM or an automatically generated SBOM on its own. If you cannot continue analyzing at the original path, contact support.

Exit Codes and Retries#

The script analyzes and uploads the targets in VULS_REACH_TARGETS one by one from the first. If one target fails, the script continues with the remaining targets. At the end, it writes the result of each target to the log, and exits with one of the following exit codes.

Exit code	Meaning
0	The upload succeeded for all targets
1	One or more targets failed, or the script failed in the preparation stage (checking environment variables, downloading `vuls-reach`, and so on)
2	The argument is not `scan`

A failed analysis or upload does not change the analysis results that are already registered in FutureVuls.

In the following cases, the script automatically sends the same analysis results again after a few seconds. It retries up to 2 times (3 attempts in total).

A temporary error (such as サーバの到達可能性データが更新中です。しばらく待ってから再実行してください, which means that the reachability data of the server is being updated) is returned
HTTP 502, 503, or 504 is returned (for example, during maintenance)
There is no response (for example, the connection fails). However, the script does not retry when one request is stopped because it takes more than 300 seconds

If all 3 attempts fail, the target fails. Run the CI again after a while. The script does not retry other errors.

Troubleshooting#

When an upload fails, the error message from FutureVuls is written to the CI log. The FutureVuls API returns these messages in Japanese. The "Meaning" column shows each message in English.

Message	Meaning	Cause	Action
`許可されていない動作です`	Operation not permitted	The token has no update permission (a group token with the API permission "Read Only", a group set token, or an organization token)	Specify a group token with the API permission "Read, Update" or higher
HTTP 401	—	The token is invalid, the token has no API permission, or the IP address restriction of the organization does not allow the source IP address of your CI	Check the status and the API permission of the token. If you restrict access by IP address, allow the source IP address of your CI (see "Registering Accessible IP Addresses")
`サーバが見つかりません`	No server found	The server of `VULS_SERVER_UUID` is not in the group of the token	Check the server UUID and the group of the token
`applicationId に一致するアプリケーションがありません。先に通常スキャンを実行し、GET /v1/lockfiles またはコンソールで id を確認してください`	No application matches the given applicationId. Run a normal scan first and check the id with GET /v1/lockfiles or in the console	The application of the applicationId is not on the specified server (a wrong ID, a deleted application, and so on)	Check the applicationId again as described in Step 1
`lockfile の指定がアプリケーションと一致しません。VULS_REACH_TARGETS の applicationId と lockfile パスの対応を確認してください`	The declared lockfile does not match the application. Check the applicationId and lockfile path pairing in VULS_REACH_TARGETS	The lockfile path does not match the registered name of the application, the path differs from the path of the first upload for an SBOM application, the SBOM application `Go application` is specified, and so on	Check the pairs of applicationId and lockfile path in `VULS_REACH_TARGETS`. `Go application` cannot be analyzed (see "How to Write VULS_REACH_TARGETS")
`レポートの行がこのアプリケーションの検知済みパッケージと 1 件も一致しません。applicationId の指定と、スキャンによるパッケージ検知が最新かを確認してください`	No row of the report matches a detected package of this application. Check the applicationId and whether the scan has detected the current packages	The applicationId points to a different application, or the scan has not yet detected the updated dependency libraries	Check the applicationId. If you updated dependency libraries, run the script again after the scan results are reflected
`CSIRT オプションが有効でないため、アクセスすることができません。`	CSIRT Option is disabled, so access is not allowed	Your organization is not on the CSIRT Plan	This feature is available to organizations that are on the CSIRT Plan
`レポートのサイズが上限(30 MB)を超えています`	The report exceeds the size limit (30 MB)	The report of the analysis results for one application exceeds 30 MB	Contact support with the message from the CI log
`より新しい実行のレポートが既に登録されています(runStartedAt が古い)`	A report of a newer run is already registered (runStartedAt is older)	For the same application, the report of a CI run that started later was registered first (for example, when CI runs in parallel)	No action is needed. The result of the newer run is displayed
Any other message	—	—	Wait, then run it again. If the error continues, contact support with the message from the CI log.