coretrace-python-analyzer 0.22.0__py3-none-any.whl → 0.24.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. coretrace_python/__init__.py +1 -1
  2. coretrace_python/abstract/module_constants.py +121 -0
  3. coretrace_python/abstract/strings.py +12 -42
  4. coretrace_python/bundled/dependency/dependency_policy/dependency_policy.py +12 -2
  5. coretrace_python/bundled/dependency/reachable_vulnerability/reachable_vulnerability.py +8 -2
  6. coretrace_python/bundled/dependency/vulnerable_dependency/vulnerable_dependency.py +8 -2
  7. coretrace_python/bundled/models/python_stdlib/python_stdlib.py +27 -0
  8. coretrace_python/bundled/secrets/config_secrets/config_secrets.py +2 -1
  9. coretrace_python/bundled/security/code_injection/code_injection.py +93 -5
  10. coretrace_python/bundled/security/code_injection/plugin.toml +1 -1
  11. coretrace_python/bundled/security/command_injection/command_injection.py +7 -1
  12. coretrace_python/bundled/security/insecure_deserialization/insecure_deserialization.py +8 -1
  13. coretrace_python/bundled/security/nosql_injection/nosql_injection.py +8 -1
  14. coretrace_python/bundled/security/open_redirect/open_redirect.py +8 -1
  15. coretrace_python/bundled/security/path_traversal/path_traversal.py +8 -1
  16. coretrace_python/bundled/security/plaintext_credentials/plaintext_credentials.py +8 -1
  17. coretrace_python/bundled/security/sql_injection/sql_injection.py +8 -1
  18. coretrace_python/bundled/security/ssrf/ssrf.py +8 -1
  19. coretrace_python/bundled/security/xss/xss.py +8 -1
  20. coretrace_python/bundled/syntax/dangerous_eval/dangerous_eval.py +8 -1
  21. coretrace_python/bundled/syntax/flask_debug/flask_debug.py +8 -2
  22. coretrace_python/bundled/syntax/insecure_tempfile/insecure_tempfile.py +8 -1
  23. coretrace_python/bundled/syntax/insecure_tls/insecure_tls.py +7 -1
  24. coretrace_python/bundled/syntax/missing_timeout/missing_timeout.py +8 -2
  25. coretrace_python/bundled/syntax/unsafe_archive/unsafe_archive.py +7 -1
  26. coretrace_python/bundled/syntax/unsafe_xml/plugin.toml +1 -1
  27. coretrace_python/bundled/syntax/unsafe_xml/unsafe_xml.py +98 -12
  28. coretrace_python/bundled/syntax/weak_crypto/weak_crypto.py +8 -1
  29. coretrace_python/bundled/syntax/weak_random/weak_random.py +8 -2
  30. coretrace_python/cache.py +21 -15
  31. coretrace_python/cli.py +36 -6
  32. coretrace_python/engine.py +384 -121
  33. coretrace_python/findings/__init__.py +10 -1
  34. coretrace_python/findings/context.py +57 -0
  35. coretrace_python/findings/model.py +11 -1
  36. coretrace_python/findings/refutation.py +210 -27
  37. coretrace_python/findings/rules.py +16 -0
  38. coretrace_python/frontend/parser.py +7 -1
  39. coretrace_python/interprocedural/__init__.py +4 -0
  40. coretrace_python/interprocedural/callgraph.py +14 -1
  41. coretrace_python/interprocedural/modulegraph.py +54 -28
  42. coretrace_python/interprocedural/summaries.py +140 -32
  43. coretrace_python/ir/defuse.py +26 -1
  44. coretrace_python/ir/lowering.py +2 -1
  45. coretrace_python/ir/model.py +5 -2
  46. coretrace_python/ir/printer.py +4 -1
  47. coretrace_python/plugins/__init__.py +7 -1
  48. coretrace_python/plugins/api.py +21 -4
  49. coretrace_python/plugins/detectors.py +27 -4
  50. coretrace_python/plugins/secrets.py +33 -13
  51. coretrace_python/reporters/report.py +6 -2
  52. coretrace_python/reporters/sarif.py +69 -14
  53. coretrace_python/semantic/scopes.py +42 -1
  54. coretrace_python/semantic/symbols.py +2 -1
  55. coretrace_python/source/__init__.py +9 -1
  56. coretrace_python/source/manager.py +53 -7
  57. coretrace_python/source/model.py +12 -1
  58. coretrace_python/taint/__init__.py +2 -0
  59. coretrace_python/taint/engine.py +114 -27
  60. coretrace_python/taint/models.py +27 -3
  61. coretrace_python/taint/templates.py +686 -77
  62. {coretrace_python_analyzer-0.22.0.dist-info → coretrace_python_analyzer-0.24.0.dist-info}/METADATA +1 -1
  63. {coretrace_python_analyzer-0.22.0.dist-info → coretrace_python_analyzer-0.24.0.dist-info}/RECORD +67 -64
  64. {coretrace_python_analyzer-0.22.0.dist-info → coretrace_python_analyzer-0.24.0.dist-info}/WHEEL +0 -0
  65. {coretrace_python_analyzer-0.22.0.dist-info → coretrace_python_analyzer-0.24.0.dist-info}/entry_points.txt +0 -0
  66. {coretrace_python_analyzer-0.22.0.dist-info → coretrace_python_analyzer-0.24.0.dist-info}/licenses/LICENSE +0 -0
  67. {coretrace_python_analyzer-0.22.0.dist-info → coretrace_python_analyzer-0.24.0.dist-info}/licenses/NOTICE +0 -0
@@ -10,11 +10,12 @@ a base of unknown value or a URL built in a helper function, stays a vulnerabili
10
10
 
11
11
  from __future__ import annotations
12
12
 
13
+ from collections.abc import Mapping
13
14
  from typing import ClassVar
14
15
 
15
16
  from coretrace_python.abstract.strings import ModuleStringsAnalysis
16
17
  from coretrace_python.analysis import AnyAnalysis
17
- from coretrace_python.findings import Severity
18
+ from coretrace_python.findings import RuleDescription, Severity
18
19
  from coretrace_python.findings.refutation import Status, Verdict
19
20
  from coretrace_python.hir import nodes
20
21
  from coretrace_python.ir.ssa import SSAAnalysis
@@ -25,6 +26,12 @@ from coretrace_python.taint.urls import flow_url, redirects_disabled
25
26
 
26
27
  class SsrfPlugin(TaintDetector):
27
28
  name: ClassVar[str] = "ssrf"
29
+ rules: ClassVar[Mapping[str, RuleDescription]] = {
30
+ "ssrf": RuleDescription(
31
+ "Server-side request forgery",
32
+ "Attacker-controlled data reaches the destination of an HTTP client request (Requests, httpx, urllib).",
33
+ ),
34
+ }
28
35
  rule_id: ClassVar[str] = "ssrf"
29
36
  kind: ClassVar[TaintKind] = TaintKind.SSRF
30
37
  severity: ClassVar[Severity] = Severity.HIGH
@@ -2,15 +2,22 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ from collections.abc import Mapping
5
6
  from typing import ClassVar
6
7
 
7
- from coretrace_python.findings import Severity
8
+ from coretrace_python.findings import RuleDescription, Severity
8
9
  from coretrace_python.plugins import TaintDetector
9
10
  from coretrace_python.taint import TaintKind
10
11
 
11
12
 
12
13
  class XssPlugin(TaintDetector):
13
14
  name: ClassVar[str] = "xss"
15
+ rules: ClassVar[Mapping[str, RuleDescription]] = {
16
+ "xss": RuleDescription(
17
+ "Cross-site scripting",
18
+ "Attacker-controlled data reaches an HTTP response body built without escaping.",
19
+ ),
20
+ }
14
21
  rule_id: ClassVar[str] = "xss"
15
22
  kind: ClassVar[TaintKind] = TaintKind.HTML
16
23
  severity: ClassVar[Severity] = Severity.HIGH
@@ -2,15 +2,22 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ from collections.abc import Mapping
5
6
  from typing import ClassVar
6
7
 
7
- from coretrace_python.findings import Severity
8
+ from coretrace_python.findings import RuleDescription, Severity
8
9
  from coretrace_python.plugins import SymbolCallDetector
9
10
  from coretrace_python.semantic.symbols import SymbolId
10
11
 
11
12
 
12
13
  class DangerousEvalPlugin(SymbolCallDetector):
13
14
  name: ClassVar[str] = "dangerous-eval"
15
+ rules: ClassVar[Mapping[str, RuleDescription]] = {
16
+ "dangerous-eval": RuleDescription(
17
+ "Dynamic code execution",
18
+ "A call to eval or exec, whatever name the file gives them.",
19
+ ),
20
+ }
14
21
  rule_id: ClassVar[str] = "dangerous-eval"
15
22
  symbols: ClassVar[frozenset[SymbolId]] = frozenset(
16
23
  {SymbolId("python.builtins.eval"), SymbolId("python.builtins.exec")}
@@ -2,11 +2,11 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- from collections.abc import Iterator, Sequence
5
+ from collections.abc import Iterator, Mapping, Sequence
6
6
  from typing import ClassVar
7
7
 
8
8
  from coretrace_python.analysis import AnyAnalysis
9
- from coretrace_python.findings import Confidence, Finding, Severity
9
+ from coretrace_python.findings import Confidence, Finding, RuleDescription, Severity
10
10
  from coretrace_python.hir import nodes
11
11
  from coretrace_python.hir.visitors import Node, children
12
12
  from coretrace_python.plugins import Plugin, PluginContext
@@ -18,6 +18,12 @@ RUN = SymbolId("python.flask.Flask.run")
18
18
 
19
19
  class FlaskDebugPlugin(Plugin):
20
20
  name: ClassVar[str] = "flask-debug"
21
+ rules: ClassVar[Mapping[str, RuleDescription]] = {
22
+ "debug-enabled": RuleDescription(
23
+ "Debug mode enabled",
24
+ "A Flask application run with debug=True, which exposes an interactive debugger.",
25
+ ),
26
+ }
21
27
  requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({ScopeAnalysis, SymbolAnalysis})
22
28
 
23
29
  def analyze(self, ctx: PluginContext) -> Sequence[Finding]:
@@ -3,10 +3,11 @@ create it first. ``mkstemp``, ``NamedTemporaryFile`` and ``TemporaryDirectory``
3
3
 
4
4
  from __future__ import annotations
5
5
 
6
+ from collections.abc import Mapping
6
7
  from typing import ClassVar
7
8
 
8
9
  from coretrace_python.analysis import AnyAnalysis
9
- from coretrace_python.findings import Severity
10
+ from coretrace_python.findings import RuleDescription, Severity
10
11
  from coretrace_python.interprocedural import CallGraphAnalysis
11
12
  from coretrace_python.ir.ssa import SSAAnalysis
12
13
  from coretrace_python.plugins import SymbolCallDetector
@@ -15,6 +16,12 @@ from coretrace_python.semantic.symbols import SymbolId
15
16
 
16
17
  class InsecureTempFilePlugin(SymbolCallDetector):
17
18
  name: ClassVar[str] = "insecure-temp-file"
19
+ rules: ClassVar[Mapping[str, RuleDescription]] = {
20
+ "insecure-temp-file": RuleDescription(
21
+ "Insecure temporary file",
22
+ "tempfile.mktemp, which names a file without creating it, so that another process can create it first.",
23
+ ),
24
+ }
18
25
  rule_id: ClassVar[str] = "insecure-temp-file"
19
26
  requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({SSAAnalysis, CallGraphAnalysis})
20
27
  symbols: ClassVar[frozenset[SymbolId]] = frozenset({SymbolId("python.tempfile.mktemp")})
@@ -7,7 +7,7 @@ from collections.abc import Mapping
7
7
  from typing import ClassVar
8
8
 
9
9
  from coretrace_python.analysis import AnyAnalysis
10
- from coretrace_python.findings import Severity
10
+ from coretrace_python.findings import RuleDescription, Severity
11
11
  from coretrace_python.interprocedural import CallGraphAnalysis
12
12
  from coretrace_python.ir.model import Call, Constant, Instruction, Value
13
13
  from coretrace_python.ir.ssa import SSAAnalysis
@@ -24,6 +24,12 @@ UNVERIFIED = frozenset({SymbolId("python.ssl._create_unverified_context")})
24
24
 
25
25
  class InsecureTlsPlugin(SymbolCallDetector):
26
26
  name: ClassVar[str] = "insecure-tls"
27
+ rules: ClassVar[Mapping[str, RuleDescription]] = {
28
+ "insecure-tls": RuleDescription(
29
+ "TLS certificate verification disabled",
30
+ "verify=False on a Requests or httpx call, or ssl._create_unverified_context(), which accept any certificate.",
31
+ ),
32
+ }
27
33
  rule_id: ClassVar[str] = "insecure-tls"
28
34
  requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({SSAAnalysis, CallGraphAnalysis})
29
35
  symbols: ClassVar[frozenset[SymbolId]] = HTTP_CALLS | UNVERIFIED
@@ -2,11 +2,11 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- from collections.abc import Sequence
5
+ from collections.abc import Mapping, Sequence
6
6
  from typing import ClassVar
7
7
 
8
8
  from coretrace_python.analysis import AnyAnalysis
9
- from coretrace_python.findings import Confidence, Finding, Severity
9
+ from coretrace_python.findings import Confidence, Finding, RuleDescription, Severity
10
10
  from coretrace_python.interprocedural import CallGraphAnalysis
11
11
  from coretrace_python.ir.model import Call
12
12
  from coretrace_python.ir.ssa import SSAAnalysis
@@ -20,6 +20,12 @@ HTTP_CALLS = frozenset(SymbolId(f"python.{caller}.{method}") for caller in _CALL
20
20
 
21
21
  class MissingTimeoutPlugin(Plugin):
22
22
  name: ClassVar[str] = "missing-timeout"
23
+ rules: ClassVar[Mapping[str, RuleDescription]] = {
24
+ "missing-timeout": RuleDescription(
25
+ "HTTP request without a timeout",
26
+ "A Requests or httpx call without a timeout, which can wait forever.",
27
+ ),
28
+ }
23
29
  requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({SSAAnalysis, CallGraphAnalysis})
24
30
 
25
31
  def analyze(self, ctx: PluginContext) -> Sequence[Finding]:
@@ -7,7 +7,7 @@ from collections.abc import Mapping
7
7
  from typing import ClassVar
8
8
 
9
9
  from coretrace_python.analysis import AnyAnalysis
10
- from coretrace_python.findings import Severity
10
+ from coretrace_python.findings import RuleDescription, Severity
11
11
  from coretrace_python.interprocedural import CallGraphAnalysis
12
12
  from coretrace_python.ir.model import Call, Instruction, Value
13
13
  from coretrace_python.ir.ssa import SSAAnalysis
@@ -20,6 +20,12 @@ _EXTRACTORS = tuple(f"{opener}.{method}" for opener in _OPENERS for method in ("
20
20
 
21
21
  class UnsafeArchivePlugin(SymbolCallDetector):
22
22
  name: ClassVar[str] = "unsafe-archive-extraction"
23
+ rules: ClassVar[Mapping[str, RuleDescription]] = {
24
+ "unsafe-archive-extraction": RuleDescription(
25
+ "Unsafe archive extraction",
26
+ "A tarfile or zipfile extraction, or shutil.unpack_archive, without a member filter: a member can be written outside the destination.",
27
+ ),
28
+ }
23
29
  rule_id: ClassVar[str] = "unsafe-archive-extraction"
24
30
  requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({SSAAnalysis, CallGraphAnalysis})
25
31
  symbols: ClassVar[frozenset[SymbolId]] = frozenset(
@@ -1,7 +1,7 @@
1
1
  name = "unsafe-xml"
2
2
  version = "1.0.0"
3
3
  plugin_api = ">=1,<2"
4
- requires = ["interprocedural.callgraph", "ir.ssa"]
4
+ requires = ["interprocedural.callgraph", "ir.ssa", "abstract.module_strings"]
5
5
  provides = ["vulnerability.unsafe-xml"]
6
6
 
7
7
  [entrypoint]
@@ -1,35 +1,121 @@
1
- """XML parsers of the standard library and lxml expand entities: a crafted document reads
2
- local files or exhausts memory. ``defusedxml`` offers the same functions safely."""
1
+ """XML parsers of the standard library and of lxml, each reported for what it risks.
2
+
3
+ The standard library's parsers run on Expat, which never reads a local file or opens a
4
+ connection, but expands the entities a document declares: a crafted document can exhaust
5
+ memory with Expat older than 2.7.2, a fact of run time (``pyexpat.EXPAT_VERSION``). lxml
6
+ resolves external entities by default before 5.0, and in ``iterparse`` and
7
+ ``ETCompatXMLParser`` before 6.1 (CVE-2026-41066), which lets a crafted document read
8
+ local files; ``resolve_entities=True`` does so whatever the version, ``False`` never.
9
+ ``'internal'`` keeps external entities out only from lxml 5.0 on: an earlier lxml reads
10
+ the string as true. ``defusedxml`` offers the same functions safely. XML content the
11
+ project wrote itself, a string constant or a module-level string bound once given to a
12
+ function that parses its argument as the document, is no attacker's: its finding is kept
13
+ at low confidence. A path is not the document: whoever can write the file chooses it."""
3
14
 
4
15
  from __future__ import annotations
5
16
 
17
+ from collections.abc import Mapping
6
18
  from typing import ClassVar
7
19
 
20
+ from coretrace_python.abstract.strings import ModuleStringsAnalysis
8
21
  from coretrace_python.analysis import AnyAnalysis
9
- from coretrace_python.findings import Severity
22
+ from coretrace_python.findings import Confidence, RuleDescription, Severity
10
23
  from coretrace_python.interprocedural import CallGraphAnalysis
24
+ from coretrace_python.ir.model import Call, Constant, Global, Instruction, Value
11
25
  from coretrace_python.ir.ssa import SSAAnalysis
12
- from coretrace_python.plugins import SymbolCallDetector
26
+ from coretrace_python.plugins import CallReport, PluginContext, SymbolCallDetector
13
27
  from coretrace_python.semantic.symbols import SymbolId
14
28
 
15
- _PARSERS = (
29
+
30
+ def _symbols(*paths: str) -> frozenset[SymbolId]:
31
+ return frozenset(SymbolId(f"python.{path}") for path in paths)
32
+
33
+
34
+ _STANDARD_LIBRARY = _symbols(
16
35
  "xml.etree.ElementTree.parse", "xml.etree.ElementTree.fromstring", "xml.etree.ElementTree.iterparse",
17
36
  "xml.etree.ElementTree.XMLParser", "xml.etree.ElementTree.fromstringlist",
18
37
  "xml.dom.minidom.parse", "xml.dom.minidom.parseString",
19
38
  "xml.dom.pulldom.parse", "xml.dom.pulldom.parseString",
20
39
  "xml.sax.parse", "xml.sax.parseString", "xml.sax.make_parser",
21
40
  "xml.dom.expatbuilder.parse", "xml.dom.expatbuilder.parseString",
22
- "lxml.etree.parse", "lxml.etree.fromstring", "lxml.etree.XMLParser", "lxml.etree.iterparse",
23
- "lxml.etree.XML",
24
41
  )
42
+ _LXML = _symbols("lxml.etree.parse", "lxml.etree.fromstring", "lxml.etree.XMLParser", "lxml.etree.XML")
43
+ # Their default kept ``resolve_entities=True`` until lxml 6.1 (CVE-2026-41066).
44
+ _LXML_UNTIL_6_1 = _symbols("lxml.etree.iterparse", "lxml.etree.ETCompatXMLParser")
45
+ # The functions whose first argument is the XML itself, not a file, a URL or a stream.
46
+ _CONTENT = _symbols(
47
+ "xml.etree.ElementTree.fromstring", "xml.etree.ElementTree.fromstringlist",
48
+ "xml.dom.minidom.parseString", "xml.dom.pulldom.parseString", "xml.sax.parseString",
49
+ "xml.dom.expatbuilder.parseString", "lxml.etree.fromstring", "lxml.etree.XML",
50
+ )
51
+ # A keyword that is not a constant: its value is unknown.
52
+ _UNKNOWN = object()
53
+
54
+
55
+ def _resolve_entities(call: Call, defs: Mapping[Value, Instruction]) -> object:
56
+ """The constant ``resolve_entities=`` of ``call``, ``None`` when it is not passed."""
57
+
58
+ for name, value in call.keywords:
59
+ if name == "resolve_entities":
60
+ made = defs.get(value)
61
+ return made.value if isinstance(made, Constant) else _UNKNOWN
62
+ return None
25
63
 
26
64
 
27
65
  class UnsafeXmlPlugin(SymbolCallDetector):
28
66
  name: ClassVar[str] = "unsafe-xml"
67
+ rules: ClassVar[Mapping[str, RuleDescription]] = {
68
+ "unsafe-xml": RuleDescription(
69
+ "Unsafe XML parser",
70
+ "An XML parser of the standard library or of lxml, exposed to the entities a document declares; defusedxml is the safe replacement.",
71
+ ),
72
+ }
29
73
  rule_id: ClassVar[str] = "unsafe-xml"
30
- requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({SSAAnalysis, CallGraphAnalysis})
31
- symbols: ClassVar[frozenset[SymbolId]] = frozenset(SymbolId(f"python.{p}") for p in _PARSERS)
74
+ requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({SSAAnalysis, CallGraphAnalysis, ModuleStringsAnalysis})
75
+ symbols: ClassVar[frozenset[SymbolId]] = _STANDARD_LIBRARY | _LXML | _LXML_UNTIL_6_1
32
76
  severity: ClassVar[Severity] = Severity.MEDIUM
33
- message_template: ClassVar[str] = (
34
- "call to {symbol} parses XML with entity expansion enabled; use defusedxml"
35
- )
77
+ message_template: ClassVar[str] = "call to {symbol} parses XML unsafely; use defusedxml"
78
+
79
+ def accepts(self, call: Call, symbol: SymbolId, defs: Mapping[Value, Instruction]) -> bool:
80
+ # ``resolve_entities`` is an lxml option; the standard library has none.
81
+ return _resolve_entities(call, defs) is not False
82
+
83
+ def describe(
84
+ self, ctx: PluginContext, call: Call, symbol: SymbolId, defs: Mapping[Value, Instruction]
85
+ ) -> CallReport:
86
+ if symbol in _STANDARD_LIBRARY:
87
+ risk = "expands the entities a document declares, which can exhaust memory with Expat older than 2.7.2"
88
+ advice = "use defusedxml"
89
+ elif _resolve_entities(call, defs) is True:
90
+ risk = "resolves external entities (resolve_entities=True), which lets a crafted document read local files"
91
+ advice = "use defusedxml"
92
+ elif _resolve_entities(call, defs) == "internal":
93
+ risk = (
94
+ "sets resolve_entities='internal', which keeps external entities out only from lxml 5.0 on: "
95
+ "before lxml 5.0 the string reads as true and external entities are resolved, which lets a "
96
+ "crafted document read local files"
97
+ )
98
+ advice = "use defusedxml or resolve_entities=False"
99
+ elif symbol in _LXML_UNTIL_6_1:
100
+ risk = (
101
+ "resolves external entities by default before lxml 6.1 (CVE-2026-41066), "
102
+ "which lets a crafted document read local files"
103
+ )
104
+ advice = "use defusedxml or resolve_entities=False"
105
+ else:
106
+ risk = "resolves external entities by default before lxml 5.0, which lets a crafted document read local files"
107
+ advice = "use defusedxml"
108
+ written = symbol in _CONTENT and self.written_by_the_project(ctx, call, defs)
109
+ confidence = Confidence.LOW if written else self.confidence
110
+ return CallReport(f"call to {symbol} {risk}; {advice}", confidence)
111
+
112
+ def written_by_the_project(self, ctx: PluginContext, call: Call, defs: Mapping[Value, Instruction]) -> bool:
113
+ """Whether the first argument of ``call``, which a ``_CONTENT`` function parses as
114
+ the document, is a string constant or a module-level name bound once to one."""
115
+
116
+ if not call.arguments:
117
+ return False
118
+ made = defs.get(call.arguments[0])
119
+ if isinstance(made, Constant):
120
+ return isinstance(made.value, str | bytes)
121
+ return isinstance(made, Global) and made.name in ctx.get(ModuleStringsAnalysis)
@@ -2,15 +2,22 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ from collections.abc import Mapping
5
6
  from typing import ClassVar
6
7
 
7
- from coretrace_python.findings import Severity
8
+ from coretrace_python.findings import RuleDescription, Severity
8
9
  from coretrace_python.plugins import SymbolCallDetector
9
10
  from coretrace_python.semantic.symbols import SymbolId
10
11
 
11
12
 
12
13
  class WeakCryptoPlugin(SymbolCallDetector):
13
14
  name: ClassVar[str] = "weak-crypto"
15
+ rules: ClassVar[Mapping[str, RuleDescription]] = {
16
+ "weak-crypto": RuleDescription(
17
+ "Weak cryptographic algorithm",
18
+ "A broken algorithm such as hashlib.md5 or hashlib.sha1.",
19
+ ),
20
+ }
14
21
  rule_id: ClassVar[str] = "weak-crypto"
15
22
  symbols: ClassVar[frozenset[SymbolId]] = frozenset(
16
23
  {SymbolId("python.hashlib.md5"), SymbolId("python.hashlib.sha1")}
@@ -7,11 +7,11 @@ produces one."""
7
7
  from __future__ import annotations
8
8
 
9
9
  import re
10
- from collections.abc import Iterator, Sequence
10
+ from collections.abc import Iterator, Mapping, Sequence
11
11
  from typing import ClassVar
12
12
 
13
13
  from coretrace_python.analysis import AnyAnalysis
14
- from coretrace_python.findings import Confidence, Finding, Severity
14
+ from coretrace_python.findings import Confidence, Finding, RuleDescription, Severity
15
15
  from coretrace_python.hir import nodes
16
16
  from coretrace_python.hir.visitors import Node, children
17
17
  from coretrace_python.plugins import Plugin, PluginContext
@@ -25,6 +25,12 @@ CREDENTIAL = re.compile(r"(?i)(token|secret|password|passwd|api_?key|session|non
25
25
 
26
26
  class WeakRandomPlugin(Plugin):
27
27
  name: ClassVar[str] = "weak-random"
28
+ rules: ClassVar[Mapping[str, RuleDescription]] = {
29
+ "weak-random": RuleDescription(
30
+ "Weak random value for a credential",
31
+ "A value of the random module used as a credential; random is not cryptographically secure.",
32
+ ),
33
+ }
28
34
  rule_id: ClassVar[str] = "weak-random"
29
35
  requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({ScopeAnalysis, SymbolAnalysis})
30
36
 
coretrace_python/cache.py CHANGED
@@ -21,7 +21,7 @@ from pathlib import Path
21
21
  from types import MappingProxyType
22
22
  from typing import Any
23
23
 
24
- from coretrace_python.findings import Confidence, Finding, Severity
24
+ from coretrace_python.findings import Confidence, Finding, RelatedLocation, Severity
25
25
  from coretrace_python.interprocedural import (
26
26
  Arguments,
27
27
  CallSite,
@@ -35,7 +35,6 @@ from coretrace_python.interprocedural import (
35
35
  Mutation,
36
36
  NonlocalWrite,
37
37
  PriorCall,
38
- SummaryIndex,
39
38
  SymbolRead,
40
39
  Target,
41
40
  UnknownTarget,
@@ -43,7 +42,11 @@ from coretrace_python.interprocedural import (
43
42
  from coretrace_python.semantic.symbols import SymbolId
44
43
  from coretrace_python.source import FileLocation, Location, SourceId, SourceSpan
45
44
 
46
- CACHE_FORMAT = 14
45
+ # Cached summaries from earlier versions preserve unstable external-call
46
+ # insertion order. They must be recomputed with canonical ordering (#261).
47
+ # Findings carry their related locations from format 18 on (#271). A module's key holds
48
+ # the names it is imported by from format 19 on (#264).
49
+ CACHE_FORMAT = 19
47
50
 
48
51
 
49
52
  @dataclass(frozen=True)
@@ -155,16 +158,6 @@ def decode(data: Mapping[str, Any]) -> CachedModule:
155
158
  )
156
159
 
157
160
 
158
- def encode_index(index: SummaryIndex) -> dict[str, Any]:
159
- """A summary index as plain data, to hand a worker process what it imports."""
160
-
161
- return {str(symbol): _encode_summary(index.summaries[symbol]) for symbol in index.symbols}
162
-
163
-
164
- def decode_index(data: Mapping[str, Any]) -> SummaryIndex:
165
- return SummaryIndex({SymbolId(_string(k)): _decode_summary(v) for k, v in data.items()})
166
-
167
-
168
161
  def _string(value: Any) -> str:
169
162
  if not isinstance(value, str):
170
163
  raise TypeError(f"expected a string, got {value!r}")
@@ -238,6 +231,7 @@ def _encode_finding(finding: Finding) -> dict[str, Any]:
238
231
  "span": _encode_location(finding.span),
239
232
  "function": finding.function,
240
233
  "metadata": dict(finding.metadata),
234
+ "related": [[_encode_span(r.span), r.message] for r in finding.related],
241
235
  }
242
236
 
243
237
 
@@ -251,6 +245,7 @@ def _decode_finding(data: Mapping[str, Any]) -> Finding:
251
245
  _decode_location(data["span"]),
252
246
  None if function is None else _string(function),
253
247
  {_string(k): _string(v) for k, v in data["metadata"].items()},
248
+ tuple(RelatedLocation(_decode_span(span), _string(message)) for span, message in data["related"]),
254
249
  )
255
250
 
256
251
 
@@ -264,11 +259,13 @@ def _encode_call(call: ExternalCall) -> dict[str, Any]:
264
259
  "given": _encode_arguments(call.arguments),
265
260
  "argument_cleared": [_encode_cleared(c) for c in call.argument_cleared],
266
261
  "keyword_cleared": [_encode_cleared(c) for c in call.keyword_cleared],
262
+ "invoked_at": None if call.invoked_at is None else _encode_span(call.invoked_at),
267
263
  }
268
264
 
269
265
 
270
266
  def _decode_call(data: Mapping[str, Any]) -> ExternalCall:
271
267
  site = data["call_site"]
268
+ invoked_at = data["invoked_at"]
272
269
  return ExternalCall(
273
270
  SymbolId(_string(data["symbol"])),
274
271
  tuple(_indices(deps) for deps in data["arguments"]),
@@ -278,6 +275,7 @@ def _decode_call(data: Mapping[str, Any]) -> ExternalCall:
278
275
  _decode_arguments(data["given"]),
279
276
  tuple(_decode_cleared(c) for c in data["argument_cleared"]),
280
277
  tuple(_decode_cleared(c) for c in data["keyword_cleared"]),
278
+ None if invoked_at is None else _decode_span(invoked_at),
281
279
  )
282
280
 
283
281
 
@@ -308,7 +306,12 @@ def _encode_summary(summary: FunctionSummary) -> dict[str, Any]:
308
306
  ],
309
307
  "side_effects": sorted(summary.side_effects),
310
308
  "nonlocal_writes": [
311
- {"name": w.name, "dependencies": sorted(w.dependencies), "externals": sorted(str(s) for s in w.externals)}
309
+ {
310
+ "name": w.name,
311
+ "dependencies": sorted(w.dependencies),
312
+ "externals": sorted(str(s) for s in w.externals),
313
+ "kept": w.kept,
314
+ }
312
315
  for w in summary.nonlocal_writes
313
316
  ],
314
317
  "static": summary.static,
@@ -336,7 +339,10 @@ def _decode_summary(data: Mapping[str, Any]) -> FunctionSummary:
336
339
  frozenset(_string(name) for name in data["side_effects"]),
337
340
  tuple(
338
341
  NonlocalWrite(
339
- _string(w["name"]), _indices(w["dependencies"]), frozenset(SymbolId(_string(s)) for s in w["externals"])
342
+ _string(w["name"]),
343
+ _indices(w["dependencies"]),
344
+ frozenset(SymbolId(_string(s)) for s in w["externals"]),
345
+ bool(w["kept"]),
340
346
  )
341
347
  for w in data["nonlocal_writes"]
342
348
  ),
coretrace_python/cli.py CHANGED
@@ -109,11 +109,13 @@ def build_parser() -> argparse.ArgumentParser:
109
109
  "them for modules unchanged since the previous run",
110
110
  )
111
111
  parser.add_argument(
112
+ "-j",
112
113
  "--jobs",
113
114
  type=int,
114
115
  default=None,
115
116
  metavar="N",
116
- help="with --check on a directory, analyse independent modules in N processes",
117
+ help="with --check on a directory, analyse independent modules in N processes, "
118
+ "0 for one per available core; default: 1",
117
119
  )
118
120
  parser.add_argument(
119
121
  "--sbom",
@@ -214,8 +216,8 @@ def main(argv: list[str] | None = None) -> int:
214
216
  if args.jobs is not None and not (args.check and args.path.is_dir()):
215
217
  print("error: --jobs only applies to --check on a directory", file=sys.stderr)
216
218
  return EXIT_ERROR
217
- if args.jobs is not None and args.jobs < 1:
218
- print("error: --jobs must be at least 1", file=sys.stderr)
219
+ if args.jobs is not None and args.jobs < 0:
220
+ print("error: --jobs must be 0 (one per available core) or more", file=sys.stderr)
219
221
  return EXIT_ERROR
220
222
  if args.sbom is not None and not (args.check and args.path.is_dir()):
221
223
  print("error: --sbom only applies to --check on a directory", file=sys.stderr)
@@ -270,7 +272,7 @@ def main(argv: list[str] | None = None) -> int:
270
272
  args.path,
271
273
  plugin_roots,
272
274
  cache=cache,
273
- jobs=args.jobs or 1,
275
+ jobs=_processes(args.jobs),
274
276
  advisory_files=args.advisories,
275
277
  policy_file=args.policy,
276
278
  )
@@ -278,6 +280,7 @@ def main(argv: list[str] | None = None) -> int:
278
280
  coverage = analysis.coverage
279
281
  suppressed = analysis.suppressed
280
282
  components = analysis.components
283
+ rules = analysis.rules
281
284
  if args.sbom is not None:
282
285
  args.sbom.write_text(
283
286
  render_sbom(
@@ -301,10 +304,11 @@ def main(argv: list[str] | None = None) -> int:
301
304
  encoding="utf-8",
302
305
  )
303
306
  else:
304
- file_analysis = engine.analyze_file(SourceManager().load_file(args.path), plugin_roots)
307
+ file_analysis = engine.analyze_file(SourceManager().load_file(args.path), plugin_roots, root)
305
308
  findings, coverage = file_analysis.findings, file_analysis.coverage
306
309
  suppressed = file_analysis.suppressed
307
310
  components = ()
311
+ rules = file_analysis.rules
308
312
  baselined = None
309
313
  recorded = None
310
314
  if previous is not None:
@@ -315,7 +319,7 @@ def main(argv: list[str] | None = None) -> int:
315
319
  elif args.baseline is not None:
316
320
  recorded = Baseline.of(findings, root, key)
317
321
  findings, baselined = (), findings
318
- report = engine.report(findings, coverage, root, suppressed, baselined, components)
322
+ report = engine.report(findings, coverage, root, suppressed, baselined, components, rules)
319
323
  text = render(args.format or "text", report)
320
324
  # Recorded once the report is rendered, so that a failed check keeps the
321
325
  # previous baseline.
@@ -331,5 +335,31 @@ def main(argv: list[str] | None = None) -> int:
331
335
  return EXIT_CLEAN
332
336
 
333
337
 
338
+ def _processes(jobs: int | None) -> int:
339
+ """The number of processes ``--jobs`` asks for: 0 is one per core the process may run
340
+ on, as ``runtime.jobs`` of ``ctrace``; none is one."""
341
+
342
+ if jobs is None:
343
+ return 1
344
+ if jobs == 0:
345
+ return _available_cores()
346
+ return jobs
347
+
348
+
349
+ def _available_cores() -> int:
350
+ """The cores the process may run on, where Python can tell its affinity
351
+ (``os.process_cpu_count`` from 3.13, ``os.sched_getaffinity`` on Linux before), else
352
+ the cores of the machine."""
353
+
354
+ process_cpu_count = getattr(os, "process_cpu_count", None)
355
+ if process_cpu_count is not None:
356
+ cores: int | None = process_cpu_count()
357
+ elif hasattr(os, "sched_getaffinity"):
358
+ cores = len(os.sched_getaffinity(0))
359
+ else:
360
+ cores = os.cpu_count()
361
+ return cores or 1
362
+
363
+
334
364
  if __name__ == "__main__":
335
365
  raise SystemExit(main())