solve-score 0.1.0

Independent implementation of SOLVE v0.5 (Scoring Obstacle Levels in Vulnerabilities & Exploits), a rubric for scoring vulnerability-discovery and exploit-development difficulty. Reproduces the 16 published calibration assessments. Not affiliated with or endorsed by Irregular.
Documentation
//! SOLVE v0.5 — Scoring Obstacle Levels in Vulnerabilities & Exploits.
//!
//! Scores how hard a vulnerability-discovery and exploit-development challenge is, before
//! anyone attempts it. Four components are judged independently on `0.0..=10.0` and combined
//! with a soft maximum, so a challenge is hard when any single stage is hard, and several hard
//! stages together add at most one further point.
//!
//! ```
//! use solve::{
//!     Assessment, CodeAnalysis, CodeLength, Cwe, ExpertKnowledge, ExploitDevelopment, Score,
//!     VulnerabilityDiscovery, anchors::{AttackSurface, Locality, Readability},
//! };
//!
//! let assessment = Assessment {
//!     code_analysis: CodeAnalysis {
//!         readability: Readability::CompiledLogic.score(),
//!         complexity: Score::lit(4.0),
//!         length: CodeLength::Tokens(8_000),
//!         attack_surface: AttackSurface::MediumMinus.score(),
//!     },
//!     vulnerability_discovery: VulnerabilityDiscovery::new(
//!         [Cwe::USE_AFTER_FREE, Cwe::TYPE_CONFUSION],
//!         Score::lit(5.0),
//!         Locality::SameCodebase.score(),
//!     ),
//!     exploit_development: ExploitDevelopment::with_technique_count(
//!         Score::lit(6.0),
//!         1,
//!         Score::lit(2.0),
//!     ),
//!     expert_knowledge: ExpertKnowledge::none(),
//! };
//!
//! let components = assessment.components();
//! assert_eq!(components.code_analysis, Score::lit(3.4));
//! assert_eq!(components.vulnerability_discovery, Score::lit(6.6));
//! assert_eq!(components.exploit_development, Score::lit(7.0));
//!
//! assert!((assessment.score().get() - 6.7965).abs() < 1e-4);
//! assert_eq!(assessment.score().level().to_string(), "Medium");
//! ```
//!
//! # The arithmetic
//!
//! Each component total is rounded to one decimal place *before* aggregation, which the
//! reference calculator does and which changes results.
//!
//! | Component | Total |
//! |---|---|
//! | Code analysis | `round1(readability × (lengthScore + attackSurface) / 20 / 3 + complexity × 2/3)` |
//! | Vulnerability discovery | `round1(min(10, complexity + cweCount) × 4/5 + locality / 5)` |
//! | Exploit development | `round1(max(min(10, complexity + techniqueCount), harness))` |
//! | Expert knowledge | `max` over required domains |
//!
//! Code length scores as `round1(clamp(log2(units / 500), 0, 10))`, counting `cl100k_base`
//! tokens for source and disassembly plus `.rodata` lines for binaries.
//!
//! Combining, for `m = max` and `s = sum` over the four totals:
//!
//! ```text
//! maxplus = 0 if m == 0 else m + (s - m) / (3 · m)
//! SOLVE   = maxplus × 10 / 11
//! ```
//!
//! # Divergences from the prose specification
//!
//! Two places where the specification's text and its own reference calculator disagree. This
//! crate follows the calculator, because the published `DownUnderCTF` figures were produced by
//! it, and reproduces all sixteen exactly.
//!
//! 1. **Exploit development has no lower bound.** The prose clamps `complexity + techniques`
//!    to `[1, 10]`; the calculator applies only the upper bound, and the published `pyny`
//!    assessment scores zero on this component.
//! 2. **`maxplus` is not monotonic below 1.** The specification states the combined score is
//!    monotonic in each component. It is not: raising a component can *lower* the score when
//!    the maximum component is under `1.0`. Four components at `0.5` score `1.364`, but
//!    raising one to `0.6` drops the result to `1.303`. The partial derivative in the maximum
//!    parameter is `1 - (s - m) / (3m²)`, negative whenever `s - m > 3m²`, which requires
//!    `m < 1`. Above `1.0` — every published example, and any challenge that is not trivial on
//!    all four axes — monotonicity holds.
//!
//! # Attribution
//!
//! SOLVE: Scoring Obstacle Levels in Vulnerabilities & Exploits (Version 0.5) © 2025 by
//! Pattern Labs Tech Inc. (now Irregular) is licensed under CC BY-SA 4.0.
//!
//! This crate is an independent implementation of that specification, and is not affiliated with,
//! sponsored by, or endorsed by Irregular or Pattern Labs Tech Inc. A score produced here is not
//! an assessment by Irregular. Their own benchmarks are not public and are not implemented here.
//! See `NOTICE.md`.

#![forbid(unsafe_code)]

pub mod aggregate;
pub mod anchors;
pub mod component;
pub mod error;
pub mod length;
pub mod score;
pub mod taxonomy;

pub use aggregate::maxplus;
pub use component::{
    CodeAnalysis, DomainRequirement, ExpertKnowledge, ExploitDevelopment, VulnerabilityDiscovery,
};
pub use error::SolveError;
pub use length::CodeLength;
pub use score::{Level, Score};
pub use taxonomy::{Cwe, Domain, Technique};

/// A complete SOLVE assessment of one challenge.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Assessment {
    /// Reading the code and orienting within it.
    pub code_analysis: CodeAnalysis,
    /// Finding the bug.
    pub vulnerability_discovery: VulnerabilityDiscovery,
    /// Weaponising it.
    pub exploit_development: ExploitDevelopment,
    /// Specialist knowledge the challenge assumes.
    pub expert_knowledge: ExpertKnowledge,
}

impl Assessment {
    /// The four component totals, each rounded to one decimal place.
    #[must_use]
    pub fn components(&self) -> Components {
        Components {
            code_analysis: self.code_analysis.total(),
            vulnerability_discovery: self.vulnerability_discovery.total(),
            exploit_development: self.exploit_development.total(),
            expert_knowledge: self.expert_knowledge.total(),
        }
    }

    /// The combined SOLVE score.
    #[must_use]
    pub fn score(&self) -> Score {
        self.components().combined()
    }
}

/// The four component totals that feed the combined score.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Components {
    /// Code analysis difficulty.
    pub code_analysis: Score,
    /// Vulnerability discovery difficulty.
    pub vulnerability_discovery: Score,
    /// Exploit development difficulty.
    pub exploit_development: Score,
    /// Expert knowledge level.
    pub expert_knowledge: Score,
}

impl Components {
    /// The totals in specification order.
    #[must_use]
    pub fn as_array(&self) -> [Score; 4] {
        [
            self.code_analysis,
            self.vulnerability_discovery,
            self.exploit_development,
            self.expert_knowledge,
        ]
    }

    /// `maxplus` over the four totals, rescaled onto `0.0..=10.0`.
    #[must_use]
    pub fn combined(&self) -> Score {
        let values = self.as_array().map(Score::get);
        Score::clamped(aggregate::rescale(maxplus(&values)))
    }
}