1CSGREP(1)                        User Commands                       CSGREP(1)
2
3
4

NAME

6       csgrep - filter the list of defects by the specified regex-based predi‐
7       cates
8

SYNOPSIS

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

DESCRIPTION

13       --checker arg
14              defect matches if its checker matches the given regex (each  de‐
15              fect has assigned exactly one checker)
16
17       --path arg
18              defect  matches  if  the path of its key event matches the given
19              regex
20
21       --event arg
22              defect matches if its key event matches the  given  regex  (each
23              defect  has exactly one key event, which determines its location
24              in the code)
25
26       --error arg
27              defect matches if the message of its key event matches the given
28              regex
29
30       --msg arg
31              defect matches if any of its messages matches the given regex
32
33       --tool arg
34              defect matches if it was detected by tool that matches the given
35              regex
36
37       --annot arg
38              defect matches if its annotation matches the given regex
39
40       --src-annot arg
41              defect matches if an annotation in the _source_ file matches the
42              given regex
43
44       --imp-level arg
45              defect  matches if the importance level is greater or equal than
46              the given number
47
48       --drop-scan-props
49              do not propagate scan properties
50
51       -U [ --embed-context ] arg
52              embed a number of lines of context from the source file for  the
53              key event
54
55       --prune-events arg
56              event  is  preserved  if  its verbosity level is below the given
57              number
58
59       --warning-rate-limit arg
60              stop processing a warning if the count of  its  occurrences  ex‐
61              ceeds the specified limit
62
63       --limit-msg-len arg
64              limit message length by a number provided
65
66       -u [ --remove-duplicates ]
67              remove defects that are not unique by their key event
68
69       --set-scan-prop arg
70              NAME:VALUE pair to override the specified scan property
71
72       --strip-path-prefix arg
73              string prefix to strip from path (applied after all filters)
74
75       --prepend-path-prefix arg
76              string  prefix  to  prepend to relative paths (applied after all
77              filters)
78
79       -i [ --ignore-case ]
80              ignore case when matching regular expressions
81
82       --ignore-parser-warnings
83              if enabled, parser warnings about the input files do not  affect
84              exit code
85
86       -v [ --invert-match ]
87              select defects that do not match the selected criteria
88
89       -n [ --invert-regex ]
90              invert regular expressions in all predicates
91
92       -f [ --filter-file ] arg
93              read custom filtering rules from a file in JSON format
94
95       --color
96              use  colorized  console output (default if connected to a termi‐
97              nal)
98
99       --no-color
100              do not use colorized console output
101
102       -q [ --quiet ]
103              do not report any parsing errors
104
105       --mode arg (=grep)
106              grep, json, evtstat, files, filestat, grouped, sarif,  stat,  or
107              dig_key_events
108
109       --help print the usage of csgrep
110
111       --version
112              print the version of csgrep
113

OPTIONS

115       The  --filter-file  option  takes a list of JSON files in the following
116       format.  Missing replace entry is equal to "replace" : "".
117
118           {
119               "msg-filter" : [
120                   {
121                        "checker" : "DIVINE|SYMBIOTIC",
122                        "regexp" : "memory"
123                   },
124                   {
125                        "checker" : "COMPILER_WARNING",
126                        "regexp" : "called on unallocated object",
127                        "replace" : "called correctly, no UB here"
128                   }
129               ]
130           }
131

EXIT STATUS

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

EXAMPLE - CHECKERS, EVENTS, MESSAGES

138       Error: FORWARD_NULL (CWE-476):
139       libhsm.c:1168: assign_zero: Assigning: key_handles = NULL.
140       libhsm.c:1210: var_deref_op: Dereferencing null pointer key_handles.
141
142       In the above example, FORWARD_NULL  is  the  checker,  assign_zero  and
143       var_deref_op  are  events,  where  var_deref_op  is  the  key event and
144       "Dereferencing null pointer key_handles."  is  the  message  associated
145       with the key event.
146

DESCRIPTION OF AVAILABLE MODES

148       dig_key_events - for each defect, print only the checker and key event
149
150       evtstat  -  print  overall checker/key_event statistics for the matched
151       defects
152
153       files - print only names of error files that contain  the  matched  de‐
154       fects
155
156       filestat  -  print  statistics of matched defects per individual source
157       files
158
159       grep - print matched defects using the same format as expected  on  the
160       input
161
162       grouped  - print matched defects, grouped by error files they originate
163       from
164
165       json - print matched defects in a JSON format
166
167       sarif - print matched defects in a SARIF format
168
169       stat - print overall statistics of the matched defects in  given  error
170       files
171
172
173
174csgrep 3.1.0                     October 2023                        CSGREP(1)