opengrep ci
opengrep ci [FLAGS]Runs the engine of opengrep scan, with defaults suited to continuous integration. The command takes no targets: it scans the current directory, or the directory given by --subdir, and is meant to run at the root of a git repository. When run elsewhere, it logs a warning and continues with the information it can determine.
The rules come from --config or OPENGREP_RULES, as for a scan. Without either, opengrep ci uses --config auto and downloads rules from the registry.
In addition to a scan, opengrep ci provides:
- Repository metadata. The CI provider is detected from the environment (GitHub Actions, GitLab CI, CircleCI, Jenkins, Bitbucket, Azure Pipelines, Buildkite or Travis, and plain git otherwise). The first line printed on standard error names the provider and the event that triggered the run, such as
git · unknownorgitlab-ci · push. Environment variables such asOPENGREP_PR_IDcan set parts of the metadata. - A baseline. The baseline is derived from the metadata, so that in a pull or merge request, only the findings that the request introduces are reported.
--baseline-commitoverrides it. - Blocking findings. Whether a finding is blocking depends on the metadata of its rule.
opengrep cilists the rules of the blocking findings underblocking rules fired, and exits with status 1 when there is at least one, even without--error.--audit-onkeeps the status at 0 for the CI events it names. - Suppressed errors. By default, any other failure ends the run with exit status 0, so that, for example, an invalid rule file does not fail the build. See
--suppress-errors.
Exit status
| Status | Meaning |
|---|---|
| 0 | The scan completed without blocking findings. |
| 1 | At least one blocking finding was reported. |
| other | The statuses of opengrep scan, with --no-suppress-errors only; otherwise 0. |
Flags
| Flag | Summary |
|---|---|
--allow-rule-timeout-control | Let rules set their own time limits, which are otherwise ignored. |
--audit-on | Report blocking findings but exit with status 0 when the CI event has one of these names. |
--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. |
--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. |
--exclude | Skip files and directories whose path matches a gitignore-style pattern. |
--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. |
--include | Scan only the files whose path matches one of these patterns. |
--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. |
--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. |
--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. |
--profile | Listed in Internal and debugging interfaces. |
--quiet | Print only the findings, and nothing on standard error. |
--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. |
--skin | The layout of the text output. |
--subdir | Scan only this directory, with the CI metadata of the whole repository. |
--suppress-errors | Make opengrep ci exit with status 0 on errors; on by default. |
--taint-intrafile | Follow taint through calls to functions in the same file, for every taint rule. |
--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. |
--verbose | Log the progress of the run, at the info level. |
--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. |
Examples
A scan of a repository
rule.yaml
rules: - id: find-eval pattern: eval(...) message: found eval languages: [python] severity: WARNINGapp.py
eval(1)Command and result
$ git init -q && git add . && git commit -qm init
$ opengrep ci -q --config rule.yaml
blocking · 1 finding
app.py
warn find-eval
found eval
1: eval(1)
blocking rules fired
find-eval
$ opengrep ci --config rule.yaml > /dev/null 2>&1; echo "exit status: $?"
exit status: 1The line naming the provider and the event, the counts and the closing summary go to standard error:
Command and result
$ opengrep ci --config rule.yaml 2>&1 >/dev/null | tail -3
CI scan completed successfully.
Found 1 finding (1 blocking) from 1 rule.
Has findings for blocking rules so exiting with code 1