dfuzzer - Man Page

Tool for fuzz testing processes communicating through D-Bus

Synopsis

dfuzzer {--bus=BUS_NAME} [Options...]

Description

dfuzzer is the D-Bus fuzzer, the tool for fuzz testing processes communicating through D-Bus. It can be used to test processes connected to both, the session bus and the system bus daemon. The fuzzer works as a client, it first connects to the bus daemon and then it traverses and fuzz tests all the methods provided by a D-Bus service (specified by the -n/--bus-name= option). By default only failures and warnings are printed. Use -v/--verbose for verbose mode.

Fuzz tests are performed on methods of a chosen interface(s) and an object(s) for the given bus name. Fuzzer generates random arguments for each method of an interface and calls these methods everytime with different generated arguments.

dfuzzer is monitoring tested process state during fuzz testing. In case tested process crashed it is printed on the output of dfuzzer. Fuzzer always prints exit status (see section "Exit status") before exiting.

If you are getting exceptions (printed only in verbose mode: -v/--verbose option) like org.freedesktop.DBus.Error.AccessDenied or org.freedesktop.DBus.Error.AuthFailed during testing, try to run dfuzzer as root (warning: this is dangerous, proceed with caution).

Options

The following options are understood:

-b NAME, --bus-name=NAME

D-Bus name to test.

-o PATH, --object=PATH

D-Bus object path to test. All children objects are traversed.

-i NAME, --interface=NAME

D-Bus interface name to test. Requires -o/--object= to be set as well.

-t NAME, --method=NAME

If provided, only method named NAME is tested. Requires -o/--object= and -i/--interface= to be set as well.

Implies --skip-properties.

-p NAME, --property=NAME

If provided, only property named NAME is tested. Requires -o/--object= and -i/--interface= to be set as well.

Implies --skip-methods.

--skip-methods

Skip method testing and test only properties.

--skip-properties

Skip property testing and test only methods.

-e COMMAND, --command=COMMAND

Command to execute after each method call. If given command finishes unsuccessfully, fail message is printed with its return value.

--show-command-output

Don't suppress stdout/stderr of a COMMAND specified via --command=

-f FILENAME, --dictionary=FILENAME

Name of a file with custom dictionary whhich is used as input for fuzzed methods before generating random data. Currently supports only strings (one per line).

-x ITERATIONS, --max-iterations=ITERATIONS

Set the upper limit for number of iterations done for each method. This limit comes into effect only if the automatically calculated number of iterations would exceed this limit. At least 1 iteration is required.

-y ITERATIONS, --min-iterations=ITERATIONS

Same as -x/--max-iterations= but for the lower limit. Again, the limit comes into effect only if the number of automatically calculated iterations would fall below ITERATIONS.

-I ITERATIONS, --iterations=ITERATIONS

Set both -y/--min-iterations= and -x/--max-iterations= to ITERATIONS effectively setting the number of iterations for each method to ITERATIONS.

-L DIRNAME, --log-dir=DIRNAME

If set, dfuzzer writes a machine-readable CSV log into DIRNAME/BUSNAME. The directory must exist.

-b SIZE, --buffer-limit=DIRNAME

Maximum buffer size for generated strings in bytes. Defaults to 50000. Minimal accepted value is 256.

-l,  --list

List all available services on both the system and the session buses.

-s,  --no-suppressions

Do not load suppression file(s). Default behavior is to locate and load suppression files in standard locations in the following order:

./dfuzzer.conf

~/.dfuzzer.conf

/etc/dfuzzer.conf

For information about the format of the suppression file see the section "Suppression file format".

-v,  --verbose

Enable verbose logging.

-d,  --debug

Enable debug logging. Implies -v/--verbose. This option should not be normally used during testing.

-V,  --version

Print dfuzzer version and exit.

-h,  --help

Print a short help text and exit.

Exit Status

dfuzzer may return these codes:

0 testing ended successfully
1 an error occured (either an internall error, or a D-Bus related error)
2 testing detected failures (including warnings)
3 testing detected only warnings

Suppression File Format

Suppression file is divided into sections for each service, where each section contains a path to the suppressed method and an optional description, which is printed to the output when such method is suppressed:

[org.foo.bar]
hello   potentially destructive
world   also destructive

In this example methods hello and world will be suppressed on the org.foo.bar bus, no matter under which object/interface they appear.

For more granular suppression, the method name can be given in format

object_path:interface_name:method

where each part can be omited (omitted parts behave like a wildcard, i.e. they match any object/interface/method). For example:

[org.foo.baz]
hello                   suppress the method 'hello' on any interface
::hello                 ditto, since object and interface are empty
:hello                  ditto

/org::world             suppress the method 'world' on any interface under the object '/org'
/org:boo:world          suppress the methdo 'world' on interface 'boo' and under object '/org'
:org.freedesktop.Foo:   suppress all methods on interface 'org.freedesktop.Foo' under any object
/org::                  suppress all methods on any interface under object '/org'

Examples

List all services on system/session bus:

dfuzzer -l

Test all methods of GNOME Shell. Be verbose:

dfuzzer -v -n org.gnome.Shell

Test only a specific method on given bus name, object path, and interface:

dfuzzer -n org.freedesktop.Avahi -o / -i org.freedesktop.Avahi.Server -t GetAlternativeServiceName

Test all methods of Avahi and be verbose. Redirect all log messages including failures and warnings into avahi.log:

dfuzzer -v -n org.freedesktop.Avahi |& tee avahi.log

Test name org.freedesktop.Avahi, be verbose, and do not use suppression file:

dfuzzer -v -s -n org.freedesktop.Avahi

Author

Matus Marhefka (mmarhefk@redhat.com)

Bugs

Please report all bugs to the upstream tracker at https://github.com/dbus-fuzzer/dfuzzer.

See Also

gdbus(1)

Notes

1.

https://github.com/dbus-fuzzer/dfuzzer

Info

01/29/2024