Updated README.md
This commit is contained in:
parent
ab3a633c0c
commit
6eb6c7caba
124
README.md
124
README.md
|
@ -0,0 +1,124 @@
|
|||
--------------------
|
||||
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
|
||||
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", ...)
|
||||
...
|
||||
]
|
||||
}
|
||||
|
||||
2. "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
|
||||
}
|
||||
|
||||
|
||||
3. "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
|
||||
}
|
Loading…
Reference in New Issue