Skip to main content

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}