Skip to content

Commit 7f80a5f

Browse files
mjherzogmjherzog
committed
Complete first draft of getting-started-security
Signed-off-by: Michael Herzog <mjherzog@nexb.com>
1 parent 607db97 commit 7f80a5f

2 files changed

Lines changed: 81 additions & 16 deletions

File tree

‎website/docs/getting_started/getting_started-security.md‎

Lines changed: 77 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,36 +2,100 @@
22
Software security is a very broad domain. The AboutCode commmunity has focused
33
on the identification, reporting, triage and remediation of open source
44
vulnerabilities because this fits with our core expertise in software
5-
identification and SCA (Software Composition Analysis). We are, however, expanding our scope for software security with the recent addition of the **atom** and **chen" project to the AboutCode community, but most of our tools and data are related to software vulnerabilities.
6-
See also [atom and chen join AboutCode](https://aboutcode-org.github.io/www.aboutcode.org/blog/atom-chen-aboutcode).
5+
identification and SCA (Software Composition Analysis). We are, however,
6+
expanding our scope for software security with the recent addition of the
7+
**atom** and **chen" project to the AboutCode community, but most of our tools
8+
and data are related to software vulnerabilities. See also [atom and chen join AboutCode](https://aboutcode-org.github.io/www.aboutcode.org/blog/atom-chen-aboutcode).
79

8-
Note that our tools and data for software vulnerabilities expect that software
9-
will be identified with a [PURL (Package-URL)](https://package-url.github.io/www.packageurl.org/docs/purl/purl-spec-introduction).
10+
Note that AboutCode tools and data for software vulnerabilities expect that
11+
software will be identified with a [PURL (Package-URL)](https://package-url.github.io/www.packageurl.org/docs/purl/purl-spec-introduction).
1012

1113
## Identify vulnerabilities
1214
For the basic use case of identifying software vulnerabilities, AboutCode
13-
offers the VulnerableCode tools and data, the DejaCode application, ScanCode tools, and the PURL standard.
15+
offers the VulnerableCode tools and data, the DejaCode application, ScanCode
16+
tools, and the PURL standard.
1417

1518
- [VulnerableCode](https://vulnerablecode.readthedocs.io/en/latest/) provides
1619
a robust set of tools to build and access a database of known software
1720
vulnerabilities from upstream and downstream public data sources. The
1821
VulnerableCode tools collect, aggregate and correlated vulnerabilities and
1922
maps them to package versions using PURL.
2023

21-
AboutCode hosts a public VulnerableCode database at https://public2.vulnerablecode.io/ with a Web UI for queries and an API. Access is free
22-
but there are some restrictions on the frequency and volume of API
23-
requests. You can use the VulnerableCode tools to build, maintain and
24+
AboutCode hosts the public [VCIO](https://public2.vulnerablecode.io/)
25+
database with a Web UI for queries and an API. Access is free but there
26+
are some restrictions on the frequency and volume of API requests. You can
27+
use the VulnerableCode tools to build, maintain and
2428
use (Web UI and APIs) your own private VCIO database.
2529

26-
- [DejaCode] products, packages
30+
- [DejaCode](https://dejacode.readthedocs.io/en/latest/) integrates software
31+
vulnerability information from **VulnerableCode** and displays it for Products
32+
(inventory or SBOM items), Components and Packages. In each case there is a
33+
button to display only items with a known vulnerability. For each vulnerable
34+
Package DejaCode shows you the vulnerabilities that affect that
35+
Package along with information about Exploitability, Severity, Risk and
36+
Package version(s) that fix the Vulnerability. DejaCode also provides reports
37+
with this information.
2738

28-
- [ScanCode.io] ajfasdlj;kj `find_vulnerabilities pipeline
39+
- [ScanCode.io](https://scancodeio.readthedocs.io/en/latest/) After you run a
40+
scan that identifies software Package you can run the add-on pipeline
41+
`find_vulnerabilities` to add vulnerability data from **VulnerableCode** to
42+
your Scan project. Then you can view the vulnerability data in the UI, export
43+
it (JSON, XLSX, SPDX, CDX and other formats) or pull it from the API.
2944

45+
## Manage risk with aggregated vulnerability data
46+
[VulnerableCode](https://vulnerablecode.readthedocs.io/en/latest/) provides
47+
tools to create and maintain a database of known software vulnerabilities
48+
from public sources up and down the software supply chain. When evaluating the
49+
vulnerabilities for a package (or a single vulnerability) you will need
50+
information from upstream FOSS projects and downstream projects and distros
51+
that include software from upstream. For example, there may be significant
52+
differences in [CVSS](https://www.first.org/cvss/) Severity scores provided by
53+
different organizations With a **VulnerableCode** database like
54+
[VCIO](https://public2.vulnerablecode.io/) you can see the aggregated Severity
55+
information for each vulnerability in one place or pull it with the API for
56+
use in other systems.
3057

3158
## Triage vulnerabilities
32-
- Risk scoring
59+
One of the most complex tasks for managing vulnerabilities is to determine
60+
which vulnerabilities require your attention and in which order. [VulnerableCode](https://vulnerablecode.readthedocs.io/en/latest/) provides three key metrics for each
61+
vulnerability to assist with this triage:
62+
- _Exploitability_: Exploitability indicates the likelihood that a
63+
vulnerability in a software package could be used by malicious actors to
64+
compromise systems, applications, or networks. This metric is determined
65+
automatically based on the discovery of known exploits.
66+
- _Weighted Severity_: Weighted severity is the highest value calculated by
67+
multiplying each severity report by its corresponding weight, divided by 10.
68+
- _Risk_: Risk expressed as a number ranging from 0 to 10. It is calculated by
69+
multiplying the weighted severity and exploitability values, capped at a
70+
maximum of 10.
71+
72+
## Report exploitability with VEX
73+
A key new regulatory requirement for software publishers is to provide
74+
documentation about whether a vulnerability affects a product or component.
75+
The primary format for this information is VEX (Vulnerability Exploitability
76+
eXchange). VEX focuses on whether a vulnerability in a component can actually
77+
be exploited in a specific context.
78+
79+
There are several evolving VEX specifications including:
80+
- [CSAF](https://docs.oasis-open.org/csaf/csaf/v2.0/os/csaf-v2.0-os.html) from
81+
OASIS Open
82+
- [CycloneDX VEX](https://cyclonedx.org/capabilities/vex/) from the CycloneDX
83+
project
84+
- [OpenVEX](https://openssf.org/projects/openvex/) from OpenSSF. It is not
85+
clear which of these specifications will become primary, but they all cover
86+
similar data.
87+
88+
[DejaCode](https://dejacode.readthedocs.io/en/latest/) provides a Product
89+
(inventory or SBOM) feature to record the essential VEX data such as:
90+
- Status; The current state of an occurrence of a vulnerability, after
91+
automated or manual analysis.
92+
- Justification: The rationale for why the impact analysis state was asserted.
93+
- Responses: Can Not Fix, Rollback, Update, Will Not Fix, Workaround Available
94+
- Reach: Whether the vulnerability is reachable in the context of a package in
95+
the product being analyzed.
96+
97+
From **DejaCode** you can easily xport VEX information in CSAF, CycloneDX or
98+
OpenVEX format.
3399

34-
## Manage risks with aggregated vuln data
35100

36-
## Report exploitability with VEX
37101

‎website/docs/getting_started/getting_started-software-identification.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,8 @@ capabilities.
3838

3939
## Identify software packages and components
4040
For the basic use case of identifying software packages and components,
41-
AboutCode offers the DejaCode application, ScanCode tools, the PURLDB database and the [PURL standard](https://package-url.github.io/www.packageurl.org/docs/purl/purl-spec-introduction).
41+
AboutCode offers the DejaCode application, ScanCode tools, the PURLDB database
42+
and the [PURL standard](https://package-url.github.io/www.packageurl.org/docs/purl/purl-spec-introduction).
4243

4344
- [DejaCode](https://dejacode.readthedocs.io/en/latest/) is an enterprise-level
4445
application to automate managing your software assets including license
@@ -187,8 +188,8 @@ dependencies including:
187188
dependency data from package manifest and dependency lock files (e.g.,
188189
package.json or package-lock.json for npm. The reported package data includes
189190
the scope of a dependency and related attributes (runtime, optional, pinned,
190-
direct). Scancode uses many AboutCode libraries and utilities to identify software
191-
package dependencies including:
191+
direct). Scancode uses many AboutCode libraries and utilities to identify
192+
software package dependencies including:
192193

193194
- [dependency inspector](https://github.com/aboutcode-org/dependency-inspector/blob/main/README.rst)
194195
is a command line tool to generate package lockfiles and parsable package

0 commit comments

Comments
 (0)