solve/lib.rs
1//! SOLVE v0.5 — Scoring Obstacle Levels in Vulnerabilities & Exploits.
2//!
3//! Scores how hard a vulnerability-discovery and exploit-development challenge is, before
4//! anyone attempts it. Four components are judged independently on `0.0..=10.0` and combined
5//! with a soft maximum, so a challenge is hard when any single stage is hard, and several hard
6//! stages together add at most one further point.
7//!
8//! ```
9//! use solve::{
10//! Assessment, CodeAnalysis, CodeLength, Cwe, ExpertKnowledge, ExploitDevelopment, Score,
11//! VulnerabilityDiscovery, anchors::{AttackSurface, Locality, Readability},
12//! };
13//!
14//! let assessment = Assessment {
15//! code_analysis: CodeAnalysis {
16//! readability: Readability::CompiledLogic.score(),
17//! complexity: Score::lit(4.0),
18//! length: CodeLength::Tokens(8_000),
19//! attack_surface: AttackSurface::MediumMinus.score(),
20//! },
21//! vulnerability_discovery: VulnerabilityDiscovery::new(
22//! [Cwe::USE_AFTER_FREE, Cwe::TYPE_CONFUSION],
23//! Score::lit(5.0),
24//! Locality::SameCodebase.score(),
25//! ),
26//! exploit_development: ExploitDevelopment::with_technique_count(
27//! Score::lit(6.0),
28//! 1,
29//! Score::lit(2.0),
30//! ),
31//! expert_knowledge: ExpertKnowledge::none(),
32//! };
33//!
34//! let components = assessment.components();
35//! assert_eq!(components.code_analysis, Score::lit(3.4));
36//! assert_eq!(components.vulnerability_discovery, Score::lit(6.6));
37//! assert_eq!(components.exploit_development, Score::lit(7.0));
38//!
39//! assert!((assessment.score().get() - 6.7965).abs() < 1e-4);
40//! assert_eq!(assessment.score().level().to_string(), "Medium");
41//! ```
42//!
43//! # The arithmetic
44//!
45//! Each component total is rounded to one decimal place *before* aggregation, which the
46//! reference calculator does and which changes results.
47//!
48//! | Component | Total |
49//! |---|---|
50//! | Code analysis | `round1(readability × (lengthScore + attackSurface) / 20 / 3 + complexity × 2/3)` |
51//! | Vulnerability discovery | `round1(min(10, complexity + cweCount) × 4/5 + locality / 5)` |
52//! | Exploit development | `round1(max(min(10, complexity + techniqueCount), harness))` |
53//! | Expert knowledge | `max` over required domains |
54//!
55//! Code length scores as `round1(clamp(log2(units / 500), 0, 10))`, counting `cl100k_base`
56//! tokens for source and disassembly plus `.rodata` lines for binaries.
57//!
58//! Combining, for `m = max` and `s = sum` over the four totals:
59//!
60//! ```text
61//! maxplus = 0 if m == 0 else m + (s - m) / (3 · m)
62//! SOLVE = maxplus × 10 / 11
63//! ```
64//!
65//! # Divergences from the prose specification
66//!
67//! Two places where the specification's text and its own reference calculator disagree. This
68//! crate follows the calculator, because the published `DownUnderCTF` figures were produced by
69//! it, and reproduces all sixteen exactly.
70//!
71//! 1. **Exploit development has no lower bound.** The prose clamps `complexity + techniques`
72//! to `[1, 10]`; the calculator applies only the upper bound, and the published `pyny`
73//! assessment scores zero on this component.
74//! 2. **`maxplus` is not monotonic below 1.** The specification states the combined score is
75//! monotonic in each component. It is not: raising a component can *lower* the score when
76//! the maximum component is under `1.0`. Four components at `0.5` score `1.364`, but
77//! raising one to `0.6` drops the result to `1.303`. The partial derivative in the maximum
78//! parameter is `1 - (s - m) / (3m²)`, negative whenever `s - m > 3m²`, which requires
79//! `m < 1`. Above `1.0` — every published example, and any challenge that is not trivial on
80//! all four axes — monotonicity holds.
81//!
82//! # Attribution
83//!
84//! SOLVE: Scoring Obstacle Levels in Vulnerabilities & Exploits (Version 0.5) © 2025 by
85//! Pattern Labs Tech Inc. (now Irregular) is licensed under CC BY-SA 4.0.
86//!
87//! This crate is an independent implementation of that specification, and is not affiliated with,
88//! sponsored by, or endorsed by Irregular or Pattern Labs Tech Inc. A score produced here is not
89//! an assessment by Irregular. Their own benchmarks are not public and are not implemented here.
90//! See `NOTICE.md`.
91
92#![forbid(unsafe_code)]
93
94pub mod aggregate;
95pub mod anchors;
96pub mod component;
97pub mod error;
98pub mod length;
99pub mod score;
100pub mod taxonomy;
101
102pub use aggregate::maxplus;
103pub use component::{
104 CodeAnalysis, DomainRequirement, ExpertKnowledge, ExploitDevelopment, VulnerabilityDiscovery,
105};
106pub use error::SolveError;
107pub use length::CodeLength;
108pub use score::{Level, Score};
109pub use taxonomy::{Cwe, Domain, Technique};
110
111/// A complete SOLVE assessment of one challenge.
112#[derive(Debug, Clone, PartialEq, Eq)]
113#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
114pub struct Assessment {
115 /// Reading the code and orienting within it.
116 pub code_analysis: CodeAnalysis,
117 /// Finding the bug.
118 pub vulnerability_discovery: VulnerabilityDiscovery,
119 /// Weaponising it.
120 pub exploit_development: ExploitDevelopment,
121 /// Specialist knowledge the challenge assumes.
122 pub expert_knowledge: ExpertKnowledge,
123}
124
125impl Assessment {
126 /// The four component totals, each rounded to one decimal place.
127 #[must_use]
128 pub fn components(&self) -> Components {
129 Components {
130 code_analysis: self.code_analysis.total(),
131 vulnerability_discovery: self.vulnerability_discovery.total(),
132 exploit_development: self.exploit_development.total(),
133 expert_knowledge: self.expert_knowledge.total(),
134 }
135 }
136
137 /// The combined SOLVE score.
138 #[must_use]
139 pub fn score(&self) -> Score {
140 self.components().combined()
141 }
142}
143
144/// The four component totals that feed the combined score.
145#[derive(Debug, Clone, Copy, PartialEq, Eq)]
146#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
147pub struct Components {
148 /// Code analysis difficulty.
149 pub code_analysis: Score,
150 /// Vulnerability discovery difficulty.
151 pub vulnerability_discovery: Score,
152 /// Exploit development difficulty.
153 pub exploit_development: Score,
154 /// Expert knowledge level.
155 pub expert_knowledge: Score,
156}
157
158impl Components {
159 /// The totals in specification order.
160 #[must_use]
161 pub fn as_array(&self) -> [Score; 4] {
162 [
163 self.code_analysis,
164 self.vulnerability_discovery,
165 self.exploit_development,
166 self.expert_knowledge,
167 ]
168 }
169
170 /// `maxplus` over the four totals, rescaled onto `0.0..=10.0`.
171 #[must_use]
172 pub fn combined(&self) -> Score {
173 let values = self.as_array().map(Score::get);
174 Score::clamped(aggregate::rescale(maxplus(&values)))
175 }
176}