harn-vm 0.10.170

//! The child-process refusal record, and the credential-denial term it
//! reports on.
//!
//! Split out of `mod.rs`, which is on the legacy source-length inventory and
//! may not grow. These belong together anyway: the denial term decides what is
//! refused, and the record is how a refusal becomes something a consumer can
//! act on instead of a bare non-zero exit.

use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};

use crate::orchestration::{CapabilityPolicy, SandboxProfile};
use crate::value::{VmError, VmValue};

use super::{
    effective_fallback, normalize_for_policy, path_is_within, sandbox_denial_error,
    sandbox_signal_status, sandbox_user_home_dir, warn_once, ActiveBackend, PrepareOutcome,
    SandboxBackend, SandboxFallback,
};

#[path = "refusal_mechanism.rs"]
mod refusal_mechanism;
pub use refusal_mechanism::{
    infer_process_sandbox_mechanism, ProcessSandboxGrants, ProcessSandboxMechanism,
};

/// How a child-process refusal was determined, and therefore how much its
/// `refused_paths` can be trusted.
///
/// One variant, because there is one producer. A consumer should still match on
/// this rather than assume: the field exists so that when a platform learns to
/// name refused paths (macOS can, via the unified log, asynchronously) the new
/// tier arrives as a variant a consumer already handles, instead of silently
/// changing what an existing value means.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum RefusalObservability {
    /// Classified by matching the child's own output, which is all any current
    /// backend can do. `refused_paths` is therefore always EMPTY under this
    /// tier, and that emptiness says nothing about what was refused.
    ///
    /// Lossy in both directions: a tool that localizes its errors is a refusal
    /// that never counts, and any failing child that merely prints one of the
    /// phrases is attributed to the sandbox.
    Inferred,
}

impl RefusalObservability {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Inferred => "inferred",
        }
    }
}

/// How completely the active process-sandbox backend reports mid-run denials.
///
/// This is separate from an individual refusal's `observability`: it describes
/// what an EMPTY refusal slot means. In particular, `InferredOnly` means that
/// no structured backend report was available, so absence must not be read as
/// proof that the sandbox allowed every operation.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum ProcessSandboxDenialReporting {
    NotEnforced,
    BackendUnavailable,
    InferredOnly,
}

impl ProcessSandboxDenialReporting {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::NotEnforced => "not_enforced",
            Self::BackendUnavailable => "backend_unavailable",
            Self::InferredOnly => "inferred_only",
        }
    }
}

/// Operation class reported by a backend. Current backends cannot report this
/// fact, so inferred records say `Unknown` instead of guessing from prose.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum ProcessSandboxOperation {
    Read,
    Write,
    Unknown,
}

impl ProcessSandboxOperation {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Read => "read",
            Self::Write => "write",
            Self::Unknown => "unknown",
        }
    }
}

/// Whether an OS exit signal is one of the signals a process sandbox may use
/// for a mid-run refusal. Both `std::process` and hostlib's process adapter
/// project their platform-specific exit status through this one classifier.
#[cfg(unix)]
pub fn is_process_sandbox_signal(signal: Option<i32>) -> bool {
    matches!(
        signal,
        Some(libc::SIGSYS) | Some(libc::SIGABRT) | Some(libc::SIGKILL)
    )
}

#[cfg(not(unix))]
pub fn is_process_sandbox_signal(_signal: Option<i32>) -> bool {
    false
}

/// A typed child-process sandbox refusal.
///
/// Replaces reading the identity back out of an error message string. The
/// detector is still the substring heuristic below on every platform that
/// cannot do better; what changes is that its uncertainty is now a field
/// (`observability`) instead of something a consumer has to know by folklore.
///
/// Projected into both the event stream and the command handler result, which
/// is why `command` and `cwd` are mandatory and `refused_paths` is not: those
/// two are known at spawn on every platform, and the path is not.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct ProcessSandboxRefusal {
    pub schema: String,
    pub command: Vec<String>,
    pub cwd: String,
    pub backend: String,
    pub operation: ProcessSandboxOperation,
    /// Which sandbox boundary refused the child: egress, a local socket, a
    /// home-directory read, a write, or unknown. Inferred from the output
    /// under the same `observability` as the rest of the record. Records
    /// written before the field existed read back as `Unknown`.
    #[serde(default)]
    pub mechanism: ProcessSandboxMechanism,
    /// The mechanism spelled out with the grants in force, for the agent and
    /// the receipt. Diagnostic prose; the typed fact is `mechanism`.
    #[serde(default)]
    pub reason: String,
    /// The refused resource when the backend reports one. `None` under the
    /// current inference-only contract; never recover this by parsing prose.
    pub resource: Option<String>,
    /// May be empty even on a real refusal. Read `observability` first.
    pub refused_paths: Vec<String>,
    pub observability: RefusalObservability,
    /// Bounded excerpt of the child's own output that triggered an `Inferred`
    /// classification. Diagnostic only; never parse it.
    pub stderr_excerpt: String,
    pub count: u32,
}

impl ProcessSandboxRefusal {
    pub const SCHEMA: &'static str = "harn.process.sandbox_refusal.v1";
    /// Keep the excerpt small enough to sit in a receipt without becoming a log.
    const MAX_EXCERPT: usize = 512;

    /// Emit the refusal as a structured event.
    ///
    /// This event-side projection is emitted at the moment of classification.
    /// The command response carries the same typed record independently, so
    /// neither consumer reconstructs it later from an error string.
    pub fn emit(&self) {
        let mut metadata = std::collections::BTreeMap::new();
        metadata.insert("schema".to_string(), serde_json::json!(self.schema));
        metadata.insert("command".to_string(), serde_json::json!(self.command));
        metadata.insert("cwd".to_string(), serde_json::json!(self.cwd));
        metadata.insert("backend".to_string(), serde_json::json!(self.backend));
        metadata.insert(
            "operation".to_string(),
            serde_json::json!(self.operation.as_str()),
        );
        metadata.insert("resource".to_string(), serde_json::json!(self.resource));
        metadata.insert(
            "mechanism".to_string(),
            serde_json::json!(self.mechanism.as_str()),
        );
        metadata.insert("reason".to_string(), serde_json::json!(self.reason));
        metadata.insert(
            "refused_paths".to_string(),
            serde_json::json!(self.refused_paths),
        );
        metadata.insert(
            "observability".to_string(),
            serde_json::to_value(self.observability).unwrap_or(serde_json::Value::Null),
        );
        metadata.insert(
            "stderr_excerpt".to_string(),
            serde_json::json!(self.stderr_excerpt),
        );
        metadata.insert("count".to_string(), serde_json::json!(self.count));
        crate::events::log_warn_meta(
            "process_sandbox_refusal",
            "a child process was refused by the OS sandbox",
            metadata,
        );
    }

    pub fn inferred(backend: String, command: Vec<String>, cwd: String, evidence: &str) -> Self {
        Self::inferred_under(backend, command, cwd, evidence, None)
    }

    /// Classify against the policy that confined the child, so the mechanism
    /// explanation can name the grants that were in force.
    pub fn inferred_under(
        backend: String,
        command: Vec<String>,
        cwd: String,
        evidence: &str,
        policy: Option<&CapabilityPolicy>,
    ) -> Self {
        let mut stderr_excerpt: String = evidence.chars().take(Self::MAX_EXCERPT).collect();
        if evidence.chars().count() > Self::MAX_EXCERPT {
            stderr_excerpt.push('…');
        }
        // `operation` is what a BACKEND reports and stays `Unknown` under
        // inference; `mechanism` is the inferred fact and says so.
        let (mechanism, grants) = infer_process_sandbox_mechanism(evidence, policy);
        Self {
            schema: Self::SCHEMA.to_string(),
            command,
            cwd,
            backend,
            operation: ProcessSandboxOperation::Unknown,
            mechanism,
            reason: mechanism.explanation(&grants),
            resource: None,
            refused_paths: Vec::new(),
            observability: RefusalObservability::Inferred,
            stderr_excerpt,
            count: 1,
        }
    }

    /// Project this record into the existing agent-handler denial contract.
    /// Consumers must never reconstruct these fields from `stderr_excerpt`.
    pub fn handler_denial_json(&self) -> serde_json::Value {
        serde_json::json!({
            "schema": self.schema,
            "gate": "process_sandbox",
            "capability": "process.run",
            "backend": self.backend,
            "operation": self.operation.as_str(),
            "mechanism": self.mechanism.as_str(),
            "resource": self.resource,
            "command": self.command,
            "cwd": self.cwd,
            "refused_paths": self.refused_paths,
            "observability": self.observability.as_str(),
            "stderr_excerpt": self.stderr_excerpt,
            "count": self.count,
            "retryable": false,
            "reason": format!("The process sandbox refused an operation in the child process: {}.", self.reason),
        })
    }

    pub fn handler_denial_value(&self) -> VmValue {
        crate::json_to_vm_value(&self.handler_denial_json())
    }
}

/// Spawn-time contract for assessing a completed child. Capture this before a
/// background waiter changes threads: execution policy is scoped to the
/// spawning thread, but reporting coverage belongs to the command receipt.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ProcessSandboxReportingContext {
    pub backend: String,
    pub reporting: ProcessSandboxDenialReporting,
    /// The policy that confined the spawn, captured on the spawning thread so
    /// a refusal classified later (on a waiter thread) still names the grants
    /// that were actually in force.
    pub policy: Option<Box<CapabilityPolicy>>,
}

impl ProcessSandboxReportingContext {
    pub fn current() -> Self {
        let policy = super::active_sandbox_policy();
        let reporting = match policy {
            Some(_) if ActiveBackend::available() => ProcessSandboxDenialReporting::InferredOnly,
            Some(_) => ProcessSandboxDenialReporting::BackendUnavailable,
            // A child of a confined process runs under that process's
            // profile, so its permission errors are the kernel's too.
            None if super::self_confinement::current_process_confinement().is_some() => {
                ProcessSandboxDenialReporting::InferredOnly
            }
            None => ProcessSandboxDenialReporting::NotEnforced,
        };
        Self {
            backend: super::active_backend_filesystem_mechanism().to_string(),
            reporting,
            policy: policy.map(|(policy, _)| Box::new(policy)),
        }
    }

    pub fn assess_exit(
        &self,
        success: bool,
        sandbox_signal: bool,
        stdout: &[u8],
        stderr: &[u8],
        command: &[String],
        cwd: &str,
    ) -> ProcessSandboxAssessment {
        let stderr_lower = String::from_utf8_lossy(stderr).to_ascii_lowercase();
        let stdout_lower = String::from_utf8_lossy(stdout).to_ascii_lowercase();
        let stderr_permission = stderr_lower.contains("operation not permitted")
            || stderr_lower.contains("permission denied")
            || stderr_lower.contains("access is denied");
        let stdout_permission = stdout_lower.contains("operation not permitted");
        let permission_errno = !success && (stderr_permission || stdout_permission);
        let refusal = (self.reporting == ProcessSandboxDenialReporting::InferredOnly
            && (permission_errno || sandbox_signal))
            .then(|| {
                let evidence = if stderr_permission || (!stdout_permission && !stderr.is_empty()) {
                    stderr
                } else {
                    stdout
                };
                ProcessSandboxRefusal::inferred_under(
                    self.backend.clone(),
                    command.to_vec(),
                    cwd.to_string(),
                    &String::from_utf8_lossy(evidence),
                    self.policy.as_deref(),
                )
            });
        ProcessSandboxAssessment {
            reporting: self.reporting,
            refusal,
        }
    }
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ProcessSandboxAssessment {
    pub reporting: ProcessSandboxDenialReporting,
    pub refusal: Option<ProcessSandboxRefusal>,
}

pub fn process_violation_error(
    output: &std::process::Output,
    command: &[String],
    cwd: &str,
) -> Option<VmError> {
    let policy = crate::orchestration::current_execution_policy()?;
    // Only a profile that actually confined the process may attribute the
    // child's failure to the OS sandbox. Under a profile that spawned it
    // unconfined, a permission error came from the child's own work.
    if !policy.sandbox_profile.confines_processes() {
        return None;
    }
    let sandbox_signal = sandbox_signal_status(output);
    let assessment = ProcessSandboxReportingContext::current().assess_exit(
        output.status.success(),
        sandbox_signal,
        &output.stdout,
        &output.stderr,
        command,
        cwd,
    );
    if let Some(refusal) = assessment.refusal {
        refusal.emit();
        let stderr = String::from_utf8_lossy(&output.stderr);
        let stdout = String::from_utf8_lossy(&output.stdout);
        let action = if sandbox_signal {
            "terminated"
        } else {
            "denied"
        };
        return Some(sandbox_denial_error(
            format!(
                "sandbox violation: process was {action} by the OS sandbox (status {}); \
                 mechanism={}: {}",
                output.status,
                refusal.mechanism.as_str(),
                refusal.reason,
            ),
            &format!("{stderr}\n{stdout}"),
            &policy,
        ));
    }
    None
}

/// Every subtree a confined child must not read: the non-removable credential
/// defaults, resolved against this user's home, plus whatever the policy added.
///
/// Unlike the additive root lists this is NOT existence-filtered. A denial for a
/// path that does not exist yet must survive that path being created between
/// profile generation and the child's read, so the rule is emitted regardless.
pub(crate) fn process_sandbox_read_deny_roots(policy: &CapabilityPolicy) -> Vec<PathBuf> {
    let mut denied: Vec<PathBuf> = Vec::new();
    if let Some(home) = sandbox_user_home_dir() {
        for relative in crate::orchestration::default_read_deny_home_paths() {
            denied.push(normalize_for_policy(&home.join(relative)));
        }
    }
    for root in &policy.process_sandbox.read_deny_roots {
        let normalized = normalize_for_policy(Path::new(root));
        if !denied.contains(&normalized) {
            denied.push(normalized);
        }
    }
    denied
}

/// True when `candidate` is inside any denied subtree.
pub(crate) fn path_is_denied(candidate: &Path, denied: &[PathBuf]) -> bool {
    denied.iter().any(|root| path_is_within(candidate, root))
}

pub use crate::value::{
    SandboxMechanism, SandboxMechanismAvailability, SandboxMechanismUnavailable, SandboxRequirement,
};

use crate::value::NO_OS_SANDBOX;

/// Helper for backends that can't attach confinement at all (macOS
/// without `/usr/bin/sandbox-exec`, and the unconfined backend on Windows
/// and every other platform without one): either fail loudly under
/// `OsHardened` / `enforce`, or warn once and proceed direct.
///
/// Linux and OpenBSD don't reach this path — they install confinement
/// in `pre_exec` and surface unavailability through `landlock_profile`
/// directly.
pub(crate) fn unavailable(
    mechanism: SandboxMechanism,
    availability: SandboxMechanismAvailability,
    profile: SandboxProfile,
) -> Result<PrepareOutcome, VmError> {
    match effective_fallback(profile) {
        SandboxFallback::Off | SandboxFallback::Warn => {
            warn_once(
                "handler_sandbox_unavailable",
                &mechanism_skipped_warning(mechanism, availability),
            );
            Ok(PrepareOutcome::Direct)
        }
        SandboxFallback::Enforce => {
            Err(SandboxMechanismUnavailable::new(mechanism, availability, profile).into_error())
        }
    }
}

/// The warn-and-proceed sentence: the mechanism fact and the consequence. The
/// remedy belongs to whoever owns the control, so it is not stated here.
pub(crate) fn mechanism_skipped_warning(
    mechanism: SandboxMechanism,
    availability: SandboxMechanismAvailability,
) -> String {
    if mechanism == SandboxMechanism::Unconfined {
        return format!("{NO_OS_SANDBOX}; child processes run unconfined");
    }
    let fact = availability.description();
    format!(
        "{} {fact}; process filesystem isolation is disabled",
        mechanism.display_name()
    )
}

#[cfg(test)]
#[path = "refusal_tests.rs"]
mod refusal_tests;