README.md

   1 ![Enhanced Seccomp Helper Library](https://github.com/seccomp/libseccomp-artwork/blob/master/logo/libseccomp-color_text.png)
   2 ===============================================================================
   3 https://github.com/seccomp/libseccomp
   4
   5 [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/608/badge)](https://bestpractices.coreinfrastructure.org/projects/608)
   6 [![Build Status](https://img.shields.io/travis/seccomp/libseccomp/master.svg)](https://travis-ci.org/seccomp/libseccomp)
   7 [![Coverage Status](https://img.shields.io/coveralls/github/seccomp/libseccomp/master.svg)](https://coveralls.io/github/seccomp/libseccomp?branch=master)
   8
   9 The libseccomp library provides an easy to use, platform independent, interface
  10 to the Linux Kernel's syscall filtering mechanism.  The libseccomp API is
  11 designed to abstract away the underlying BPF based syscall filter language and
  12 present a more conventional function-call based filtering interface that should
  13 be familiar to, and easily adopted by, application developers.
  14
  15 ## Online Resources
  16
  17 The library source repository currently lives on GitHub at the following URL:
  18
  19 * https://github.com/seccomp/libseccomp
  20
  21 The Go language bindings repository currently lives on GitHub at the following
  22 URL:
  23
  24 * https://github.com/seccomp/libseccomp-golang
  25
  26 The project mailing list is currently hosted on Google Groups at the URL below,
  27 please note that a Google account is not required to subscribe to the mailing
  28 list.
  29
  30 * https://groups.google.com/forum/#!forum/libseccomp
  31 * https://groups.google.com/forum/#!forum/libseccomp/join
  32
  33 ## Supported Architectures
  34
  35 The libseccomp library currently supports the architectures listed below:
  36
  37 * 32-bit x86 (x86)
  38 * 64-bit x86 (x86_64)
  39 * 64-bit x86 x32 ABI (x32)
  40 * 32-bit ARM EABI (arm)
  41 * 64-bit ARM (aarch64)
  42 * 32-bit MIPS (mips)
  43 * 32-bit MIPS little endian (mipsel)
  44 * 64-bit MIPS (mips64)
  45 * 64-bit MIPS little endian (mipsel64)
  46 * 64-bit MIPS n32 ABI (mips64n32)
  47 * 64-bit MIPS n32 ABI little endian (mipsel64n32)
  48 * 32-bit PA-RISC (parisc)
  49 * 64-bit PA-RISC (parisc64)
  50 * 32-bit PowerPC (ppc)
  51 * 64-bit PowerPC (ppc64)
  52 * 64-bit PowerPC little endian (ppc64le)
  53 * 32-bit s390 (s390)
  54 * 64-bit s390x (s390x)
  55
  56 ## Documentation
  57
  58 The "doc/" directory contains all of the currently available documentation,
  59 mostly in the form of manpages.  The top level directory also contains a README
  60 file (this file) as well as the LICENSE, CREDITS, CONTRIBUTING, and
  61 CHANGELOG files.
  62
  63 Those who are interested in contributing to the the project are encouraged to
  64 read the CONTRIBUTING in the top level directory.
  65
  66 ## Building and Installing the Library
  67
  68 If you are building the libseccomp library from an official release tarball,
  69 you should follow the familiar three step process used by most autotools based
  70 applications:
  71
  72         # ./configure
  73         # make [V=0|1]
  74         # make install
  75
  76 However, if you are building the library from sources retrieved from the source
  77 repository you may need to run the autogen.sh script before running configure.
  78 In both cases, running "./configure -h" will display a list of build-time
  79 configuration options.
  80
  81 ## Testing the Library
  82
  83 There are a number of tests located in the "tests/" directory and a make target
  84 which can be used to help automate their execution.  If you want to run the
  85 standard regression tests you can execute the following after building the
  86 library:
  87
  88         # make check
  89
  90 These tests can be safely run on any Linux system, even those where the kernel
  91 does not support seccomp-bpf (seccomp mode 2).  However, be warned that the
  92 test run can take a while to run and produces a lot of output.
  93
  94 The generated seccomp-bpf filters can be tested on a live system using the
  95 "live" tests; they can be executed using the following commands:
  96
  97         # make check-build
  98         # (cd tests; ./regression -T live)
  99
 100 These tests will fail if the running Linux Kernel does not provide the
 101 necessary support.
 102
 103 ## Developer Tools
 104
 105 The "tools/" directory includes a number of tools which may be helpful in the
 106 development of the library, or applications using the library.  Not all of
 107 these tools are installed by default.
 108
 109 ## Bug and Vulnerability Reporting
 110
 111 Problems with the libseccomp library can be reported using the GitHub issue
 112 tracking system or the mailing list.  Those who wish to privately report
 113 potential vulnerabilities can send mail to paul@paul-moore.com.