Update README.md and MkDocs

Author: matteogreek

docs/contributing.md

@@ -1,59 +1,24 @@
 # How to contribute to project "KB"
 
-#### **Do you intend to contribute with new vulnerability data?**
+Welcome to the contribution guidelines for project "KB". This webpage provides information on how to contribute to our two different tools: [KayBee](kaybee.md) and [Prospector](prospector.md).
 
-A structured process to create and share vulnerability data is work in progress.
+## Kaybee
 
-For the time being, you can use `kaybee create <VULN.ID>` to generate a skeleton
-statement that you can then edit with a normal text editor.
+If you're interested in contributing to the development of Kaybee,
+the following pages provide instructions on setting up the development environment and how to contribute to our project.
 
-You can then create pull requests against the `vulnerability-data` branch in this repository
-or you can host the statements in your own repository (please do let us know if you choose
-this option so that we can benefit from your work by pulling your statements).
+- [Development Setup](kaybee/dev_setup.md)
+- [Contribution Guidelines](kaybee/guidelines.md)
 
-You will need to dedicate a branch to the statements: the branch must contain a
-top-level `statements` folder in which you can store your statements. You can
-refer to the [`vulnerability-data` branch in this
-repository](https://github.com/SAP/project-kb/tree/vulnerability-data) to see
-what is the expected structure.
+## Prospector
 
-Your statement should provide, at least, a vulnerability identifier (use the CVE
-identifier if it exists), the URL of the source code repository of the affected
-component and one or more identifiers of the commits used to fix the
-vulnerability.
+If you're interested in contributing to the development of Prospector,
+the following pages provide instructions on setting up the development environment and how to contribute to our project.
 
-#### **Did you find a bug?**
+- [Development Setup](prospector/dev_setup.md)
+- [Contribution Guidelines](prospector/issues.md)
 
-* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/sap/project-kb/issues).
-
-* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/sap/project-kb/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring.
-
-
-#### **Did you write a patch that fixes a bug?**
-
-* Open a new GitHub pull request with the patch.
-* Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
-* Add one or more test cases as appropriate
-* Make sure all other tests and checks still pass (that is, run `make check` in the `kaybee` folder; it should succeed)
-
-#### **Did you fix whitespace, format code, or make a purely cosmetic patch?**
-
-Changes that are cosmetic in nature and do not add anything substantial to the stability, functionality, or testability are accepted at this time.
-
-#### **Do you intend to add a new feature or change an existing one?**
-
-* Suggest your change by creating an issue  and start writing code in your own fork and make a PR when ready.
-Please make sure you provide tests for your code, and ensure you can successfully execute `make check` (in the `kaybee` folder)
-with no errors and that you include adequate documentation in your code.
-
-
-
-
-#### **Do you have questions about the source code?**
-
-* For now, file an issue (we consider that the need of clarifications at this stage indicates missing or inadequate documentation).
-
-#### **Do you want to contribute to the documentation?**
+## Do you want to contribute to the documentation?
 
 You are most welcome to do so, project "KB" needs every one of you to succeed, every drop matters!
 

docs/css/buttons.css

@@ -0,0 +1,5 @@
+/*.md-button .md-button--primary {
+    background-color: green;
+    color: #ffffff;
+    margin-right: 50px;
+}*/

docs/css/faq.css

@@ -1,26 +1,27 @@
-margin: 1.6rem 0;
-    span.toctitle {
+/*margin: 1.6rem 0;*/
+
+span.toctitle {
     font-size: 1.8rem;
     font-weight: 600;
     letter-spacing: -0.01em;
 }
 
-div.toc > ul  {
+div.toc>ul {
     margin: 0;
 }
 
-div.toc > ul > li {
+div.toc>ul>li {
     margin: 10px;
     list-style: none;
     font-weight: 800;
 }
 
-div.toc > ul > li > ul> li {
+div.toc>ul>li>ul>li {
     list-style: none;
     font-weight: 400;
 }
 
-div.toc > ul > li > ul> li:before {
+div.toc>ul>li>ul>li:before {
     content: "-";
     font-weight: 600;
     display: block;
@@ -31,4 +32,4 @@ div.toc > ul > li > ul> li:before {
 
 /* div.md-sidebar--secondary {
     /* display: none; */
-} */
+/*} */

docs/dev_docs.md

@@ -8,69 +8,41 @@
 [![REUSE status](https://api.reuse.software/badge/github.com/sap/project-kb)](https://api.reuse.software/info/github.com/sap/project-kb)
 [![Join the chat at https://gitter.im/project-kb/help](https://badges.gitter.im/project-kb/help.svg)](https://gitter.im/project-kb/help?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-`project KB` supports the creation, management and aggregation of a
-distributed, collaborative knowledge base of vulnerabilities that affect
+The goal of `Project KB` is to enable the creation, management and aggregation of a
+distributed, collaborative knowledge base of vulnerabilities affecting
 open-source software.
 
-This repository contains both a [tool](kaybee) and [vulnerability data](https://github.com/SAP/project-kb/tree/master/vulnerability-data).
+`Project KB` consists of [vulnerability data](https://github.com/SAP/project-kb/tree/main/vulnerability-data)
+as well as set of tools to support the mining, curation and management of such data.
 
-Additionally, the [MSR2019](https://github.com/SAP/project-kb/tree/master/MSR2019) folder contains the package associated with
-the paper we published at the Mining Software Repository conference in 2019 (see
-below).
+## Available Tools
+<div style="text-align: center;">
+ <div style="display: inline-block; margin-right: 20px;">
+  <a href="kaybee" class="md-button md-button--primary">Kaybee</a>
+ </div>
+ <div style="display: inline-block;">
+  <a href="prospector" class="md-button md-button--primary">Prospector</a>
+ </div>
+</div>
 
-## Why this project
+### Kaybee
 
-In order to feed [Eclipse Steady](https://github.com/eclipse/steady/) with fresh
-data, we have spent a considerable amount of time, in the past few years, mining
-and curating a knowledge base of vulnerabilities that affect open-source
-components. We know that other parties have been doing the same, in academia as
-well as in the industry. From this experience, we have learnt that with the
-growing size of open source ecosystems and the pace at which new vulnerabilities
-are discovered, the _old approach_ cannot scale. We are also more and more
-convinced that vulnerability knowledge-bases about open-source should be
-open-source themselves and adopt the same community-oriented model that governs
-the rest of the open-source ecosystem.
+KayBee is a vulnerability data management tool, it makes possible to fetch the vulnerability statements from this
+repository (or from any other repository) and export them to a number of
+formats, including a script to import them to a [Steady
+backend](https://github.com/eclipse/steady).
 
-These considerations have pushed us to release our vulnerability knowledge base
-in early 2019. In June 2020, we made a further step releasing tool support to
-make the creation, aggregation, and consumption of vulnerability data much
-easier.
+### Prospector
 
-We hope this will encourage more contributors to join our efforts to build a
-collaborative, comprehensive knowledge base where each party remains in control
-of the data they produce and of how they aggregate and consume data from the
-other sources.
+Prospector is a vulnerability data mining tool that aims at reducing the effort needed to find security fixes for known vulnerabilities in open source software repositories.
 
-### What can project "KB" be used for, in practice
+Given a vulnerability advisory and a software repository, it
+analyses them to produce a report in which commits are ranked
+according to the likelihood that they fix the vulnerability.
 
-(work in progress)
+## Vulnerability data
 
-Project "KB" consists essentially of two things: a tool and a knowledge base.
-
-The **tool** (`kaybee`) allows users to do the following:
-
-- create vulnerability statements; a vulnerability statement is a plain-text file in yaml format
-  that contains data about a given vulnerability, such as the commits that provide a fix for it,
-  a set of notes and references to related Web pages, a list of open-source components that
-  are directly affected by the vulnerability at hand, and so on.
-- fetch vulnerability statements from one or more remote sources (git repositories)
-- merge the content of multiple sources of statements, based on a conflict resolution policy
-- export the result of the merge operation to a variety of different formats
-
-The **knowledge base**, offers a set of vulnerability statements that can be consumed using the `kaybee` tool.
-It contents are kept in the dedicated branch `vulnerability-data`.
-
-## Getting started
-
-### Installing the `kaybee` tool
-
-### Importing vulnerability data in Eclipse Steady
-
-The steps that are required to import the knowledge base in [Eclipse
-Steady](https://github.com/eclipse/steady/) are described in [this
-tutorial](https://eclipse.github.io/steady/vuln_db/tutorials/vuln_db_tutorial/).
-Further information can be found
-[here](https://eclipse.github.io/steady/vuln_db/).
+The vulnerability data of Project KB are stored in textual form as a set of YAML files, in the [vulnerability-data branch](https://github.com/SAP/project-kb/tree/vulnerability-data).
 
 ## Publications
 
@@ -96,57 +68,33 @@ If you use the dataset for your research work, please cite it as:
 **MSR 2019 DATA SHOWCASE SUBMISSION**: please find [here the data and the
 scripts described in that paper](MSR2019)
 
-## Credits
-
-### Sparta project
+> If you wrote a paper that uses the data or the tools from this repository, please let us know (through an issue) and we'll add it to this list.
 
-The development of Project KB is partly supported by [EU-funded project Sparta](https://www.sparta.eu/).
-
-### 3rd party vulnerability data sources
-
-3rd party information from NVD and MITRE might have been used as input
-for compiling parts of this knowledge base. See MITRE's [Terms of
-Use](http://cve.mitre.org/about/termsofuse.html) for more information.
-See also [this notice](https://github.com/SAP/project-kb/tree/master/NOTICE.txt).
-
-
-## Features
-
-- Creation of vulnerability statements
-- Retrieval and reconciliation of statement from multiple repositories, based on
-  user-specified policies
-
-## Requirements
-
-None, the `kaybee` binary is self-contained. Binary versions for Windows, Linux,
-MacOS are available for [download](https://github.com/SAP/project-kb/releases).
-
-## Limitations
+## Credits
 
-This project is work-in-progress. The vulnerability knowledge base only contains
-information about vulnerabilities in Java and Python open source components.
+### EU-funded research projects
 
-## Known Issues
+The development of Project KB is partially supported by the following projects:
 
-The list of current issues is available
-[here](https://github.com/SAP/project-kb/issues).
+* [AssureMOSS](https://assuremoss.eu) (Grant No.952647).
+* [Sparta](https://www.sparta.eu/) (Grant No.830892).
 
-Feel free to open a new issue if you think you found a bug or if you have a
-feature request.
+### Vulnerability data sources
 
-## How to obtain support
+Vulnerability information from NVD and MITRE might have been used as input
+for building parts of this knowledge base. See MITRE's [CVE Usage license](http://cve.mitre.org/about/termsofuse.html) for more information.
 
-First, take a look at our documentation.
+## Limitations and Known Issues
 
-If you cannot find the answer to your questions, you may want to ask for help
-on this [Gitter channel](https://gitter.im/project-kb/help).
+This project is **work-in-progress**, you can find the list of known issues [here](https://github.com/SAP/project-kb/issues).
 
-If you think you found a bug, please create an [issue](https://github.com/SAP/project-kb/issues).
+Currently the vulnerability knowledge base only contains information about vulnerabilities in Java and Python open source components.
 
+## Support
 
-## License
+For the time being, please use [GitHub
+issues](https://github.com/SAP/project-kb/issues) to report bugs, request new features and ask for support.
 
-Copyright (c) 2020 SAP SE or an SAP affiliate company. All rights reserved.
+## Contributing
 
-This project is licensed under the Apache Software License, v.2 except as noted
-otherwise in the [LICENSE file](https://github.com/SAP/project-kb/blob/master/LICENSE.txt).
+See [How to contribute](contributing.md).

docs/index.md

@@ -1,4 +1,4 @@
-# Getting started with project "KB"
+# KayBee
 
 ## Installation
 
@@ -51,6 +51,8 @@ as in this example:
       branch: vulnerability-data
       rank: 10
 
+Please refer to the output of `kaybee help` and `kaybee <command> help` to
+know what flags and options are available.
 
 ## Retrieving vulnerability data
 
@@ -143,3 +145,6 @@ will probably come later on.
 ## Publishing
 
 *To be written....*
+
+## Contributing
+* [How to contribute](contributing.md)

docs/getting_started.md renamed to docs/kaybee.md

@@ -0,0 +1,2 @@
+# Development Setup
+Coming soon...

docs/kaybee/dev_setup.md

@@ -0,0 +1,51 @@
+# Contribution Guidelines
+
+## **Do you intend to contribute with new vulnerability data?**
+
+A structured process to create and share vulnerability data is work in progress.
+
+For the time being, you can use `kaybee create <VULN.ID>` to generate a skeleton
+statement that you can then edit with a normal text editor.
+
+You can then create pull requests against the `vulnerability-data` branch in this repository
+or you can host the statements in your own repository (please do let us know if you choose
+this option so that we can benefit from your work by pulling your statements).
+
+You will need to dedicate a branch to the statements: the branch must contain a
+top-level `statements` folder in which you can store your statements. You can
+refer to the [`vulnerability-data` branch in this
+repository](https://github.com/SAP/project-kb/tree/vulnerability-data) to see
+what is the expected structure.
+
+Your statement should provide, at least, a vulnerability identifier (use the CVE
+identifier if it exists), the URL of the source code repository of the affected
+component and one or more identifiers of the commits used to fix the
+vulnerability.
+
+## **Did you find a bug?**
+
+* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/sap/project-kb/issues).
+
+* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/sap/project-kb/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring.
+
+
+## **Did you write a patch that fixes a bug?**
+
+* Open a new GitHub pull request with the patch.
+* Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
+* Add one or more test cases as appropriate
+* Make sure all other tests and checks still pass (that is, run `make check` in the `kaybee` folder; it should succeed)
+
+## **Did you fix whitespace, format code, or make a purely cosmetic patch?**
+
+Changes that are cosmetic in nature and do not add anything substantial to the stability, functionality, or testability are accepted at this time.
+
+## **Do you intend to add a new feature or change an existing one?**
+
+Suggest your change by creating an issue  and start writing code in your own fork and make a PR when ready.
+Please make sure you provide tests for your code, and ensure you can successfully execute `make check` (in the `kaybee` folder)
+with no errors and that you include adequate documentation in your code.
+
+## **Do you have questions about the source code?**
+
+For now, file an issue (we consider that the need of clarifications at this stage indicates missing or inadequate documentation).