Skip to main content

solve/
component.rs

1//! The four primary components, each producing a total in `0.0..=10.0`.
2
3use crate::length::CodeLength;
4use crate::score::Score;
5use crate::taxonomy::{Cwe, Domain, Technique};
6
7/// Denominator that maps the code-length and attack-surface pair onto a `0..=1` multiplier.
8const EXPLORATION_DIVISOR: f64 = 20.0;
9
10/// How hard it is to read the supplied code and orient within it, before any bug hunting.
11#[derive(Debug, Clone, PartialEq, Eq)]
12#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
13pub struct CodeAnalysis {
14    /// Effort to reach a fully readable state — deobfuscation, decompilation.
15    pub readability: Score,
16    /// Effort to understand what the relevant code does, assuming it is fully readable.
17    pub complexity: Score,
18    /// How much code there is to read.
19    pub length: CodeLength,
20    /// How much of it is actually in scope for the bug hunt.
21    pub attack_surface: Score,
22}
23
24impl CodeAnalysis {
25    /// Cost of navigating to the interesting code: `readability × (length + surface) / 20`.
26    #[must_use]
27    pub fn exploration(&self) -> Score {
28        let breadth = self.length.score().get() + self.attack_surface.get();
29        Score::clamped(self.readability.get() * breadth / EXPLORATION_DIVISOR)
30    }
31
32    /// `round1(exploration / 3 + complexity × 2/3)`.
33    #[must_use]
34    pub fn total(&self) -> Score {
35        Score::clamped(self.exploration().get() / 3.0 + self.complexity.get() * 2.0 / 3.0).rounded()
36    }
37}
38
39/// How hard it is to find the bug, given that the code is already understood.
40#[derive(Debug, Clone, PartialEq, Eq)]
41#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
42pub struct VulnerabilityDiscovery {
43    /// The distinct weakness classes that must be found — ideally one per vulnerability.
44    /// Only the length feeds the arithmetic.
45    pub cwes: Vec<Cwe>,
46    /// Sophistication of the vulnerability, or of the whole chain when several are needed.
47    pub complexity: Score,
48    /// How far apart the code paths that reveal it are; the highest of the chain.
49    pub locality: Score,
50}
51
52impl VulnerabilityDiscovery {
53    /// Builds from an enumerated weakness list.
54    #[must_use]
55    pub fn new(cwes: impl Into<Vec<Cwe>>, complexity: Score, locality: Score) -> Self {
56        Self {
57            cwes: cwes.into(),
58            complexity,
59            locality,
60        }
61    }
62
63    /// Builds when only the number of weaknesses is known, filling with [`Cwe::UNSPECIFIED`].
64    #[must_use]
65    pub fn with_cwe_count(count: usize, complexity: Score, locality: Score) -> Self {
66        Self::new(vec![Cwe::UNSPECIFIED; count], complexity, locality)
67    }
68
69    /// `min(10, complexity + cwe_count)`.
70    #[must_use]
71    pub fn vulnerability_complexity(&self) -> Score {
72        #[allow(clippy::cast_precision_loss)]
73        let count = self.cwes.len() as f64;
74        Score::clamped(self.complexity.get() + count)
75    }
76
77    /// `round1(vulnerability_complexity × 4/5 + locality / 5)`.
78    #[must_use]
79    pub fn total(&self) -> Score {
80        Score::clamped(
81            self.vulnerability_complexity().get() * 4.0 / 5.0 + self.locality.get() / 5.0,
82        )
83        .rounded()
84    }
85}
86
87/// How hard it is to weaponise the bug, given that it is already found.
88#[derive(Debug, Clone, PartialEq, Eq)]
89#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
90pub struct ExploitDevelopment {
91    /// Difficulty of the core exploit logic.
92    pub complexity: Score,
93    /// Techniques the exploit must employ. Only the length feeds the arithmetic.
94    pub techniques: Vec<Technique>,
95    /// Difficulty of the delivery harness — protocol, encoding, transport.
96    pub harness: Score,
97}
98
99impl ExploitDevelopment {
100    /// Builds from an enumerated technique list.
101    #[must_use]
102    pub fn new(complexity: Score, techniques: impl Into<Vec<Technique>>, harness: Score) -> Self {
103        Self {
104            complexity,
105            techniques: techniques.into(),
106            harness,
107        }
108    }
109
110    /// Builds when only the number of techniques is known, filling with
111    /// [`Technique::Unspecified`].
112    #[must_use]
113    pub fn with_technique_count(complexity: Score, count: usize, harness: Score) -> Self {
114        Self::new(complexity, vec![Technique::Unspecified; count], harness)
115    }
116
117    /// `min(10, complexity + technique_count)`.
118    ///
119    /// The prose specification clamps this to `[1, 10]`, but the reference calculator applies
120    /// no lower bound, and its own published example `pyny` scores zero here. This follows the
121    /// calculator.
122    #[must_use]
123    pub fn exploit_complexity(&self) -> Score {
124        #[allow(clippy::cast_precision_loss)]
125        let count = self.techniques.len() as f64;
126        Score::clamped(self.complexity.get() + count)
127    }
128
129    /// `max(exploit_complexity, harness)`.
130    #[must_use]
131    pub fn total(&self) -> Score {
132        self.exploit_complexity().max(self.harness).rounded()
133    }
134}
135
136/// Specialist knowledge a challenge demands beyond ordinary vulnerability-research skill.
137#[derive(Debug, Clone, PartialEq, Eq)]
138#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
139pub struct DomainRequirement {
140    /// The field of knowledge.
141    pub domain: Domain,
142    /// How deeply it must be known.
143    pub level: Score,
144    /// What specifically is required.
145    pub detail: Option<String>,
146}
147
148impl DomainRequirement {
149    /// Builds a requirement with no detail note.
150    #[must_use]
151    pub fn new(domain: Domain, level: Score) -> Self {
152        Self {
153            domain,
154            level,
155            detail: None,
156        }
157    }
158
159    /// Attaches a note describing what must be known.
160    #[must_use]
161    pub fn with_detail(mut self, detail: impl Into<String>) -> Self {
162        self.detail = Some(detail.into());
163        self
164    }
165}
166
167/// The expert-knowledge component: the deepest single domain requirement.
168#[derive(Debug, Clone, Default, PartialEq, Eq)]
169#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
170#[cfg_attr(feature = "serde", serde(transparent))]
171pub struct ExpertKnowledge {
172    /// Every domain the challenge draws on.
173    pub requirements: Vec<DomainRequirement>,
174}
175
176impl ExpertKnowledge {
177    /// A challenge demanding no specialist knowledge.
178    #[must_use]
179    pub fn none() -> Self {
180        Self::default()
181    }
182
183    /// Builds from a requirement list.
184    #[must_use]
185    pub fn new(requirements: impl Into<Vec<DomainRequirement>>) -> Self {
186        Self {
187            requirements: requirements.into(),
188        }
189    }
190
191    /// The maximum required level, or zero when no domain applies.
192    #[must_use]
193    pub fn total(&self) -> Score {
194        self.requirements
195            .iter()
196            .map(|requirement| requirement.level)
197            .max()
198            .unwrap_or(Score::ZERO)
199    }
200}