seccompiler 0.5.0

// Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0 OR BSD-3-Clause
#![deny(missing_docs)]
#![cfg(target_endian = "little")]
//! Provides easy-to-use Linux seccomp-bpf jailing.
//!
//! Seccomp is a Linux kernel security feature which enables a tight control over what kernel-level
//! mechanisms a process has access to. This is typically used to reduce the attack surface and
//! exposed resources when running untrusted code. This works by allowing users to write and set a
//! BPF (Berkeley Packet Filter) program for each process or thread, that intercepts syscalls and
//! decides whether the syscall is safe to execute.
//!
//! Writing BPF programs by hand is difficult and error-prone. This crate provides high-level
//! wrappers for working with system call filtering.
//!
//! The core concept of the library is the filter. It is an abstraction that
//! models a collection of syscall-mapped rules, coupled with on-match and
//! default actions, that logically describes a policy for dispatching actions
//! (e.g. Allow, Trap, Errno) for incoming system calls.
//!
//! Seccompiler provides constructs for defining filters, compiling them into
//! loadable BPF programs and installing them in the kernel.
//!
//! Filters are defined either with a JSON file or using Rust code, with
//! library-defined structures. Both representations are semantically equivalent
//! and model the rules of the filter. Choosing one or the other depends on the use
//! case and preference.
//!
//! # Supported platforms
//!
//! Due to the fact that seccomp is a Linux-specific feature, this crate is
//! supported only on Linux systems.
//!
//! Supported host architectures:
//! - Little-endian x86_64
//! - Little-endian aarch64
//! - Little-endian riscv64
//!
//! # Terminology
//!
//! The smallest unit of the [`SeccompFilter`] is the [`SeccompCondition`], which is a
//! comparison operation applied to the current system call. It’s parametrised by
//! the argument index, the length of the argument, the operator and the actual
//! expected value.
//!
//! Going one step further, a [`SeccompRule`] is a vector of [`SeccompCondition`]s,
//! that must all match for the rule to be considered matched. In other words, a
//! rule is a collection of **and-bound** conditions for a system call.
//!
//! Finally, at the top level, there’s the [`SeccompFilter`]. The filter can be
//! viewed as a collection of syscall-associated rules, with a predefined on-match
//! [`SeccompAction`] and a default [`SeccompAction`] that is returned if none of the rules match.
//!
//! In a filter, each system call number maps to a vector of **or-bound** rules.
//! In order for the filter to match, it is enough that one rule associated to the
//! system call matches. A system call may also map to an empty rule vector, which
//! means that the system call will match, regardless of the actual arguments.
//!
//! # Examples
//!
//! The following example defines and installs a simple Rust filter, that sends SIGSYS for
//! `accept4`, `fcntl(any, F_SETFD, FD_CLOEXEC, ..)` and `fcntl(any, F_GETFD, ...)`.
//! It allows any other syscalls.
//!
//! ```
//! use seccompiler::{
//!     BpfProgram, SeccompAction, SeccompCmpArgLen, SeccompCmpOp, SeccompCondition, SeccompFilter,
//!     SeccompRule,
//! };
//! use std::convert::TryInto;
//!
//! let filter: BpfProgram = SeccompFilter::new(
//!     vec![
//!         (libc::SYS_accept4, vec![]),
//!         (
//!             libc::SYS_fcntl,
//!             vec![
//!                 SeccompRule::new(vec![
//!                     SeccompCondition::new(
//!                         1,
//!                         SeccompCmpArgLen::Dword,
//!                         SeccompCmpOp::Eq,
//!                         libc::F_SETFD as u64,
//!                     )
//!                     .unwrap(),
//!                     SeccompCondition::new(
//!                         2,
//!                         SeccompCmpArgLen::Dword,
//!                         SeccompCmpOp::Eq,
//!                         libc::FD_CLOEXEC as u64,
//!                     )
//!                     .unwrap(),
//!                 ])
//!                 .unwrap(),
//!                 SeccompRule::new(vec![SeccompCondition::new(
//!                     1,
//!                     SeccompCmpArgLen::Dword,
//!                     SeccompCmpOp::Eq,
//!                     libc::F_GETFD as u64,
//!                 )
//!                 .unwrap()])
//!                 .unwrap(),
//!             ],
//!         ),
//!     ]
//!     .into_iter()
//!     .collect(),
//!     SeccompAction::Allow,
//!     SeccompAction::Trap,
//!     std::env::consts::ARCH.try_into().unwrap(),
//! )
//! .unwrap()
//! .try_into()
//! .unwrap();
//!
//! seccompiler::apply_filter(&filter).unwrap();
//! ```
//!
//!
//! This second example defines and installs an equivalent JSON filter (uses the `json` feature):
//!
//! ```
//! # #[cfg(feature = "json")]
//! # {
//! use seccompiler::BpfMap;
//! use std::convert::TryInto;
//!
//! let json_input = r#"{
//!     "main_thread": {
//!         "mismatch_action": "allow",
//!         "match_action": "trap",
//!         "filter": [
//!             {
//!                 "syscall": "accept4"
//!             },
//!             {
//!                 "syscall": "fcntl",
//!                 "args": [
//!                     {
//!                         "index": 1,
//!                         "type": "dword",
//!                         "op": "eq",
//!                         "val": 2,
//!                         "comment": "F_SETFD"
//!                     },
//!                     {
//!                         "index": 2,
//!                         "type": "dword",
//!                         "op": "eq",
//!                         "val": 1,
//!                         "comment": "FD_CLOEXEC"
//!                     }
//!                 ]
//!             },
//!             {
//!                 "syscall": "fcntl",
//!                 "args": [
//!                     {
//!                         "index": 1,
//!                         "type": "dword",
//!                         "op": "eq",
//!                         "val": 1,
//!                         "comment": "F_GETFD"
//!                     }
//!                 ]
//!             }
//!         ]
//!     }
//! }"#;
//!
//! let filter_map: BpfMap = seccompiler::compile_from_json(
//!     json_input.as_bytes(),
//!     std::env::consts::ARCH.try_into().unwrap(),
//! )
//! .unwrap();
//! let filter = filter_map.get("main_thread").unwrap();
//!
//! seccompiler::apply_filter(&filter).unwrap();
//!
//! # }
//! ```
//!
//! [`SeccompFilter`]: struct.SeccompFilter.html
//! [`SeccompCondition`]: struct.SeccompCondition.html
//! [`SeccompRule`]: struct.SeccompRule.html
//! [`SeccompAction`]: enum.SeccompAction.html

mod backend;
#[cfg(feature = "json")]
mod frontend;
#[cfg(feature = "json")]
mod syscall_table;

#[cfg(feature = "json")]
use std::convert::TryInto;
#[cfg(feature = "json")]
use std::io::Read;

use std::collections::HashMap;
use std::fmt::{Display, Formatter};
use std::io;

#[cfg(feature = "json")]
use frontend::json::{Error as JsonFrontendError, JsonCompiler};

// Re-export the IR public types.
pub use backend::{
    sock_filter, BpfProgram, BpfProgramRef, Error as BackendError, SeccompAction, SeccompCmpArgLen,
    SeccompCmpOp, SeccompCondition, SeccompFilter, SeccompRule, TargetArch,
};

// BPF structure definition for filter array.
// See /usr/include/linux/filter.h .
#[repr(C)]
struct sock_fprog {
    pub len: ::std::os::raw::c_ushort,
    pub filter: *const sock_filter,
}

/// Library Result type.
pub type Result<T> = std::result::Result<T, Error>;

///`BpfMap` is another type exposed by the library, which maps thread categories to BPF programs.
pub type BpfMap = HashMap<String, BpfProgram>;

/// Library errors.
#[derive(Debug)]
pub enum Error {
    /// Error originating in the backend compiler.
    Backend(BackendError),
    /// Attempting to install an empty filter.
    EmptyFilter,
    /// System error related to calling `prctl`.
    Prctl(io::Error),
    /// System error related to calling `seccomp` syscall.
    Seccomp(io::Error),
    /// Returned when calling `seccomp` with the thread sync flag (TSYNC) fails. Contains the pid
    /// of the thread that caused the failure.
    ThreadSync(libc::c_long),
    /// Json Frontend Error.
    #[cfg(feature = "json")]
    JsonFrontend(JsonFrontendError),
}

impl std::error::Error for Error {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        use self::Error::*;

        match self {
            Backend(error) => Some(error),
            Prctl(error) => Some(error),
            Seccomp(error) => Some(error),
            ThreadSync(_) => None,
            #[cfg(feature = "json")]
            JsonFrontend(error) => Some(error),
            _ => None,
        }
    }
}

impl Display for Error {
    fn fmt(&self, f: &mut Formatter) -> std::fmt::Result {
        use self::Error::*;

        match self {
            Backend(error) => {
                write!(f, "Backend error: {}", error)
            }
            EmptyFilter => {
                write!(f, "Cannot install empty filter.")
            }
            Prctl(errno) => {
                write!(f, "Error calling `prctl`: {}", errno)
            }
            Seccomp(errno) => {
                write!(f, "Error calling `seccomp`: {}", errno)
            }
            ThreadSync(pid) => {
                write!(
                    f,
                    "Seccomp filter synchronization failed in thread `{}`",
                    pid
                )
            }
            #[cfg(feature = "json")]
            JsonFrontend(error) => {
                write!(f, "Json Frontend error: {}", error)
            }
        }
    }
}

impl From<BackendError> for Error {
    fn from(value: BackendError) -> Self {
        Self::Backend(value)
    }
}
#[cfg(feature = "json")]
impl From<JsonFrontendError> for Error {
    fn from(value: JsonFrontendError) -> Self {
        Self::JsonFrontend(value)
    }
}

/// Apply a BPF filter to the calling thread.
///
/// # Arguments
///
/// * `bpf_filter` - A reference to the [`BpfProgram`] to be installed.
///
/// [`BpfProgram`]: type.BpfProgram.html
pub fn apply_filter(bpf_filter: BpfProgramRef) -> Result<()> {
    apply_filter_with_flags(bpf_filter, 0)
}

/// Apply a BPF filter to the all threads in the process via the TSYNC feature. Please read the
/// man page for seccomp (`man 2 seccomp`) for more information.
///
/// # Arguments
///
/// * `bpf_filter` - A reference to the [`BpfProgram`] to be installed.
///
/// [`BpfProgram`]: type.BpfProgram.html
pub fn apply_filter_all_threads(bpf_filter: BpfProgramRef) -> Result<()> {
    apply_filter_with_flags(bpf_filter, libc::SECCOMP_FILTER_FLAG_TSYNC)
}

/// Apply a BPF filter to the calling thread.
///
/// # Arguments
///
/// * `bpf_filter` - A reference to the [`BpfProgram`] to be installed.
/// * `flags` - A u64 representing a bitset of seccomp's flags parameter.
///
/// [`BpfProgram`]: type.BpfProgram.html
fn apply_filter_with_flags(bpf_filter: BpfProgramRef, flags: libc::c_ulong) -> Result<()> {
    // If the program is empty, don't install the filter.
    if bpf_filter.is_empty() {
        return Err(Error::EmptyFilter);
    }

    // SAFETY:
    // Safe because syscall arguments are valid.
    let rc = unsafe { libc::prctl(libc::PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) };
    if rc != 0 {
        return Err(Error::Prctl(io::Error::last_os_error()));
    }

    let bpf_prog = sock_fprog {
        len: bpf_filter.len() as u16,
        filter: bpf_filter.as_ptr(),
    };
    let bpf_prog_ptr = &bpf_prog as *const sock_fprog;

    // SAFETY:
    // Safe because the kernel performs a `copy_from_user` on the filter and leaves the memory
    // untouched. We can therefore use a reference to the BpfProgram, without needing ownership.
    let rc = unsafe {
        libc::syscall(
            libc::SYS_seccomp,
            libc::SECCOMP_SET_MODE_FILTER,
            flags,
            bpf_prog_ptr,
        )
    };

    #[allow(clippy::comparison_chain)]
    // Per manpage, if TSYNC fails, retcode is >0 and equals the pid of the thread that caused the
    // failure. Otherwise, error code is -1 and errno is set.
    if rc < 0 {
        return Err(Error::Seccomp(io::Error::last_os_error()));
    } else if rc > 0 {
        return Err(Error::ThreadSync(rc));
    }

    Ok(())
}

/// Compile [`BpfProgram`]s from JSON.
///
/// # Arguments
///
/// * `reader` - [`std::io::Read`] object containing the JSON data conforming to the
///    [JSON file format](https://github.com/rust-vmm/seccompiler/blob/master/docs/json_format.md).
/// * `arch` - target architecture of the filter.
///
/// [`BpfProgram`]: type.BpfProgram.html
#[cfg(feature = "json")]
pub fn compile_from_json<R: Read>(reader: R, arch: TargetArch) -> Result<BpfMap> {
    // Run the frontend.
    let seccomp_filters: HashMap<String, SeccompFilter> =
        JsonCompiler::new(arch).compile(reader)?;

    // Run the backend.
    let mut bpf_data: BpfMap = BpfMap::with_capacity(seccomp_filters.len());
    for (name, seccomp_filter) in seccomp_filters {
        bpf_data.insert(name, seccomp_filter.try_into()?);
    }

    Ok(bpf_data)
}