Skip to content

Commit f55de81

Browse files
authored
Merge pull request #31 from CoreTrace/feat/frameworks
feat: framework models for Flask, FastAPI and SQLAlchemy
2 parents 45c7f7d + a939116 commit f55de81

15 files changed

Lines changed: 601 additions & 39 deletions

File tree

‎README.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,10 +32,12 @@ coretrace-python-analyzer --check app.py --plugins plugins/ --format sarif > rep
3232
```
3333

3434
`--plugins` is a directory searched recursively for `plugin.toml` manifests and may be
35-
repeated. The repository ships a first set under `plugins/`: standard-library security
36-
models (`models/python_stdlib`), taint detectors for SQL injection, command injection,
37-
path traversal, SSRF and XSS (`security/`), and syntactic detectors for `eval`/`exec`
38-
and weak hashes (`syntax/`). Model plugins contribute sources, sinks and sanitizers;
35+
repeated. The repository ships a first set under `plugins/`: security models for the
36+
standard library, Flask, FastAPI and SQLAlchemy (`models/`), taint detectors for SQL
37+
injection, command injection, path traversal, SSRF and XSS (`security/`), and syntactic
38+
detectors for `eval`/`exec` and weak hashes (`syntax/`). Route handlers of Flask and
39+
FastAPI receive their parameters as HTTP input; `request.args` and its siblings are HTTP
40+
sources. Model plugins contribute sources, sinks and sanitizers;
3941
detectors consume the shared taint result, so adding a framework model makes every
4042
detector aware of it. Taint follows calls between functions of the same module through
4143
function summaries: a tainted argument passed to a helper that reaches a sink is reported
@@ -64,6 +66,9 @@ instructions and unassigned paths read an explicit `undefined` value.
6466
Unsupported syntax produces a source-located diagnostic and a non-zero exit status.
6567

6668
Names are resolved to canonical symbols through lexical scopes, imports and builtins.
69+
Calling a symbol denotes that symbol, so `app = Flask(__name__)` makes `app.route` resolve
70+
to `python.flask.Flask.route` and `sqlite3.connect(p).cursor().execute` resolves to
71+
`python.sqlite3.connect.cursor.execute`; model plugins register those chains.
6772
Import aliases do not change an API's identity, so all of the following resolve to
6873
`python.os.system`:
6974

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
"""FastAPI security models: route handlers and response sinks."""
2+
3+
from __future__ import annotations
4+
5+
from typing import ClassVar
6+
7+
from coretrace_python.plugins import ModelPlugin
8+
from coretrace_python.semantic.symbols import SymbolId
9+
from coretrace_python.taint import EntryPoint, Model, Sink, TaintKind
10+
11+
_METHODS = ("get", "post", "put", "delete", "patch", "options", "head", "api_route", "websocket")
12+
13+
14+
def _sym(path: str) -> SymbolId:
15+
return SymbolId(f"python.{path}")
16+
17+
18+
class FastApiModels(ModelPlugin):
19+
name: ClassVar[str] = "fastapi-models"
20+
models: ClassVar[tuple[Model, ...]] = (
21+
*(EntryPoint(_sym(f"fastapi.FastAPI.{method}"), "http") for method in _METHODS),
22+
*(EntryPoint(_sym(f"fastapi.APIRouter.{method}"), "http") for method in _METHODS),
23+
Sink(_sym("fastapi.responses.HTMLResponse"), TaintKind.HTML),
24+
Sink(_sym("fastapi.responses.FileResponse"), TaintKind.PATH),
25+
)

‎plugins/models/fastapi/plugin.toml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
name = "fastapi-models"
2+
version = "1.0.0"
3+
plugin_api = ">=1,<2"
4+
requires = []
5+
provides = ["model.http-sources", "model.fastapi-routes"]
6+
7+
[entrypoint]
8+
module = "fastapi_models"
9+
class = "FastApiModels"
Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
"""Flask security models: HTTP sources, route handlers, HTML sinks and escaping."""
2+
3+
from __future__ import annotations
4+
5+
from typing import ClassVar
6+
7+
from coretrace_python.plugins import ModelPlugin
8+
from coretrace_python.semantic.symbols import SymbolId
9+
from coretrace_python.taint import EntryPoint, Model, Sanitizer, Sink, Source, TaintKind
10+
11+
_REQUEST_ATTRIBUTES = (
12+
"args", "form", "values", "json", "data", "cookies", "headers", "files",
13+
"get_json", "get_data", "url", "full_path", "path", "query_string", "stream",
14+
)
15+
16+
17+
def _sym(path: str) -> SymbolId:
18+
return SymbolId(f"python.{path}")
19+
20+
21+
class FlaskModels(ModelPlugin):
22+
name: ClassVar[str] = "flask-models"
23+
models: ClassVar[tuple[Model, ...]] = (
24+
*(Source(_sym(f"flask.request.{attribute}"), "http") for attribute in _REQUEST_ATTRIBUTES),
25+
EntryPoint(_sym("flask.Flask.route"), "http"),
26+
EntryPoint(_sym("flask.Blueprint.route"), "http"),
27+
Sink(_sym("flask.render_template_string"), TaintKind.HTML),
28+
Sink(_sym("flask.make_response"), TaintKind.HTML),
29+
Sink(_sym("flask.Response"), TaintKind.HTML),
30+
Sink(_sym("flask.Markup"), TaintKind.HTML),
31+
Sink(_sym("flask.send_file"), TaintKind.PATH),
32+
Sanitizer(_sym("flask.escape"), TaintKind.HTML),
33+
Sanitizer(_sym("markupsafe.escape"), TaintKind.HTML),
34+
)

‎plugins/models/flask/plugin.toml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
name = "flask-models"
2+
version = "1.0.0"
3+
plugin_api = ">=1,<2"
4+
requires = []
5+
provides = ["model.http-sources", "model.flask-routes"]
6+
7+
[entrypoint]
8+
module = "flask_models"
9+
class = "FlaskModels"

‎plugins/models/python_stdlib/python_stdlib.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,11 @@ class PythonStdlibModels(ModelPlugin):
3535
Sink(_sym("os.rmdir"), TaintKind.PATH),
3636
Sink(_sym("shutil.rmtree"), TaintKind.PATH),
3737
Sink(_sym("urllib.request.urlopen"), TaintKind.SSRF),
38+
*(
39+
Sink(_sym(f"sqlite3.connect{cursor}.{method}"), TaintKind.SQL)
40+
for cursor in ("", ".cursor")
41+
for method in ("execute", "executemany", "executescript")
42+
),
3843
Sanitizer(_sym("shlex.quote"), TaintKind.COMMAND),
3944
Sanitizer(_sym("html.escape"), TaintKind.HTML),
4045
Sanitizer(_sym("os.path.basename"), TaintKind.PATH),
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
name = "sqlalchemy-models"
2+
version = "1.0.0"
3+
plugin_api = ">=1,<2"
4+
requires = []
5+
provides = ["model.sql-sinks"]
6+
7+
[entrypoint]
8+
module = "sqlalchemy_models"
9+
class = "SqlAlchemyModels"
Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
"""SQLAlchemy security models: raw SQL execution sinks.
2+
3+
Symbols follow the engine's call-chain rule: the result of calling a symbol denotes
4+
that symbol, so ``create_engine(url).connect().execute`` is
5+
``python.sqlalchemy.create_engine.connect.execute``.
6+
"""
7+
8+
from __future__ import annotations
9+
10+
from typing import ClassVar
11+
12+
from coretrace_python.plugins import ModelPlugin
13+
from coretrace_python.semantic.symbols import SymbolId
14+
from coretrace_python.taint import Model, Sink, TaintKind
15+
16+
_EXECUTORS = (
17+
"sqlalchemy.create_engine",
18+
"sqlalchemy.create_engine.connect",
19+
"sqlalchemy.create_engine.begin",
20+
"sqlalchemy.engine.create_engine",
21+
"sqlalchemy.engine.create_engine.connect",
22+
"sqlalchemy.orm.Session",
23+
"sqlalchemy.orm.sessionmaker",
24+
"sqlalchemy.orm.scoped_session",
25+
)
26+
27+
28+
def _sym(path: str) -> SymbolId:
29+
return SymbolId(f"python.{path}")
30+
31+
32+
class SqlAlchemyModels(ModelPlugin):
33+
name: ClassVar[str] = "sqlalchemy-models"
34+
models: ClassVar[tuple[Model, ...]] = tuple(
35+
Sink(_sym(f"{executor}.{method}"), TaintKind.SQL)
36+
for executor in _EXECUTORS
37+
for method in ("execute", "exec_driver_sql", "scalar", "scalars")
38+
)

‎src/coretrace_python/interprocedural/callgraph.py‎

Lines changed: 48 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
from coretrace_python.cfg import CFGError
1818
from coretrace_python.hir import nodes
1919
from coretrace_python.ir.lowering import LoweringError, analyzable_functions, qualified_name
20-
from coretrace_python.ir.model import Call, FunctionIR, Global, Symbol, Value
20+
from coretrace_python.ir.model import Call, FunctionIR, GetAttr, Global, Symbol, Value, WithEnter
2121
from coretrace_python.ir.ssa import SSAAnalysis
2222
from coretrace_python.semantic.scopes import BindingKind, ScopeAnalysis, ScopeTable
2323
from coretrace_python.semantic.symbols import SymbolId
@@ -57,7 +57,9 @@ def __init__(
5757
definitions: Mapping[str, nodes.Function],
5858
sites: Mapping[str, tuple[CallSite, ...]],
5959
unsupported: frozenset[str],
60+
symbols: Mapping[str, Mapping[Value, SymbolId]] | None = None,
6061
) -> None:
62+
self._symbols = {name: MappingProxyType(dict(found)) for name, found in (symbols or {}).items()}
6163
self.definitions: Mapping[str, nodes.Function] = MappingProxyType(dict(definitions))
6264
self.functions = tuple(definitions)
6365
self._names = {function.span: name for name, function in definitions.items()}
@@ -76,6 +78,11 @@ def __init__(
7678
def name_of(self, function: nodes.Function) -> str:
7779
return self._names[function.span]
7880

81+
def symbols(self, name: str) -> Mapping[Value, SymbolId]:
82+
"""Values of ``name`` that denote a symbol, including derived call-chain symbols."""
83+
84+
return self._symbols.get(name, MappingProxyType({}))
85+
7986
def sites(self, caller: str) -> tuple[CallSite, ...]:
8087
return self._sites.get(caller, ())
8188

@@ -91,26 +98,56 @@ def callers(self, name: str) -> frozenset[str]:
9198
return self._callers.get(name, frozenset())
9299

93100

101+
def derive_symbols(function: FunctionIR) -> dict[Value, SymbolId]:
102+
"""Symbols of values: ``Symbol`` results, attributes of symbol values, results of
103+
calling a symbol (``sqlite3.connect(p)`` denotes ``python.sqlite3.connect``) and the
104+
values a ``with`` on such a result binds. Known functions and parameters derive nothing."""
105+
106+
symbols: dict[Value, SymbolId] = {}
107+
changed = True
108+
while changed:
109+
changed = False
110+
for block in function.blocks:
111+
for instruction in block.instructions:
112+
if instruction.result is None or instruction.result in symbols:
113+
continue
114+
symbol: SymbolId | None = None
115+
if isinstance(instruction, Symbol):
116+
symbol = instruction.symbol_id
117+
elif isinstance(instruction, GetAttr) and instruction.object in symbols:
118+
symbol = symbols[instruction.object].attribute(instruction.attribute)
119+
elif isinstance(instruction, Call | WithEnter):
120+
origin = (
121+
instruction.callee if isinstance(instruction, Call) else instruction.context
122+
)
123+
symbol = symbols.get(origin)
124+
if symbol is not None:
125+
symbols[instruction.result] = symbol
126+
changed = True
127+
return symbols
128+
129+
94130
def resolve_targets(
95131
function: FunctionIR, scopes: ScopeTable, known: frozenset[str]
96-
) -> dict[Value, Target]:
97-
"""Map every callee value of ``function`` to its target."""
132+
) -> tuple[dict[Value, Target], dict[Value, SymbolId]]:
133+
"""Map every callee value of ``function`` to its target, and every symbol value."""
98134

99135
module = scopes.module_scope
100-
targets: dict[Value, Target] = {}
136+
symbols = derive_symbols(function)
137+
targets: dict[Value, Target] = {
138+
value: ExternalSymbol(symbol) for value, symbol in symbols.items()
139+
}
101140
for block in function.blocks:
102141
for instruction in block.instructions:
103-
if isinstance(instruction, Symbol):
104-
targets[instruction.result] = ExternalSymbol(instruction.symbol_id)
105-
elif isinstance(instruction, Global):
142+
if isinstance(instruction, Global):
106143
binding = module.bindings.get(instruction.name)
107144
if (
108145
binding is not None
109146
and binding.kind is BindingKind.FUNCTION
110147
and instruction.name in known
111148
):
112149
targets[instruction.result] = KnownFunction(instruction.name)
113-
return targets
150+
return targets, symbols
114151

115152

116153
class CallGraphAnalysis(Analysis[CallGraph]):
@@ -128,6 +165,7 @@ def compute(cls, ctx: AnalysisContext) -> CallGraph:
128165
name for name, function in definitions.items() if function in ctx.module.body
129166
)
130167
sites: dict[str, tuple[CallSite, ...]] = {}
168+
symbols: dict[str, Mapping[Value, SymbolId]] = {}
131169
unsupported: set[str] = set()
132170
for name, function in definitions.items():
133171
try:
@@ -136,7 +174,7 @@ def compute(cls, ctx: AnalysisContext) -> CallGraph:
136174
unsupported.add(name)
137175
sites[name] = ()
138176
continue
139-
targets = resolve_targets(ssa, scopes, known)
177+
targets, symbols[name] = resolve_targets(ssa, scopes, known)
140178
found: list[CallSite] = []
141179
for block in ssa.blocks:
142180
for instruction in block.instructions:
@@ -151,4 +189,4 @@ def compute(cls, ctx: AnalysisContext) -> CallGraph:
151189
)
152190
)
153191
sites[name] = tuple(found)
154-
return CallGraph(definitions, sites, frozenset(unsupported))
192+
return CallGraph(definitions, sites, frozenset(unsupported), symbols)

‎src/coretrace_python/semantic/symbols.py‎

Lines changed: 49 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,12 @@
33
from __future__ import annotations
44

55
import builtins
6+
from collections.abc import Mapping
7+
from types import MappingProxyType
68
from typing import ClassVar
79

810
from coretrace_python.analysis import Analysis, AnalysisContext, AnyAnalysis
11+
from coretrace_python.hir import nodes
912
from coretrace_python.semantic.identity import SymbolId
1013
from coretrace_python.semantic.imports import ImportAnalysis, ImportTable
1114
from coretrace_python.semantic.scopes import ResolutionKind, ScopeAnalysis, ScopeId, ScopeTable
@@ -14,22 +17,62 @@
1417

1518

1619
class SymbolTable:
17-
"""Resolve names to canonical symbols through scopes, imports and builtins."""
20+
"""Resolve names to canonical symbols through scopes, imports, builtins and the
21+
module-level instances created by calling a symbol (``app = Flask(__name__)``)."""
1822

19-
def __init__(self, scopes: ScopeTable, imports: ImportTable) -> None:
23+
def __init__(
24+
self,
25+
scopes: ScopeTable,
26+
imports: ImportTable,
27+
instances: Mapping[str, SymbolId] | None = None,
28+
) -> None:
2029
self._scopes = scopes
2130
self._imports = imports
31+
self._instances = MappingProxyType(dict(instances or {}))
2232

2333
def resolve(self, scope_id: ScopeId, name: str) -> SymbolId | None:
2434
resolution = self._scopes.resolve(scope_id, name)
2535
if resolution.kind is ResolutionKind.UNBOUND:
2636
return SymbolId(f"python.builtins.{name}") if name in BUILTIN_NAMES else None
2737
assert resolution.scope is not None
28-
return self._imports.bindings(resolution.scope).get(name)
38+
imported = self._imports.bindings(resolution.scope).get(name)
39+
if imported is not None:
40+
return imported
41+
if resolution.scope == self._scopes.module_scope.id:
42+
return self._instances.get(name)
43+
return None
2944

45+
def resolve_expression(self, scope_id: ScopeId, node: nodes.Expression) -> SymbolId | None:
46+
"""The symbol of a name or attribute chain, or of the callee of a call."""
3047

31-
def analyze_symbols(scopes: ScopeTable, imports: ImportTable) -> SymbolTable:
32-
return SymbolTable(scopes, imports)
48+
if isinstance(node, nodes.Name):
49+
return self.resolve(scope_id, node.identifier)
50+
if isinstance(node, nodes.Attribute):
51+
parent = self.resolve_expression(scope_id, node.value)
52+
return parent.attribute(node.name) if parent is not None else None
53+
if isinstance(node, nodes.Call):
54+
return self.resolve_expression(scope_id, node.callee)
55+
return None
56+
57+
58+
def analyze_symbols(
59+
scopes: ScopeTable, imports: ImportTable, module: nodes.Module | None = None
60+
) -> SymbolTable:
61+
table = SymbolTable(scopes, imports)
62+
if module is None:
63+
return table
64+
instances: dict[str, SymbolId] = {}
65+
module_scope = scopes.module_scope.id
66+
for statement in module.body:
67+
if (
68+
isinstance(statement, nodes.Assign)
69+
and isinstance(statement.target, nodes.Name)
70+
and isinstance(statement.value, nodes.Call)
71+
):
72+
symbol = table.resolve_expression(module_scope, statement.value.callee)
73+
if symbol is not None:
74+
instances[statement.target.identifier] = symbol
75+
return SymbolTable(scopes, imports, instances)
3376

3477

3578
class SymbolAnalysis(Analysis[SymbolTable]):
@@ -38,7 +81,7 @@ class SymbolAnalysis(Analysis[SymbolTable]):
3881

3982
@classmethod
4083
def compute(cls, ctx: AnalysisContext) -> SymbolTable:
41-
return analyze_symbols(ctx.get(ScopeAnalysis), ctx.get(ImportAnalysis))
84+
return analyze_symbols(ctx.get(ScopeAnalysis), ctx.get(ImportAnalysis), ctx.module)
4285

4386

4487
__all__ = ["BUILTIN_NAMES", "SymbolAnalysis", "SymbolId", "SymbolTable", "analyze_symbols"]

0 commit comments

Comments
 (0)