stygian_charon/
lib.rs

1#![warn(missing_docs, rustdoc::broken_intra_doc_links)]
2#![deny(unsafe_code)]
3
4//! stygian-charon — defensive anti-bot diagnostics for Stygian.
5//!
6//! Classifies likely anti-bot providers from transaction evidence
7//! and from HTTP Archive (HAR) files.
8
9/// Mapping layer from runtime policy to acquisition strategy hints.
10pub mod acquisition;
11/// Adaptive SLO policy interfaces and regression-history implementation.
12pub mod adaptive;
13/// Versioned analyzer interfaces and profile selection.
14pub mod analyzer;
15/// Historical HAR replay across analyzer profiles.
16pub mod backtest;
17/// Diagnostic bundle API with redaction policy.
18pub mod bundle;
19/// Investigation report cache backends and cache key helpers.
20#[cfg(feature = "caching")]
21pub mod cache;
22/// Challenge-aware policy feedback loop (T83).
23#[cfg(feature = "caching")]
24pub mod challenge_feedback;
25/// Anti-bot change-detection feed (T88).
26///
27/// Detects canary, proxy, and extraction deltas and
28/// emits actionable incident packets via the metrics
29/// surface and the diagnostics payload.
30#[cfg(feature = "caching")]
31pub mod change_feed;
32/// Provider signature classification logic.
33pub mod classifier;
34/// Content-Type shift detection (T104) — rolling baseline tracker.
35///
36/// Catches the publisher-cloaking pattern: HTML replaced with a
37/// Markdown stub for AI-bot User-Agents, same URL, same 200, parse
38/// succeeds, but a different edition of the page.
39pub mod content_type_shift;
40/// Mode differential regression runner across snapshot capture modes.
41pub mod differential;
42/// T107 poisoned-data field-level anomaly detector.
43///
44/// Catches the "tarpit / poisoned data / silent 200s" pattern from
45/// <https://web-scraping-guide.com/#post-extract>: targets that
46/// return clean `200` responses with subtly wrong field values
47/// (price drift, listing reorder, fabricated rows, stale
48/// snapshots). The detector observes every field value the pipeline
49/// publishes and emits `field_anomaly::AnomalyReport`s when a
50/// value is statistically inconsistent with the rolling baseline.
51///
52/// Hidden behind a `field-anomaly` cargo feature so existing
53/// charon users aren't forced to opt in.
54#[cfg(feature = "field-anomaly")]
55pub mod field_anomaly;
56/// HAR parsing and extraction utilities.
57pub mod har;
58/// Investigation reports and baseline/candidate diffing.
59pub mod investigation;
60/// Telemetry and metrics collection (feature-gated).
61#[cfg(feature = "metrics")]
62pub mod metrics;
63/// External observatory runner and comparison reports.
64pub mod observatory;
65/// Target-class playbooks as code (T85). Resolves per-target
66/// acquisition / proxy / pacing / escalation knobs with
67/// deterministic precedence.
68pub mod playbooks;
69/// Runtime policy planning based on investigation output.
70pub mod policy;
71/// Proof-of-work capability profile (T93).
72///
73/// Quantifies solve latency, success rate, retry count, and
74/// failure modes into a deterministic unit-interval score,
75/// with sparse-telemetry fallback and a policy mapper that
76/// nudges the runtime policy toward a posture matching the
77/// observed capability.
78///
79/// Persistence reuses the same `LruTtlStore` primitive
80/// T83 / T91 use (no new cache store; PoW key namespace is
81/// `charon:pow:...`).
82#[cfg(feature = "caching")]
83pub mod pow_profile;
84/// Challenge-style probe pack for adversarial and regression testing.
85pub mod probe;
86/// Release risk scoring and release-candidate trend reporting.
87pub mod release_risk;
88/// Normalized fingerprint snapshot schema types and compatibility checks.
89pub mod snapshot;
90/// Challenge-token lifecycle contracts (T91). Strict per-vendor
91/// TTL / nonce / single-use / session-binding invariants enforced
92/// before submission.
93#[cfg(feature = "caching")]
94pub mod token_lifecycle;
95/// Public types for transaction and report models.
96pub mod types;
97/// Vendor fingerprinting confidence classifier (T89).
98pub mod vendor_classifier;
99/// Vendor-to-playbook auto-resolution (T90).
100///
101/// Bridges the vendor classifier and the playbook resolver,
102/// with multi-vendor precedence, merge rules, and a `Manual`
103/// fallback that keeps existing manual mode selection working
104/// unchanged.
105pub mod vendor_resolver;
106
107pub use acquisition::{
108    AcquisitionModeHint, AcquisitionPolicy, AcquisitionStartHint, RuntimePolicyHints,
109    map_adapter_strategy, map_policy_hints, map_runtime_policy,
110};
111pub use adaptive::{AdaptivePolicyError, AdaptiveSloPolicy, RegressionHistoryPolicy};
112pub use analyzer::{AnalyzerProfile, AnalyzerVersion, ProviderAnalyzer};
113pub use backtest::{
114    BacktestCase, BacktestDisagreement, BacktestError, BacktestReport, BacktestSample,
115    run_profile_backtest,
116};
117pub use bundle::{
118    BundleCoherenceViolation, BundleError, BundleMetadata, BundleRedactionPolicy, DiagnosticBundle,
119    apply_redaction, build_diagnostic_bundle, build_diagnostic_bundle_with_snapshot,
120    diagnostic_bundle_from_investigation,
121};
122#[cfg(feature = "redis-cache")]
123pub use cache::RedisInvestigationCache;
124#[cfg(feature = "caching")]
125pub use cache::{InvestigationReportCache, MemoryInvestigationCache, investigation_cache_key};
126#[cfg(feature = "caching")]
127pub use challenge_feedback::{
128    ChallengeFeedbackPolicy, ChallengeMemory, ChallengeMemoryEntry, ChallengeOutcome,
129    DEFAULT_CHALLENGE_CAPACITY, DEFAULT_CHALLENGE_TTL, EngineKey, EngineKeyParseError,
130    MAX_RISK_DELTA, adjust_runtime_policy, build_runtime_policy_with_memory, engine_memory_key,
131    memory_adjustment_for,
132};
133#[cfg(feature = "caching")]
134pub use change_feed::{
135    ChangeClassification, ChangeDeltaInput, ChangeDetector, ChangeEvent, ChangeEventSink,
136    ChangeFeedReport, ChangeFeedThresholds, DeltaSeverity, DeltaSource, DeltaSummary,
137    InMemoryChangeFeedSink, MitigationPath, record_change_event,
138};
139pub use classifier::{
140    classify_har, classify_har_with_profile, classify_transaction,
141    classify_transaction_with_profile,
142};
143pub use content_type_shift::{
144    ContentTypeDrift, ContentTypeError, ContentTypeObservation, ContentTypeShiftDetector,
145    ContentTypeShiftReport, MimeClass, RollingBaselineDetector, current_unix_secs, drift_summary,
146};
147pub use differential::{
148    ModeComparison, ModeDifferentialCorpus, ModeDifferentialError, ModeDifferentialPairResult,
149    ModeDifferentialRunReport, ModeDifferentialThresholds, run_mode_differential_regression,
150};
151pub use investigation::{
152    compare_reports, infer_requirements, infer_requirements_with_target_class, investigate_har,
153    investigate_har_with_profile,
154};
155#[cfg(feature = "caching")]
156pub use investigation::{investigate_har_cached, investigate_har_cached_with_target_class};
157#[cfg(feature = "live-validation")]
158pub use observatory::{LiveObservatoryProbe, run_external_observatory_live};
159pub use observatory::{
160    ObservatoryCase, ObservatoryComparison, ObservatoryError, ObservatoryEscalation,
161    ObservatoryReport, ObservatorySample, run_external_observatory_from_hars,
162};
163pub use policy::{analyze_and_plan, build_runtime_policy, plan_from_report};
164#[cfg(feature = "caching")]
165pub use pow_profile::{
166    DEFAULT_LATENCY_BUDGET_MS, DEFAULT_POW_CAPACITY, DEFAULT_POW_TTL, DEFAULT_RETRY_BUDGET,
167    DEFAULT_SAMPLE_WINDOW_SECS, MAX_POW_RISK_DELTA, MIN_OBSERVATIONS_FOR_SCORING,
168    PowCapabilityBand, PowCapabilityProfile, PowCapabilitySample, PowCapabilityScore,
169    PowCapabilityScorer, PowCapabilityStore, PowFailureMode, PowPolicyThresholds, ProfileWeights,
170    SPARSE_FALLBACK_SCORE, adjust_runtime_policy_for_pow, band_for_score, pow_profile_key,
171    score_from_profile,
172};
173pub use probe::{
174    ChallengeProbe, ProbeCategory, ProbeExpectation, ProbePackReport, ProbeRunResult,
175    challenge_probe_pack, run_probe_pack,
176};
177pub use release_risk::{
178    ReleaseCandidateRiskSnapshot, ReleaseRiskAssessment, ReleaseRiskBreakdown, ReleaseRiskInput,
179    ReleaseRiskLevel, ReleaseRiskThresholds, ReleaseRiskWeights, ReleaseTrendDirection,
180    ReleaseTrendPoint, ReleaseTrendReport, assess_release_risk, build_release_trend_report,
181    release_risk_input_from_reports,
182};
183pub use snapshot::{
184    FingerprintSignals, NormalizedFingerprintSnapshot, ScreenFingerprint, SnapshotCoherenceReport,
185    SnapshotCoherenceViolation, SnapshotCollectionError, SnapshotCompatibilityError,
186    SnapshotDeterminismOptions, SnapshotDriftReport, SnapshotMode, SnapshotSignalDrift,
187    SnapshotSignalDriftKind, TlsFingerprint, WebGlFingerprint,
188    collect_deterministic_snapshot_bytes, compare_snapshot_signal_drift,
189    evaluate_snapshot_coherence, normalize_snapshot_for_determinism,
190    validate_snapshot_compatibility,
191};
192#[cfg(feature = "caching")]
193pub use token_lifecycle::{
194    ChallengeClass, DEFAULT_NONCE_BOOK_CAPACITY, DEFAULT_NONCE_TTL, InvalidationKind,
195    InvalidationReason, NonceBook, NonceObservation, TokenContract, TokenLifecycleError,
196    TokenPolicy, TokenPolicyTable, TokenValidator, ValidationOutcome, builtin_token_policies,
197    nonce_book_key,
198};
199pub use types::{
200    AdapterStrategy, AntiBotProvider, AntiBotRequirement, BlockedRatioSlo, Detection,
201    ExecutionMode, HarClassificationReport, HarRequestSummary, HostSummary,
202    IntegrationRecommendation, InvestigationBundle, InvestigationDiff, InvestigationReport,
203    MarkerCount, ProviderScore, RequirementLevel, RequirementsProfile, RuntimePolicy, SessionMode,
204    TargetClass, TelemetryLevel, TransactionView,
205};
206pub use vendor_classifier::{
207    DEFAULT_HIGH_CONFIDENCE_THRESHOLD, Evidence, EvidenceBundle, EvidenceSource,
208    VendorClassification, VendorClassifier, VendorDefinition, VendorError, VendorId, VendorScore,
209    VendorSignal, parse_vendor_definition,
210};
211pub use vendor_resolver::{
212    AppliedRule, MergeStrategy, PlaybookResolverExt, ResolutionRationale, ResolutionRule,
213    StrategyMarker, VendorResolution, VendorResolver, VendorResolverError, VendorRuleMatch,
214    parse_resolution_rule,
215};
stygian_charon/lib.rs

stygian_charon/
lib.rs
