.TH ITS4 1 "" "It's the software, stupid! (Security Scanner)"  \" -*- nroff -*-
.SH NAME
its4 \- Scan C/C++ source for potential security problems.
.SH SYNOPSIS
.B its4
[\-mprCDHQSVW?] [\-a function] [\-c {0,1,2,3,4,5}] [\-i function] [\-I file] 
[\-l function] [\-o filename] [\-q function] [\-s {0,1,2,3,4,5,6}] [\-v file] 
[\-w cols] [\-\-db\-location=file] [\-\-help] [\-\-ignore=function] 
[\-\-no\-commands] [\-\-no\-descriptions] [\-\-no\-severity] [\-\-paranoid]
[\-\-no\-solutions] [\-\-output=filename] [\-\-query=function] [\-\-reverse] 
[\-\-no\-handlers] [\-\-quiet] [\-\-ignore-file=file] [\-\-add=function]
[\-\-input-mode] [\-\-limit=function] [\-\-severity\-cutoff={0,1,2,3,4,5}] 
[\-\-sort={0,1,2,3,4,5,6}] [\-\-width=cols] [\-\-mvs-reports] [FILE...]
.SH DESCRIPTION
This manual page documents 
.BR its4,
a scanner for C and C++ code that searches for potential security holes.
.PP
The
.B its4 
scanner searches the entire program source with heuristics in an attempt to
find library calls that may indicate a security vulnerability. 
.PP
File arguments are required unless either the
.I "\-\-query"
or
.I "\-\-version"
argument is used.

.SS OPTIONS
.TP
.I "\-a, \-\-add=function"
Add a new function name to the database for this scan only.  Modify
the database file or create a new database file for a more permanent
solution.
.TP
.I "\-c, \-\-severity\-cutoff={0,1,2,3,4,5}"
Set severity cutoff.  The default is 2.  Lower numbers generally give more 
warnings.
.TP
.I "\-C, \-\-no\-commands"
Ignore commands to ITS4 that are embedded in comments.  
See the section "COMMANDS" for information on these commands.
.TP
.I "\-D, \-\-no\-descriptions"
Don't display descriptions of potential problems.
.TP
.I "\-H, \-\-no\-handlers"
Don't use any clever tricks, just match token names.  This flag gives more
warnings than if you don't use it (or at least no fewer).  The reason is
because checks that reduced the severity of 
.B "strcpy(dst, ''foo'')"
to 0 are now not made.
.TP
.I "\-i, \-\-ignore=function"
Ignore instances of a particular function name.  This flag can be used as 
many times as you like.
.TP
.I "\-I, \-\-ignore-file=filename"
Specify a file to read ignore info from, causing ITS4 to not report
instances of those functions.  Each function to ignore should be on
its own line.
.TP
.I "\-l, \-\-limit=function"
Tells ITS4 not to scan for any functions, except those passed in with this
flag.  You can use this flag as many times as you want.
.TP
.I "\-m, \-\-input-mode"
Tells ITS4 to print out all non-argv spots at which input can
enter.  This option causes some other options to be ignored.
Most importantly, the regular scan does not happen, no
severities are visibly reported, and the cutoff is ignored.
Also, the default sorting value changes to 0, from 2 (see below).
.TP
.I "\-o, \-\-output=filename"
Direct output to a given filename instead of stdout.
.TP
.I "\-p, \-\-paranoid"
By default, ITS4 ignores identifiers that don't look like functions. 
If you are afraid the code you're scanning abuses the preprocessor 
heinously, you may catch some extra stuff by turning this on. 
You will probably up the noise level significantly, though.
.TP
.I "\-q, \-\-query=function"
Show database record for the given function name.  This flag can be used 
as many times as you like.
.TP
.I "\-r, \-\-reverse"
Sort output in reverse order.
.TP
.I "\-s, \-\-sort={0,1,2,3,4,5,6}"
Sort output.  Takes integer from 0-6.  Default is 2, unless \-m 
(\-\-input\-mode) flag is also set, in which case the default is 0.
.TP
.BR  0 = 
No sort, report in order scanned.  
.TP
.BR  1 = 
Sort by most severe, then group by location.                            
.TP                                    
.BR  2 = 
Sort by most severe, then group by vulnerability.                        
.TP                                    
.BR  3 = 
Sort by vulnerability, then severity.                                   
.TP                                    
.BR  4 = 
Sort by vulnerability, then location.                                   
.TP                                    
.BR  5 = 
Sort by file, then by severity.                                        
.TP                                    
.BR  6 = 
Sort by file, then by vulnerability.
.TP                                    
.TP
.I "\-S, \-\-no\-solutions"
Don't display solution guidelines for potential problems.
.TP
.I "\-v, \-\-db\-location=file"
Set the location of the vulnerability database to use.
.TP
.I "\-V, \-\-no\-severity"
Don't display the severity.
.TP
.I "\-w, \-\-with=cols"
Set terminal width (for output wrapping).  Without this flag, the 
COLUMNS environment variable is checked.  If it is not present, then
80 is used.
.TP
.I "\-W, \-\-mvs-reports"
Format output for use with Microsoft Visual Studio.
.TP
.I "\-?, \-\-help"
Print a usage message on standard output and exit successfully.
.TP
.I "\-\-version"
Print version information on standard output then exit successfully.
.SH COMMANDS
The programmer can pass commands to the ITS4 scanner from within the
source code by embedding the commands within comments.  Currently, the
only command supported is the IGNORE command, which is capable of
suppressing individual warnings (unless the \-C flag is passed to the
program).  If there is code on the same line as the comment, then the
command applies to that line.  If not, the command applies to the very
next line (so don't have blank lines between the comment and the
code).  If there are two comments on one line, both with ITS4
commands, the first operates only on the current line, up to the
comment.  The second operates only on the current line after the
comment, or the next line if there is no code on the current line.

.PP
The ignore command is best explained with some examples:

strcpy(dst, src); /* ITS4: ignore */
.TP
strcpy(dst, src); /* ITS4: ignore strcpy */
.TP
strcpy(dst, src); strcat(dst, src2);  /* ITS4: ignore */ // ignores both
.TP
strcpy(dst, src); strcat(dst, src2);  /* ITS4: ignore strcpy, strcat */
.PP
You can't embed a comment in the same comment block as the command.
Use a separate comment for that.
.SH BUGS
This man page is wrong if your system does not have GNU getopt, which
supports long options.  If that is the case, only short versions of 
options are supported.
.SH AUTHOR
John Viega, 
.I viega@list.org
.PP
.B NOTE: 
The copyright of this software is held by Reliable Software Technologies.
There are some restrictions to its commercial use.  See the 
.BR LICENCE 
file that came with the package for details, or visit 
.I http://www.rstcorp.com/its4