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:
- You must have a Package Firewall access token.
- Find the registry URL for your ecosystem in the supported ecosystems table.
- Review the configuration steps for your package manager in Integrate with package managers.
To complete this task:
-
Go to the root directory of your project.
-
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
.npmrcfile in the project directory. -
Add the access token to the
.npmrcfile as an environment variable reference. Don't write the token itself to the file://npm.firewall.veracode.com/:_authToken=${FIREWALL_TOKEN} -
Set the
FIREWALL_TOKENenvironment variable on developer machines and in your continuous integration (CI) environment. -
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.
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:
- Delete the lock file from the project directory. For example, delete
package-lock.jsonfor npm. - 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:
- 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. - 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.
- Run an install with the lock file. Package Firewall checks each locked version that the install downloads.
- 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.