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
//! The four primary components, each producing a total in `0.0..=10.0`.

use crate::length::CodeLength;
use crate::score::Score;
use crate::taxonomy::{Cwe, Domain, Technique};

/// Denominator that maps the code-length and attack-surface pair onto a `0..=1` multiplier.
const EXPLORATION_DIVISOR: f64 = 20.0;

/// How hard it is to read the supplied code and orient within it, before any bug hunting.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct CodeAnalysis {
    /// Effort to reach a fully readable state — deobfuscation, decompilation.
    pub readability: Score,
    /// Effort to understand what the relevant code does, assuming it is fully readable.
    pub complexity: Score,
    /// How much code there is to read.
    pub length: CodeLength,
    /// How much of it is actually in scope for the bug hunt.
    pub attack_surface: Score,
}

impl CodeAnalysis {
    /// Cost of navigating to the interesting code: `readability × (length + surface) / 20`.
    #[must_use]
    pub fn exploration(&self) -> Score {
        let breadth = self.length.score().get() + self.attack_surface.get();
        Score::clamped(self.readability.get() * breadth / EXPLORATION_DIVISOR)
    }

    /// `round1(exploration / 3 + complexity × 2/3)`.
    #[must_use]
    pub fn total(&self) -> Score {
        Score::clamped(self.exploration().get() / 3.0 + self.complexity.get() * 2.0 / 3.0).rounded()
    }
}

/// How hard it is to find the bug, given that the code is already understood.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct VulnerabilityDiscovery {
    /// The distinct weakness classes that must be found — ideally one per vulnerability.
    /// Only the length feeds the arithmetic.
    pub cwes: Vec<Cwe>,
    /// Sophistication of the vulnerability, or of the whole chain when several are needed.
    pub complexity: Score,
    /// How far apart the code paths that reveal it are; the highest of the chain.
    pub locality: Score,
}

impl VulnerabilityDiscovery {
    /// Builds from an enumerated weakness list.
    #[must_use]
    pub fn new(cwes: impl Into<Vec<Cwe>>, complexity: Score, locality: Score) -> Self {
        Self {
            cwes: cwes.into(),
            complexity,
            locality,
        }
    }

    /// Builds when only the number of weaknesses is known, filling with [`Cwe::UNSPECIFIED`].
    #[must_use]
    pub fn with_cwe_count(count: usize, complexity: Score, locality: Score) -> Self {
        Self::new(vec![Cwe::UNSPECIFIED; count], complexity, locality)
    }

    /// `min(10, complexity + cwe_count)`.
    #[must_use]
    pub fn vulnerability_complexity(&self) -> Score {
        #[allow(clippy::cast_precision_loss)]
        let count = self.cwes.len() as f64;
        Score::clamped(self.complexity.get() + count)
    }

    /// `round1(vulnerability_complexity × 4/5 + locality / 5)`.
    #[must_use]
    pub fn total(&self) -> Score {
        Score::clamped(
            self.vulnerability_complexity().get() * 4.0 / 5.0 + self.locality.get() / 5.0,
        )
        .rounded()
    }
}

/// How hard it is to weaponise the bug, given that it is already found.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct ExploitDevelopment {
    /// Difficulty of the core exploit logic.
    pub complexity: Score,
    /// Techniques the exploit must employ. Only the length feeds the arithmetic.
    pub techniques: Vec<Technique>,
    /// Difficulty of the delivery harness — protocol, encoding, transport.
    pub harness: Score,
}

impl ExploitDevelopment {
    /// Builds from an enumerated technique list.
    #[must_use]
    pub fn new(complexity: Score, techniques: impl Into<Vec<Technique>>, harness: Score) -> Self {
        Self {
            complexity,
            techniques: techniques.into(),
            harness,
        }
    }

    /// Builds when only the number of techniques is known, filling with
    /// [`Technique::Unspecified`].
    #[must_use]
    pub fn with_technique_count(complexity: Score, count: usize, harness: Score) -> Self {
        Self::new(complexity, vec![Technique::Unspecified; count], harness)
    }

    /// `min(10, complexity + technique_count)`.
    ///
    /// The prose specification clamps this to `[1, 10]`, but the reference calculator applies
    /// no lower bound, and its own published example `pyny` scores zero here. This follows the
    /// calculator.
    #[must_use]
    pub fn exploit_complexity(&self) -> Score {
        #[allow(clippy::cast_precision_loss)]
        let count = self.techniques.len() as f64;
        Score::clamped(self.complexity.get() + count)
    }

    /// `max(exploit_complexity, harness)`.
    #[must_use]
    pub fn total(&self) -> Score {
        self.exploit_complexity().max(self.harness).rounded()
    }
}

/// Specialist knowledge a challenge demands beyond ordinary vulnerability-research skill.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct DomainRequirement {
    /// The field of knowledge.
    pub domain: Domain,
    /// How deeply it must be known.
    pub level: Score,
    /// What specifically is required.
    pub detail: Option<String>,
}

impl DomainRequirement {
    /// Builds a requirement with no detail note.
    #[must_use]
    pub fn new(domain: Domain, level: Score) -> Self {
        Self {
            domain,
            level,
            detail: None,
        }
    }

    /// Attaches a note describing what must be known.
    #[must_use]
    pub fn with_detail(mut self, detail: impl Into<String>) -> Self {
        self.detail = Some(detail.into());
        self
    }
}

/// The expert-knowledge component: the deepest single domain requirement.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(transparent))]
pub struct ExpertKnowledge {
    /// Every domain the challenge draws on.
    pub requirements: Vec<DomainRequirement>,
}

impl ExpertKnowledge {
    /// A challenge demanding no specialist knowledge.
    #[must_use]
    pub fn none() -> Self {
        Self::default()
    }

    /// Builds from a requirement list.
    #[must_use]
    pub fn new(requirements: impl Into<Vec<DomainRequirement>>) -> Self {
        Self {
            requirements: requirements.into(),
        }
    }

    /// The maximum required level, or zero when no domain applies.
    #[must_use]
    pub fn total(&self) -> Score {
        self.requirements
            .iter()
            .map(|requirement| requirement.level)
            .max()
            .unwrap_or(Score::ZERO)
    }
}