Package: isla-solver
ISLa: Input Specification LanguageInputs on Demand!ISLa is agrammar-aware string constraint solverwith its own specification language.
With ISLa, it is possible to specifyinput constraintslike "a variable has to be
defined before it is used," "the `file name' block must be 100 bytes long," or "the
number of columns in all CSV rows must be identical."Building on modern constraint solvers, ISLa provides you with a unique
flexibility to specify—and generate—the system inputs you need. ISLa can be
used forprecise fuzzing:Keep adding input specifications until you are satisfied
with the number of inputs passing the tested system's parser. Furthermore, you can write
ISLa specifications to carve out specific inputs for testing aparticular program
functionality.ExampleOur running example is a simple "assignment language" consisting of strings such asx := 1 ; y := x. As a first step towards using ISLa, we formalize this language as
a context-free grammar inBNF:<start>::=<stmt><stmt>::=<assgn>|<assgn>" ; "<stmt><assgn>::=<var>" := "<rhs><rhs>::=<var>|<digit><var>::="a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | 
            "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" |
            "u" | "v" | "w" | "x" | "y" | "z"<digit>::="0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"After saving this grammar to a file, say,assgn.bnf, we can already generate inputs
from the assignment grammar using the ISLa command line interface:>islasolveassgn.bnf
s:=tThe following command creates 10 assignments:>islasolve-n10assgn.bnf
a:=6;j:=x
q:=u
e:=h;o:=l;g:=w
s:=i
k:=v;d:=m;f:=1n:=y;t:=5z:=3;p:=7;b:=0c:=2;r:=4q:=8;l:=9u:=0The setting-n -1specifies that we want to generate an infinite number of inputs.
Since we did not choose an ISLa constraint, we additionally have to choose a value
for the-fflag. This setting determines the number of times an input element that
is not subject to any constraint (which is the case here) should be expanded. The final
line "UNSAT" means that after these 10 solutions, no further solution could be found.
If "UNSAT" is thefirstline output by the solver, it is likely that the given
constraint isunsatisfiable, i.e., there exists no solution of this constraint with
respect to the current grammar.With ISLa, we can restrict the assignment language on-demand. For example, the ISLa
constraint<var> = "a"results in assignment sequences only containing "a" variables:>islasolve/tmp/assgn.bnf-n10-f1--constraint'<var> = "a"'a:=5;a:=a;a:=7a:=6a:=a
a:=0;a:=a;a:=a
a:=a;a:=1;a:=4a:=a;a:=3;a:=a
a:=8;a:=2a:=9;a:=a
a:=a;a:=9a:=a;a:=a:bulb: The setting-f 1restricts the number of times that ILSa randomly
instantiates unconstrained input elements to one time. Here, this affects the<digit>nonterminals: Without-f 1, we would see 10 different variants of the
first input with variying numbers in the first and third assignment.Or do we prefer assignments where all digits can be divided by 2 without remainder? No
problem with ISLa:>islasolveassgn.bnf-n10-f1-s2--constraint"str.to.int(<digit>) mod 2 = 0"i:=a;x:=0;u:=s
p:=l;m:=8;b:=y
k:=c;t:=d;r:=q
j:=z
h:=0e:=4g:=n;v:=f;w:=4o:=o;j:=a;c:=0t:=r;k:=0;e:=0k:=t;f:=8;e:=8:bulb: The-sflag specifies how many results for a single query should be obtained
from the SMT solver Z3. We limited this number to 2 (the default is 10—the same
default value is used for the-fflag) to obtain a wider diversity of inputs within
the first 10 results.The constraints above talk overall<var>and<digit>grammar nonterminals in
any derivation tree derived from the assignment language grammar. In addition to such
simple constraints, ISLa allows to explicitlyquantifyover grammar elements using
theforallandexistskeywords.Assume that an interpreter for our assignment language rejects inputs where a variable
is accessed that has not been previously assigned a value. This "definition-use"
property, which is asemantic input propertyof the language, is expressed as follows:forall <assgn> assgn_1:
  exists <assgn> assgn_2: (
    before(assgn_2, assgn_1) and 
    assgn_1.<rhs>.<var> = assgn_2.<var>)Since this is a more lengthy constraint, let us save it in a filedefuse.isla. The
following command line invocation uses this constraint:>islasolve-n10-f1-s1assgn.bnfdefuse.isla
q:=2;m:=1;c:=4p:=8;o:=3;l:=p
z:=7;p:=6;e:=p
d:=5;a:=d;h:=9s:=0;x:=0k:=8p:=4;r:=p
p:=6;u:=p
p:=5;v:=p
p:=3;p:=5;w:=pAs we can see, all right-hand side variables occur at the left-hand side of a prior
assignment.For more information on the command line interface, runisla -h. Each sub command
comes with its own help text; for example,isla solve -hprovides details on how to
use thesolvecommand.You can also use the ISLa solver via its Python API:fromisla.solverimportISLaSolvergrammar='''<start> ::= <stmt><stmt>  ::= <assgn> | <assgn> " ; " <stmt><assgn> ::= <var> " := " <rhs><rhs>   ::= <var> | <digit><var>   ::= "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" |"k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" |"u" | "v" | "w" | "x" | "y" | "z"<digit> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"'''constraint="""forall <assgn> assgn_1:exists <assgn> assgn_2: (before(assgn_2, assgn_1) andassgn_1.<rhs>.<var> = assgn_2.<var>)"""solver=ISLaSolver(grammar=grammar,formula=constraint,max_number_free_instantiations=1,# -fmax_number_smt_instantiations=1,# -s)for_inrange(10):print(solver.solve())An example output of the above program snippet is:q := 7 ; m := 1 ; c := 8
p := 2 ; o := 2 ; l := p
z := 9 ; p := 4 ; e := p
d := 8 ; a := d ; h := 5
s := 0 ; x := 0
k := 7
p := 8 ; r := p
p := 9 ; u := p
p := 4 ; v := p
p := 2 ; p := 1 ; w := pFurther ResourcesOurinteractive ISLa tutorial,
published as a part of the Fuzzing Book, provides an easily accessible introduction
to the specification and generation of custom system inputs using ISLa.TheISLa Documentationcontainsinstallation and usage instructions;further examples;theISLa Language Specification,which precisely specifies the syntax and
semantics of ISLa constraints. It also contains a list of supported default
predicates;and aDeveloper's Guideto get started with ISLa's code.We published ascientific paper on ISLaat ESEC/FSE 2022. The paper describes the ISLa language and solver more formally.In the directorysrc/isla_formalizations/, you find our specifications for the
subject languages of our experimental evaluation.The filesrun_eval_....fishare the scripts we used to collect and analyze our
evaluation data. To analyze ISLa's current performance yourself, you can run the
scripts with the-hargument to obtain some guidance on their parameters (the fish
shell is required to use these scripts).Build, Run, InstallISLa depends onPython 3.10and the Python header files. To compile all of ISLa's
dependencies, you need gcc, g++ make, and cmake. To check out the current ISLa version,
git will be needed. Furthermore, python3.10-venv is required to run ISLearn in a virtual
environment.Additionally,for testing ISLa, clang and thecsvlintexecutable are required (for
the Scriptsize-C and CSV case studies).OnAlpine Linux, all dependencies (butcsvlint) can be installed usingapkaddpython3.10python3.10-devpython3.10-venvgccg++makecmakegitclangThecsvlintexecutable can be obtained fromhttps://github.com/Clever/csvlint/releases/download/v0.3.0/csvlint-v0.3.0-linux-amd64.tar.gz.
You obtain and unpackcsvlintby running (in a Unix shell)wgethttps://github.com/Clever/csvlint/releases/download/v0.3.0/csvlint-v0.3.0-linux-amd64.tar.gz-O/tmp/csvlint.tar.gz
tarxzf/tmp/csvlint.tar.gz-C/tmpThen, move the file/tmp/csvlint-v0.3.0-linux-amd64/csvlintto some location in your
PATH (e.g.,/usr/bin).InstallIf all external dependencies are available, a simplepip install isla-solversuffices.
We recommend installing ISLa inside a virtual environment (virtualenv):python3.10-mvenvvenvsourcevenv/bin/activate
pipinstall--upgradepip
pipinstallisla-solverNow, theislacommand should be available on the command line within the virtual
environment.DockerFor testing ISLa without having to care about external dependencies like Python, we provide a Docker container,
which already contains all dependencies.First, pull and run the Docker container:dockerpulldsteinhoefel/isla:latest
dockerrun-it--nameisladsteinhoefel/islaYou should now have entered the container. Next, check out the ISLa repository, and
update the requirements:gitclonehttps://github.com/rindPHI/isla.gitcdisla/Now, you can perform an editable installation of ISLa and run the ISLa tests:pipinstall-e.[dev,test]python3.10-mpytest-n16testsBuildISLearn is built locally as follows:gitclonehttps://github.com/rindPHI/isla.gitcdisla/

python3.10-mvenvvenvsourcevenv/bin/activate

pipinstall--upgradepip
pipinstall--upgradebuild
python3-mbuildThen, you will find the built wheel (*.whl) in thedist/directory.Testing & DevelopmentFor development, we recommend using ISLa inside a virtual environment (virtualenv). By thing the following steps in a
standard shell (bash), one can run the ISLa tests:gitclonehttps://github.com/rindPHI/isla.gitcdisla/

python3.10-mvenvvenvsourcevenv/bin/activate

pipinstall--upgradepip
pipinstall-rrequirements_test.txt# Run testspipinstall-e.[dev,test]python3-mpytest-n16testsThen you can, for instance, runpython3 tests/xml_demo.pyinside the virtual environment.ChangelogSeeCHANGELOG.md.Copyright, Authors and LicenseCopyright © 2022CISPA Helmholtz Center for Information Security.The ISLa code and documentation was, unless otherwise indicated, authored byDominic Steinhöfel.ISLa is released under the GNU General Public License v3.0 (seeCOPYING).