Update MkDocs index and prospector pages

matteogreek · copernico · commit 6bd09eb58636 · 2023-05-29T17:35:30.000+02:00
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -1,14 +1,6 @@
 # How to contribute to project "KB"
 
-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).
-
-## Kaybee
-
-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.
-
-- [Development Setup](kaybee/dev_setup.md)
-- [Contribution Guidelines](kaybee/guidelines.md)
+Welcome to the contribution guidelines for project "KB". This webpage provides information on how to contribute to our two different tools: [Prospector](prospector.md) and [KayBee](kaybee.md).
 
 ## Prospector
 
@@ -18,10 +10,18 @@ the following pages provide instructions on setting up the development environme
 - [Development Setup](prospector/dev_setup.md)
 - [Contribution Guidelines](prospector/issues.md)
 
+## Kaybee
+
+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.
+
+- [Development Setup](kaybee/dev_setup.md)
+- [Contribution Guidelines](kaybee/guidelines.md)
+
 ## 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!
 
-Thanks! :heart: :heart: :heart:
+Thanks!
 
 The project "KB" team
diff --git a/docs/index.md b/docs/index.md
@@ -18,20 +18,13 @@ as well as set of tools to support the mining, curation and management of such d
 ## 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>
+  <a href="prospector" class="md-button md-button--primary">Prospector</a>
  </div>
  <div style="display: inline-block;">
-  <a href="prospector" class="md-button md-button--primary">Prospector</a>
+  <a href="kaybee" class="md-button md-button--primary">Kaybee</a>
  </div>
 </div>
 
-### Kaybee
-
-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).
-
 ### Prospector
 
 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.
@@ -40,6 +33,14 @@ 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.
 
+### Kaybee
+
+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).
+
+
 ## Vulnerability data
 
 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).
diff --git a/docs/prospector.md b/docs/prospector.md
@@ -4,7 +4,7 @@
     Prospector is a research prototype,
     currently under development: the instructions below are intended for development, testing and demonstration purposes only!
 
-    :exclamation: Please note that **Windows is not supported** while WSL and WSL2 are fine.
+    Please note that **Windows is not supported** while WSL and WSL2 are fine.
 
 Prospector is a tool to reduce the effort needed to find security fixes for
 *known* vulnerabilities in open source software repositories.
@@ -33,7 +33,34 @@ cd project-kb/prospector
 ```
 The bash script builds and starts the required Docker containers. Once the building step is completed, the script will show the list of available options.
 
-4. Try the following example:
+
+| Option                                                                                      | Description                                                                               |
+| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `vuln_id`                                                                                   | ID of the vulnerability to analyze                                                        |
+| `-h`, `--help`                                                                              | Show help message and exit                                                                |
+| `--repository REPOSITORY`                                                                   | Git repository URL                                                                        |
+| `--preprocess-only`                                                                         | Perform commit preprocessing only                                                         |
+| `--pub-date PUB_DATE`                                                                       | Publication date of the advisory                                                          |
+| `--description DESCRIPTION`                                                                 | Advisory description                                                                      |
+| `--max-candidates MAX_CANDIDATES`                                                           | Maximum number of candidates to consider                                                  |
+| `--version-interval VERSION_INTERVAL`                                                       | Version or tag interval X:Y to consider                                                   |
+| `--modified-files MODIFIED_FILES`                                                           | Names (or partial names) comma-separated that the commits are supposed to modify          |
+| `--filter-extensions FILTER_EXTENSIONS`                                                     | Filter out commits that do not modify at least one file with this extension               |
+| `--keywords KEYWORDS`                                                                       | Consider these specific keywords                                                          |
+| `--use-nvd`, `--no-use-nvd`                                                                 | Get data from NVD or not                                                                  |
+| `--fetch-references`                                                                        | Fetch content of references linked from the advisory                                      |
+| `--backend BACKEND`                                                                         | URL of the backend server                                                                 |
+| `--use-backend {always,never,optional}`                                                     | Use the backend server or not                                                             |
+| `--report {html,json,console,all}`                                                          | Format of the report (options: console, json, html, all)                                  |
+| `--report-filename REPORT_FILENAME`                                                         | File to save the report                                                                   |
+| `-c CONFIG`, `--config CONFIG`                                                              | Configuration file                                                                        |
+| `-p`, `--ping`                                                                              | Ping the server to check if it's online                                                   |
+| `-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}`, `--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}` | Set the logging level                                                                     |
+| `--ignore-refs IGNORE_REFS`                                                                 | Whether to ignore the fact that the fixing commit is reachable directly from the advisory |
+
+
+
+1. Try the following example:
 ```
 ./run_prospector.sh CVE-2020-1925 --repository https://github.com/apache/olingo-odata4
 ```
@@ -43,34 +70,38 @@ By default, Prospector saves the results in a HTML file named *prospector-report
 ???+ success
     Open the *prospector-report.html* file in a web browser to view what Prospector was able to find!
 
+<figure markdown>
+  ![Image title](report_casestudy_complete.png){ width="600" }
+  <figcaption>Prospector Report for CVE-2020-1925</figcaption>
+</figure>
+
 ## Tool Demostration
 
 ### Video Recording
 <iframe width="560" height="315" src="https://www.youtube.com/<IDHERE>" frameborder="0" allowfullscreen></iframe>
 
 A video recording of the tool demo is also available [here](https://zenodo.org/record/7974442)
 
-### Outline of the Demo
 The steps shown in the video are the following:
 
 1. Cloning the [project “KB”](https://github.com/SAP/project-kb) GitHub repository
 2.  Execution of the script *run_prospector.sh* from the *prospector* subfolder. The script automatically builds and starts all the necessary docker containers
 3.  The command line flags are shown on the screen; for the demo, we use the strictly
 required inputs only, which are: *(A)* a vulnerability identifier and *(B)* the URL of the source code
 repository of the project affected by the vulnerability
-4. As illustrative example, Prospector is executed on *CVE-2020-1925* and the *Apache Olingo*
+1. As illustrative example, Prospector is executed on *CVE-2020-1925* and the *Apache Olingo*
 repository. As the tool runs, we give a high-level explanation of the processing it performs
 (advisory record extraction, candidate commits retrieval and processing, rule application, report
 generation).
-5. The report generated at the end of the previous step is shown and its key elements are
+1. The report generated at the end of the previous step is shown and its key elements are
 described.
-6. We highlight the fact that the advisory content is processed to extract important tokens
+1. We highlight the fact that the advisory content is processed to extract important tokens
 (keywords, file names, etc.).
-7. We explain that commits are ranked by their relevance, which is computed by applying a
+1. We explain that commits are ranked by their relevance, which is computed by applying a
 set of rules to each of them. The sum of the weights of the rules that match a commit determine
 its relevance. The list of commits shown in the report can be filtered by a applying a relevance
 threshold using a slider.
-8. As a concrete example, we point out that the tool detected that the first commit in the list
+1. As a concrete example, we point out that the tool detected that the first commit in the list
 modifies a class that is mentioned in the textual description of the advisory.
 
 ## Contributing
diff --git a/docs/report_casestudy_complete.png b/docs/report_casestudy_complete.png
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -43,6 +43,7 @@ markdown_extensions:
       custom_checkbox: true
   - pymdownx.tilde
   - attr_list
+  - md_in_html
 
 
 # Customization
