walkero
/
flawfinder
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

Rewrite documentation in man page and --help option for clarity 

- Group options in --help, just like the man page, for clarity
  - Create a new group, "Selecting Input Data", so that they are
    clearly distinguished from selecting what hits to display.
  - Other clarifications in the man page.
This commit is contained in:
David A. Wheeler 2014-07-12 20:43:04 -04:00
parent 23fe9f27c5
commit 923cf6042c
2 changed files with 130 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
flawfinder
View File

@ -1536,33 +1536,44 @@ def process_file_args(files, patch_infos):
def usage():
print """
flawfinder [--help] [--context] [-c] [--columns | -C] [--html]
[--dataonly | -D]
[--minlevel=X | -m X]
[--immediate] [-i] [--inputs | -I] [--neverignore | -n]
[ --patch=F ] [--quiet | -Q] [--singleline | -S ]
[--loadhitlist=F ] [ --savehitlist=F ] [ --diffhitlist=F ]
[--listrules]
[--] [ source code file or source root directory ]+
flawfinder [--help | -h] [--listrules] [--version]
[--allowlink] [--followdotdir] [--nolink]
[--patch filename | -P filename]
[--inputs | -I] [--minlevel X | -m X]
[--falsepositive | -F] [--neverignore | -n]
[--context | -c] [--columns | -C] [--dataonly | -D]
[--html] [--immediate | -i] [--singleline | -S]
[--omittime] [--quiet | -Q]
[--loadhitlist F] [--savehitlist F] [--diffhitlist F]
[--] [source code file or source root directory]+
--help Show this usage help
The options cover various aspects of flawfinder as follows.
--allowlink
Allow symbolic links.
Documentation:
--help Show this usage help.
--listrules List the rules in the ruleset (rule database).
--version Show version number.
Selecting Input Data:
--allowlink Allow symbolic links.
--followdotdir
Follow directories whose names begin with ".".
Normally they are ignored.
--nolink Skip symbolic links (ignored).
--patch F | -P F
Display information related to the patch F
(patch must be already applied).
--context
-c Show context (the line having the "hit"/potential flaw)
--columns Show the column number (as well as the file name and
line number) of each hit; this is shown after the line number
by adding a colon and the column number in the line (the first
character in a line is column number 1).
--html Display as HTML output.
-F Do not include hits that are likely to be false positives.
Selecting Hits to Display:
--inputs | -I
Show only functions that obtain data from outside the program;
this also sets minlevel to 0.
-m X | --minlevel=X
Set minimum risk level to X for inclusion in hitlist. This
can be from 0 (``no risk'') to 5 (``maximum risk''); the
default is 1.
--falsepositive | -F
Do not include hits that are likely to be false positives.
Currently, this means that function names are ignored if
they're not followed by "(", and that declarations of char-
acter arrays aren't noted. Thus, if you have use a vari-
@ -1571,47 +1582,35 @@ flawfinder [--help] [--context] [-c] [--columns | -C] [--html]
because this also increases the likelihood of missing
important hits; in particular, function names in #define
clauses and calls through function pointers will be missed.
-m X
--minlevel=X
Set minimum risk level to X for inclusion in hitlist. This
can be from 0 (``no risk'') to 5 (``maximum risk''); the
default is 1.
-S
--singleline Single-line output.
--neverignore
-n Never ignore security issues, even if they have an ``ignore''
--neverignore | -n
Never ignore security issues, even if they have an ``ignore''
directive in a comment.
--immediate
-i Immediately display hits (don't just wait until the end).
--inputs Show only functions that obtain data from outside the program;
-I this also sets minlevel to 0.
--nolink Skip symbolic links (ignored).
Selecting Output Format:
--columns Show the column number (as well as the file name and
line number) of each hit; this is shown after the line number
by adding a colon and the column number in the line (the first
character in a line is column number 1).
--context | -c
Show context (the line having the "hit"/potential flaw)
--dataonly | -D
Don't display the headers and footers of the analysis;
use this along with --quiet to get just the results.
--html Display as HTML output.
--immediate | -i
Immediately display hits (don't just wait until the end).
--singleline | -S
Single-line output.
--omittime Omit time to run.
--patch=F display information related to the patch F. (patch must be already applied)
--Q
--quiet Don't display status information (i.e., which files are being
--quiet | -Q
Don't display status information (i.e., which files are being
examined) while the analysis is going on.
--D
--dataonly Don't display the headers and footers of the analysis;
use this along with --quiet to get just the results.
--listrules List the rules in the ruleset (rule database).
--loadhitlist=F
Load hits from F instead of analyzing source programs.
Hitlist Management:
--savehitlist=F
Save all hits (the "hitlist") to F.
--loadhitlist=F
Load hits from F instead of analyzing source programs.
--diffhitlist=F
Show only hits (loaded or analyzed) not in F.

111
flawfinder.1
View File

@ -28,14 +28,19 @@ flawfinder \- find potential security flaws ("hits") in source code
.RB [ \-\-help ]
.RB [ \-\-listrules ]
.RB [ \-\-version ]
.\" Selecting Hits:
.br
.\" Selecting Input Data:
.RB [ \-\-allowlink ]
.RB [ \-\-followdotdir ]
.RB [ \-\-nolink ]
.RB [ \-\-patch\ \fIfilename\fR | \-P\ \fIfilename\fR ]
.br
.\" Selecting Hits to Display:
.RB [ \-\-inputs | \-I ]
[ \fB\-\-minlevel \fR\fIX\fR | \fB\-m\fR\ \fIX\fR ]
.RB [ \-\-falsepositive | \-F ]
.RB [ \-\-neverignore | \-n ]
.RB [ \-\-patch\ \fIfilename\fR | \-P\ \fIfilename\fR ]
.RB [ \-\-followdotdir ]
.br
.\" Selecting Output Format:
.RB [ \-\-context | \-c ]
.RB [ \-\-columns | \-C ]
@ -45,10 +50,12 @@ flawfinder \- find potential security flaws ("hits") in source code
.RB [ \-\-singleline | \-S ]
.RB [ \-\-omittime ]
.RB [ \-\-quiet | \-Q ]
.br
.\" Managing hit list.
[ \fB\-\-loadhitlist\ \fR\fIF\fR ]
[ \fB\-\-savehitlist\ \fR\fIF\fR ]
[ \fB\-\-diffhitlist\ \fR\fIF\fR ]
.br
.RB [ \-\- ]
.I [ source code file or source root directory ]+
.SH DESCRIPTION
@ -105,14 +112,19 @@ put a specially-formatted comment either on the same
line (after the source code) or all by itself in the previous line.
The comment must have one of the two following formats:
.IP \(bu
// Flawfinder: ignore
// Flawfinder: ignore
.IP \(bu
/* Flawfinder: ignore */
/* Flawfinder: ignore */
.PP
If someone has previously audited a program, and you are skeptical
of their comments that suppress warnings, use the \-\-neverignore (-n)
option, which causes flawfinder to report all security issues at the
relevant level even if there is an ignore directive.
.PP
Note that, for compatibility's sake, you can replace "Flawfinder:" with
"ITS4:" or "RATS:" in these specially-formatted comments.
Since it's possible that such lines are wrong, you can use the
``\-\-neverignore'' option, which causes flawfinder to never ignore any line
\-\-neverignore option, which causes flawfinder to never ignore any line
no matter what the comments say.
Thus, responses that would otherwise be ignored would be included
(or, more confusingly, \-\-neverignore ignores the ignores).
@ -133,6 +145,23 @@ Hitlists can be saved (using \-\-savehitlist), reloaded back for redisplay
(using \-\-loadhitlist), and you can show only the hits that are different
from another run (using \-\-diffhitlist).
.PP
Flawfinder works by doing simple lexical tokenization
(skipping comments and correctly tokenizing strings),
looing for token matches to the database (particularly to find function calls),
and then uses code for different
functions to estimate risk based on the text of the parameters.
Other tools that apply this approach include RATS and ITS4.
Unlike tools such as splint, gcc warning flags,
and clang, flawfinder does not use or have access to
information about control flow, data flow, or data types when
estimating the level of risk.
Thus, flawfinder will necessarily
produce many false positives and fail to report many vulnerabilities.
On the other hand, flawfinder can find vulnerabilities in programs that
cannot be linked, and in some cases, cannot even be compiled.
Flawfinder also doesn't get as confused by macro definitions
and other oddities that more sophisticated tools have trouble with.
.PP
Any filename given on the command line will be examined (even if
it doesn't have a usual C/C++ filename extension); thus you can force
flawfinder to examine any specific files you desire.
@ -170,7 +199,7 @@ The summary ends with important reminders:
Not every hit is necessarily a security vulnerability, and
there may be other security vulnerabilities not reported by the tool.
.PP
Flawfinder intentionally works similarly to another program, ITS4, which is not
Flawfinder works similarly to another program, ITS4, which is not
fully open source software (as defined in the Open Source Definition)
nor free software (as defined by the Free Software Foundation).
The author of Flawfinder has never seen ITS4's source code.
@ -256,6 +285,7 @@ The next section describes those options in more detail.
Flawfinder has a number of options, which can be grouped into options that
control its own documentation,
select input data,
select which hits to display,
select the output format,
and perform hitlist management.
@ -264,8 +294,8 @@ and perform hitlist management.
.TP 12
.BI \-\-help
.\" Leave -h and -? undocumented... they also invoke help, but it's
.\" easier just to document the single help option.
.BI \-h
.\" Leave -? undocumented... it also invokes help.
Show usage (help) information.
.TP 12
@ -278,7 +308,37 @@ depending on how the term is used.
.BI \-\-version
Shows (just) the version number and exits.
.SS "Selecting Hits to Display"
.SS "Selecting Input Data"
.TP 12
.BI \-\-allowlink
Allow the use of symbolic links; normally symbolic links are skipped.
Don't use this option if you're analyzing code by others;
attackers could do many things to cause problems for an analysis
with this option enabled.
For example, an attacker
could insert symbolic links to files such as /etc/passwd
(leaking information about the file) or create a circular loop,
which would cause flawfinder to run ``forever''.
Another problem with enabling this option is that
if the same file is referenced multiple times using symbolic links,
it will be analyzed multiple times (and thus reported multiple times).
Note that flawfinder already includes some protection against symbolic links
to special file types such as device file types (e.g., /dev/zero or
C:\\mystuff\\com1).
Note that for flawfinder version 1.01 and before, this was the default.
.TP
.BI \-\-followdotdir
Enter directories whose names begin with ".".
Normally such directories are ignored, since they normally
include version control private data, configurations, and so on.
.TP
.BI \-\-nolink
Ignored.
Historically this disabled following symbolic links, but this
behavior is now the default.
.TP 12
.BI \-\-patch patchfile
@ -298,25 +358,10 @@ Only unified diff format is accepted (either GNU diff or svn diff output is
okay); if you have a different format, again regenerate it first.
Only hits that occur on resultant changed lines, or immediately
above and below them, are reported.
This option implies --neverignore.
This option implies \-\-neverignore.
.TP 12
.BI \-\-allowlink
Allow the use of symbolic links; normally symbolic links are skipped.
Don't use this option if you're analyzing code by others;
attackers could do many things to cause problems for an analysis
with this option enabled.
For example, an attacker
could insert symbolic links to files such as /etc/passwd
(leaking information about the file) or create a circular loop,
which would cause flawfinder to run ``forever''.
Another problem with enabling this option is that
if the same file is referenced multiple times using symbolic links,
it will be analyzed multiple times (and thus reported multiple times).
Note that flawfinder already includes some protection against symbolic links
to special file types such as device file types (e.g., /dev/zero or
C:\\mystuff\\com1).
Note that for flawfinder version 1.01 and before, this was the default.
.SS "Selecting Hits to Display"
.TP
.BI "\-\-inputs"
@ -354,12 +399,6 @@ clauses and calls through function pointers will be missed.
Never ignore security issues, even if they have an ``ignore'' directive
in a comment.
.TP
.BI \-\-followdotdir
Enter directories whose names begin with ".".
Normally such directories are ignored, since they normally
include version control private data, configurations, and so on.
.SS "Selecting Output Format"
.TP 12
@ -655,8 +694,8 @@ This protection also doesn't work on Cygwin platforms, unfortunately.
.PP
Cygwin systems (Unix emulation on top of Windows)
have an additional problem if flawfinder is used to analyze
programs the analyzer cannot trust
due to a design flaw in Windows (that it inherits from MS-DOS).
programs that the analyst cannot trust.
The problem is due to a design flaw in Windows (that it inherits from MS-DOS).
On Windows and MS-DOS, certain filenames (e.g., ``com1'') are
automatically treated by the operating system as the names of peripherals,
and this is true even when a full pathname is given.