Provided by: flawfinder_1.31-1_all bug

NAME

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

SYNOPSIS

       flawfinder [--help|-h] [--version] [--listrules]
       [--allowlink] [--followdotdir] [--nolink]
       [--patch=filename|-P filename]
       [--inputs|-I] [ --minlevel=X | -m X ] [--falsepositive|-F]
       [--neverignore|-n]
       [--regex=PATTERN | -e PATTERN]
       [--context|-c]     [--columns|-C]     [--dataonly|-D]     [--html|-H]     [--immediate|-i]
       [--singleline|-S] [--omittime] [--quiet|-Q]
       [--loadhitlist=F] [--savehitlist=F] [--diffhitlist=F]
       [--] [ source code file or source root directory ]+

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  GNU
       "diff -u" or "svn diff" or "git 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.  Hit descriptions also note the relevant Common
       Weakness Enumeration (CWE) identifier(s) in parentheses, as discussed  below.   Flawfinder
       is officially CWE-Compatible.

       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 */

       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 comment directives say (more confusingly, --neverignore ignores the ignores).

       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.   The  --listrules  option  reports the list of current rules and
       their default risk levels.  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).

       Flawfinder is a simple tool, leading to some fundamental pros and cons.  Flawfinder  works
       by doing simple lexical tokenization (skipping comments and correctly tokenizing strings),
       looking for  token  matches  to  the  database  (particularly  to  find  function  calls).
       Flawfinder  is  thus similar to RATS and ITS4, which also use simple lexical tokenization.
       Flawfinder then examines the text of the function parameters  to  estimate  risk.   Unlike
       tools  such  as  splint,  gcc's  warning flags, and clang, flawfinder does not use or have
       access to information about control flow, data flow, or  data  types  when  searching  for
       potential  vulnerabilities  or  estimating  the  level  of  risk.   Thus,  flawfinder will
       necessarily produce many false positives for  vulnerabilities  and  fail  to  report  many
       vulnerabilities.   On the other hand, flawfinder can find vulnerabilities in programs that
       cannot be built or cannot be linked.  It can often work with programs that cannot even  be
       compiled  (at  least by the reviewer's tools).  Flawfinder also doesn't get as confused by
       macro definitions and other oddities that more  sophisticated  tools  have  trouble  with.
       Flawfinder  can  also  be  useful  as  a  simple  introduction to static analysis tools in
       general, since it is easy to start using and easy to understand.

       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 (the
       --allowlink option follows symbolic links).

       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 is released under the GNU GPL license version 2 or later (GPLv2+).

       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.

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  see  a large number of entries.  Each entry has 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  HOWTOhttp://www.dwheeler.com/secure-programs⟩  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 input data, select which hits to display, select the output format,
       and perform hitlist management.  Flawfinder supports the standard syntax  defined  in  the
       POSIX  (Issue  7, 2013 Edition) section ``Utility Conventions''.  It also supports the GNU
       long options (double-dash options of form --option)  as  defined  in  the  GNU  C  Library
       Reference  Manual  ``Program  Argument  Syntax  Conventions''  and  GNU  Coding  Standards
       ``Standards for Command Line Interfaces''.  Long  option  arguments  can  be  provided  as
       ``--name=value''  or  ``-name  value''.   Some options can only be accessed using the more
       readable GNU long option conventions; common options  are  also  supported  by  the  older
       single-letter option convention.

   Documentation
       --help

       -h          Show usage (help) information.

       --version   Shows (just) the version number and exits.

       --listrules List  the  terms (tokens) that trigger further examination, their default risk
                   level,  and  the  default  warning  (including  the  CWE   identifier(s),   if
                   applicable), all tab-separated.  The terms are primarily names of potentially-
                   dangerous functions.  Note that the reported risk level and warning  for  some
                   specific  code may be different than the default, depending on how the term is
                   used.  Combine with -D if you  do  not  want  the  usual  header.   Flawfinder
                   version  1.29 changed the separator from spaces to tabs, and added the default
                   warning field.

   Selecting Input Data
       --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.

       --followdotdir
                   Enter  directories  whose names begin with ".".  Normally such directories are
                   ignored, since they normally include version control  private  data  (such  as
                   .git/ or .svn/), configurations, and so on.

       --nolink    Ignored.   Historically  this disabled following symbolic links; this behavior
                   is now the default.

       --patch=patchfile

       -P patchfile
                   Examine the selected files or directories, but only report hits in lines  that
                   are  added  or  modified by the given patch file.  The patch file must be in a
                   recognized unified diff format (e.g., the output of GNU  "diff  -u  old  new",
                   "svn  diff",  or  "git diff [commit]").  Flawfinder assumes that the patch has
                   already been applied to the files.  The patch file can also include changes to
                   irrelevant files (they will simply be ignored).  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  (GNU  diff,  svn
                   diff,  and  git  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.

   Selecting Hits to Display
       --inputs

       -I     Show only functions that obtain data from  outside  the  program;  this  also  sets
              minlevel to 0.

       --minlevel=X

       -m 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 character arrays aren't noted.  Thus, if you have  use  a  variable
              named  "access"  everywhere,  this  will  eliminate  references  to  this  ordinary
              variable.  This isn't the default, 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.

       --neverignore

       -n     Never ignore security issues, even if  they  have  an  ``ignore''  directive  in  a
              comment.

       --regexp=PATTERN

       -e PATTERN
              Only  report  hits  with  text that matches the regular expression pattern PATTERN.
              For example, to only report hits  containing  the  text  "CWE-120",  use  ``--regex
              CWE-120''.  These option flag names are the same as grep.

   Selecting Output Format
       --columns

       -C          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).  This is useful
                   for editors that can jump to specific columns, or for integrating  with  other
                   tools (such as those to further filter out false positives).

       --context

       -c          Show  context, i.e., the line having the "hit"/potential flaw.  By default the
                   line is shown immediately after the warning.

       --dataonly

       -D          Don't display the header and footer.  Use this along with --quiet to see  just
                   the data itself.

       --html

       -H          Format the output as HTML instead of as simple text.

       --immediate

       -i          Immediately display hits (don't just wait until the end).

       --singleline

       -S          Display  as  single  line of text output for each hit.  Useful for interacting
                   with compilation tools.

       --omittime  Omit timing information.  This is useful for regression  tests  of  flawfinder
                   itself,  so  that  the  output doesn't vary depending on how long the analysis
                   takes.

       --quiet

       -Q          Don't display status information (i.e., which files are being examined)  while
                   the analysis is going on.

   Hitlist Management
       --savehitlist=F
                   Save all resulting hits (the "hitlist") to F.

       --loadhitlist=F
                   Load the hitlist from F instead of analyzing source programs.  Warning: Do not
                   load hitlists from untrusted sources (for security reasons).

       --diffhitlist=F
                   Show only hits (loaded or analyzed)  not  in  F.   F  was  presumably  created
                   previously  using --savehitlist.  Warning: Do not diff hitlists from untrusted
                   sources (for security reasons).  If the --loadhitlist option is not  provided,
                   this  will  show  the  hits  in  the  analyzed source code files that were not
                   previously stored in F.  If used along with --loadhitlist, this will show  the
                   hits   in   the  loaded  hitlist  not  in  F.   The  difference  algorithm  is
                   conservative; hits are only considered the ``same''  if  they  have  the  same
                   filename, line number, column position, function name, and risk level.

EXAMPLES

       Here  are  various  examples of how to invoke flawfinder.  The first examples show various
       simple command-line options.  Flawfinder is designed to work well with  text  editors  and
       integrated development environments, so the next sections show how to integrate flawfinder
       into vim and emacs.

   Simple command-line options
       flawfinder /usr/src/linux-3.16
                   Examine all the C/C++ files in the directory /usr/src/linux-3.16 and  all  its
                   subdirectories  (recursively),  reporting  on  all  hits  found.   By  default
                   flawfinder will skip symbolic links and directories with names that start with
                   a period.

       flawfinder --minlevel=4 .
                   Examine  all  the  C/C++ files in the current directory and its subdirectories
                   (recursively); only report vulnerabilities level 4 and  up  (the  two  highest
                   risk levels).

       flawfinder --inputs mydir
                   Examine all the C/C++ files in mydir and its subdirectories (recursively), and
                   report functions that take inputs (so that you can ensure that they filter the
                   inputs appropriately).

       flawfinder --neverignore mydir
                   Examine  all  the  C/C++  files in the directory mydir and its subdirectories,
                   including even the hits marked for ignoring in the code comments.

       flawfinder -QD mydir
                   Examine mydir and report only the actual  results  (removing  the  header  and
                   footer  of  the output).  This form is useful if the output will be piped into
                   other tools for further analysis.  The -C (--columns)  and  -S  (--singleline)
                   options can also be useful if you're piping the data into other tools.

       flawfinder -QDSC mydir
                   Examine  mydir, reporting only the actual results (no header or footer).  Each
                   hit is reported on one line, and column numbers are reported.  This can  be  a
                   useful command if you are feeding flawfinder output to other tools.

       flawfinder --quiet --html --context mydir > results.html
                   Examine all the C/C++ files in the directory mydir and its subdirectories, and
                   produce an HTML formatted version of  the  results.   Source  code  management
                   systems (such as SourceForge and Savannah) might use a command like this.

       flawfinder --quiet --savehitlist saved.hits *.[ch]
                   Examine  all  .c  and  .h files in the current directory.  Don't report on the
                   status of processing, and save the resulting hitlist (the set of all hits)  in
                   the file saved.hits.

       flawfinder --diffhitlist saved.hits *.[ch]
                   Examine  all  .c and .h files in the current directory, and show any hits that
                   weren't already in the file saved.hits.  This can be used  to  show  only  the
                   ``new''  vulnerabilities in a modified program, if saved.hits was created from
                   the older version of the program being analyzed.

       flawfinder --patch recent.patch .
                   Examine the current directory recursively, but only  report  lines  that  were
                   changed or added in the already-applied patchfile named recent.patch.

       flawfinder --regex "CWE-120|CWE-126" src/
                   Examine  directory  src  recursively,  but  only  report hits where CWE-120 or
                   CWE-126 apply.

   Invoking from vim
       The text editor vim includes a "quickfix" mechanism that works well  with  flawfinder,  so
       that you can easily view the warning messages and jump to the relevant source code.

       First,  you  need to invoke flawfinder to create a list of hits, and there are two ways to
       do this.  The first way is to start flawfinder first, and then (using its  output)  invoke
       vim.   The  second  way  is  to start (or continue to run) vim, and then invoke flawfinder
       (typically from inside vim).

       For the first way, run flawfinder and store its output in some FLAWFILE (say  "flawfile"),
       then  invoke  vim  using  its  -q  option,  like  this: "vim -q flawfile".  The second way
       (starting flawfinder after starting vim) can be done a legion of ways.  One is  to  invoke
       flawfinder using a shell command, ":!flawfinder-command > FLAWFILE", then follow that with
       the command ":cf FLAWFILE".  Another way is  to  store  the  flawfinder  command  in  your
       makefile (as, say, a pseudocommand like "flaw"), and then run ":make flaw".

       In  all  these cases you need a command for flawfinder to run.  A plausible command, which
       places each hit in its own line (-S) and removes headers and footers  that  would  confuse
       it, is:

       flawfinder -SQD .

       You  can now use various editing commands to view the results.  The command ":cn" displays
       the next hit; ":cN" displays the previous hit, and ":cr" rewinds back to  the  first  hit.
       ":copen"  will  open  a  window  to  show  the  current list of hits, called the "quickfix
       window"; ":cclose" will close the quickfix window.  If the buffer in the used  window  has
       changed,  and  the  error is in another file, jumping to the error will fail.  You have to
       make sure the window contains a buffer which can be abandoned before trying to jump  to  a
       new file, say by saving the file; this prevents accidental data loss.

   Invoking from emacs
       The  text  editor  /  operating  system  emacs  includes  "grep  mode"  and "compile mode"
       mechanisms that work well with flawfinder, making it easy to view warning  messages,  jump
       to the relevant source code, and fix any problems you find.

       First,  you  need  to invoke flawfinder to create a list of warning messages.  You can use
       "grep mode" or "compile mode" to create this list.  Often "grep mode" is more  convenient;
       it  leaves  compile  mode  untouched  so  you  can  easily  recompile  once you've changed
       something.  However, if you want to jump to the exact column position of  a  hit,  compile
       mode  may  be  more  convenient  because  emacs can use the column output of flawfinder to
       directly jump to the right location without any special configuration.

       To use grep mode, enter the command "M-x  grep"  and  then  enter  the  needed  flawfinder
       command.   To  use  compile  mode,  enter  the  command "M-x compile" and enter the needed
       flawfinder command.  This is a meta-key command, so you'll need to use the  meta  key  for
       your  keyboard  (this is usually the ESC key).  As with all emacs commands, you'll need to
       press RETURN after typing "grep" or "compile".  So on  many  systems,  the  grep  mode  is
       invoked by typing ESC x g r e p RETURN.

       You  then  need  to  enter  a command, removing whatever was there before if necessary.  A
       plausible command is:

       flawfinder -SQDC .

       This command makes every hit report a single line, which  is  much  easier  for  tools  to
       handle.  The quiet and dataonly options remove the other status information not needed for
       use inside  emacs.   The  trailing  period  means  that  the  current  directory  and  all
       descendents are searched for C/C++ code, and analyzed for flaws.

       Once  you've  invoked  flawfinder,  you  can use emacs to jump around in its results.  The
       command C-x ` (Control-x backtick) visits the source code location for  the  next  warning
       message.   C-u  C-x ` (control-u control-x backtick) restarts from the beginning.  You can
       visit the source for any particular error message by moving to that  hit  message  in  the
       *compilation*  buffer or *grep* buffer and typing the return key.  (Technical note: in the
       compilation buffer, this invokes compile-goto-error.)  You  can  also  click  the  Mouse-2
       button on the error message (you don't need to switch to the *compilation* buffer first).

       If  you  want  to  use  grep  mode  to  jump  to specific columns of a hit, you'll need to
       specially configure emacs to do this.  To do this, modify the emacs variable "grep-regexp-
       alist".  This variable tells Emacs how to parse output of a "grep" command, similar to the
       variable "compilation-error-regexp-alist" which lists various formats of compilation error
       messages.

   Invoking from Integrated Development Environments (IDEs)
       For (other) IDEs, consult your IDE's set of plug-ins.

COMMON WEAKNESS ENUMERATION (CWE)

       The  Common Weakness Enumeration (CWE) is ``a formal list or dictionary of common software
       weaknesses that can occur in software's architecture, design, code or implementation  that
       can lead to exploitable security vulnerabilities...  created to serve as a common language
       for describing software security weaknesses'' (http://cwe.mitre.org/about/faq.html).   For
       more information on CWEs, see http://cwe.mitre.org.

       Flawfinder  supports the CWE and is officially CWE-Compatible.  Hit descriptions typically
       include a relevant Common Weakness Enumeration (CWE) identifier in parentheses where there
       is  known  to  be  a  relevant  CWE.  For example, many of the buffer-related hits mention
       CWE-120, the CWE identifier for ``buffer  copy  without  checking  size  of  input''  (aka
       ``Classic  Buffer Overflow'').  In a few cases more than one CWE identifier may be listed.
       The HTML report also includes hypertext links to the CWE definitions hosted at MITRE.   In
       this way, flawfinder is designed to meet the CWE-Output requirement.

       Many  of  the  CWEs reported by flawfinder are identified in the CWE/SANS top 25 list 2011
       (http://cwe.mitre.org/top25/).  Many people will want to search for  CWEs  in  this  list,
       such  as  CWE-120  (classic  buffer  overflow), When flawfinder maps to a CWE that is more
       general  than  a  top  25  item,  it  lists  it   as   more-general:more-specific   (e.g.,
       CWE-119:CWE-120),  where more-general is the actual mapping.  If flawfinder maps to a more
       specific CWE item that is a specific case of a top 25 item,  it  is  listed  in  the  form
       top-25/more-specific  (e.g., CWE-362/CWE-367), where the real mapping is the more specific
       CWE entry.  If the same entry maps to multiple CWEs, the  CWEs  are  separated  by  commas
       (this often occurs with CWE-20, Improper Input Validation).  This simplifies searching for
       certain CWEs.

       CWE version 2.7 (released June 23, 2014) was  used  for  the  mapping.   The  current  CWE
       mappings  select  the  most  specific  CWE  the  tool  can determine.  In theory, most CWE
       security elements (signatures/patterns that the tool searches for) could theoretically  be
       mapped to CWE-676 (Use of Potentially Dangerous Function), but such a mapping would not be
       useful.  Thus, more specific mappings were preferred where one could be found.  Flawfinder
       is a lexical analysis tool; as a result, it is impractical for it to be more specific than
       the mappings currently implemented.  This also means that it  is  unlikely  to  need  much
       updating  for  map  currency;  it  simply  doesn't  have enough information to refine to a
       detailed CWE level that CWE changes would typically affect.  The list of  CWE  identifiers
       was  generated automatically using "make show-cwes", so there is confidence that this list
       is correct.  Please report CWE mapping problems as bugs if you find any.

       Flawfinder may fail to find a vulnerability, even if flawfinder covers one  of  these  CWE
       weaknesses.  That said, flawfinder does find vulnerabilities listed by the CWEs it covers,
       and it will not report lines without  those  vulnerabilities  in  many  cases.   Thus,  as
       required  for  any  tool  intending  to  be CWE compatible, flawfinder has a rate of false
       positives less than 100% and a rate of false negatives less than 100%.  Flawfinder  almost
       always reports whenever it finds a match to a CWE security element (a signature/pattern as
       defined in its database), though certain obscure constructs can cause it to fail (see BUGS
       below).

       Flawfinder  can  report  on the following CWEs (these are the CWEs that flawfinder covers;
       ``*'' marks those in the CWE/SANS top 25 list):

       · CWE-20: Improper Input Validation

       · CWE-22: Improper Limitation of a Pathname to a Restricted Directory (``Path Traversal'')

       · CWE-78: Improper Neutralization of Special Elements used in an OS Command (``OS  Command
         Injection'')*

       · CWE-119:  Improper  Restriction  of  Operations  within the Bounds of a Memory Buffer (a
         parent of CWE-120*, so this is shown as CWE-119:CWE-120)

       · CWE-120: Buffer Copy without Checking Size of Input (``Classic Buffer Overflow'')*

       · CWE-126: Buffer Over-read

       · CWE-134: Uncontrolled Format String*

       · CWE-190: Integer Overflow or Wraparound*

       · CWE-250: Execution with Unnecessary Privileges

       · CWE-327: Use of a Broken or Risky Cryptographic Algorithm*

       · CWE-362: Concurrent  Execution  using  Shared  Resource  with  Improper  Synchronization
         (``Race Condition'')

       · CWE-377: Insecure Temporary File

       · CWE-676: Use of Potentially Dangerous Function*

       · CWE-732: Incorrect Permission Assignment for Critical Resource*

       · CWE-785:  Use  of  Path  Manipulation  Function  without  Maximum-sized Buffer (child of
         CWE-120*, so this is shown as CWE-120/CWE-785)

       · CWE-807: Reliance on Untrusted Inputs in a Security Decision*

       · CWE-829: Inclusion of Functionality from Untrusted Control Sphere*

       You can select a specific subset of CWEs to report by using the ``--regex''  (-e)  option.
       This option accepts a regular expression, so you can select multiple CWEs, e.g., ``--regex
       "CWE-120|CWE-126"''.  If you select multiple CWEs with ``|'' on a command  line  you  will
       typically  need  to  quote  the  parameters  (since an unquoted ``|'' is the pipe symbol).
       Flawfinder is designed to meet the CWE-Searchable requirement.

       If your goal is to report a subset of CWEs that are listed in a file, that can be achieved
       on  a  Unix-like  system  using  the  ``--regex''  aka ``-e'' option.  The file must be in
       regular expression format.  For example, ``flawfinder -e $(cat file1)'' would report  only
       hits  that  matched  the  pattern in ``file1''.  If file1 contained ``CWE-120|CWE-126'' it
       would only report hits matching those CWEs.

       A list of all CWE security elements (the signatures/patterns that  flawfinder  looks  for)
       can  be  found  by  using the ``--listrules'' option.  Each line lists the signature token
       (typically a function name) that may lead to a  hit,  the  default  risk  level,  and  the
       default  warning  (which  includes the default CWE identifier).  For most purposes this is
       also enough if you want to see what CWE security  elements  map  to  which  CWEs,  or  the
       reverse.   For  example,  to  see  the most of the signatures (function names) that map to
       CWE-327, without seeing the default risk level or detailed warning text, run  ``flawfinder
       --listrules | grep CWE-327 | cut -f1''.  You can also see the tokens without a CWE mapping
       this way by running  ``flawfinder  -D  --listrules  |  grep  -v  CWE-''.   However,  while
       --listrules  lists  all CWE security elements, it only lists the default mappings from CWE
       security elements to CWE identifiers.  It does not include the refinements that flawfinder
       applies (e.g., by examining function parameters).

       If  you  want  a  detailed  and  exact  mapping  between the CWE security elements and CWE
       identifiers, the flawfinder source code (included in the distribution) is the  best  place
       for  that  information.   This  detailed information is primarily of interest to those few
       people who are trying to refine the CWE mappings of flawfinder or refine CWE  in  general.
       The  source code documents the mapping between the security elements to the respective CWE
       identifiers, and is a single Python file.  The ``c_rules''  dataset  defines  most  rules,
       with  reference  to  a  function  that  may  make further refinements.  You can search the
       dataset for function names to see what CWE it generates by default; if first parameter  is
       not ``normal'' then that is the name of a refining Python method that may select different
       CWEs (depending on additional information).  Conversely, you can search for ``CWE-number''
       and  find  what  security  elements (signatures or patterns) refer to that CWE identifier.
       For most people, this is much more than they need; most people just  want  to  scan  their
       source code to quickly find problems.

SECURITY

       The  whole  point  of  this  tool  is  to  help find vulnerabilities so they can be fixed.
       However, developers and reviewers must know how to develop secure  software  to  use  this
       tool,   because   otherwise,   a   fool  with  a  tool  is  still  a  fool.   My  book  at
       http://www.dwheeler.com/secure-programs may help.

       This tool should be, at most, a small  part  of  a  larger  software  development  process
       designed  to  eliminate or reduce the impact of vulnerabilities.  Developers and reviewers
       need know how to develop secure software, and they need to apply this knowledge to  reduce
       the risks of vulnerabilities in the first place.

       Different  vulnerability-finding  tools tend to find different vulnerabilities.  Thus, you
       are best off using human review and a variety of tools.  This  tool  can  help  find  some
       vulnerabilities, but by no means all.

       You  should  always  analyze  a copy of the source program being analyzed, not a directory
       that can be modified by a developer while flawfinder is performing the analysis.  This  is
       especially  true  if  you don't necessily trust a developer of the program being analyzed.
       If an attacker has control over the files while you're analyzing them, the attacker  could
       move  files  around or change their contents to prevent the exposure of a security problem
       (or create the impression of a problem where there is  none).   If  you're  worried  about
       malicious  programmers  you  should  do this anyway, because after analysis you'll need to
       verify that the code eventually run is the code  you  analyzed.   Also,  do  not  use  the
       --allowlink option in such cases; attackers could create malicious symbolic links to files
       outside of their source code area (such as /etc/passwd).

       Source code management systems (like SourceForge and Savannah) definitely fall  into  this
       category; if you're maintaining one of those systems, first copy or extract the files into
       a separate directory (that can't be controlled by attackers) before running flawfinder  or
       any other code analysis tool.

       Note  that  flawfinder  only opens regular files, directories, and (if requested) symbolic
       links; it will never open other kinds of files, even if a symbolic link is made  to  them.
       This counters attackers who insert unusual file types into the source code.  However, this
       only works if the filesystem being analyzed can't be modified by an  attacker  during  the
       analysis,  as  recommended  above.  This protection also doesn't work on Cygwin platforms,
       unfortunately.

       Cygwin systems (Unix emulation on top of Windows) have an additional problem if flawfinder
       is used to analyze 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.  Yes, Windows and MS-DOS
       really  are designed this badly.  Flawfinder deals with this by checking what a filesystem
       object is, and then only opening directories and regular files (and symlinks if  enabled).
       Unfortunately,  this  doesn't  work on Cygwin; on at least some versions of Cygwin on some
       versions of Windows, merely trying to determine if a file is a device type can  cause  the
       program  to  hang.  A workaround is to delete or rename any filenames that are interpreted
       as device names before performing the analysis.  These so-called  ``reserved  names''  are
       CON,  PRN, AUX, CLOCK$, NUL, COM1-COM9, and LPT1-LPT9, optionally followed by an extension
       (e.g., ``com1.txt''), in any directory, and in any case (Windows is case-insensitive).

       Do not load or diff hitlists from untrusted  sources.   They  are  implemented  using  the
       Python pickle module, and the pickle module is not intended to be secure against erroneous
       or maliciously constructed data.  Stored hitlists are intended for later use by  the  same
       user who created the hitlist; in that context this restriction is not a problem.

BUGS

       Flawfinder  is  based  on  simple  text pattern matching, which is part of its fundamental
       design and not easily changed.  This design apporach leads  to  a  number  of  fundamental
       limitations,  e.g.,  a  higher false positive rate, and is the underlying cause of most of
       the bugs listed here.  On the positive side,  flawfinder  doesn't  get  confused  by  many
       complicated  preprocessor  sequences  that  other tools sometimes choke on; flawfinder can
       often handle code that cannot link, and sometimes cannot even build.

       Flawfinder is currently limited to C/C++.  In addition,  when  analyzing  C++  it  focuses
       primarily  on the C subset of C++.  For example, flawfinder does not report on expressions
       like cin >> charbuf, where charbuf is a char array.  That is  because  flawfinder  doesn't
       have type information, and ">>" is safe with many other types; reporting on all ">>" would
       lead to too many false positives.  That said, it's designed so  that  adding  support  for
       other languages should be easy where its text-based approach can usefully apply.

       Flawfinder  can  be fooled by user-defined functions or method names that happen to be the
       same as those defined as ``hits'' in its database, and will often trigger  on  definitions
       (as  well as uses) of functions with the same name.  This is typically not a problem for C
       code.  In C code, a function with the same name as a common  library  routine  name  often
       indicates  that  the  developer is simply rewriting a common library routine with the same
       interface, say for portability's sake.  C programs tend to avoid reusing the same name for
       a  different  purpose  (since  in  C  function  names  are  global by default).  There are
       reasonable odds that these rewritten routines will be vulnerable  to  the  same  kinds  of
       misuse,  and  thus,  reusing these rules is a reasonable approach.  However, this can be a
       much more serious problem in C++ code which heavily uses classes and namespaces, since the
       same  method  name  may have many different meanings.  The --falsepositive option can help
       somewhat in this case.  If this is a serious problem, feel free to modify the program,  or
       process the flawfinder output through other tools to remove the false positives.

       Preprocessor  commands  embedded  in  the  middle  of a parameter list of a call can cause
       problems in parsing, in particular, if a string is opened and then closed  multiple  times
       using  an  #ifdef  ..  #else construct, flawfinder gets confused.  Such constructs are bad
       style, and will confuse many other tools too.  If you must  analyze  such  files,  rewrite
       those lines.  Thankfully, these are quite rare.

       Some  complex or unusual constructs can mislead flawfinder.  In particular, if a parameter
       begins with gettext(" and ends with ), flawfinder  will  presume  that  the  parameter  of
       gettext  is  a constant.  This means it will get confused by patterns like gettext("hi") +
       function("bye").  In practice, this doesn't seem to be a  problem;  gettext()  is  usually
       wrapped around the entire parameter.

       The  routine to detect statically defined character arrays uses simple text matching; some
       complicated expressions can cause it to trigger or not trigger unexpectedly.

       Flawfinder looks for specific patterns known to be common mistakes.   Flawfinder  (or  any
       tool  like  it)  is not a good tool for finding intentionally malicious code (e.g., Trojan
       horses); malicious programmers can easily insert code that would not be detected  by  this
       kind of tool.

       Flawfinder  looks  for  specific patterns known to be common mistakes in application code.
       Thus, it is likely to be less effective analyzing programs that  aren't  application-layer
       code  (e.g.,  kernel code or self-hosting code).  The techniques may still be useful; feel
       free to replace the database if your situation is significantly different from normal.

       Flawfinder's output format (filename:linenumber, followed optionally by  a  :columnnumber)
       can be misunderstood if any source files have very weird filenames.  Filenames embedding a
       newline/linefeed character will cause odd breaks, and filenames including  colon  (:)  are
       likely  to be misunderstood.  This is especially important if flawfinder's output is being
       used by other tools, such as filters or text editors.  If  you're  looking  at  new  code,
       examine  the  files  for  such  characters.  It's incredibly unwise to have such filenames
       anyway; many tools can't handle such filenames at all.  Newline  and  linefeed  are  often
       used  as  internal  data  delimeters.   The  colon  is often used as special characters in
       filesystems: MacOS uses it as a directory separator, Windows/MS-DOS uses  it  to  identify
       drive  letters,  Windows/MS-DOS  inconsistently  uses  it to identify special devices like
       CON:, and applications on many platforms use the colon to identify  URIs/URLs.   Filenames
       including  spaces  and/or tabs don't cause problems for flawfinder, though note that other
       tools might have problems with them.

       Flawfinder is not internationalized, so it currently does not support localization.

       In general, flawfinder attempts to err on the side of caution; it tends to report hits, so
       that  they  can  be examined further, instead of silently ignoring them.  Thus, flawfinder
       prefers to have false positives (reports that turn out to not  be  problems)  rather  than
       false  negatives  (failure  to  report  on  a  security  vulnerability).   But  this  is a
       generality; flawfinder uses simplistic heuristics and simply can't get everything "right".

       Security vulnerabilities might not be identified as such by  flawfinder,  and  conversely,
       some  hits  aren't  really security vulnerabilities.  This is true for all static security
       scanners, and is especially true for tools like  flawfinder  that  use  a  simple  lexical
       analysis  and pattern analysis to identify potential vulnerabilities.  Still, it can serve
       as a useful aid for humans, helping to identify useful  places  to  examine  further,  and
       that's the point of this simple tool.

SEE ALSO

       See the flawfinder website at http://www.dwheeler.com/flawfinder.  You should also see the
       Secure Programming for Unix and Linux HOWTO at http://www.dwheeler.com/secure-programs.

AUTHOR

       David A. Wheeler (dwheeler@dwheeler.com).