Go to file
Stanislav Dashevskyi 80d021449e
Create LICENSE
2019-05-31 10:11:32 +02:00
molerat Fix the "--output-file" option 2018-07-26 11:45:17 +02:00
repoman Update command line help message 2017-09-04 13:19:44 +02:00
.gitignore Added the modules and everything 2017-08-24 17:37:25 +02:00
LICENSE Create LICENSE 2019-05-31 10:11:32 +02:00
README.md README.md edited online with Bitbucket 2018-07-25 14:58:46 +00:00
pom.xml Added the modules and everything 2017-08-24 17:37:25 +02:00

README.md

About
About

This is a project for collecting the vulnerability evidence from source code repositories. The project has a collection of tools that allows to identify and extract the potentially vulnerable coding (using a commit that fixed a CVE), and track its origins in the repository history to identify the versions that are likely not affected by a CVE.

The project consists of two parts:

  1. "repoman" - a simple program slicer for Java source code.

  2. "molerat" - a library that is using "repoman" and other methods to identify and track the potentially vulnerable coding.


Prerequisites

  1. Java compiler and runtime (tested with jdk 1.8).

  2. Maven (tested with version 3.5.0)

  3. MongoDB (tested with version 3.4)

    • make sure the mongodb service is running

Building and packaging

Building with Maven is pretty straightforward. The following commands are available:

  1. "mvn compile" - automatically downloads the dependencies and builds the entire project tree.

  2. "mvn package" - same as the previous command, but also creates executable jar files for "repoman" and "molerat" that can be found in the "target" folder of each project.

  3. "mvn clean" - deletes all temporary folders.


Usage

The project can be compiled into an executable jar library: 1. Execute the "mvn package" command 2. Navigate to the "./molerat/target" folder 3. Run it with "java -jar molerat.jar" (this command will display the help message).

Currently, it is possible to run the analysis by either specifying all parameters (such as repository path, tracker type, etc.) manually, or by providing a .csv file, where each line corresponds to one vulnerability to be analyzed, and contains the following fields separated with commas:

1. Project name  (e.g., "Tomcat")
2. CVE identifier (e.g., "CVE-2014-0230")
3. Repository type (either "git" for Git, or "svn" for Apache Subversion)
4. Path to the working copy of the repository (e.g., "/home/user/tomcat")
5. A revision/commit id of the vulnerability fix (e.g., "e28dd578fad90a6d5726ec34f3245c9f99d909a5A")
6. The name of a method for extracting the vulnerability evidence (e.g., "SliceDecayVulnerabilityEvidenceTracker")

NOTE: the list of available trackers can be shown by running the "java -jar molerat.jar --list-trackers" command

IMPORTANT: if you are running the analysis using a .csv input file, please make sure that the fields are specified in the exact order as shown above.


MongoDB database

There is no access control for the database, just make sure that the "bindIp" setting is set to "127.0.0.1" which allows only local access (typically, this setting is enabled by default, but you might consult "https://docs.mongodb.com/manual/administration/configuration/" webpage to make sure).

The database has following collections and relationships between them:

  1. "projects" -> the collection that lists all projects for which the analysis was performed ("projects" has one-to-many relationship with "vulns")
db.projects.findOne();
{ 
	_id : "",  					-> the id of a project (bson id)
	name : "",					-> the name of a project (e.g., "Tomcat")
	repo_type : "",				-> the type of its source repository (e.g., "git")
	repo_path : "",				-> the path of the repository (e.g., "/home/user/tomcat")
	vulns : [					-> the list of CVEs for which an analysis was performed 
		vuln_id : "",					(e.g,. "CVE-2014-0230", ...)
		...
	]
}
  1. "vulns" -> the collection that lists all CVEs for which the analysis was performed ("vulns" has one-to-gazillion relationship with "entries")
db.vulns.findOne();
{	
	_id : "",					-> the id of a CVE (bson id)
	cve : "",					-> the name of a CVE
	owner_id : "",				-> the bson id of a corresponding project
	fix_commit : "",			-> the id of a commit that fixed the CVE
}
  1. "entries" -> the collection that lists vulnerability evidence entries
db.entries.findOne();
{
	_id : "",					-> the id of an evicence entry (bson id)
	owner_id : "",				-> the id of a corresponding CVE
	revision : "",				-> the current commit/revision to which the entry belongs
	revision_distance : "",		-> this number indincates how far the current revision is from fix
	file_path : "",				-> the path of a file to which the entry belongs
	container : "",				-> the method/constructor to which the entry belongs
	line_number : "",			-> the number of the line of code 
	line_contents : ""			-> the contents of the line of code 
}