Repository Firewall Evaluation API
Use the Repository Firewall Evaluation API to preemptively evaluate components as when requested during a build through a proxy repository. This simplifies evaluating components through the Repository Firewall as the components do not have to be first downloaded through the proxy repository from the public ecosystems.
When a match is found using the file hash with the pathname or packageUrl, the evaluation returns the component details including any violations of the policies for the repository. Otherwise, the component is reported as unknown. A request may contain a maximum of 100 components for evaluation in one request.
Evaluating components
The evaluation request requires the identifier for the repository manager and the proxy repository. These are used to determine the policy to use in the evaluation.
See Firewall REST API for details on obtaining repository identifiers.
POST /api/v2/firewall/components/{repositoryManagerId}/{repositoryId}/evaluateReview the documentation for Sonatype Component Identifiers for each ecosystem. Learn about the packageURL from the OSSIndex documentation.
The data element in the POST request requires an array of component identifiers using the component hash and either the pathname or the packageURL to evaluate. This example includes both the pathname and packageURL however this is not required.
{
"format":"maven2",
"components":
[
{
"pathname":"commons-fileupload/commons-fileupload/1.0/commons-fileupload-1.0.jar",
"packageUrl":"pkg:maven/commons-fileupload/commons-fileupload@1.0",
"hash":"2366159e25523d99e96d05211a2fa5399c938735"
}
]
}Example request
curl -X POST -u admin:admin123 -H "Content-Type: application/json" \
-d "{\"format\":\"maven2\",\"components\":[{\"pathname\":\"commons-fileupload/commons-fileupload/1.0/commons-fileupload-1.0.jar\",\"packageUrl\":\"pkg:maven/commons-fileupload/commons-fileupload@1.0\",\"hash\":\"2366159e25523d99e96d05211a2fa5399c938735\"}]}" \
"http://localhost:8070/api/v2/firewall/components/d90592ce43174f7ea9b5b265f14a8ff1/556cea6db6b84e4fa6e04f9e3ebf13d9/evaluate"
{
"repositoryId": "556cea6db6b84e4fa6e04f9e3ebf13d9",
"repositoryManagerId": "d90592ce43174f7ea9b5b265f14a8ff1",
"repositoryPublicId": "maven-proxy",
"repositoryType": "proxy",
"results":
[
{
"catalogDate": "2005-11-22T18:09:21.000+0000",
"component":
{
"hash": "2366159e25523d99e96d05211a2fa5399c938735",
"packageUrl": "pkg:maven/commons-fileupload/commons-fileupload@1.0",
"pathname": "commons-fileupload/commons-fileupload/1.0/commons-fileupload-1.0.jar"
},
"policyViolations":
[
{
"constraintViolations":
[
{
"constraintId": "bfea4a16f0c34fa5853998e367f1c569",
"constraintName": "High risk CVSS score",
"reasons":
[
{
"reason": "Found security vulnerability CVE-2014-0050 with severity >= 7 (severity = 7.5)",
"reference": null
},
{
"reason": "Found security vulnerability CVE-2014-0050 with severity < 9 (severity = 7.5)",
"reference": null
}
]
}
],
"policyId": "5d9e1a8b839e435f8dcd00cc20c87e20",
"policyName": "Security-High",
"policyViolationId": "eddcaafac4474c49b15bacd2542c1c0f",
"threatLevel": 9
},
{
"constraintViolations":
[
{
"constraintId": "bfea4a16f0c34fa5853998e367f1c569",
"constraintName": "High risk CVSS score",
"reasons":
[
{
"reason": "Found security vulnerability CVE-2016-3092 with severity >= 7 (severity = 7.5)",
"reference": null
},
{
"reason": "Found security vulnerability CVE-2016-3092 with severity < 9 (severity = 7.5)",
"reference": null
}
]
}
],
"policyId": "5d9e1a8b839e435f8dcd00cc20c87e20",
"policyName": "Security-High",
"policyViolationId": "8219bc5c681e49d4aa6bc895f5f2090f",
"threatLevel": 9
},
{
"constraintViolations":
[
{
"constraintId": "bfea4a16f0c34fa5853998e367f1c569",
"constraintName": "High risk CVSS score",
"reasons":
[
{
"reason": "Found security vulnerability CVE-2023-24998 with severity >= 7 (severity = 7.5)",
"reference": null
},
{
"reason": "Found security vulnerability CVE-2023-24998 with severity < 9 (severity = 7.5)",
"reference": null
}
]
}
],
"policyId": "5d9e1a8b839e435f8dcd00cc20c87e20",
"policyName": "Security-High",
"policyViolationId": "617a8e9956f14be0ada31e991792425e",
"threatLevel": 9
},
{
"constraintViolations":
[
{
"constraintId": "41d9d137675d4445b71273f2202758b8",
"constraintName": "Medium risk CVSS score",
"reasons":
[
{
"reason": "Found security vulnerability sonatype-2014-0173 with severity >= 4 (severity = 5.3)",
"reference": null
},
{
"reason": "Found security vulnerability sonatype-2014-0173 with severity < 7 (severity = 5.3)",
"reference": null
}
]
}
],
"policyId": "f39af87aa13a4a55a10ecebd924eb4e0",
"policyName": "Security-Medium",
"policyViolationId": "ab2235f445cd43798088ccc37f023ead",
"threatLevel": 7
},
{
"constraintViolations":
[
{
"constraintId": "05ea46fb3ed149d084dcc8e6e61ca02c",
"constraintName": "Low risk CVSS score",
"reasons":
[
{
"reason": "Found security vulnerability CVE-2013-0248 with severity >= 0 (severity = 3.3)",
"reference": null
},
{
"reason": "Found security vulnerability CVE-2013-0248 with severity < 4 (severity = 3.3)",
"reference": null
}
]
}
],
"policyId": "034487b7ed3247d2b33307fcc6c75708",
"policyName": "Security-Low",
"policyViolationId": "9b4b0fcb83ce4705b075aadc954fbe7d",
"threatLevel": 3
},
{
"constraintViolations":
[
{
"constraintId": "70476a86871c4c5099b883ef51274082",
"constraintName": "Version is unpopular",
"reasons":
[
{
"reason": "Relative popularity was <= 10% (relative popularity = 1%)",
"reference": null
}
]
}
],
"policyId": "c5fa791ac71b4d80b3a7a593b1aa3ea9",
"policyName": "Architecture-Quality",
"policyViolationId": "9ba7f605b92e4714927f0d82f7e98857",
"threatLevel": 1
},
{
"constraintViolations":
[
{
"constraintId": "fd2e59808bb047f7a05b3d0d3d27d174",
"constraintName": "Version is old",
"reasons":
[
{
"reason": "Found component older than 5 years",
"reference": null
}
]
}
],
"policyId": "c5fa791ac71b4d80b3a7a593b1aa3ea9",
"policyName": "Architecture-Quality",
"policyViolationId": "45ce4e2b40dd458f93d37a88ce28f282",
"threatLevel": 1
}
],
"quarantineDate": null,
"quarantined": false
}
]
}Repository Firewall hashing strategy
Repository Firewall uses the SHA-1 hashing algorithm for component identification. This is either the whole SHA-1 hash or the SHA-1 truncated to the first 10 bytes or 20 first characters. This truncation method is used to improve performance when searching and indexing the database.
The hashing used by the Repository Firewall for supported ecosystems is classified into two categories: package files hashing and synthetic hashing.
Package File Hashing
Package file hashing involves creating a hash of the compressed package downloaded from pubic open-source ecosystems. Most supported ecosystems are in this category.
Maven, Pypi, Composer, RubyGems, Cocoapods, Nuget, Cran, Conan
The file hash may be generated by directly hashing the file or by accessing the hash from the open-source ecosystem website.
shasum /path/to/component
For the example above, you may visit Maven Central to access the sha1 directly from the repository. Example commons-fileupload.
Synthetic Hashes
In contrast, synthetic hashes are generated using elements other than the package file. For instance, the package/version combination is used for Golang, while MD5 checksums are employed for Conda packages.
Golang, Conda
For the Golang ecosystem, the SHA-1 hash is created using a string composed of the package name and version.
source + '/x/' + name + '@v' + version
Calculating the SHA1 of GoLang package named text and version 0.3.7
echo -n "golang.org/x/text@v0.3.7" | openssl sha1 > SHA1(stdin)= fe597b3fed5dbc388e7ce53c58b6de6bce5e104e
{
"format": "golang",
"components":[{
"packageUrl": "pkg:golang/golang.org/x/text@v0.3.7",
"sha1": "fe597b3fed5dbc388e7ce53c58b6de6bce5e104e"
}]
}For Conda, we use the MD5 checksum of the package to calculate the SHA-1. Find the MD5 checksum of a package by searching the package info using the conda search tool.
conda search --info <package-name>