csource

Documentation

Overview

Package csource generates [almost] equivalent C programs from syzkaller programs.

Outline of the process:

• inputs to the generation are the program and options
• options control multiple aspects of the resulting C program, like if we want a multi-threaded program or a single-threaded, what type of sandbox we want to use, if we want to setup net devices or not, etc
• we use actual executor sources as the base
• gen.go takes all executor/common*.h headers and bundles them into generated.go
• during generation we tear executor headers apart and take only the bits we need for the current program/options, this is done by running C preprocessor with particular set of defines so that the preprocessor removes unneeded #ifdef SYZ_FOO sections
• then we generate actual syscall calls with the given arguments based on the binary "encodingexec" representation of the program (the same representation executor uses for interpretation)
• then we glue it all together
• as the last step we run some text post-processing on the resulting source code: remove debug calls, replace exitf/fail with exit, hoist/sort/dedup includes, remove duplicate empty lines, etc

Index

• Variables
• func Build(target *prog.Target, src []byte) (string, error)
• func BuildExecutor(t *testing.T, target *prog.Target, rootDir string, cflags ...string) string
• func BuildNoWarn(target *prog.Target, src []byte) (string, error)
• func FeaturesToFlags(features flatrpc.Feature, manual Features) flatrpc.ExecEnv
• func Format(src []byte) ([]byte, error)
• func PrintAvailableFeaturesFlags()
• func Write(p *prog.Prog, opts Options) ([]byte, error)
• type Feature
• type Features
  • func ParseFeaturesFlags(enable, disable string, defaultValue bool) (Features, error)
• type LegacyOptions
• type Options
  • func DefaultOpts(cfg *mgrconfig.Config) Options
  • func DeserializeOptions(data []byte) (Options, error)
  • func (opts Options) Check(OS string) error
  • func (opts Options) Serialize() []byte

Variables

var ExecutorOpts = Options{
	Threaded:  true,
	Repeat:    true,
	Procs:     2,
	Slowdown:  1,
	Sandbox:   "none",
	UseTmpDir: true,
}

This is the main configuration used by executor, only for testing.

var FlatRPCFeaturesToCSource = map[flatrpc.Feature]string{
	flatrpc.FeatureNetInjection:    "tun",
	flatrpc.FeatureNetDevices:      "net_dev",
	flatrpc.FeatureDevlinkPCI:      "devlink_pci",
	flatrpc.FeatureNicVF:           "nic_vf",
	flatrpc.FeatureVhciInjection:   "vhci",
	flatrpc.FeatureWifiEmulation:   "wifi",
	flatrpc.FeatureUSBEmulation:    "usb",
	flatrpc.FeatureBinFmtMisc:      "binfmt_misc",
	flatrpc.FeatureLRWPANEmulation: "ieee802154",
	flatrpc.FeatureSwap:            "swap",
}

Functions

func Build

func Build(target *prog.Target, src []byte) (string, error)

Build builds a C program from source src and returns name of the resulting binary.

func BuildExecutor

func BuildExecutor(t *testing.T, target *prog.Target, rootDir string, cflags ...string) string

BuildExecutor builds the executor binary for tests. rootDir must point to syzkaller root directory in slash notation.

func BuildNoWarn

func BuildNoWarn(target *prog.Target, src []byte) (string, error)

BuildNoWarn is the same as Build, but ignores all compilation warnings. Should not be used in tests, but may be used e.g. when we are bisecting and potentially using an old repro with newer compiler, or a compiler that we never seen before. In these cases it's more important to build successfully.

func FeaturesToFlags

func FeaturesToFlags(features flatrpc.Feature, manual Features) flatrpc.ExecEnv

func Format

func Format(src []byte) ([]byte, error)

Format reformats C source using clang-format.

func PrintAvailableFeaturesFlags

func PrintAvailableFeaturesFlags()

func Write

func Write(p *prog.Prog, opts Options) ([]byte, error)

Write generates C source for program p based on the provided options opt.

Types

type Feature

type Feature struct {
	Description string
	Enabled     bool
}

type Features

type Features map[string]Feature

func ParseFeaturesFlags

func ParseFeaturesFlags(enable, disable string, defaultValue bool) (Features, error)

type LegacyOptions

type LegacyOptions struct {
	Collide   bool `json:"collide,omitempty"`
	Fault     bool `json:"fault,omitempty"`
	FaultCall int  `json:"fault_call,omitempty"`
	FaultNth  int  `json:"fault_nth,omitempty"`
}

These are legacy options, they remain only for the sake of backward compatibility.

type Options

type Options struct {
	Threaded    bool   `json:"threaded,omitempty"`
	Repeat      bool   `json:"repeat,omitempty"`
	RepeatTimes int    `json:"repeat_times,omitempty"` // if non-0, repeat that many times
	Procs       int    `json:"procs"`
	Slowdown    int    `json:"slowdown"`
	Sandbox     string `json:"sandbox"`
	SandboxArg  int    `json:"sandbox_arg"`

	Leak bool `json:"leak,omitempty"` // do leak checking

	// These options allow for a more fine-tuned control over the generated C code.
	NetInjection  bool `json:"tun,omitempty"`
	NetDevices    bool `json:"netdev,omitempty"`
	NetReset      bool `json:"resetnet,omitempty"`
	Cgroups       bool `json:"cgroups,omitempty"`
	BinfmtMisc    bool `json:"binfmt_misc,omitempty"`
	CloseFDs      bool `json:"close_fds"`
	KCSAN         bool `json:"kcsan,omitempty"`
	DevlinkPCI    bool `json:"devlinkpci,omitempty"`
	NicVF         bool `json:"nicvf,omitempty"`
	USB           bool `json:"usb,omitempty"`
	VhciInjection bool `json:"vhci,omitempty"`
	Wifi          bool `json:"wifi,omitempty"`
	IEEE802154    bool `json:"ieee802154,omitempty"`
	Sysctl        bool `json:"sysctl,omitempty"`
	Swap          bool `json:"swap,omitempty"`

	UseTmpDir  bool `json:"tmpdir,omitempty"`
	HandleSegv bool `json:"segv,omitempty"`

	Trace bool `json:"trace,omitempty"`
	LegacyOptions
}

Options control various aspects of source generation. Dashboard also provides serialized Options along with syzkaller reproducers.

func DefaultOpts

func DefaultOpts(cfg *mgrconfig.Config) Options

func DeserializeOptions

func DeserializeOptions(data []byte) (Options, error)

func (Options) Check

func (opts Options) Check(OS string) error

Check checks if the opts combination is valid or not. For example, Collide without Threaded is not valid. Invalid combinations must not be passed to Write.

func (Options) Serialize

func (opts Options) Serialize() []byte