Skip to content

Commit 3a60f1e

Browse files
committed
fix(command-injection): judge process commands by what the input controls
Every tainted argument of subprocess calls was a high command injection, whether or not a shell runs it. The rule now reads the command a flow reaches: a shell string, a string naming the program or the program itself stays high; an element of an argument list run without a shell is an option, medium unless a documented option of the program runs a command it chooses; a constant prefix that keeps the input from being an option, or an operand after -- for a program that honours it, is refuted; a value after an option the model does not describe stays a hotspot to review. TaintDetector gains an assess hook returning the verdict and the severity, since a hotspot verdict only lowers the confidence. List and tuple displays keep the place of their unpacked elements in the IR, so that the order of a command survives *(...) parts. Closes #208
1 parent 41fdf30 commit 3a60f1e

11 files changed

Lines changed: 565 additions & 11 deletions

File tree

‎docs/plugins.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,14 @@ judges by its own criteria. The refutation's
127127
verdict, which other consumers of the flow such as the advisory correlation read, does
128128
not change; a rule reading more analyses declares them in its `requires`.
129129

130+
A rule that tells cases of its sinks apart by severity too overrides `assess(ctx,
131+
function, flow, verdict)`, which returns an `Assessment` of the verdict and the
132+
severity; by default it pairs `judge`'s verdict with the rule's `severity`. A `hotspot`
133+
verdict lowers the confidence of the finding, never its severity. `command-injection`
134+
reads there the command a flow reaches (`coretrace_python.taint.commands`): a shell
135+
string or the program is `high`; an element of an argument list run without a shell is
136+
an option, `medium` unless a documented option of the program runs a command it chooses.
137+
130138
### Security models: `ModelPlugin`
131139

132140
Declares sources, sinks and sanitizers for a library or a framework. A model plugin

‎docs/usage.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@ variable is not treated that way yet.
115115

116116
| Rule | Reached sink |
117117
|---|---|
118-
| `command-injection` | Shell or process execution (`os.system`, `subprocess` with a string, …). |
118+
| `command-injection` | Shell or process execution (`os.system`, `subprocess` with a string, …), judged on what the input controls in the command. A string a shell runs, a string naming the program or the program itself is `high`. An element of an argument list run without a shell can only be read as an option: `medium`, or `high` when a documented option of the program runs a command it chooses (`git push --receive-pack=…`, `ssh -o ProxyCommand=…`, `sh -c`). A constant prefix that keeps the input from being an option (`f"v{version}"`), or an operand after `--` for a program that honours it, is refuted. A value after an option that may take one, where the program's options are not known, stays a hotspot to review. |
119119
| `code-injection` | The code `eval` or `exec` runs; the globals and locals passed with it are data. `dangerous-eval` reports every such call, this rule the ones attacker input reaches. |
120120
| `sql-injection` | A database statement (`cursor.execute`, SQLAlchemy `text`, Django `raw`, …). Parameters of a parameterised query are not statements. |
121121
| `nosql-injection` | A NoSQL query, such as a MongoDB filter, given attacker input that may hold a structure: a JSON body giving `{"$ne": null}` matches any value. The input that may hold a structure is JSON, the raw bodies a `json.loads` decodes, files, WebSocket messages and standard input. Text cannot hold an operator: form fields, query parameters, headers, cookies, URL parameters, the command line, the environment, and an entry-point parameter annotated with scalars (`str`, `int`, `Optional[str]`, `Annotated[str, Query()]`, `list[str]`, …), which FastAPI validates. A Django, REST framework, aiohttp or tornado view reads a request object: its text attributes (`GET`, `POST`, `headers`, `query_params`, `query`, `match_info`, `arguments`, …) and the URL parameters after it are text, its body, files and `data` are not. Limits: a helper function the request is passed to reads it as a whole; the keys of a dict are not followed, so a string concatenated into `$where` is not reported. The analyzer ships no NoSQL sink: model plugins declare them. |

‎src/coretrace_python/bundled/security/command_injection/command_injection.py‎

Lines changed: 354 additions & 3 deletions
Large diffs are not rendered by default.

‎src/coretrace_python/bundled/security/command_injection/plugin.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
name = "command-injection"
22
version = "1.0.0"
33
plugin_api = ">=1,<2"
4-
requires = ["taint.flows", "findings.refutation"]
4+
requires = ["taint.flows", "findings.refutation", "ir.ssa", "ir.defuse", "abstract.module_strings"]
55
provides = ["vulnerability.command-injection"]
66

77
[entrypoint]

‎src/coretrace_python/ir/lowering.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -189,7 +189,10 @@ def expression(self, node: nodes.Expression) -> Value:
189189
if isinstance(node, nodes.List | nodes.Tuple):
190190
elements, unpacked = self.spread(node.elements)
191191
builder = BuildList if isinstance(node, nodes.List) else BuildTuple
192-
return self.emit(builder(self.new_value(), node.span, elements, unpacked))
192+
at = tuple(
193+
i for i, element in enumerate(node.elements) if isinstance(element, nodes.Starred)
194+
)
195+
return self.emit(builder(self.new_value(), node.span, elements, unpacked, at))
193196
if isinstance(node, nodes.Dict):
194197
items = tuple((self.expression(k), self.expression(v)) for k, v in node.items if k is not None)
195198
unpacked = tuple(self.expression(v) for k, v in node.items if k is None)

‎src/coretrace_python/ir/model.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,18 +134,26 @@ class BoolOp(Operands):
134134

135135
@dataclass(frozen=True)
136136
class BuildList(Operands):
137+
"""``unpacked_at`` gives the place of each ``*iterable`` of ``unpacked`` among all the
138+
items of the display, so that the order of ``[1, *a, 2]`` is kept."""
139+
137140
result: Value
138141
location: SourceSpan
139142
elements: tuple[Value, ...]
140143
unpacked: tuple[Value, ...] = ()
144+
unpacked_at: tuple[int, ...] = ()
141145

142146

143147
@dataclass(frozen=True)
144148
class BuildTuple(Operands):
149+
"""``unpacked_at`` gives the place of each ``*iterable`` of ``unpacked`` among all the
150+
items of the display, so that the order of ``[1, *a, 2]`` is kept."""
151+
145152
result: Value
146153
location: SourceSpan
147154
elements: tuple[Value, ...]
148155
unpacked: tuple[Value, ...] = ()
156+
unpacked_at: tuple[int, ...] = ()
149157

150158

151159
@dataclass(frozen=True)

‎src/coretrace_python/plugins/__init__.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
apply_refinement,
1212
run_plugins,
1313
)
14-
from coretrace_python.plugins.detectors import SymbolCallDetector, TaintDetector
14+
from coretrace_python.plugins.detectors import Assessment, SymbolCallDetector, TaintDetector
1515
from coretrace_python.plugins.loader import (
1616
IncompatiblePluginError,
1717
LoadedPlugin,
@@ -35,6 +35,7 @@
3535

3636
__all__ = [
3737
"PLUGIN_API_VERSION",
38+
"Assessment",
3839
"Entrypoint",
3940
"IncompatiblePluginError",
4041
"LoadedPlugin",

‎src/coretrace_python/plugins/detectors.py‎

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
11
"""Reusable detector bases (architecture §15).
22
33
``TaintDetector`` turns the flows of one taint kind into findings; every security
4-
detector is a few class attributes on top of it. ``SymbolCallDetector`` reports calls
4+
detector is a few class attributes on top of it, and a rule that knows more about its
5+
sinks refines the verdict (``judge``) or the severity too (``assess``). ``SymbolCallDetector`` reports calls
56
whose callee resolves to a canonical symbol, through imports and local aliases alike,
67
by reading the SSA form.
78
"""
89

910
from __future__ import annotations
1011

1112
from collections.abc import Mapping, Sequence
13+
from dataclasses import dataclass
1214
from typing import ClassVar
1315

1416
from coretrace_python.analysis import AnyAnalysis
@@ -23,6 +25,14 @@
2325
from coretrace_python.taint import TaintAnalysis, TaintFlow, TaintKind
2426

2527

28+
@dataclass(frozen=True)
29+
class Assessment:
30+
"""A rule's verdict on one flow and the severity it reports the flow at."""
31+
32+
verdict: Verdict
33+
severity: Severity
34+
35+
2636
class TaintDetector(Plugin):
2737
"""Report every taint flow carrying ``kind`` into a sink."""
2838

@@ -43,7 +53,8 @@ def analyze(self, ctx: PluginContext) -> Sequence[Finding]:
4353
verdict = verdicts.verdict(flow)
4454
if verdict.status is Status.REFUTED:
4555
continue
46-
verdict = self.judge(ctx, function, flow, verdict)
56+
assessment = self.assess(ctx, function, flow, verdict)
57+
verdict = assessment.verdict
4758
if verdict.status is Status.REFUTED:
4859
continue
4960
message = f"{self.title}: {flow.source.label} input reaches {flow.sink.symbol}"
@@ -65,7 +76,7 @@ def analyze(self, ctx: PluginContext) -> Sequence[Finding]:
6576
Finding(
6677
rule_id=self.rule_id,
6778
message=message,
68-
severity=self.severity,
79+
severity=assessment.severity,
6980
confidence=confidence,
7081
span=flow.location,
7182
function=function.name,
@@ -81,6 +92,15 @@ def judge(self, ctx: PluginContext, function: nodes.Function, flow: TaintFlow, v
8192

8293
return verdict
8394

95+
def assess(
96+
self, ctx: PluginContext, function: nodes.Function, flow: TaintFlow, verdict: Verdict
97+
) -> Assessment:
98+
"""This rule's verdict on ``flow`` (``judge``'s) and its severity: the rule's own,
99+
unless the rule tells cases of its sinks apart. A ``hotspot`` verdict lowers the
100+
confidence of the finding, never its severity, which is set here."""
101+
102+
return Assessment(self.judge(ctx, function, flow, verdict), self.severity)
103+
84104

85105
def _lower(confidence: Confidence) -> Confidence:
86106
return {Confidence.HIGH: Confidence.MEDIUM}.get(confidence, Confidence.LOW)
Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
"""The command a process is started with, as a list or tuple display spells it: one
2+
reading that the rules about processes share. Each element keeps its place, unpacked
3+
literals included; an unpacked iterable of unknown contents stands for any number of
4+
elements, perhaps none. A display that anything else may change before the call (any
5+
other use of it) spells no command."""
6+
7+
from __future__ import annotations
8+
9+
from collections.abc import Mapping
10+
from dataclasses import dataclass
11+
12+
from coretrace_python.ir.defuse import DefUse
13+
from coretrace_python.ir.model import BuildList, BuildTuple, Instruction, Value
14+
15+
16+
@dataclass(frozen=True)
17+
class CommandPart:
18+
"""One element of a command, or, when ``known`` is false, an unpacked iterable of
19+
unknown contents standing for any number of elements."""
20+
21+
value: Value
22+
known: bool = True
23+
24+
25+
def command_parts(
26+
value: Value, defs: Mapping[Value, Instruction], uses: DefUse
27+
) -> tuple[CommandPart, ...] | None:
28+
"""The elements of the command ``value`` spells, in order, or None when it is not a
29+
list or tuple display used only there."""
30+
31+
made = defs.get(value)
32+
if not isinstance(made, BuildList | BuildTuple) or len(uses.uses(value)) != 1:
33+
return None
34+
if len(made.unpacked_at) != len(made.unpacked):
35+
return None
36+
plain, unpacked = iter(made.elements), iter(made.unpacked)
37+
parts: list[CommandPart] = []
38+
for index in range(len(made.elements) + len(made.unpacked)):
39+
if index not in made.unpacked_at:
40+
parts.append(CommandPart(next(plain)))
41+
continue
42+
iterable = next(unpacked)
43+
nested = command_parts(iterable, defs, uses)
44+
parts.extend(nested if nested is not None else (CommandPart(iterable, known=False),))
45+
return tuple(parts)

‎tests/test_command_arguments.py‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
"""Acceptance tests for issue #208: what the attacker controls in a process's command.
2+
3+
A string that a shell interprets, a string naming the program, or the program itself is
4+
a command injection, ``high``. An element of an argument list run without a shell
5+
cannot inject a command, only an option: ``medium`` by default when the executable is
6+
fixed, ``high`` when the option's dangerous behaviour is established by model data
7+
(``git push --receive-pack=<cmd>``, ``ssh -o ProxyCommand=...``, ``sh -c``). A constant
8+
prefix is judged by what the attacker still controls: ``f"v{x}"`` is no option at all,
9+
``f"--output={x}"`` is the value of a fixed option, ``f"--{x}"`` leaves the option open.
10+
A value after an option is that option's value only when the model establishes that the
11+
option consumes it, and a free element when the model establishes that the options before
12+
it take no value (``rm -rf``); otherwise the finding stays, for review. Severity is set per case:
13+
the ``hotspot`` verdict lowers the confidence, never the severity.
14+
"""
15+
16+
from __future__ import annotations
17+
18+
from pathlib import Path
19+
20+
import pytest
21+
22+
from coretrace_python import engine
23+
from coretrace_python.frontend import build_hir
24+
from coretrace_python.ir.lowering import lower_module
25+
from coretrace_python.ir.model import BuildList, BuildTuple
26+
from coretrace_python.source import SourceManager
27+
28+
PLUGINS = Path(__file__).resolve().parent.parent / "src" / "coretrace_python" / "bundled"
29+
30+
HIGH = ("high", "vulnerability", "high")
31+
MEDIUM = ("medium", "vulnerability", "high")
32+
HIGH_TO_REVIEW = ("high", "hotspot", "medium")
33+
MEDIUM_TO_REVIEW = ("medium", "hotspot", "medium")
34+
35+
36+
def judged(call: str) -> list[tuple[str, str, str]]:
37+
"""Severity, verdict and confidence of each command-injection finding on ``call``,
38+
made with ``x`` read from the command line and ``extra`` of unknown value."""
39+
40+
text = f"import os\nimport subprocess\nimport sys\n\n\ndef run(extra):\n x = sys.argv[1]\n {call}\n"
41+
findings = engine.check(SourceManager().add_source("app/run.py", text), [PLUGINS])
42+
return [
43+
(f.severity.value, f.metadata["verdict"], f.confidence.value)
44+
for f in findings
45+
if f.rule_id == "command-injection"
46+
]
47+
48+
49+
@pytest.mark.parametrize(
50+
("call", "expected"),
51+
[
52+
# 1, 2, 3, 8: the attacker reaches a shell or chooses the program.
53+
('subprocess.run(f"git tag {x}", shell=True)', HIGH),
54+
('os.system("ls " + x)', HIGH),
55+
("subprocess.run(x)", HIGH),
56+
('subprocess.run([x, "-l"])', HIGH),
57+
('subprocess.run(["ls"], executable=x)', HIGH),
58+
("subprocess.run(x, shell=extra)", HIGH_TO_REVIEW),
59+
# 4: a free element is an option the attacker chooses.
60+
('subprocess.run(["ls", x])', MEDIUM),
61+
('subprocess.run(["git", "status", x])', MEDIUM),
62+
('subprocess.run(["git", "push", "origin", x])', HIGH),
63+
('subprocess.run(["/usr/bin/git", "push", "origin", x])', HIGH),
64+
# 5, 5b, 5c: a constant prefix.
65+
('subprocess.run(["git", "tag", f"v{x}"])', None),
66+
('subprocess.run(["git", "commit", "-m", f"release {x}"])', None),
67+
('subprocess.run(["curl", f"--output={x}"])', MEDIUM),
68+
('subprocess.run(["git", "fetch", f"--upload-pack={x}"])', HIGH),
69+
('subprocess.run(["ssh", f"-o{x}", "host"])', HIGH),
70+
('subprocess.run(["ls", f"--{x}"])', MEDIUM),
71+
# 6: after the end of options, for a program known to honour it.
72+
('subprocess.run(["git", "log", "--", x])', None),
73+
('subprocess.run(["ls", "--", x])', MEDIUM),
74+
# 7: after an option that may take a value.
75+
('subprocess.run(["ssh", "-o", x, "host"])', HIGH),
76+
('subprocess.run(["sh", "-c", x])', HIGH),
77+
('subprocess.run(["find", ".", "-exec", x, ";"])', HIGH),
78+
('subprocess.run(["xcrun", "notarytool", "--keychain", x])', MEDIUM_TO_REVIEW),
79+
('subprocess.run(["git", "push", "--force", x])', HIGH_TO_REVIEW),
80+
# Short options grouped in one element, read as getopt does.
81+
('subprocess.run(["rm", "-rf", x])', MEDIUM),
82+
('subprocess.run(["rm", "-r", "-f", x])', MEDIUM),
83+
('subprocess.run(["rm", "-rz", x])', MEDIUM_TO_REVIEW),
84+
('subprocess.run(["ssh", "-vo", x, "host"])', HIGH),
85+
('subprocess.run(["ssh", "-ov", x, "host"])', HIGH),
86+
# Unpacked parts keep their place in the command.
87+
('subprocess.run(["xcrun", "notarytool", *(["--keychain", x])])', MEDIUM_TO_REVIEW),
88+
("subprocess.run([*extra, x])", HIGH),
89+
('subprocess.run(["ls", *extra, x])', MEDIUM),
90+
('subprocess.run(["ls", *x.split()])', MEDIUM),
91+
],
92+
)
93+
def test_the_result_follows_what_the_attacker_controls(
94+
call: str, expected: tuple[str, str, str] | None
95+
) -> None:
96+
assert judged(call) == ([] if expected is None else [expected])
97+
98+
99+
def test_an_unpacked_element_keeps_its_place_in_a_list_or_tuple_display() -> None:
100+
module = lower_module(
101+
build_hir(
102+
SourceManager().add_source("m.py", "def f(a, b):\n use([1, *a, 2, *b], (*a, 1))\n")
103+
)
104+
)
105+
instructions = [i for block in module.functions[0].blocks for i in block.instructions]
106+
(built_list,) = [i for i in instructions if isinstance(i, BuildList)]
107+
(built_tuple,) = [i for i in instructions if isinstance(i, BuildTuple)]
108+
109+
assert built_list.unpacked_at == (1, 3)
110+
assert built_tuple.unpacked_at == (0,)

0 commit comments

Comments
 (0)