gvisor.dev/gvisor@v0.0.0-20240520182842-f9d4d51c7e0f/pkg/seccomp/precompiledseccomp/README.md (about)

     1  # precompiledseccomp
     2  
     3  This package provides build tooling to embed precompiled seccomp-bpf programs
     4  inside Go binaries. Within gVisor, this is useful to keep startup time fast.
     5  
     6  It also features basic support for runtime-modifiable `uint32` variables within
     7  embedded programs. This allows having values that are only known at runtime
     8  (e.g. FD numbers) to remain usable within seccomp filtering rules.
     9  
    10  ## Usage
    11  
    12  You will need two Go libraries: One where you'll list the seccomp-bpf programs
    13  that you want embedded, and one where those precompiled programs will be
    14  embedded. This allows you to define the list of seccomp-bpf programs
    15  programmatically.
    16  
    17  ### 1: Define a Go library returning a set of programs to precompile
    18  
    19  You need to define a `go_library` target which declares a package-level
    20  function:
    21  
    22  ```go
    23  func PrecompiledPrograms() ([]precompiledseccomp.Program, error)
    24  ```
    25  
    26  Look at [example.go](example/example.go) for a documented example.
    27  
    28  ### 2: Call `precompiled_seccomp_rules`
    29  
    30  The [`precompiled_seccomp_rules`](defs.bzl) BUILD macro will auto-generate a
    31  `.go` file which contains the precompiled seccomp-bpf binary that your first Go
    32  library specifies.
    33  
    34  Look at [example/usage/BUILD](example/usage/BUILD) for an example.
    35  
    36  ### 3: Use the generated library to access embedded programs
    37  
    38  Use the auto-generated `.go` file from step 2 in the second `go_library`. A new
    39  package-level function will be defined:
    40  
    41  ```go
    42  func GetPrecompiled(programName string) (precompiledseccomp.Program, bool)
    43  ```
    44  
    45  You can call it to get the precompiled seccomp-bpf program.
    46  
    47  See [example/usage/usage.go](example/usage/usage.go) for a documented example.
    48  
    49  ## How does it work?
    50  
    51  See the [`precompiled_seccomp_rules`](defs.bzl) BUILD macro for the precise
    52  logic. At a high level, it generates a `go_binary` target that imports your
    53  first `go_library` (expressing your desired seccomp-bpf program). When this Go
    54  binary runs, it will compile the programs and output Go code that contains the
    55  compiled programs. Lastly, we use a `genrule` to execute this generated program
    56  and direct its output to a file of your choosing, which you can now embed in
    57  your second `go_library`.
    58  
    59  In order to support variables, the compilation step actually compiles the
    60  program twice, using different placeholder values for all variables. It looks at
    61  the places in the BPF bytecode where these values show up, and ensures that
    62  these offsets are consistent across both compilation attempts.