Copyright (C) 2000 Alan DeKok <aland@ox.org>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
USA

----------------------------------------------------------------------

  'pscan' is a program which attempts to scan C source files for
common function abuses, which often lead to buffer overflows.  See the
included file 'test.c' for examples of good, and bad programming
practice.  For the latest version, see:

	http://www.striker.ottawa.on.ca/~aland/pscan/


  The scan works by looking for a one of a list of problem functions,
and applying the following rule:

  IF the last parameter of the function is the format string,
  AND the format string is NOT a static string,
  THEN complain.

  See 'test.c' for examples.  

  Once pscan has found the problems, it's up to you to examine the
source code, and correct the (possible) security breach.


<RANT>
  I know there's nothing which can be done now about the API's which
  cause these problems.  But API's which are *easy* to abuse in this
  manner are poorly designed.  This program is a hack which *might*
  help you automatically detect programmer abuses of bad API's.  If
  you want a secure language, choose something other than C.
</RANT>


  You can build pscan by typing:

	make

  If you don't have lex or yacc installed, it probably won't work.
You'll have to figure out how to build it yourself, as I'm too lazy to
write an autoconf for a ~100 line C program.


  Once pscan is built, you can test it by typing:

	./pscan test.c

  You should see it complain about a number of errors, giving the
source file, line number, and problematic function name.

  If there are any errors found, pscan exits with status 1.  Typing:

	echo $?

should get you a '1'.

  Now try:

	./pscan ./pscan.c

  You shouldn't see any errors, and the exit code will be 0 (zero).

  You can scan multiple C source files with one run of pscan, by
specifying multiple filenames on the command line:

	./pscan ./*.c

  If ANY problems are found, they are printed out, and pscan exits
with status 1.

  If you don't trust it, pscan has a verbose option: -v.

	./pscan -vv ./test.c

  The output should make itself clear.


  In addition to the problem C library functions, many programs
define their own functions with similar security problems.  The
included shell script 'find_formats.sh' tries to discover C function
prototypes for the problem functions.  It won't find them all, but it
will find many of the most common ones.


  Alan DeKok <aland@ox.org>
  July 7, 2000.