8 releases

0.2.3 Feb 14, 2022
0.2.2 Jan 1, 2022
0.2.1 Dec 31, 2021
0.1.3 May 11, 2021
0.1.1 Apr 20, 2021

#20 in Operating systems

Download history 1838/week @ 2022-04-21 1936/week @ 2022-04-28 1596/week @ 2022-05-05 2472/week @ 2022-05-12 1869/week @ 2022-05-19 2243/week @ 2022-05-26 1619/week @ 2022-06-02 1680/week @ 2022-06-09 2067/week @ 2022-06-16 1967/week @ 2022-06-23 1621/week @ 2022-06-30 2028/week @ 2022-07-07 1922/week @ 2022-07-14 2123/week @ 2022-07-21 2568/week @ 2022-07-28 2155/week @ 2022-08-04

9,206 downloads per month
Used in 2 crates (via extrasafe)

MIT/Apache

140KB
2K SLoC

libseccomp-rs

build-test Latest release on crates.io Documentation on docs.rs codecov

Rust Language Bindings for the libseccomp Library

The libseccomp library provides an easy to use, platform independent, interface to the Linux Kernel's syscall filtering mechanism. The libseccomp API is designed to abstract away the underlying BPF based syscall filter language and present a more conventional function-call based filtering interface that should be familiar to, and easily adopted by, application developers.

The libseccomp-rs provides a Rust based interface to the libseccomp library. This repository contains libseccomp and libseccomp-sys crates that enable developers to use the libseccomp API in Rust.

  • libseccomp: High-level safe API
  • libseccomp-sys: Low-level unsafe API

CHANGELOG

Example

Create and load a single seccomp rule:

use libseccomp::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Creates and returns a new filter context.
    let mut filter = ScmpFilterContext::new_filter(ScmpAction::Allow)?;

    // Adds an architecture to the filter.
    filter.add_arch(ScmpArch::X8664)?;

    // Returns the number of a syscall by name.
    let syscall = ScmpSyscall::from_name("dup3")?;

    // Adds a single rule for an unconditional action on the syscall.
    filter.add_rule(ScmpAction::Errno(10), syscall)?;

    // Loads the filter context into the kernel.
    filter.load()?;

    // The dup3 fails by the seccomp rule.
    assert_eq!(
        unsafe { libc::dup3(0, 100, libc::O_CLOEXEC) } as i32,
        -libc::EPERM
    );
    assert_eq!(std::io::Error::last_os_error().raw_os_error().unwrap(), 10);

    Ok(())
}

Requirements

Before using the libseccomp crate, you need to install the libseccomp library for your system. The libseccomp library version 2.4 or newer is required.

Installing the libseccomp library from a package

e.g. Debian-based Linux

$ sudo apt install libseccomp-dev

Building and installing the libseccomp library from sources

If you want to build the libseccomp library from an official release tarball instead of the package, you should follow the quick step.

$ LIBSECCOMP_VERSION=2.5.3
$ wget https://github.com/seccomp/libseccomp/releases/download/v${LIBSECCOMP_VERSION}/libseccomp-${LIBSECCOMP_VERSION}.tar.gz
$ tar xvf libseccomp-${LIBSECCOMP_VERSION}.tar.gz
$ cd libseccomp-${LIBSECCOMP_VERSION}
$ ./configure
$ make
$ sudo make install

For more details, see the libseccomp library repository.

Setup

If you use the libseccomp crate with dynamically linked the libseccomp library, you do not need additional settings.

However, if you want to use the libseccomp crate against musl-libc with statically linked the libseccomp library, you have to set the LIBSECCOMP_LINK_TYPE and LIBSECCOMP_LIB_PATH environment variables as follows.

$ export LIBSECCOMP_LINK_TYPE=static
$ export LIBSECCOMP_LIB_PATH="the path of the directory containing libseccomp.a (e.g. /usr/lib)"

Note: To build the libseccomp crate against musl-libc, you need to build the libseccomp library manually for musl-libc or use a musl-based distribution that provides a package for the statically-linked libseccomp library

Now, add the following to your Cargo.toml to start building the libseccomp crate.

[dependencies]
libseccomp = "0.2.3"

Testing the crate

The libseccomp crate provides a number of unit tests. If you want to run the standard regression tests, you can execute the following command.

$ make test

How to contribute

Anyone is welcome to join and contribute code, documentation, and use cases.

  • Change or add something
  • Make sure you're using the latest stable version of Rust
  • Run make check to guarantee code style conformance
  • Open a pull request in Github

We use the following format for doc comments of a function:

/// Brief summary of the function on one line. (Start from "verb-s")
///
/// Detailed description of the function. (if you have)
///
/// Description of the return value on success.
/// (Start from "This function returns...")
///
/// # Arguments (if the function has arguments)
///
/// * `arg` - Descripition of the argument
///
/// # Errors (if the function returns `Result`)
///
///  If this function encounters..., an error will be returned.
///
/// # Panics (if the function can `panic`)
///
///  Panics if...
///
/// # Examples (if you want to show the example)
///
/// ```
/// Example codes
/// ```
pub fn foo() {

License

This crate is licensed under:

  • MIT License (see LICENSE-MIT); or
  • Apache 2.0 License (see LICENSE-APACHE),

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in libseccomp-rs by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies