diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index ceee77bca..b4f10fb60 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -3,26 +3,28 @@ VulnerableCode Overview ======================== -VulnerableCode is a work-in-progress towards a free and open vulnerabilities -database and the packages they impact and the tools to aggregate and correlate -these vulnerabilities. +VulnerableCode is a FOSS project that provides tools to build a database +of software vulnerabilities and the packages they impact. The tools +handle collecting, aggregating and correlating these vulnerabilities. +Our project also supports a public Cloud instance of this database – +VulnerableCode.io. Why VulnerableCode? ------------------- -The existing solutions are commercial proprietary vulnerability databases, which -in itself does not make sense because the data is about FOSS (Free and Open -Source Software). +Existing vulnerability database solutions are primarily commercial or +proprietary which does not make sense because the data is about FOSS +(Free and Open Source Software). -The National Vulnerability Database which is a primary centralized data source -for known vulnerabilities is not particularly well suited to address FOSS -security issues because: +The National Vulnerability Database, which is a primary centralized data +source for known vulnerabilities, is not particularly well suited to +address FOSS security issues because: 1. It predates the explosion of FOSS software usage -2. It's data format reflects a commercial vendor-centric point of view in part +2. Its data format reflects a commercial vendor-centric point of view in part due to the usage of `CPE `__ to map vulnerabilities to existing packages. -3. CPEs are just not designed to map FOSS to vulnerabilities owing to their +3. CPEs are not designed to map FOSS to vulnerabilities owing to their vendor-product centric semantics. This makes it really hard to answer the fundamental questions "Is package foo vulnerable" and "Is package foo vulnerable to vulnerability bar?" @@ -32,44 +34,38 @@ How does it work? VulnerableCode independently aggregates many software vulnerability data sources and supports data re-creation in a decentralized fashion. These data sources -(see complete list :ref:`here `) include security advisories -published by Linux and BSD distributions, application software package managers -and package repositories, FOSS projects, GitHub and more. Thanks to this -approach, the data is focused on specific ecosystems yet aggregated in a single -database that enables querying a richer graph of relations between multiple -incarnations of a package. Being specific increases the accuracy and validity +(see complete list +`here `__) +include security advisories published by Linux and BSD distributions, +application software package managers and package repositories, FOSS projects, +GitHub and more. Thanks to this approach, the data is focused on specific ecosystems and +aggregated in a single database that enables querying a richer graph of relations between multiple +representations of a package. Being specific increases the accuracy and validity of the data as the same version of an upstream package across different -ecosystems may or may not be vulnerable to the same vulnerability. +ecosystems may or may not be subject to the same vulnerability. -The packages are identified using Package URL `PURL -`__ as primary identifiers rather than -CPEs. This makes answers to questions such as "Is package foo vulnerable -to vulnerability bar?" much more accurate and easy to interpret. +In VulnerableCode, packages are identified using Package URL `PURL +`__ as the primary identifier instead of +a CPE. This makes answers to questions such as "Is package foo vulnerable +to vulnerability bar?" more accurate and easier to interpret. +The primary access to VulnerableCode data is through a REST API, but there +is also a Web UI for searching and browsing vulnerabilities by package +or by vulnerability. For the initial releases both access modes are +read-only, but our longer-term goal is to enable community curation of +the data including addition of new packages and vulnerabilities, and +reviewing and updating their relationships. -The primary access to the data is through a REST API. +*We also plan to mine for vulnerabilities that didn't receive any +exposure due to various reasons like, but not limited to, the complicated +procedure to obtain a CVE ID or not being able to classify a bug as a vulnerability.* -In addition, an emerging web interface goal is to support vulnerabilities data -browsing and search and progressively to enable community curation of the data -with the addition of new packages and vulnerabilities, and reviewing and -updating their relationships. -We also plan to mine for vulnerabilities which didn't receive any -exposure due to various reasons like but not limited to the complicated -procedure to receive CVE ID or not able to classify a bug as a security -compromise. +How can I contribute to VulnerableCode? +--------------------------------------- - -Is VulnerableCode being actively developed? -------------------------------------------- - -Yes -- VulnerableCode is a work in progress! Please stay in touch on our `Gitter channel `_; and if you have any feedback, feel free to `enter an issue in our GitHub repo `_. - - -Recent presentations --------------------- - -- `Open Source Summit 2020 `_ +Please get in touch on our `Gitter channel `__. +You can review or get the code and report issues at our `GitHub repo `__. .. Some of this documentation is borrowed from the metaflow documentation and is also under Apache-2.0