nordisk/heimdall

crates/heimdall-scan/src/lib.rs

// SPDX-License-Identifier: AGPL-3.0-only
//! The static-scanner guest contract. **Heimdall is a defensive sandbox.**
//!
//! A static scanner is a Heimdall wasm guest that judges one package artifact
//! without running it. This crate is the whole contract between the caller
//! (Holger) and such a guest, shared by both sides so neither writes it twice:
//!
//! * [`input`]: the job input, one envelope holding the artifact bytes and the
//!   data snapshots the checks need (popular names, internal namespaces, the
//!   registry document, the malicious-package feed). There is no network in a
//!   guest; every piece of outside knowledge arrives here.
//! * [`purl`]: the package identity, passed as the `purl` job parameter.
//! * [`report`]: the canonical findings document the guest emits as
//!   [`REPORT_NAME`], one verdict per check (`clean`, `findings`, `unknown`).
//!   A check that cannot judge says `unknown`, never `clean` (fail closed).
//! * [`statement`]: the document wrapped as an in-toto Statement v1 predicate,
//!   ready for the caller to sign into its evidence.
//!
//! The wire is described in docs/API.md, "Static-scanner guests".

#![forbid(unsafe_code)]

pub mod input;
pub mod purl;
pub mod report;
pub mod statement;

pub use input::{DataKind, InputError, ScanInput, ScanInputRef};
pub use purl::{Purl, PurlError};
pub use report::{
    Check, CheckResult, DataDigest, Finding, Report, ReportError, ScannerId, Severity, Subject,
    UnknownReason, Verdict,
};
pub use statement::{in_toto_statement, PREDICATE_TYPE, STATEMENT_TYPE};

/// The one file a static-scanner guest emits: the findings document.
pub const REPORT_NAME: &str = "findings.json";

/// Stable codes a static-scanner guest puts in brackets at the start of its
/// refusal reason (`[heimdall-scan-1] …`). The host reports every guest
/// refusal as `heimdall-wasm-1`; the bracketed code says which. A refusal
/// means the guest could not even read its job (no findings document); a
/// package it could read but not judge gets `unknown` checks instead.
pub mod codes {
    /// The input is not a valid scan-input envelope.
    pub const BAD_INPUT: &str = "heimdall-scan-1";
    /// A job parameter is unknown, repeated or malformed.
    pub const BAD_PARAMS: &str = "heimdall-scan-2";
    /// The `purl` parameter is missing or not a package URL.
    pub const BAD_PURL: &str = "heimdall-scan-3";
    /// The `checks` parameter names a check this guest does not run.
    pub const UNKNOWN_CHECK: &str = "heimdall-scan-4";

    /// Every code, for the uniqueness test and the docs.
    pub const ALL: [&str; 4] = [BAD_INPUT, BAD_PARAMS, BAD_PURL, UNKNOWN_CHECK];
}