Skip to main content

Integrate with source code management (SCM) solutions

Integrate Package Firewall with your source code management (SCM) solution, such as GitHub, Azure DevOps, or GitLab. The integration helps prevent malicious or policy-violating package versions from being added to applications built from your code.

When you configure Package Firewall in your SCM project, the configuration stays with the code. Every developer and build that uses the project routes package requests through Package Firewall.

Configure a project to use Package Firewall​

Add a package manager configuration file to your repository. This file routes package download requests through a Veracode Package Firewall URL.

Before you begin:

To complete this task:

  1. Go to the root directory of your project.

  2. Run the registry configuration command for your package manager. For example, to create a project-level npm configuration file, run this command:

    npm config set --location=project registry https://npm.firewall.veracode.com/

    The command creates an .npmrc file in the project directory.

  3. Add the access token to the .npmrc file as an environment variable reference. Don't write the token itself to the file:

    //npm.firewall.veracode.com/:_authToken=${FIREWALL_TOKEN}
  4. Set the FIREWALL_TOKEN environment variable on developer machines and in your continuous integration (CI) environment.

  5. Commit the configuration file to your SCM repository.

Regenerate lock files and dependency files​

Lock files record where each package version was downloaded from. A lock file that was created before you configured Package Firewall can continue to refer to external package registries. In this case, Package Firewall won't analyze the packages.

Regenerate lock files and dependency files when:

  • You first configure Package Firewall for a project.
  • You change your Package Firewall policy preferences.
note

If you don't regenerate relevant lock files and dependency files, your code might continue to refer to external package registries. In this case, Package Firewall won't analyze the packages that your code uses.

To complete this task:

  1. Delete the lock file from the project directory. For example, delete package-lock.json for npm.
  2. Run the install command for your package manager from the project directory. For example, run npm install.

Analyze existing lock files​

Existing projects need extra attention. Their lock files and local caches might already contain package versions that Package Firewall never analyzed. Developer machines and CI runners can install versions from a local cache without contacting the registry, so Package Firewall won't analyze those versions.

If your project already has a lock file, you can either regenerate it or analyze it. Regenerate the lock file when you can accept newer resolved versions. Analyze it when you need to keep the current versions and confirm that they pass your policy.

Do this analysis before you rely on Package Firewall to analyze new packages and versions.

Regenerating the lock file also causes a full analysis through Package Firewall. However, this approach is more error-prone and requires technical knowledge of your package manager.

To complete this task:

  1. Confirm that the lock file points to the Package Firewall registry. Open the lock file and search for the public registry URL for your ecosystem, which is listed in the supported ecosystems table. For example, search for https://registry.npmjs.org/ for npm. If the lock file contains public registry URLs, regenerate it.
  2. Make sure that the install downloads packages instead of reading them from a local cache. Clear the local package cache, or use a clean CI runner. An install that reads from a cache doesn't contact the registry, so Package Firewall doesn't check those packages.
  3. Run an install with the lock file. Package Firewall checks each locked version that the install downloads.
  4. If the install fails because a locked version is blocked, do one of the following:
    • Update the affected dependency to a version that passes your policy.
    • Add a policy exception for the package version.