Skip to content

Commit

Permalink
feat: compare versions using ecosystem-specific semantics (#157)
Browse files Browse the repository at this point in the history
* feat: use spec compliant implementation to compare versions from packagist ecosystem

* refactor: use a map and common type to make it easier to implement ecosystem version comparators

* fix: remove build metadata when comparing build versions

* feat: implement proper semver v2 comparator

* feat: implement comparator for NuGet

* feat: implement comparator for RubyGems

* feat: implement comparator for Maven

* feat: implement comparator for PyPI

* feat: implement comparator for Debian

* test: improve reporting for `semantic` specs

* fix: minor bugs in RubyGems comparator

* fix: minor bugs in Packagist comparator

* fix: properly preserve original version string in parsing

* test: create scripts to generate semantic fixtures for ecosystems based off their respective osv dbs

* docs: update details about how comparisons are done

* fix: compare Maven versions with `sp` correctly

* feat: restructure `semantic` parser and comparator implementation

* feat: use `CompareAs` field to allow using different comparators for csvs

* feat: replace `compareComponent` with `Cmp` on `Components`

* refactor: move utilities around

* fix: support `Pub` ecosystem

* refactor: move stuff around

* refactor: deduplicate some switch statements
  • Loading branch information
G-Rath committed Nov 11, 2022
1 parent 9bfcd15 commit 573f2ca
Show file tree
Hide file tree
Showing 72 changed files with 59,772 additions and 1,050 deletions.
48 changes: 34 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,9 +81,9 @@ osv-detector --parse-as 'package-lock.json' path/to/my/file.lock
```

By default, the detector attempts to detect known vulnerabilities by checking
the versions of packages specified by the parsed lockfile against the versions
specified by the OSVs in the loaded OSV databases, using an internal
semver-based package that aims to minimize false negatives (see
the versions of packages specified by the OVSs in the loaded OSV databases,
comparing based on the version ordering rules for the specific ecosystem being
checked as closely as possible (see
[this section](#version-parsing-and-comparing) for more details about version
handling).

Expand Down Expand Up @@ -335,7 +335,7 @@ the detector doesn't know about, such as `NuGet`.
You can either pass in CSV rows:

```
osv-detector --parse-as csv-row 'npm,@typescript-eslint/types,5.13.0' 'Packagist,sentry/sdk,2.0.4'
osv-detector --parse-as csv-row 'npm,,@typescript-eslint/types,5.13.0' 'Packagist,sentry/sdk,2.0.4'
```

or you can specify paths to csv files:
Expand All @@ -344,25 +344,43 @@ or you can specify paths to csv files:
osv-detector --parse-as csv-file path/to/my/first-csv path/to/my/second-csv
```

Each CSV row must have at least three fields which hold the ecosystem, package
name, and version (or commit) respectively, and CSV files cannot contain a
header.
Each CSV row represents a package and is made up of at least four fields:

1. The ecosystem that the package is from, which is used as part of identifying
if an OSV is about the given package
- This does not have to be one of the ecosystems referenced in the detector,
or in the OSV specification
- This should be omitted if you are wanting to compare a commit using an API
database
2. The ecosystem whose version comparison semantics to use when determining if
an OSV applies to the given package
- This has to be an ecosystem for which the detector supports comparing
versions of; this field can be blank if the first field refers to an
ecosystem the detector supports comparing, otherwise it should be the
ecosystem whose version semantics most closely match that of your arbitrary
ecosystem
- This should be omitted if you are wanting to compare a commit using an API
database
3. The name of the package
4. The version of the package, or the SHA of a `git` commit
- If you are providing a commit, then you must leave the first two fields
empty and ensure an API-based database is loaded i.e. via `--use-api`

> **Warning**
>
> Do not include a header if you are using a CSV file
The `ecosystem` does _not_ have to be one listed by the detector as known,
meaning you can use any ecosystem that [osv.dev](https://osv.dev/) provides.

If the ecosystem field is empty, then the `version` field is expected to be a
commit. In this case, the `package` column is decorative as only the commit is
passed to the API.

> Remember to tell the detector to use the `osv.dev` API via the `--use-api`
> flag if you're wanting to check commits!
You can also omit the version to have the detector list all known
vulnerabilities in the loaded database that apply to the given package:

```
osv-detector --parse-as csv-row 'NuGet,Yarp.ReverseProxy,'
osv-detector --parse-as csv-row 'NuGet,,Yarp.ReverseProxy,'
```

While this uses the `--parse-as` flag, these are _not_ considered standard
Expand Down Expand Up @@ -417,8 +435,10 @@ The following packages were found in /path/to/my/Gemfile.lock:

## Version parsing and comparing

Versions are compared using an internal `semver` package which aims to support
any number of components followed by a build string.
Versions are compared using an internal `semantic` package which aims to support
compare versions accurately per the version semantics of each ecosystem, falling
back to a relaxed version of SemVer that supports unlimited number components
followed by a build string.

Components are numbers broken up by dots, e.g. `1.2.3` has the components
`1, 2, 3`. Anything that is not a number or a dot is considered to be the start
Expand Down
4 changes: 2 additions & 2 deletions fixtures/csvs-files/two-rows.csv
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
NuGet,Yarp.ReverseProxy,
npm,@typescript-eslint/types,5.13.0
NuGet,,Yarp.ReverseProxy,
npm,,@typescript-eslint/types,5.13.0
209 changes: 209 additions & 0 deletions generators/GenerateMavenVersions.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,209 @@
import org.apache.maven.artifact.versioning.ComparableVersion;

import org.json.JSONArray;
import org.json.JSONObject;

import java.io.*;
import java.net.URL;
import java.nio.channels.Channels;
import java.nio.channels.ReadableByteChannel;
import java.nio.charset.StandardCharsets;
import java.util.*;
import java.util.stream.Collectors;
import java.util.stream.IntStream;
import java.util.zip.ZipEntry;
import java.util.zip.ZipFile;

/**
* Script for generating a list of maven version comparison fixtures based off
* every version mentioned in the OSV Maven database, sorted using the native
* Maven implementation.
* <p>
* To run this, you need to ensure copies of the following libraries are present
* on the class path:
*
* <ul>
* <li><a href="https://search.maven.org/artifact/org.json/json/20220924/bundle"><code>json</code></a></li>
* <li><a href="https://search.maven.org/artifact/org.apache.maven/maven-artifact/3.8.6/jar"><code>maven-artifact</code></a></li>
* </ul>
* The easiest way to do this is by putting the jars into a <code>lib</code> subfolder and then running:
* <code>
* java -cp generators/lib/* generators/GenerateMavenVersions.java
* </code>
*/
public class GenerateMavenVersions {
public static String downloadMavenDb() throws IOException {
URL website = new URL("https://osv-vulnerabilities.storage.googleapis.com/Maven/all.zip");
String file = "./maven-db.zip";

ReadableByteChannel rbc = Channels.newChannel(website.openStream());

try(FileOutputStream fos = new FileOutputStream(file)) {
fos.getChannel().transferFrom(rbc, 0, Long.MAX_VALUE);
}

return file;
}

public static Map<String, List<String>> fetchPackageVersions() throws IOException {
String dbPath = downloadMavenDb();
List<JSONObject> osvs = loadOSVs(dbPath);

Map<String, List<String>> packages = new HashMap<>();

osvs.forEach(osv -> osv.getJSONArray("affected").forEach(aff -> {
JSONObject affected = (JSONObject) aff;

String pkgName = affected.getJSONObject("package").getString("name");

if(!affected.has("versions")) {
return;
}
JSONArray versions = affected.getJSONArray("versions");

packages.putIfAbsent(pkgName, new ArrayList<>());

if(versions.isEmpty()) {
return;
}

versions.forEach(version -> packages.get(pkgName).add((String) version));
}));

packages.forEach((key, _ignore) -> packages.put(
key,
packages.get(key)
.stream()
.distinct()
.sorted(Comparator.comparing(ComparableVersion::new))
.collect(Collectors.toList())
));

return packages;
}

public static List<JSONObject> loadOSVs(String pathToDbZip) throws IOException {
List<JSONObject> osvs = new ArrayList<>();

try(ZipFile zipFile = new ZipFile(pathToDbZip)) {
Enumeration<? extends ZipEntry> entries = zipFile.entries();

while(entries.hasMoreElements()) {
ZipEntry entry = entries.nextElement();
InputStream stream = zipFile.getInputStream(entry);

BufferedReader streamReader = new BufferedReader(new InputStreamReader(stream, StandardCharsets.UTF_8));
StringBuilder responseStrBuilder = new StringBuilder();

String inputStr;
while((inputStr = streamReader.readLine()) != null) {
responseStrBuilder.append(inputStr);
}
osvs.add(new JSONObject(responseStrBuilder.toString()));
}
}

return osvs;
}

public static void writeToFile(String outfile, List<String> lines) throws IOException {
try(PrintWriter writer = new PrintWriter(outfile, StandardCharsets.UTF_8)) {
lines.forEach(writer::println);
}
}

public static boolean compareVers(String version1, String op, String version2) {
ComparableVersion v1 = new ComparableVersion(version1);
ComparableVersion v2 = new ComparableVersion(version2);

int r = v1.compareTo(v2);

if(op.equals("=")) {
return r == 0;
}

if(op.equals("<")) {
return r < 0;
}

if(op.equals(">")) {
return r > 0;
}

throw new RuntimeException("unsupported comparison operator " + op);
}

public static void compareVersions(List<String> lines, String select) {
lines.forEach(line -> {
line = line.trim();

if(line.isEmpty() || line.startsWith("#") || line.startsWith("//")) {
return;
}

String[] parts = line.split(" ");
String v1 = parts[0];
String op = parts[1];
String v2 = parts[2];

boolean r = compareVers(v1, op, v2);

if(select.equals("failures") && r) {
return;
}

if(select.equals("successes") && !r) {
return;
}

String color = r ? "\033[92m" : "\033[91m";
String rs = r ? "T" : "F";

System.out.printf("%s%s\033[0m: \033[93m%s\033[0m\n", color, rs, line);
});
}

public static void compareVersionsInFile(String filepath, String select) throws IOException {
List<String> lines = new ArrayList<>();

try(BufferedReader br = new BufferedReader(new FileReader(filepath))) {
String line = br.readLine();

while(line != null) {
lines.add(line);
line = br.readLine();
}
}

compareVersions(lines, select);
}

public static List<String> generateVersionCompares(List<String> versions) {
return IntStream.range(1, versions.size()).mapToObj(i -> {
String currentVersion = versions.get(i);
String previousVersion = versions.get(i - 1);
String op = compareVers(currentVersion, "=", previousVersion) ? "=" : "<";

return String.format("%s %s %s", previousVersion, op, currentVersion);
}).collect(Collectors.toList());
}

public static List<String> generatePackageCompares(Map<String, List<String>> packages) {
return packages
.values()
.stream()
.map(GenerateMavenVersions::generateVersionCompares)
.flatMap(Collection::stream)
.distinct()
.collect(Collectors.toList());
}

public static void main(String[] args) throws IOException {
String outfile = "maven-versions-generated.txt";
Map<String, List<String>> packages = fetchPackageVersions();

writeToFile(outfile, generatePackageCompares(packages));

compareVersionsInFile(outfile, "failures");
}
}

0 comments on commit 573f2ca

Please sign in to comment.