Repository navigation
Expand file tree
/
Copy pathexamples.html
More file actions
142 lines (123 loc) · 13.3 KB
/
Copy pathexamples.html
File metadata and controls
142 lines (123 loc) · 13.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Examples · Opengrep</title>
<meta name="description" content="Two runnable Opengrep examples: semantic pattern matching with constant propagation, and cross-function taint analysis with dataflow traces.">
<meta name="theme-color" content="#0b0b0e">
<link rel="canonical" href="https://opengrep.dev/examples.html">
<link rel="icon" href="assets/favicon.svg" type="image/svg+xml">
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Noto+Sans+Mono:wght@200..700&display=swap">
<link rel="stylesheet" href="style.css">
</head>
<body>
<header class="site-header">
<nav class="wrap nav" aria-label="Main">
<a href="index.html">home</a>
<a href="about.html">about</a>
<a href="examples.html" aria-current="page">examples</a>
<a href="docs/index.html">docs</a>
<a href="https://github.com/opengrep/opengrep">github</a>
</nav>
</header>
<main class="wrap">
<header class="hero">
<h1 class="crumb"><a class="brand" href="index.html"><img class="logo" src="assets/logo.svg" alt="Opengrep" width="582" height="100"></a><span class="sep" aria-hidden="true">:</span>examples</h1>
<p class="lede">Two small, runnable examples. Copy the files, run the command, get the same result.</p>
</header>
<!-- example 1 -->
<section class="example" id="semantic" aria-labelledby="ex1-h">
<h2 id="ex1-h"><span class="hash" aria-hidden="true">##</span> semantic matching</h2>
<p>A rule is a pattern that looks like the code it finds. Opengrep matches it against the syntax tree, not the text, so import aliases, line breaks, argument order and values held in variables don't get in the way.</p>
<div class="file">
<div class="file-head">shell-true.yaml</div>
<button class="copy" type="button">copy</button>
<pre class="code"><code><span class="line"><span class="k">rules</span>:</span><span class="line"> - <span class="k">id</span>: subprocess-shell-true</span><span class="line"> <span class="k">languages</span>: [python]</span><span class="line"> <span class="k">severity</span>: ERROR</span><span class="line"> <span class="k">message</span>: shell=True runs the command through a shell (command injection risk)</span><span class="line"> <span class="k">pattern</span>: subprocess.<span class="mv">$FUNC</span>(<span class="mv">...</span>, shell=<span class="s">True</span>, <span class="mv">...</span>)</span></code></pre>
</div>
<div class="file">
<div class="file-head">deploy.py</div>
<button class="copy" type="button">copy</button>
<pre class="code"><code><span class="line"><span class="k">import</span> subprocess</span><span class="line"><span class="k">from</span> subprocess <span class="k">import</span> run <span class="k">as</span> sh</span><span class="line"></span><span class="line"></span><span class="line"><span class="k">def</span> deploy(branch):</span><span class="line hit"> subprocess.call(<span class="s">"git checkout "</span> + branch, shell=<span class="s">True</span>)</span><span class="line"></span><span class="line hit"> sh(<span class="s">f"make release BRANCH={branch}"</span>, shell=<span class="s">True</span>)</span><span class="line"></span><span class="line"> use_shell = <span class="s">True</span></span><span class="line hit"> subprocess.Popen(</span><span class="line hit"> [<span class="s">"make"</span>, <span class="s">"clean"</span>],</span><span class="line hit"> cwd=<span class="s">"/srv/app"</span>,</span><span class="line hit"> shell=use_shell,</span><span class="line hit"> )</span><span class="line"></span><span class="line"> subprocess.run([<span class="s">"make"</span>, <span class="s">"test"</span>], shell=<span class="s">False</span>)</span></code></pre>
</div>
<div class="file">
<div class="file-head">output</div>
<pre class="out"><code><span class="p">$ </span>opengrep scan -q --output-enclosing-context -f shell-true.yaml deploy.py
<span class="b">deploy.py</span>
<span class="err">error</span> <span class="rule">subprocess-shell-true</span>
shell=True runs the command through a shell (command injection risk)
<span class="n"> in: </span><span class="n">function</span> deploy
<span class="n"> 6: </span>subprocess.call("git checkout " + branch, shell=True)
<span class="n"> in: </span><span class="n">function</span> deploy
<span class="n"> 8: </span>sh(f"make release BRANCH={branch}", shell=True)
<span class="n"> in: </span><span class="n">function</span> deploy
<span class="n"> 11: </span>subprocess.Popen(
<span class="n"> 12: </span> ["make", "clean"],
<span class="n"> 13: </span> cwd="/srv/app",
<span class="n"> 14: </span> shell=use_shell,
<span class="n"> 15: </span>)</code></pre>
</div>
<ul class="notes">
<li><span class="ref">line 6</span><span>the plain case: <code>shell=True</code> passed directly.</span></li>
<li><span class="ref">line 8</span><span><code>sh</code> is <code>subprocess.run</code> imported under another name.</span></li>
<li><span class="ref">line 11</span><span>spread over five lines, with <code>cwd</code> before <code>shell</code>, and <code>use_shell</code> resolved to <code>True</code> by constant propagation.</span></li>
<li><span class="ref">line 17</span><span><code>shell=False</code>, so no finding.</span></li>
</ul>
</section>
<!-- example 2 -->
<section class="example" id="taint" aria-labelledby="ex2-h">
<h2 id="ex2-h"><span class="hash" aria-hidden="true">##</span> cross-function taint analysis</h2>
<p>A taint rule says where untrusted data comes from (sources), where it must never end up (sinks) and what makes it safe (sanitizers). With the rule option <a class="plain" href="docs/rule-options/taint_intrafile.html"><code>taint_intrafile</code></a>, Opengrep follows the data through function calls, return values, lambdas and higher-order functions.</p>
<div class="file">
<div class="file-head">command-injection.yaml</div>
<button class="copy" type="button">copy</button>
<pre class="code"><code><span class="line"><span class="k">rules</span>:</span><span class="line"> - <span class="k">id</span>: command-injection</span><span class="line"> <span class="k">mode</span>: taint</span><span class="line"> <span class="k">languages</span>: [javascript]</span><span class="line"> <span class="k">severity</span>: ERROR</span><span class="line"> <span class="k">message</span>: User input reaches a shell command</span><span class="line"> <span class="k">options</span>:</span><span class="line"> <span class="k">taint_intrafile</span>: true</span><span class="line"> <span class="k">pattern-sources</span>:</span><span class="line"> - <span class="k">pattern</span>: req.query</span><span class="line"> - <span class="k">pattern</span>: req.body</span><span class="line"> <span class="k">pattern-sanitizers</span>:</span><span class="line"> - <span class="k">pattern</span>: shellescape(<span class="mv">...</span>)</span><span class="line"> <span class="k">pattern-sinks</span>:</span><span class="line"> - <span class="k">pattern</span>: exec(<span class="mv">...</span>)</span></code></pre>
</div>
<div class="file">
<div class="file-head">server.js</div>
<button class="copy" type="button">copy</button>
<pre class="code"><code><span class="line"><span class="k">const</span> express = require(<span class="s">"express"</span>);</span><span class="line"><span class="k">const</span> { exec } = require(<span class="s">"child_process"</span>);</span><span class="line"><span class="k">const</span> shellescape = require(<span class="s">"shell-escape"</span>);</span><span class="line"></span><span class="line"><span class="k">const</span> app = express();</span><span class="line"></span><span class="line"><span class="k">function</span> tarCommand(dir) {</span><span class="line"> <span class="k">return</span> <span class="s">"tar czf /backups/latest.tgz "</span> + dir;</span><span class="line">}</span><span class="line"></span><span class="line"><span class="k">function</span> escape(dir) {</span><span class="line"> <span class="k">return</span> shellescape([dir]);</span><span class="line">}</span><span class="line"></span><span class="line"><span class="k">function</span> backup(req, res) {</span><span class="line hit"> exec(tarCommand(req.query.dir));</span><span class="line">}</span><span class="line"></span><span class="line"><span class="k">function</span> backupAll(req, res) {</span><span class="line hit"> req.body.dirs.map(tarCommand)</span><span class="line hit"> .forEach((cmd) => exec(cmd));</span><span class="line">}</span><span class="line"></span><span class="line"><span class="k">function</span> backupSafe(req, res) {</span><span class="line"> exec(tarCommand(escape(req.query.dir)));</span><span class="line">}</span><span class="line"></span><span class="line">app.get(<span class="s">"/backup"</span>, backup);</span><span class="line">app.post(<span class="s">"/backup-all"</span>, backupAll);</span><span class="line">app.get(<span class="s">"/backup-safe"</span>, backupSafe);</span></code></pre>
</div>
<div class="file">
<div class="file-head">output</div>
<pre class="out"><code><span class="p">$ </span>opengrep scan -q --dataflow-traces \
--output-enclosing-context -f command-injection.yaml server.js
<span class="b">server.js</span>
<span class="err">error</span> <span class="rule">command-injection</span>
User input reaches a shell command
<span class="n"> in: </span><span class="n">function</span> backup
<span class="n"> 16: </span>exec(tarCommand(req.query.dir))<span class="n">;</span>
<span class="n">│</span>
<span class="n">├─ </span>source <span class="n">16: </span><span class="n">exec(tarCommand(</span>req.query<span class="n">.dir));</span>
<span class="n">├─ </span>through call <span class="n">16: </span><span class="n">exec(</span>tarCommand<span class="n">(req.query.dir));</span>
<span class="n">│ </span><span class="n">├─ </span>param <span class="n"> 7: </span><span class="n">function tarCommand(</span>dir<span class="n">) {</span>
<span class="n">│ </span><span class="n">└─ </span>return <span class="n"> 8: </span>return<span class="n"> "tar czf /backups/latest.tgz " + dir;</span>
<span class="n">└─ </span>sink <span class="n">16: </span>exec(tarCommand(req.query.dir))<span class="n">;</span>
<span class="n"> in: </span><span class="n">function</span> backupAll
<span class="n"> 21: </span><span class="n">.forEach((cmd) => </span>exec(cmd)<span class="n">);</span>
<span class="n">│</span>
<span class="n">├─ </span>source <span class="n">20: </span>req.body<span class="n">.dirs.map(tarCommand)</span>
<span class="n">├─ </span>through call <span class="n">21: </span><span class="n">.</span>forEach<span class="n">((cmd) => exec(cmd));</span>
<span class="n">└─ </span>sink <span class="n">21: </span><span class="n">.forEach((cmd) => </span>exec(cmd)<span class="n">);</span></code></pre>
</div>
<ul class="notes">
<li><span class="ref">line 16</span><span><code>req.query.dir</code> flows through <code>tarCommand()</code> and its return value into <code>exec</code>.</span></li>
<li><span class="ref">line 20</span><span>each entry of <code>req.body.dirs</code> passes through <code>map(tarCommand)</code> and a lambda before reaching <code>exec</code>.</span></li>
<li><span class="ref">line 25</span><span>no finding: the input goes through <code>escape()</code>, which calls the sanitizer.</span></li>
</ul>
</section>
<section aria-labelledby="flags-h">
<h2 id="flags-h"><span class="hash" aria-hidden="true">##</span> flags</h2>
<p>The commands above use these flags:</p>
<ul class="notes flags">
<li><span class="ref"><a class="plain" href="docs/flags/quiet.html"><code>-q</code></a></span><span>quiet: only the findings. Leaves out the banner, the progress and the summary that Opengrep prints around them.</span></li>
<li><span class="ref"><a class="plain" href="docs/flags/output-enclosing-context.html"><code>--output-enclosing-context</code></a></span><span>adds the <code>in:</code> line, naming the function, or the class and the method, that contains each finding.</span></li>
<li><span class="ref"><a class="plain" href="docs/flags/dataflow-traces.html"><code>--dataflow-traces</code></a></span><span>draws the path of the data under each taint finding, from the source to the sink. A call the data goes through opens into the steps inside the function, from the parameter it enters by (<code>param</code>) to the <code>return</code> it leaves by.</span></li>
</ul>
</section>
</main>
<script src="main.js"></script>
</body>
</html>