csgrep - Man Page

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


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


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


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


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


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


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


print the usage of csgrep


print the version of csgrep


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


August 2023 csgrep 3.0.4