Configuring the Unified Agent for NuGet

The following article will include best practices and configuration recommendations for using the Unified Agent to scan NuGet projects.

Good To Know

The .nuspec file is the manifest file for NuGet.
You can declare NuGet dependencies in two ways:
1. .csproj file (for .NET Core version 2.0 and newer)
2. packages.config file (for versions older than .NET Core 2.0)
When our Unified Agent parameter, nuget.runPreStep, is set to ‘true’, the Unified Agent will run the following:
1. ‘dotnet restore’ for .csproj (default)
2. 'nuget restore' for packages.config

The ‘dotnet restore’ command can be changed to ‘nuget restore’ by inputting the following parameter within the Unified Agent configuration: nuget.preferredEnvironment=nuget.
The 'nuget restore' command cannot be changed to 'dotnet restore'.

To check your .NET version, run the following command:

CODE

dotnet --version

Best Practices

Before scanning a NuGet project, ensure the following for the most accurate results:

You are using NuGet CLI version 5.4+
The project can be built successfully on the machine where you are running the scan
If you have a hint path inside a .csproj file, make sure that the hint path references a valid path

Configuring UA Parameters

The following parameters should always be set for the most accurate results:

CODE

nuget.runPreStep=true
nuget.resolveDependencies=true
nuget.resolveCsProjFiles=true
nuget.resolveNuspecFiles=true

However, there are instances where the nuget.runPreStep=true is not needed:

If your NuGet project only consists of .csproj files and the build creates the project.assets.json file, then there is no need for nuget.runPreStep=true.
If your NuGet project is packages.config based and the nuget.packagesDirectory parameter is provided (not the default cache), then there is no need for nuget.runPreStep=true.
If you are running the restore command with the -UseLockFile flag prior to the Unified Agent scan. With the -UseLockFile flag, it enables and generates the packages.lock.json used with the restore command.

To generate a packages.lock.json, please see Microsoft’s article here: Enable repeatable package restores using a lock file.

Version .NET Core 2.0 and higher

If your project is using .NET 2.0 version or higher, we will scan your .csproj files. The recommended configuration is:

CODE

resolveAllDependencies=false
nuget.resolveDependencies=true
nuget.resolveCsProjFiles=true
nuget.preferredEnvironment=dotnet
nuget.runPreStep=true

Versions below .NET Core 2.0

If your project is using versions below .NET 2.0, we will scan your packages.config files. The recommended configuration is:

CODE

resolveAllDependencies=false
nuget.resolveDependencies=true
nuget.resolveCsProjFiles=true
nuget.preferredEnvironment=nuget
nuget.runPreStep=true

Additional Parameters

If your project is csproj based with a project.assets.json file, set the following:

CODE

nuget.resolveAssetsFiles=true
nuget.resolvePackagesConfigFiles=false

If your project is .csproj based with a packages.config file, set the following:

CODE

nuget.resolveAssetsFiles=false
nuget.resolvePackagesConfigFiles=true

If your project contains both, set all flags to ‘true’ (default):

CODE

nuget.resolveAssetsFiles=true
nuget.resolvePackagesConfigFiles=true

Frequently Asked Questions

I scanned a project, but the version of a component is not what I expected. Why is this happening?

When an incorrect version of a component is displayed, this likely means that the scan results were generated by obtaining the hierarchy tree through parsing .nuspec files. This means that the Unified Agent parsed the cache itself and used a heuristic approach to determine what version the components should be since multiple versions of a component may exist within the cache. To prevent this from happening, ensure that project can build successfully and the Unified Agent is scanning a project.assets.json or packages.lock.json file.

I scanned a project with all of the required parameters set correctly, but still only got a flat list. Why is this happening?

This usually means that the project could not be built successfully during the scan process. Please try to manually build the project and fix any problems in the project that could be preventing a successful build.

I ran a scan and some packages appear to be missing. What could be a cause?

If you are missing packages, please ensure that all parameters are set appropriately. If setting the parameters doesn’t fix this, try checking if the project can be built outside of the Unified Agent scant. Build failures can prevent the Unified Agent from finding the packages. If the Unified Agent can not find a package and calculate the real sha-1 of that package, the Unified Agent does not include the package in the scan.

Does the Unified Agent resolve system packages?

No, we do not support resolving system packages at this time.

NuGet Resolution Example Scenarios

For all of these scenarios a .csproj or package.json is included in the project:

1.Parameter nuget.resolveDependencies is not set to ‘true

By default, the Unified Agent will still parse the .csproj or package.json file. This will result in a flat list (no transitive dependencies) with partial results.

2. Parameter nuget.restoreDependencies is not set to ‘true’

By default, the Unified Agent will still parse the .csproj or package.json file. This will result in a flat list (no transitive dependencies) with partial results.

3. The project does not contain a project.assets.json or packages-lock.json and all configuration is complete per instructions under ‘Configuring UA Parameters’

The Unified Agent will get the hierarchy tree by parsing .nuspec files and calculating sha-1 values.

4. The project contains a project.assets.json or packages-lock.json and all configuration is complete per instructions under ‘Configuring UA Parameters’

The Unified Agent will get the hierarchy tree using the project.assets.json or packages.lock.json and calculating sha-1 values. This approach will provide the most accurate results.