parlov-core

Version: 0.5.0 | Files: 7 | Lines: 977 | Dependencies: none (workspace root)

The shared vocabulary crate. Every other workspace crate depends on parlov-core for its type definitions. It contains zero business logic — only data structures, enums, error types, and deterministic helper functions.

Public API

Request / Response Primitives

ProbeDefinition — A fully specified HTTP request before execution.

ResponseSurface — The observable surface area of an HTTP response, stripped to what analysis needs.

Both types derive Serialize and Deserialize via custom serde helpers (see Internal Modules).

Exchange Types

ProbeExchange — A paired request + response. Every response permanently travels with the request that produced it.

pub struct ProbeExchange {
    pub request: ProbeDefinition,
    pub response: ResponseSurface,
}

DifferentialSet — The unit of analysis. Replaces the deprecated ProbeSet (which carried only ResponseSurface vectors without request context).

pub struct DifferentialSet {
    pub baseline: Vec<ProbeExchange>,  // Known-valid inputs
    pub probe: Vec<ProbeExchange>,     // Unknown/suspect inputs
    pub technique: Technique,          // Why these probes were generated
}

ProbeSet (deprecated) — Use DifferentialSet instead.

Oracle Domain Types

OracleClass — Which class of oracle is being tested. Currently one variant:

• Existence — Does the resource exist?

Future variants (see Methodology): Authentication, Timing, Verification, TokenValidation, State.

OracleVerdict — The analysis conclusion.

Severity — Gated by confidence. Only present when verdict is Confirmed or Likely.

Technique Metadata

Technique — Probe generation context, set by the strategy at generation time, carried through execution unchanged, consumed by the analyzer for confidence calibration and evidence labeling.

pub struct Technique {
    pub id: &'static str,              // e.g. "if-none-match"
    pub name: &'static str,            // e.g. "If-None-Match conditional request"
    pub oracle_class: OracleClass,
    pub vector: Vector,
    pub strength: NormativeStrength,
}

Vector — Detection method used to produce the differential.

NormativeStrength — How strongly the RFC mandates the expected behavior. Directly affects confidence calibration.

Signal Types

Signal — A typed observation extracted from differential analysis. Signals are the atoms that classifiers compose into verdicts.

pub struct Signal {
    pub kind: SignalKind,
    pub evidence: String,             // e.g. "304 vs 404"
    pub rfc_basis: Option<String>,    // e.g. "RFC 9110 §13.1.2"
}

SignalKind — Categories of observable differentials.

ImpactClass — Classification of leak severity, independent of confidence.

Scoring Types

ScoringReason — One contribution to the confidence or impact score. Accumulated during classification to give operators a transparent audit trail.

pub struct ScoringReason {
    pub description: String,   // e.g. "Status differential 416 vs 404"
    pub points: i16,           // Positive or negative
    pub dimension: ScoringDimension,
}

ScoringDimension — Which axis a reason contributes to: Confidence (0–100 numeric) or Impact.

The OracleResult

OracleResult — The complete output of analysis. Carries everything needed for output formatting and SARIF generation.

Method: primary_evidence(&self) -> &str — Returns the evidence string from the first StatusCodeDiff signal, or falls back to the first signal of any kind. Returns "—" (em dash) when no signals exist.

Deterministic Finding IDs

finding_id(technique_id, target_url, oracle_class, method, strategy_id) -> String

Produces a stable 12-character hex fingerprint by SHA-256 hashing the canonical identity fields and truncating to 6 bytes. Used for SARIF partialFingerprints and deduplication.

Error Type

Error — Unified error enum.

Internal Modules

serde_helpers

Custom serde implementations for types that don't have native Serialize/Deserialize support:

These are applied via #[serde(with = "...")] attributes on ProbeDefinition and ResponseSurface.

Extension Points

Adding a new oracle class: Add a variant to OracleClass. This is the only change in parlov-core. The corresponding analyzer, strategies, and patterns live in parlov-analysis and parlov-elicit.

Adding a new vector: Add a variant to Vector. Strategies declare their vector via Technique; the analyzer uses it for signal extractor selection.

Adding a new signal kind: Add a variant to SignalKind. Then implement the extractor in parlov-analysis::signals and add weights in parlov-analysis::existence::signal_weights.