csgrep - Man Page

filter the list of defects by the specified regex-based predicates

Synopsis

csgrep [options] [file1.err [...]], where options are:

Description

--checker arg

defect matches if its checker matches the given regex (each defect has assigned exactly one checker)

--path arg

defect matches if the path of its key event matches the given regex

--event arg

defect matches if its key event matches the given regex (each defect has exactly one key event, which determines its location in the code)

--error arg

defect matches if the message of its key event matches the given regex

--msg arg

defect matches if any of its messages matches the given regex

--tool arg

defect matches if it was detected by tool that matches the given regex

--annot arg

defect matches if its annotation matches the given regex

--src-annot arg

defect matches if an annotation in the _source_ file matches the given regex

--imp-level arg

defect matches if the importance level is greater or equal than the given number

--drop-scan-props

do not propagate scan properties

-U [ --embed-context ] arg

embed a number of lines of context from the source file for the key event

--prune-events arg

event is preserved if its verbosity level is below the given number

--warning-rate-limit arg

stop processing a warning if the count of its occurrences exceeds the specified limit

--limit-msg-len arg

limit message length by a number provided

-u [ --remove-duplicates ]

remove defects that are not unique by their key event

--set-imp-level arg

set importance level on all defects to the specified value

--set-scan-prop arg

NAME:VALUE pair to override the specified scan property

--strip-path-prefix arg

string prefix to strip from path (applied after all filters)

--prepend-path-prefix arg

string prefix to prepend to relative paths (applied after all filters)

-i [ --ignore-case ]

ignore case when matching regular expressions

--ignore-parser-warnings

if enabled, parser warnings about the input files do not affect exit code

-v [ --invert-match ]

select defects that do not match the selected criteria

-n [ --invert-regex ]

invert regular expressions in all predicates

-f [ --filter-file ] arg

read custom filtering rules from a file in JSON format

--color

use colorized console output (default if connected to a terminal)

--no-color

do not use colorized console output

-q [ --quiet ]

do not report any parsing errors

--mode arg (=grep)

grep, json, evtstat, files, filestat, grouped, sarif, stat, or dig_key_events

--help

print the usage of csgrep

--version

print the version of csgrep

Options

The --filter-file option takes a list of JSON files in the following format.  Missing replace entry is equal to "replace" : "".

{
    "msg-filter" : [
        {
             "checker" : "DIVINE|SYMBIOTIC",
             "regexp" : "memory"
        },
        {
             "checker" : "COMPILER_WARNING",
             "regexp" : "called on unallocated object",
             "replace" : "called correctly, no UB here"
        }
    ]
}

Exit Status

csgrep exits with status 0 if arguments are valid and input files are parsed successfully.  It does not matter whether any defects were matched or not.

Example - Checkers, Events, Messages

Error: FORWARD_NULL (CWE-476):
libhsm.c:1168: assign_zero: Assigning: key_handles = NULL.
libhsm.c:1210: var_deref_op: Dereferencing null pointer key_handles.

In the above example, FORWARD_NULL is the checker, assign_zero and var_deref_op are events, where var_deref_op is the key event and "Dereferencing null pointer key_handles." is the message associated with the key event.

Description of Available Modes

dig_key_events - for each defect, print only the checker and key event

evtstat - print overall checker/key_event statistics for the matched defects

files - print only names of error files that contain the matched defects

filestat - print statistics of matched defects per individual source files

grep - print matched defects using the same format as expected on the input

grouped - print matched defects, grouped by error files they originate from

json - print matched defects in a JSON format

sarif - print matched defects in a SARIF format

stat - print overall statistics of the matched defects in given error files

Info

January 2024 csgrep 3.2.0