opengrep scan
- See also
opengrep test,--config,opengrep ci,opengrep lsp,opengrep validate
opengrep scan [FLAGS] [TARGETS...]Runs rules on the files under TARGETS and reports the findings. TARGETS are files or directories; the default is the current directory. scan is the default command: opengrep --config rule.yaml . is equivalent to opengrep scan --config rule.yaml ..
The rules come from --config or OPENGREP_RULES, or from a single pattern given with -e/--pattern and -l/--lang. Without any of them, opengrep scan uses --config auto, which downloads rules from the Semgrep registry.
In a directory target, Opengrep skips the files that .gitignore and .semgrepignore exclude. When the project has no .semgrepignore, a default list applies, which includes node_modules/, vendor/, test/ and tests/. Files named on the command line are always scanned. See --exclude.
The findings go to standard output, in the text format unless another format is selected, such as --json or --sarif. The progress and the summary go to standard error. When standard output is a terminal, the scan starts with a banner that shows the Opengrep logo and version; --quiet leaves out everything on standard error.
Exit status
| Status | Meaning |
|---|---|
| 0 | The scan completed. Findings do not change the status unless --error is given. |
| 1 | --error was given and there are findings. |
| 2 | A fatal error, including an invalid command line or an invalid value of an environment variable. |
| 3 | A target file could not be parsed. |
| 4 | A rule pattern could not be parsed. |
| 5 | A rule file is not valid YAML. |
| 7 | No valid configuration could be loaded, for example because of an invalid rule. |
| 8 | A rule names an unsupported language. |
| 141 | The program that reads the output closed the pipe. |
Flags
| Flag | Summary |
|---|---|
--allow-rule-timeout-control | Let rules set their own time limits, which are otherwise ignored. |
--autofix | Apply the fixes of the rules to the scanned files. |
--baseline-commit | Report only the findings that are not present in the given commit. |
--config | Load rules from a file, a directory, a URL, a git repository or the registry. |
--dataflow-traces | Show the path from source to sink in the findings of taint rules. |
--debug | Log the messages of --verbose and the diagnostics of the engine. |
--develop | Listed in Internal and debugging interfaces. |
--disable-intrafile | Analyze every taint rule one function at a time, including rules that set taint_intrafile or taint_interfile. |
--dryrun | Show the fixes --autofix would make, without writing them to the files. |
--dump-ast | Listed in Internal and debugging interfaces. |
--dynamic-timeout | Scale the time limit of each rule with the size of the file. |
--dynamic-timeout-max-multiplier | The largest factor by which --dynamic-timeout multiplies the timeout. |
--dynamic-timeout-unit-kb | The file size, in KB, of one step of --dynamic-timeout. |
--emacs | Print one line per finding, in the format of Emacs compilation buffers. |
--emacs-output | Write the findings in the Emacs format to a file as well. |
--enable-interfile | Run cross-file taint analysis for the rules that set the taint_interfile option. |
--enable-nosem | Whether nosem comments suppress findings; on by default. |
--error | Exit with status 1 when there are findings. |
--exclude | Skip files and directories whose path matches a gitignore-style pattern. |
--exclude-minified-files | Skip files that look minified. |
--exclude-rule | Skip the rule with this id. |
--files-with-matches | Print only the paths of the files that have findings. |
--force-color | Style the output even when it does not go to a terminal. |
--force-exclude | Apply --include and --exclude to files named on the command line as well. |
--gitlab-sast | Print the findings as a GitLab SAST report. |
--gitlab-sast-output | Write the findings as a GitLab SAST report to a file as well. |
--gitlab-secrets | Print the findings as a GitLab secret detection report. |
--gitlab-secrets-output | Write the findings as a GitLab secret detection report to a file as well. |
--guarded-taint-signatures | Drop a cross-function taint finding when the condition leading to the sink cannot hold for the call. |
--include | Scan only the files whose path matches one of these patterns. |
--incremental-output | Print each finding as soon as it is found. |
--incremental-output-postprocess | |
--inline-metavariables | Replace the metavariables in the metadata of a rule with the code they matched. |
--interfile-dedup-by | Whether a sink reached by several sources across files produces one finding or one per source. |
--interfile-depth | The longest call chain the cross-file taint analysis follows. |
--interfile-timeout | The time a rule may spend on the cross-file taint analysis. |
--jobs | The number of workers that run rules in parallel. |
--json | Print the findings as a JSON document. |
--json-output | Write the findings as JSON to a file as well. |
--junit-xml | Print the findings as a JUnit XML report, one failed test per finding. |
--junit-xml-output | Write the findings as a JUnit XML report to a file as well. |
--lang | The language of a pattern given on the command line. |
--matching-explanations | Add to the JSON output a record of how each part of a rule matched. |
--max-chars-per-line | The width at which lines of code are wrapped in the text output. |
--max-lines-per-finding | The number of lines of code shown for a finding in the text output. |
--max-log-list-entries | The number of items above which a list in the logs is replaced by a note. |
--max-match-per-file | The number of matches in a file, across all rules, above which all its findings are dropped. |
--max-memory | The memory that the analysis of one file may use before it is abandoned. |
--max-target-bytes | Skip files larger than this size. |
--no-progress-bar | Do not draw the status line that shows the progress of a scan. |
--opengrep-ignore-pattern | An additional comment prefix that suppresses the findings on a line. |
--optimizations | Turn the optimizations of the engine, such as the prefilter, on or off. |
--output | Write the output to a file instead of standard output. |
--output-enclosing-context | Record the function or class that contains each finding. |
--pattern | Search with a pattern given on the command line instead of a rule file. |
--profile | Listed in Internal and debugging interfaces. |
--project-root | The project root, where .gitignore and .semgrepignore are read. |
--quiet | Print only the findings, and nothing on standard error. |
--replacement | The fix of a pattern given on the command line. |
--rewrite-rule-ids | Whether the ids of rules from a subdirectory are prefixed with its path; on by default. |
--sarif | Print the findings as a SARIF 2.1.0 document. |
--sarif-output | Write the findings as SARIF to a file as well, including suppressed findings. |
--scan-unknown-extensions | Scan a file named on the command line even when its extension belongs to no language. |
--semgrepignore-filename | Read the ignored paths from a file with a name other than .semgrepignore. |
--severity | Report only the findings of rules with these severities. |
--show-supported-languages | Print the supported languages and exit. |
--skin | The layout of the text output. |
--skip-invalid-configs | Skip invalid rule files in a directory or a git repository instead of stopping. |
--strict | Fail the run when a file cannot be parsed or another warning-level error occurs. |
--taint-intrafile | Follow taint through calls to functions in the same file, for every taint rule. |
--test | Run the rule tests instead of scanning, as opengrep test does. |
--text | Print the text output, the default format. |
--text-output | Write the text output to a file as well. |
--time | Report the time the scan took, per rule and per file. |
--timeout | The time limit of a rule on a file, in seconds; 0 sets no limit. |
--timeout-threshold | The number of rules that may time out on a file before the file is skipped. |
--use-git-ignore | Whether files ignored by git are skipped; on by default. |
--validate | Check the rules instead of scanning, as opengrep validate does. |
--verbose | Log the progress of the run, at the info level. |
--version | Print the Opengrep version and exit. |
--vim | Print one line per finding, in the format of Vim quickfix lists. |
--vim-output | Write the findings in the Vim quickfix format to a file as well. |
--x-ignore-semgrepignore-files | Listed in Internal and debugging interfaces. |
--x-ls | Listed in Internal and debugging interfaces. |
--x-ls-long | Listed in Internal and debugging interfaces. |
Examples
Scan a file
rule.yaml
rules: - id: find-eval pattern: eval(...) message: found eval languages: [python] severity: WARNINGapp.py
def run(expr): return eval(expr)Command and result
$ opengrep scan -q --config rule.yaml app.py
app.py
warn find-eval
found eval
2: return eval(expr)Fail when there are findings
rule.yaml
rules: - id: find-eval pattern: eval(...) message: found eval languages: [python] severity: WARNINGapp.py
eval(input())Command and result
$ opengrep scan --config rule.yaml app.py > /dev/null 2>&1; echo "exit status: $?"
exit status: 0
$ opengrep scan --config rule.yaml --error app.py > /dev/null 2>&1; echo "exit status: $?"
exit status: 1