cvss doc

cpe/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc(html_root_url = "https://docs.rs/nvd-rs/0.0.1")]
 // Package wfn provides a representation, bindings and matching of the Well-Formed CPE names as per
 // https://nvlpubs.nist.gov/nistpubs/Legacy/IR/nistir7695.pdf and
 // https://nvlpubs.nist.gov/nistpubs/Legacy/IR/nistir7696.pdf

cve/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc(html_root_url = "https://docs.rs/nvd-rs/0.0.1")]
 pub mod cve;
 pub mod error;
 pub mod node;

cvss/src/error.rs

@@ -13,8 +13,6 @@ pub enum CVSSError {
 
   #[error("invalid prefix for `{value}`")]
   InvalidPrefix { value: String },
-  #[error("Invalid CVE type `{value}`")]
-  InvalidCveType { value: String },
   #[error("Invalid CVSS `{value}` at {scope}")]
   InvalidCVSS { value: String, scope: String },
   #[error("invalid cvss version `{value}` ({expected})")]

cvss/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc(html_root_url = "https://docs.rs/nvd-rs/0.0.1")]
 // 通用漏洞评分系统
 // https://csrc.nist.gov/schema/nvd/feed/1.1-Beta/cvss-v3.x_beta.json
 // https://www.first.org/cvss/specification-document

cvss/src/metric.rs

@@ -1,3 +1,45 @@
+//! 7.4. Metric Values
+//!
+//! Each metric value has an associated constant which is used in the formulas, as defined in Table 16.
+//!
+//! **Table 16: Metric values**
+//!
+//!
+//! | Metric | Metric Value | Numerical Value |
+//! | --- | --- | --- |
+//! | Attack Vector / Modified Attack Vector | Network | 0.85 |
+//! |  | Adjacent | 0.62 |
+//! |  | Local | 0.55 |
+//! |  | Physical | 0.2 |
+//! | Attack Complexity / Modified Attack Complexity | Low | 0.77 |
+//! |  | High | 0.44 |
+//! | Privileges Required / Modified Privileges Required | None | 0.85 |
+//! |  | Low | 0.62 (or 0.68 if Scope / Modified Scope is Changed) |
+//! |  | High | 0.27 (or 0.5 if Scope / Modified Scope is Changed) |
+//! | User Interaction / Modified User Interaction | None | 0.85 |
+//! |  | Required | 0.62 |
+//! | Confidentiality / Integrity / Availability / Modified Confidentiality / Modified Integrity / Modified Availability | High | 0.56 |
+//! |  | Low | 0.22 |
+//! |  | None | 0 |
+//! | Exploit Code Maturity | Not Defined | 1 |
+//! |  | High | 1 |
+//! |  | Functional | 0.97 |
+//! |  | Proof of Concept | 0.94 |
+//! |  | Unproven | 0.91 |
+//! | Remediation Level | Not Defined | 1 |
+//! |  | Unavailable | 1 |
+//! |  | Workaround | 0.97 |
+//! |  | Temporary Fix | 0.96 |
+//! |  | Official Fix | 0.95 |
+//! | Report Confidence | Not Defined | 1 |
+//! |  | Confirmed | 1 |
+//! |  | Reasonable | 0.96 |
+//! |  | Unknown | 0.92 |
+//! | Confidentiality Requirement / Integrity Requirement / Availability Requirement | Not Defined | 1 |
+//! |  | High | 1.5 |
+//! |  | Medium | 1 |
+//! |  | Low | 0.5 |[](#body)
+//!
 use std::fmt::{Debug, Display};
 use std::str::FromStr;
 

cvss/src/v3.rs

@@ -1,3 +1,18 @@
+//!
+//! Common Vulnerability Scoring System version 3.1: Specification Document
+//! =======================================================================
+//!
+//!
+//! CVSS Version 3.1 Release
+//! ------------------------
+//!
+//! This page updates with each release of the CVSS standard. It is currently CVSS version 3.1, released in June 2019. If you wish to use a specific version of the Specification Document, use:
+//!
+//! *   [https://www.first.org/cvss/v3.1/specification-document](https://www.first.org/cvss/v3.1/specification-document) for CVSS version 3.1
+//! *   [https://www.first.org/cvss/v3.0/specification-document](https://www.first.org/cvss/v3.0/specification-document) for CVSS version 3.0
+//!
+//! * * *
+//!
 use crate::error::{CVSSError, Result};
 use crate::metric::Metric;
 use crate::v3::attack_complexity::AttackComplexityType;
@@ -20,33 +35,41 @@ pub mod privileges_required;
 pub mod scope;
 pub mod severity;
 pub mod user_interaction;
-
+///
+/// The Common Vulnerability Scoring System (CVSS) captures the principal technical characteristics of software, hardware and firmware vulnerabilities. Its outputs include numerical scores indicating the severity of a vulnerability relative to other vulnerabilities.
+///
+/// CVSS is composed of three metric groups: Base, Temporal, and Environmental. The Base Score reflects the severity of a vulnerability according to its intrinsic characteristics which are constant over time and assumes the reasonable worst case impact across different deployed environments. The Temporal Metrics adjust the Base severity of a vulnerability based on factors that change over time, such as the availability of exploit code. The Environmental Metrics adjust the Base and Temporal severities to a specific computing environment. They consider factors such as the presence of mitigations in that environment.
+///
+/// Base Scores are usually produced by the organization maintaining the vulnerable product, or a third party scoring on their behalf. It is typical for only the Base Metrics to be published as these do not change over time and are common to all environments. Consumers of CVSS should supplement the Base Score with Temporal and Environmental Scores specific to their use of the vulnerable product to produce a severity more accurate for their organizational environment. Consumers may use CVSS information as input to an organizational vulnerability management process that also considers factors that are not part of CVSS in order to rank the threats to their technology infrastructure and make informed remediation decisions. Such factors may include: number of customers on a product line, monetary losses due to a breach, life or property threatened, or public sentiment on highly publicized vulnerabilities. These are outside the scope of CVSS.
+///
+/// The benefits of CVSS include the provision of a standardized vendor and platform agnostic vulnerability scoring methodology. It is an open framework, providing transparency to the individual characteristics and methodology used to derive a score.
+///
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[serde(rename_all = "camelCase")]
 pub struct CVSS {
-  // 版本： 3.0 和 3.1
+  /// Version 版本： 3.0 和 3.1
   pub version: Version,
-  // 向量: "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H"
+  /// 向量: "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H"
   pub vector_string: String,
-  // 访问途径（AV）
+  /// [`AttackVectorType`] 访问途径（AV）
   pub attack_vector: AttackVectorType,
-  // 攻击复杂度（AC）
+  /// [`AttackComplexityType`] 攻击复杂度（AC）
   pub attack_complexity: AttackComplexityType,
-  // 所需权限（PR）
+  /// [`PrivilegesRequiredType`] 所需权限（PR）
   pub privileges_required: PrivilegesRequiredType,
-  // 用户交互（UI）
+  /// [`UserInteractionType`] 用户交互（UI）
   pub user_interaction: UserInteractionType,
-  // 影响范围（S）
+  /// [`ScopeType`] 影响范围（S）
   pub scope: ScopeType,
-  // 机密性影响（C）
+  /// [`ConfidentialityImpactType`] 机密性影响（C）
   pub confidentiality_impact: ConfidentialityImpactType,
-  // 完整性影响（I）
+  /// [`IntegrityImpactType`] 完整性影响（I）
   pub integrity_impact: IntegrityImpactType,
-  // 可用性影响（A）
+  /// [`AvailabilityImpactType`] 可用性影响（A）
   pub availability_impact: AvailabilityImpactType,
-  // 基础评分
+  /// 基础评分
   pub base_score: f32,
-  // 基础评级
+  /// [`SeverityType`] 基础评级
   pub base_severity: SeverityType,
 }
 
@@ -55,7 +78,22 @@ impl CVSS {
   fn update_severity(&mut self) {
     self.base_severity = SeverityType::from(self.base_score)
   }
-  // https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator
+  /// https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator
+  /// 7.1. Base Metrics Equations
+  /// The Base Score formula depends on sub-formulas for Impact Sub-Score (ISS), Impact, and Exploitability, all of which are defined below:
+  ///
+  /// | ISS = | 1 - \[ (1 - Confidentiality) × (1 - Integrity) × (1 - Availability) \] |
+  /// | --- | --- |
+  /// | Impact = |  |
+  /// | If Scope is Unchanged | 6.42 × ISS |
+  /// | If Scope is Changed | 7.52 × (ISS - 0.029) - 3.25 × (ISS - 0.02)15 |
+  /// | Exploitability = | 8.22 × AttackVector × AttackComplexity × |
+  /// |  | PrivilegesRequired × UserInteraction |
+  /// | BaseScore = |  |
+  /// | If Impact \\<= 0 | 0, _else_ |
+  /// | If Scope is Unchanged | Roundup (Minimum \[(Impact + Exploitability), 10\]) |
+  /// | If Scope is Changed | Roundup (Minimum \[1.08 × (Impact + Exploitability), 10\]) |[](#body)
+  ///
   fn update_score(&mut self) {
     let exploit_ability_score = self.exploit_ability_score();
     let impact_score_scope = self.impact_score();
@@ -72,10 +110,18 @@ impl CVSS {
     };
     self.base_score = base_score;
   }
-  // Roundup保留小数点后一位，小数点后第二位大于零则进一。 例如, Roundup(4.02) = 4.1; 或者 Roundup(4.00) = 4.0
+  /// Roundup保留小数点后一位，小数点后第二位大于零则进一。 例如, Roundup(4.02) = 4.1; 或者 Roundup(4.00) = 4.0
+  ///
   /// Where “Round up” is defined as the smallest number,
   /// specified to one decimal place, that is equal to or higher than its input. For example,
   /// Round up (4.02) is 4.1; and Round up (4.00) is 4.0.
+  ///
+  /// 1.  `function Roundup (input):`
+  /// 2.  `    int_input = round_to_nearest_integer (input * 100000)`
+  /// 3.  `    if (int_input % 10000) == 0:`
+  /// 4.  `        return int_input / 100000.0`
+  /// 5.  `    else:`
+  /// 6.  `        return (floor(int_input / 10000) + 1) / 10.0`
   fn roundup(&self, base_score: f32) -> f32 {
     let score_int = (base_score * 100_000.0) as u32;
     if score_int % 10000 == 0 {

cvss/src/v3/attack_complexity.rs

@@ -1,16 +1,41 @@
+//! ### 2.1.2. Attack Complexity (AC)
+//!
+//! This metric describes the conditions beyond the attacker’s control that must exist in order to exploit the vulnerability. As described below, such conditions may require the collection of more information about the target, or computational exceptions. Importantly, the assessment of this metric excludes any requirements for user interaction in order to exploit the vulnerability (such conditions are captured in the User Interaction metric). If a specific configuration is required for an attack to succeed, the Base metrics should be scored assuming the vulnerable component is in that configuration. The Base Score is greatest for the least complex attacks. The list of possible values is presented in Table 2.
+//!
+//! **Table 2: Attack Complexity**
+//!
+//! | Metric Value | Description |
+//! | --- | --- |
+//! | Low (L) | Specialized access conditions or extenuating circumstances do not exist. An attacker can expect repeatable success when attacking the vulnerable component. |
+//! | High (H) | A successful attack depends on conditions beyond the attacker's control. That is, a successful attack cannot be accomplished at will, but requires the attacker to invest in some measurable amount of effort in preparation or execution against the vulnerable component before a successful attack can be expected.\[^2\] For example, a successful attack may depend on an attacker overcoming any of the following conditions:<br>*   The attacker must gather knowledge about the environment in which the vulnerable target/component exists. For example, a requirement to collect details on target configuration settings, sequence numbers, or shared secrets.<br>*   The attacker must prepare the target environment to improve exploit reliability. For example, repeated exploitation to win a race condition, or overcoming advanced exploit mitigation techniques.<br>*   The attacker must inject themselves into the logical network path between the target and the resource requested by the victim in order to read and/or modify network communications (e.g., a man in the middle attack).|
+//!
+//! _Scoring Guidance_: When deciding between Network and Adjacent, if an attack can be launched over a wide area network or from outside the logically adjacent administrative network domain, use Network. Network should be used even if the attacker is required to be on the same intranet to exploit the vulnerable system (e.g., the attacker can only exploit the vulnerability from inside a corporate network).
+//!
 use crate::error::{CVSSError, Result};
 use crate::metric::Metric;
 use serde::{Deserialize, Serialize};
 use std::fmt::{Display, Formatter};
 use std::str::FromStr;
 
-// AC
+/// Attack Complexity (AC) 攻击复杂度
+///
+/// 攻击复杂度为攻击者无法控制的条件，这些条件必须存在才能攻击脆弱组件。
+/// 如下文所述，这些条件可能需要预先收集有关目标或系统的配置或计算异常等更多信息。
+///
+/// > The Attack Complexity metric describes the conditions beyond the attacker's control that must
+/// > exist in order to exploit the vulnerability. As described below, such conditions may require
+/// > the collection of more information about the target, the presence of certain system
+/// > configuration settings, or computational exceptions.
 #[derive(Clone, PartialEq, Debug, Deserialize, Serialize)]
 #[serde(rename_all = "UPPERCASE")]
 pub enum AttackComplexityType {
-  // AC:H
+  /// High(H) 高复杂度
+  ///
+  /// 攻击无法随意完成，攻击者在攻击成功之前，需要对脆弱组件投入大量的准备。
   High,
-  // AC:L
+  /// Low(L) 低复杂度
+  ///
+  /// 攻击者可以随意攻击，不存在惩罚机制。
   Low,
 }
 impl Display for AttackComplexityType {

cvss/src/v3/attack_vector.rs

@@ -1,23 +1,54 @@
+//! ### 2.1.1. Attack Vector (AV)
+//!
+//! This metric reflects the context by which vulnerability exploitation is possible. This metric value (and consequently the Base Score) will be larger the more remote (logically, and physically) an attacker can be in order to exploit the vulnerable component. The assumption is that the number of potential attackers for a vulnerability that could be exploited from across a network is larger than the number of potential attackers that could exploit a vulnerability requiring physical access to a device, and therefore warrants a greater Base Score. The list of possible values is presented in Table 1.
+//!
+//! **Table 1: Attack Vector**
+//!
+//! | Metric Value | Description |
+//! | --- | --- |
+//! | Network (N) | The vulnerable component is bound to the network stack and the set of possible attackers extends beyond the other options listed below, up to and including the entire Internet. Such a vulnerability is often termed “remotely exploitable” and can be thought of as an attack being exploitable _at the protocol level_ one or more network hops away (e.g., across one or more routers). An example of a network attack is an attacker causing a denial of service (DoS) by sending a specially crafted TCP packet across a wide area network (e.g., CVE‑2004‑0230). |
+//! | Adjacent (A) | The vulnerable component is bound to the network stack, but the attack is limited _at the protocol level_ to a logically adjacent topology. This can mean an attack must be launched from the same shared physical (e.g., Bluetooth or IEEE 802.11) or logical (e.g., local IP subnet) network, or from within a secure or otherwise limited administrative domain (e.g., MPLS, secure VPN to an administrative network zone). One example of an Adjacent attack would be an ARP (IPv4) or neighbor discovery (IPv6) flood leading to a denial of service on the local LAN segment (e.g., CVE‑2013‑6014). |
+//! | Local (L) | The vulnerable component is not bound to the network stack and the attacker’s path is via read/write/execute capabilities. Either: <br>*   the attacker exploits the vulnerability by accessing the target system locally (e.g., keyboard, console), or remotely (e.g., SSH); _or_<br>*   the attacker relies on User Interaction by another person to perform actions required to exploit the vulnerability (e.g., using social engineering techniques to trick a legitimate user into opening a malicious document).|
+//! | Physical (P) | The attack requires the attacker to physically touch or manipulate the vulnerable component. Physical interaction may be brief (e.g., evil maid attack\[^1\]) or persistent. An example of such an attack is a cold boot attack in which an attacker gains access to disk encryption keys after physically accessing the target system. Other examples include peripheral attacks via FireWire/USB Direct Memory Access (DMA). |
+//!
+//! _Scoring Guidance_: When deciding between Network and Adjacent, if an attack can be launched over a wide area network or from outside the logically adjacent administrative network domain, use Network. Network should be used even if the attacker is required to be on the same intranet to exploit the vulnerable system (e.g., the attacker can only exploit the vulnerability from inside a corporate network).
+//!
+
 use crate::error::{CVSSError, Result};
 use crate::metric::Metric;
 use serde::{Deserialize, Serialize};
 use std::fmt::{Display, Formatter};
 use std::str::FromStr;
 
-// AV
+/// Attack Vector(AV) 攻击途径
+///
+/// > 该指标反映了攻击脆弱组件的环境可能。该度量值（以及相应的基本分数）将越大，
+/// > 攻击者攻击脆弱组件的距离（逻辑上和物理上）就越远。
+///
+/// > This metric reflects the context by which vulnerability exploitation is possible.
+/// > This metric value (and consequently the Base score) will be larger the more remote (logically,
+/// > and physically) an attacker can be in order to exploit the vulnerable component.
 #[derive(Clone, PartialEq, Debug, Deserialize, Serialize)]
 #[serde(rename_all = "SCREAMING_SNAKE_CASE")]
 pub enum AttackVectorType {
-  // AV:N
+  /// Network(N) 远程网络
+  ///
+  /// 可远程利用，即此脆弱组件可被一个以上网络跃点的距离进行攻击（例如，跨路由器的第3层边界）。
   Network,
-  // AV:A
+  /// Adjacent Network(A) 相邻网络
+  ///
+  /// 攻击仅限于同一共享物理（如蓝牙、IEEE 802.11）或逻辑（如本地IP子网）网络，并且不能跨OSI第3层边界（如路由器）执行。
   AdjacentNetwork,
-  // AV:L
+  /// Local(L) 本地
+  ///
+  /// 攻击者只能通过本地读/写/执行功能进行攻击。在某些情况下，攻击者可能在本地登录以攻击脆弱组件，或者可能依赖用户交互来执行恶意文件。
   Local,
-  // AV:P
+  /// Physical(P) 物理
+  ///
+  /// 攻击者只能通过物理方式接触或操作脆弱组件，例如将外围设备连接到系统。
   Physical,
 }
-
+///
 impl Display for AttackVectorType {
   fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
     write!(f, "{}:{}", Self::NAME, self.as_str())