head     1.1;
branch   1.1.1;
access   ;
symbols  start:1.1.1.1 project:1.1.1;
locks    ; strict;
comment  @# @;


1.1
date     2009.07.09.02.51.48;  author yo2dh;  state Exp;
branches 1.1.1.1;
next     ;

1.1.1.1
date     2009.07.09.02.51.48;  author yo2dh;  state Exp;
branches ;
next     ;


desc
@@



1.1
log
@Initial revision
@
text
@I'll give a mini-tutorial here on how to use BOON, by way of a series
of examples.


Let's start with examples/main.c, an extremely simple example.

First, use the C preprocessor on it to expand all macros and #include's.
We provide a script called "preproc" to help with this:
  $ preproc examples/main.c
This will create the file examples/main.i, holding preprocessed code.
BOON only works on preprocessed C code, so you'll always have to do this
step before you can analyze your C code with BOON.

Now you can run the tool over the result, like this:
  $ boon examples/main.i
You should see some output like this:
  [...]
  POSSIBLE VULNERABILITIES:
  Possibly a buffer overflow in `x@@main()':
    10..10 bytes allocated, 0..19 bytes used.
    <- siz(x@@main())
    <- len(x@@main())
  [...]
Here's how to interpret this message.  It warns of a possible buffer
overrun.  Some warnings may be extraneous, you will need to check all of
them by hand.  As for this one, the tool thinks there is a decent chance
that it might be a real bug.  The tool tries to help you find the buffer
that might be overflowed; in this case, it is a local variable called "x"
in the function "main()".  In this case, it says that exactly 10 bytes
were allocated for this buffer, but that some operation might write up
to 19 bytes into the buffer.  The `<- ' lines are intended to help you
figure out what operation may have caused the overrun; in this case,
they tell us nothing, so ignore 'em for now.

So now you need to go check the source code of examples/main.c by hand
and see whether this is a real buffer overrun or not.  Go do the exercise;
you should hopefully agree that this really is a true overrun.


Time for another example.  This time, look at examples/gethostbyname.c.
As before, use "preproc" to preprocess it, then run BOON on the result.
If all goes well, you should be able to use the output of the tool to
find a buffer overrun in the source.  (Hint: A gethostbyname() call
might return a very long hostname in the hp->h_name field.)


Let's try a third example to stress-test the preprocessor and the ability
of the parser to handle the global include files installed on your system.
Use the preproc script to preprocess examples/hdrs.c, then run BOON on
the result.  What did you get?  If all went well, you should receive no
fatal errors and no vulnerabilities.

(If you're unlucky, you might have gotten a huge pile of strange looking
type errors from the parser.  This probably means that either (1) you
forgot to first preprocess the source code, or (2) the parser couldn't
handle one of the global header files included by the preprocessor.
In the former case, please note that you must always preprocess source,
so from now on I will assume you always remember to do so.  If the latter,
you'll need to troubleshoot to find the strange source construct that
confused BOON, copy the header file to the include-wrap/ directory and
modify it to remove the strange construct.  Note that the include-wrap/
directory is consulted first by the preproc script and overrides global
system confile files.  You're on your own.)


As a fourth example, try examples/fingerd.c, a slightly larger program.
(Don't forget to preprocess it first!  Otherwise, you'll see spectacular
error messages from the C parser.)  This time, you will encounter some
new phenomena.

First, you'll see a new section of output called "CAVEATS".  The output
can be very long, when analyzing large programs, so you may want
to save it and then view it with your favorite pager. The "CAVEATS"
section includes some output from the tool at places where it got a
little bit confused and saw stuff it wasn't quite expecting, but tried
to recover from in a sensible way.  Think of this as debugging output.
Usually you will at most skim through this stuff very quickly, without
expecting to it to expose any vulnerabilities, but sometimes there will
be some semi-useful warnings in there.  For now, just feel free to ignore
it if you like.

Second, you'll see a new designation of potential overrun for the
first time:
  POSSIBLE VULNERABILITIES:
  Slight chance of a buffer overflow in `msg@@fatal()':
    5..7 bytes allocated, 5..7 bytes used.
    <- siz(msg@@fatal())
    <- len(msg@@fatal())
In the future, expect to see this `Slight chance' designation quite
often.  It represents a buffer which the tool couldn't prove was
safe from overruns, but which the tool thought was pretty unlikely to
represent a real vulnerability -- in practice, stuff labelled `Slight
chance' is usually a result of imprecision in the tool, rather than
real vulnerabilities.  Therefore, in practice you will almost certainly
ignore everything labelled `Slight chance'.

However, as an exercise, you should go look through the source code
to check by hand whether this is a real overrun.  In general, as you
are getting started, I suggest to check a few dozen `Slight chance'
vulnerabilities by hand to get a feel for where the imprecision
comes from and to convince yourself that it really is pretty rare for
these cases to represent a real security vulnerability.  Once you feel
comfortable with the tool, you will want to ignore the `Slight chance'
bugs -- for large programs, there are likely to be just too many to
check by hand.


As a fourth example, go audit examples/route.c.  This is the source
code for the /sbin/route command, as distributed in an earlier Linux
distribution.  If you've followed the above lessons, you should be able
to use the tool to find some real vulnerabilities in this real-world
software.


One last example, to illustrate how to deal with large software packages
consisting of many source files.  Look in examples/talkd-bsd4.2/.  First,
preprocess all the .c files.  The following syntax may be useful:
  $ preproc examples/talkd-bsd4.2/*.c
Now you should have a series of .i files, one for each un-preprocessed
.c input file.  To run BOON on the entire talkd program, you'll need to
pass in the set of all its (preprocessed) source files, so run
  $ boon examples/talkd-bsd4.2/*.i
Oh no!  BOON parsers all the files successfully, but gives an error
message when trying to analyze the code: something about finding a field
in an unresolved struct.  Huh?  Ok, here's your chance to get some practice
trouble-shooting.  Go try to compile the source using 'gcc' (or, maybe,
'gcc -Wall').  Ah-hah!  The problem is in the source: If even gcc can't
compile it successfully, how can we expect BOON to handle this?  Looking
at gcc's error messages, we quickly see that localtime() is called in
announce.c, but the <time.h> header file was never included.  (This travesty
occurred because talkd was written for bsd4.2, where that header isn't
needed, but I'm trying to analyze talkd on Linux, where the <time.h>
header file is needed.)

So, go modify the talkd source to make it compile on your machine.
(Hint: add #include <time.h> to examples/talkd-bsd4.2/announce.c.)
Now re-run BOON.  (Don't forget to re-run the "preproc" script first!)
What did you find?

After all that work, BOON won't find any buffer overruns in the
talkd-bsd4.2.  In this case, it is a failure to find a real buffer
overrun vulnerability.  However, the failure is instructional -- two-level
pointers confuse the current implementation of BOON.


For big software packages that pass their own compile flags (-DNDEBUG=1,
or whatever) to gcc, you will probably want to preprocess it using the
same flags.  This is supported by the "preproc" script: simply set the
CFLAGS environment variable to contain the list of flags you want passed
to cpp.  You might want to build this into the package's Makefile to
make sure you capture everything.


The above examples had you analyzing programs that were all pretty
simple, but you can also apply the tool to big programs.  Give it a try,
and have fun!

Details on the implementation of the tool may be found in the following
paper: ``A First Step Towards Automated Detection of Buffer Overrun
Vulnerabilities'', David Wagner, Jeffrey S. Foster, Eric A. Brewer, and
Alexander Aiken.  NDSS 2000.  For a copy, see paper.ps in this directory,
or go to
  http://www.cs.berkeley.edu/~daw/papers/
You may want to at least skim this paper before using the tool in depth
to understand its limitations (which are quite substantial).

The file TIPS contains some more assorted scribblings & notes on the tool,
some known limitations and bugs, and some suggested workarounds.
@


1.1.1.1
log
@CVS TEST
@
text
@@
