caution

This documentation is a WIP and gives only a brief explanation of what each field in the NuGetDefense.json configuration file does and what values they accept.

Configuring NuGetDefense

NuGetDefense can run without any prior configuration. On the first run, it will generate a config file in the AppData Special Folder with the defaults used when no configuration is found. For more control over specific projects and solutions, you can add a NuGetDefense.json config file to the directory with your project or solution file and it will be used instead.

NuGetDefense.json

{
  "WarnOnly": false,
  "VulnerabilityReports": {
    "OutputTextReport": true
  },
  "CheckTransitiveDependencies": true,
  "CheckReferencedProjects": false,
  "ErrorSettings": {
    "ErrorSeverityThreshold": "any",
    "Cvss3Threshold": -1,
    "IgnoredPackages": [
      {
        "Id": "NugetDefense"
      }
    ],
    "IgnoredCvEs": [],
    "AllowedPackages": [],
    "WhiteListedPackages": [],
    "BlockedPackages": [],
    "BlacklistedPackages": []
  },
  "OssIndex": {
    "ApiToken": "",
    "Username": "",
    "Enabled": true,
    "BreakIfCannotRun": true
  },
  "GitHubAdvisoryDatabase": {
    "ApiToken": "",
    "Username": "",
    "Enabled": true,
    "BreakIfCannotRun": false
  },
  "NVD": {
    "SelfUpdate": false,
    "TimeoutInSeconds": 15,
    "Enabled": true,
    "BreakIfCannotRun": true
  },
  "SensitivePackages": []
}

WarnOnly

When enabled, NuGetDefense will always return an exit code of 0, and will output msbuild warning messages instead of msBuild Error Messages

Accepted Values

Value	Description
true	Enables WarnOnly mode preventing errors wehn vulnerabilities are reporting from the msBuild
false	Returns errors and a non-zero exit code when vulnerabilities are reported. This will break the build.msBuild

VulnerabilityReports

VulnerabilityReports allows exporting reports generated by nugetdefense with details from the scan. There are a few report types available. Any reports omitted from these settings is disabled.

Report Option	Values Accepted	Description
JsonReportPath	Any Valid File Path	Exports the VulnerabilityReport in JSON format to the provided path.
OutputTextReport	true or false	Outputs the a human readable VulnerabilityReport to the console.
XmlReportPath	Any Valid File Path	Outputs the VulnerabilityReport in XML format to the provided path.

CheckTransitiveDependencies

Transitive dependency checking relies on dotnet list --transitive and adds any versions found in that list to the packages to be scanned.

Value	Description
true	Enables scanning transitive dependencies (dependencies of the packages you have referenced that are automatically referenced in your project).
false	Disabled transitive dependency scanning.

CheckReferencedProjects

Referenced project scanning works when the project file is scanned. Any packages referenced in those projects are scanned as well.

Value	Description
true	Enables scanning project references.
false	Disabled scanning project references.

ErrorSettings

Error settings generally handle how errors for vulnerabilities are handled.packages

ErrorSeverityThreshold

Human readable levels for vulnerability severities. Each level corresponds to a CVSS score range. Scores below that range are ignored.

::: caution This setting is not compatible with Cvss3Threshold :::

Severityy	CVSS Score
any	N/A - any disables severity thresholds
None	CVSS3 score 0 - Only vulnerabilities without a CVSS score are ignored
Low	CVSS3 score 0.1 - 3.9
Medium	CVSS3 score 4.0 - 6.9
High	CVSS3 score 7.0 - 8.9
Critical	CVSS3 score 9.0 - 10.0

Cvss3Threshold

CSSV3 Score threshold for ignoring vulnerabilities.

::: caution This setting is not compatible with ErrorSeverityThreshold :::

Value	Description
0 to 10.0	Ignores all vulnerabilities with a CVSS3 score lower than the threshold. Also Ignores All Vulnerabilities without a CVSS3 score.
-1	Disables the threshold.

IgnoredPackages

An array of packages to be ignored.

Value	Description
Id	Required Id of the package to ignore
Version	Optional Version of the package to ignore. If no version is set, all versions of the package are ignored.

ex.

[
    {
        "Id": "NugetDefense",
        "Version": "1.2.3"
    },
    {
        "Id": "InternalPackage.Invulnerable"
    }
]

IgnoredCvEs

Array of CVE's or Vulenrability ID's to ingore when scanning.

ex. ["CVE-1234-1234","sonatype-1234-01234","GHSA-1234-abc9-abcd"]

AllowedPackages / WhiteListedPackages

This is an AllowList/WhiteList of packages that are allowed to be installed in the project. This is generally intended for CI use to prevent the addition of unapproved packages to a project. AllowedPackages is the official name of this setting, but for backwards compatability and non-english speaking users, WhiteListedPackages is also usable.

Value	Description
Id	Required Id of the package to ignore
Version	Optional Version of the package to ignore. If no version is set, all versions of the package are ignored.

ex.

[
    {
        "Id": "NugetDefense",
        "Version": "1.2.3"
    },
    {
        "Id": "InternalPackage.Invulnerable"
    }
]

BlockedPackages / BlackListedPackages

This is an AllowList/WhiteList of packages that are allowed to be installed in the project. This is generally intended for CI use to prevent the addition of unapproved packages to a project. AllowedPackages is the official name of this setting, but for backwards compatability and non-english speaking users, WhiteListedPackages is also usable.

Value	Description
Id	Required Id of the package to ignore
Version	Optional Version of the package to ignore. If no version is set, all versions of the package are ignored.

ex.

[
    {
        "Id": "NugetDefense",
        "Version": "1.2.3"
    },
    {
        "Id": "InternalPackage.Invulnerable"
    }
]

OssIndex / GitHubAdvisoryDatabase

OSSIndex and GitHubAdvisoryDatabase are remote vulnerability sources and information about your packages must be sent up to their servers to gather information about the known vulnerabilities for them. They share teh same configuration settings. In general it's advisable to setup an account to access remote vulnerability services. GitHubAdvisoryDatabase does not work without one, but rewuires NO permissions. OSSindex provides more useful info with an account.

Value	Description
APIToken	Required For GitHubAdvisoryDatabase Password/API Token/Secret for accessing the API using your account
Username	Optional Username of the account used to access the remote vulnerability source
Enabled	Enables using this vulnerability source. If not present or Disabled, this source will not be used to scan your packages.
BreakIfCannotRun	If enabled, throws an error if the source cannot be run. This could be caused by aPI limits or network errors.

NVD

NVD is an offline copy of the National Vulnerability Database that is optionally self-updating. This is the least reliable source for vulnerability scanning since it has an automated update/parsing process.

Value	Description
SelfUpdate	If Enabled, attempts to update the offile source before scanning.
TimeoutInSeconds	Timeout to use when retrieving the latest vulnerabilities.
Enabled	Enables using this vulnerability source. If not present or Disabled, this source will not be used to scan your packages.
BreakIfCannotRun	If enabled, throws an error if the source cannot be run. This could be caused by aPI limits or network errors.

SensitivePackages

Packages in this array are not sent to any remote vulnerability source but will still be scanned against the embedded NVD source.

Value	Description
Id	Required Id of the package to ignore
Version	Optional Version of the package to ignore. If no version is set, all versions of the package are ignored.

ex.

[
    {
        "Id": "NugetDefense",
        "Version": "1.2.3"
    },
    {
        "Id": "InternalPackage.Invulnerable"
    }
]

Log / Logs

The Log configuration section provides options to log the output to a file.

Logs accepts an array of file locations instead of a single path.

Field	Description
Output	Required Path to the log file
LogLevel	Optional Log Level to use when logging: Verbose, Debug, Information, Warning, Error, Fatal
RollingInterval	Optional Log rotation interval: Infinite, Year, Month,Day,Hour,Minute

CacheLocation

Path for the local cache for previously reported known vulnerabilities.

Defaults to: /path/to/SpecialFolder/ApplicationData/.nugetdefense/NugetDefense.sqlite