Package: dnnf
Reducing DNN Properties to Enable Falsification with Adversarial AttacksThis repo accompanies the paperReducing DNN Properties to Enable Falsification with Adversarial Attacks, and provides a tool for running falsification methods such as adversarial attacks on DNN property specifications specified using theDNNPlanguage ofDNNV. For an overview of our paper, check out ourvideo presentation.Additional documentation can be found onRead the Docs.InstallWe provide instructions for installing DNNF with pip, installing DNNF from source, as well as for building and running a docker image.Pip InstallDNNF can be installed using pip by running:$pipinstalldnnfThis will install the latest release of DNNF onPyPI.
To install the optional falsification backends, you can replacednnfin the above command withdnnf[BACKENDS],
whereBACKENDSis a comma separated list of the backends you wish to include (i.e.,cleverhansorfoolbox).
To install the most recent changes from GitHub, run:$pipinstallgit+https://github.com/dlshriver/dnnf.git@mainTo install the cleverhans or foolbox backends, run the above command with the option--install-option="--extras-require=cleverhans,foolbox"included.Installation with pip will not install the TensorFuzz falsification backend. Currently this backend is only available through manual installation or the provided docker image.Source InstallThe required dependencies to install DNNF from source are:python3gitThe additional, optional tensorfuzz backend also requires:python2.7virtualenvIf you do not plan to use tensorfuzz, then these dependencies are not required.
Please ensure that the required dependencies are installed prior to running the installation script.
For example, on a fresh Ubuntu 20.04 system, the dependencies can be installed using apt as follows:$sudoadd-apt-repositoryppa:deadsnakes/ppa$sudoapt-getupdate$sudoapt-getinstallgitpython3.8# python2.7 virtualenvTo install DNNF in the local directory, download this repo and run the provided installation script,
optionally specifying which backends to include during installation:$./install.sh[--include-cleverhans][--include-foolbox][--include-tensorfuzz]To see additional installation options, use the-hoption.We have successfully tested this installation procedure on machines running Ubuntu 20.04 and CentOS 7.Docker InstallWe provide a pre-built docker image containing DNNF, available onDocker Hub. To use this image, run the following:$dockerpulldlshriver/dnnf$dockerrun--rm-itdlshriver/dnnf(.venv)dnnf@hostname:~$dnnf-hTo build a docker image with the latest changes to DNNF, run:$dockerbuild.-tdlshriver/dnnf$dockerrun--rm-itdlshriver/dnnf(.venv)dnnf@hostname:~$dnnf-hExecutionDNNF can be run on correctness problems specified usingONNXandDNNP.
DNNP is the same property specification language used by theDNNVverifier framework.
A description of this specification language can be found in theDNNV documentation.To execute DNNF, first activate the virtual environment with:$..venv/bin/activateThis is only required if DNNF was installed manually. The virtual environment should open automatically if using the docker image.The DNNF tool can then be run as follows:$dnnfPROPERTY--networkNAMEPATHWherePROPERTYis the path to the property specification,NAMEis the name of the network used in the property specification (typicallyN), andPATHis the path to a DNN model in theONNXformat.To see additional options, run:$dnnf-hTo see the currently available falsification backends, use the--long-helpoption.Running on the BenchmarksWe provide several DNN verification benchmarks in DNNP and ONNX formats indlshriver/dnnv-benchmarks.
This benchmark repository includes both the DNNF-GHPR and the DNNF-CIFAR-EQ benchmarks introduced by DNNF!To execute DNNF on a problem in one of the benchmarks,
first navigate to the desired benchmark directory inbenchmarks(e.g.,DNNF-GHPR,DNNF-GHPR).
Then run DNNF as specified above.
For example, to run DNNF with the Projected Gradient Descent adversarial attack fromcleverhanson an DNNF-GHPR property and network,
run:$cdbenchmarks/DNNF-GHPR$dnnfproperties/dronet_property_0.py--networkNonnx/dronet.onnx--backendcleverhans.projected_gradient_descentWhich will produce output similar to:Falsifying:Forall(x,(((0<=x)&(x<=1)&(N[(slice(2,-3,None),1)](x)<=-2.1972245773362196))==>((-0.08726646259971647<=N[(slice(2,-1,None),0)](x))&(N[(slice(2,-1,None),0)](x)<=0.08726646259971647))))dnnfresult:satfalsificationtime:0.6901totaltime:2.3260The available backends for falsification are:CleverHanscleverhans.carlini_wagner_l2cleverhans.fast_gradient_methodcleverhans.hop_skip_jump_attackcleverhans.projected_gradient_descentcleverhans.spsaFoolBoxfoolbox.ATTACKwhereATTACKis the name of an adversarial attack fromthis listTensorFuzztensorfuzzAttack specific parameters can be set using the--set BACKEND NAME VALUEoption.
For example, to set thenb_iterparameter of thecleverhans.projected_gradient_descentattack to 40 steps,
you can specify--set cleverhans.projected_gradient_descent nb_iter 40.If a property uses parameters, then the parameter value can be set using--prop.PARAMETER=VALUE,
e.g.,--prop.epsilon=1, similar to DNNV.AcknowledgementsThis material is based in part upon work supported by the National Science Foundation under grant number 1900676 and 2019239.