Flawfinder (1) Linux Manual Page

NAME

flawfinder – find potential security flaws ("hits") in source code

SYNOPSIS

DESCRIPTION

Flawfinder searches through C/C++ source code looking for potential security flaws. To run flawfinder, simply give flawfinder a list of directories or files. For each directory given, all files that have C/C++ filename extensions in that directory (and its subdirectories, recursively) will be examined. Thus, for most projects, simply give flawfinder the name of the source code’s topmost directory (use “.” for the current directory), and flawfinder will examine all of the project’s C/C++ source code. If you only want to have changes reviewed, save a unified diff of those changes (created by "diff -u" or "svn diff") in a patch file and use the –patch (-P) option.

Flawfinder will produce a list of “hits” (potential security flaws), sorted by risk; the riskiest hits are shown first. The risk level is shown inside square brackets and varies from 0, very little risk, to 5, great risk. This risk level depends not only on the function, but on the values of the parameters of the function. For example, constant strings are often less risky than fully variable strings in many contexts, and in those contexts the hit will have a lower risk level. Flawfinder knows about gettext (a common library for internationalized programs) and will treat constant strings passed through gettext as though they were constant strings; this reduces the number of false hits in internationalized programs. Flawfinder will do the same sort of thing with _T() and _TEXT(), common Microsoft macros for handling internationalized programs Flawfinder correctly ignores most text inside comments and strings. Normally flawfinder shows all hits with a risk level of at least 1, but you can use the –minlevel option to show only hits with higher risk levels if you wish.

Not every hit is actually a security vulnerability, and not every security vulnerability is necessarily found. Nevertheless, flawfinder can be an aid in finding and removing security vulnerabilities. A common way to use flawfinder is to first apply flawfinder to a set of source code and examine the highest-risk items. Then, use –inputs to examine the input locations, and check to make sure that only legal and safe input values are accepted from untrusted users.

Once you’ve audited a program, you can mark source code lines that are actually fine but cause spurious warnings so that flawfinder will stop complaining about them. To mark a line so that these warnings are suppressed, 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:

*: // Flawfinder: ignore
*: /* Flawfinder: ignore */

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 no matter what the comments say. Thus, responses that would otherwise be ignored would be included (or, more confusingly, –neverignore ignores the ignores). This comment syntax is actually a more general syntax for special directives to flawfinder, but currently only ignoring lines is supported.

Flawfinder uses an internal database called the “ruleset”; the ruleset identifies functions that are common causes of security flaws. The standard ruleset includes a large number of different potential problems, including both general issues that can impact any C/C++ program, as well as a number of specific Unix-like and Windows functions that are especially problematic. As noted above, every potential security flaw found in a given source code file (matching an entry in the ruleset) is called a “hit,” and the set of hits found during any particular run of the program is called the “hitlist.” 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).

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. While searching directories recursively, flawfinder only opens and examines regular files that have C/C++ filename extensions. Flawfinder presumes that, files are C/C++ files if they have the extensions ".c", ".h", ".ec", ".ecp", ".pgc", ".C", ".cpp", ".CPP", ".cxx", ".cc", ".CC", ".pcc", ".hpp", or ".H". The filename “-” means the standard input. To prevent security problems, special files (such as device special files and named pipes) are always skipped, and by default symbolic links are skipped,

After the list of hits is a brief summary of the results (use -D to remove this information). It will show the number of hits, lines analyzed (as reported by wc -l), and the physical source lines of code (SLOC) analyzed. A physical SLOC is a non-blank, non-comment line. It will then show the number of hits at each level; note that there will never be a hit at a level lower than minlevel (1 by default). Thus, "[0] 0 [1] 9" means that at level 0 there were 0 hits reported, and at level 1 there were 9 hits reported. It will next show the number of hits at a given level or larger (so level 3+ has the sum of the number of hits at level 3, 4, and 5). Thus, an entry of "[0+] 37" shows that at level 0 or higher there were 37 hits (the 0+ entry will always be the same as the "hits" number above). Hits per KSLOC is next shown; this is each of the "level or higher" values multiplied by 1000 and divided by the physical SLOC. If symlinks were skipped, the count of those is reported. If hits were suppressed (using the "ignore" directive in source code comments as described above), the number suppressed is reported. The minimum risk level to be included in the report is displayed; by default this is 1 (use –minlevel to change this). 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.

Flawfinder intentionally 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.

BRIEF TUTORIAL

Here’s a brief example of how flawfinder might be used. Imagine that you have the C/C++ source code for some program named xyzzy (which you may or may not have written), and you’re searching for security vulnerabilities (so you can fix them before customers encounter the vulnerabilities). For this tutorial, I’ll assume that you’re using a Unix-like system, such as Linux, OpenBSD, or MacOS X.

If the source code is in a subdirectory named xyzzy, you would probably start by opening a text window and using flawfinder’s default settings, to analyze the program and report a prioritized list of potential security vulnerabilities (the “less” just makes sure the results stay on the screen):

: flawfinder xyzzy | less

At this point, you will a large number of entries; each entry begins with a filename, a colon, a line number, a risk level in brackets (where 5 is the most risky), a category, the name of the function, and a description of why flawfinder thinks the line is a vulnerability. Flawfinder normally sorts by risk level, showing the riskiest items first; if you have limited time, it’s probably best to start working on the riskiest items and continue until you run out of time. If you want to limit the display to risks with only a certain risk level or higher, use the –minlevel option. If you’re getting an extraordinary number of false positives because variable names look like dangerous function names, use the -F option to remove reports about them. If you don’t understand the error message, please see documents such as the Writing Secure Programs for Linux and Unix HOWTO at http://www.dwheeler.com/secure-programs which provides more information on writing secure programs.

Once you identify the problem and understand it, you can fix it. Occasionally you may want to re-do the analysis, both because the line numbers will change and to make sure that the new code doesn’t introduce yet a different vulnerability.

If you’ve determined that some line isn’t really a problem, and you’re sure of it, you can insert just before or on the offending line a comment like

: /* Flawfinder: ignore */

to keep them from showing up in the output.

Once you’ve done that, you should go back and search for the program’s inputs, to make sure that the program strongly filters any of its untrusted inputs. Flawfinder can identify many program inputs by using the –inputs option, like this:

: flawfinder –inputs xyzzy

Flawfinder can integrate well with text editors and integrated development environments; see the examples for more information.

Flawfinder includes many other options, including ones to create HTML versions of the output (useful for prettier displays). The next section describes those options in more detail.

OPTIONS

Flawfinder has a number of options, which can be grouped into options that control its own documentation, select which hits to display, select the output format, and perform hitlist management.

Documentation

–help: Show usage (help) information.
–version: Shows (just) the version number and exits.

Selecting Hits to Display

–patchpatchfile: -Ppatchfile Only report hits that are changed by the given patch file. The patch file must be in unified diff format (e.g., the output of "diff -u old new" or "svn diff"), where the new files are the ones that are being examined by flawfinder. The line numbers given in the patch file are used to determine which lines were changed, so if you have modified the files since the patch file was created, regenerate the patch file first. Beware that the file names of the new files given in the patch file must match exactly, including upper/lower case, path prefix, and directory separator (\ vs. /). 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.
–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

flawfinder (1) Linux Manual Page