coretrace-python-analyzer 0.23.0__tar.gz → 0.25.0__tar.gz

{coretrace_python_analyzer-0.23.0 → coretrace_python_analyzer-0.25.0}/CHANGELOG.md

@@ -1,5 +1,141 @@
 # Changelog
 
+## 0.25.0 (2026-11-01)
+
+### Compatibility and migration
+
+- The filters a template's render reaches change, and with them the advisories reported
+  as `exploitable-vulnerability` through a filter, which may appear or disappear: a
+  render now follows a cycle of includes as far as Django may render it (#284), and
+  places a template's blocks where its chain of extends places them (#285).
+- Plugin API, additive: `coretrace_python.source.LineIndex` gives the line and column of
+  each offset of a text, lines counted as `lines_of` counts them (#288).
+
+### Templates
+
+- A cycle of includes no longer stops the collection of the filters a render reaches
+  (#284). A template reached again on the way contributes what it reaches, its names
+  mapped through each include, as Django renders it when the project's conditions let
+  the cycle turn: a template including itself with other bindings, a recursive tree, or
+  a parent including the child that extends it. A filter reached this way may be
+  reported as `exploitable-vulnerability` where it was not. Where no cycle is reached,
+  the filters and their order do not change.
+- A template's render is put together over its extends chain as Django places its
+  blocks (#285). A filter in a block no template of the chain places, or in a block
+  whose only placeholder a child replaces, is no longer reached, and an advisory naming
+  it is no longer `exploitable-vulnerability` through it. A block a child redefines with
+  `{{ block.super }}` inside a block it replaces now renders the parent's definition and
+  what it includes. Where the chain cannot be followed to a root, every block counts as
+  placed, as before.
+
+### Performance
+
+- Templates in a cycle of includes are no longer walked again on every path (#284): 20
+  levels of doubled includes closed into a cycle took 56 s, and 40 templates including
+  one another more than a minute; both now take less than a second.
+- The positions in a template are no longer counted from its start, for each filter,
+  include, extends and load (#288): a template of 2 MB applying 160,000 filters took
+  50 s to analyse, and now takes 3 s.
+
+### Documentation
+
+- `docs/usage.md` documents how a cycle of includes is followed (#284) and where the
+  chain of extends places a template's blocks (#285).
+
+## 0.24.0 (2026-10-23)
+
+### Compatibility and migration
+
+- The cache format changes (19): caches built by an earlier version miss once.
+- A module in a directory without `__init__.py` inside a package is named after that
+  package, as Python names it (#264): `pkg/sub/app.py` is `pkg.sub.app`. Its relative
+  imports now resolve, and a file that was a `syntax-error` (`relative import beyond
+  top-level package`) is analysed, flask's `sansio` for one. The project symbols of its
+  functions change with its name (`python.pkg.sub.app.view`), which a model declared on
+  the former symbol must follow; baseline keys do not change, since they hold no module
+  name. A script beside it still imports it by its short name, which answers no import
+  from another directory: at the project root, `import os` is the library even beside a
+  `pkg/sub/os.py`, which a top-level module of a directory took before. Files that share
+  only that short name are no longer noted as `ambiguous-module`, nor is an import that
+  only such names from other directories match.
+- SARIF: each rule carries a title (`shortDescription`) and a description (`fullDescription`)
+  instead of repeating its id (#270), and each result carries its confidence as the
+  `confidence` property (#271). A flow reaching its sink inside a project function points at
+  that sink as a related location, which the result's message links to (#271).
+- Django templates are read as a browser reads them (#263, #272, #278): a template that
+  leaves a tag, a `<script>` or `<style>` block or an end tag open, or includes one that
+  ends inside such a construct, is no longer established as escaping, so `xss` may be
+  reported where it was not.
+- Django templates are also read as each page is put together (#273): a variable a
+  child's `{% block %}` prints inside its parent's `<script>`, an `{% include %}` that ends
+  the attribute value it stands in, or one of a name several files have outside HTML data,
+  is reported as `xss` where it was not, as is the variable `block` named anywhere but in
+  a bare `{{ block.super }}`. So is a template that includes Django's
+  `django/forms/widgets/attrs.html` inside a tag, which prints attribute names, and a
+  template including itself inside a tag or a script. A page beyond 8 MiB once put
+  together, or a template with more than 64 pages, or 16 MiB in all, through names
+  several files have, is not established and is listed in `Coverage.unread_templates`.
+- Plugin API, additive: `Plugin.rules` maps the rules a plugin reports to their
+  `RuleDescription`, optional, so that third-party plugins describe their own rules;
+  `Finding.related` lists `RelatedLocation`s (a span and a message). `Report.rules` carries the
+  descriptions to the reporters.
+- Plugin API: `coretrace_python.interprocedural.starting_summaries` gives the summaries an
+  import cycle's members start from, and `coretrace_python.engine.MAX_PROJECT_ITERATIONS`
+  is removed, since the project's summaries are iterated until they settle (#261).
+- A summary lists its external calls in source order (#261): a finding naming the first
+  call of a callee's summary may name another of that callee, at the same line, as 4 of
+  saleor's 228 `orm-n-plus-one` findings do.
+
+### Analysis
+
+- `--check` ends on projects whose summaries never settled (#261). Around a call cycle of
+  three functions or more, a caller copied its callee's external calls in an order that
+  rotated forever, so ansible, fastapi, sentry and home-assistant never ended: those calls
+  are now kept in source order. Around an import cycle of three modules or more, the
+  project's iteration shifted by one module each time and stopped at its bound, which
+  could miss a sink reached through the cycle: its members now start from the summaries a
+  module starts from, and the iteration goes on until the project's summaries settle.
+- A lambda or comprehension in the annotation of a parameter or a variable no longer
+  stops the analysis of a directory with a `KeyError` (#262). An assignment expression in
+  an annotation binds its name as Python 3.11 to 3.13 do: in a function, the name is a
+  local whether the annotation is evaluated or not; at module level, it exists only once
+  the annotation is evaluated.
+
+### Templates
+
+- Start tags and their attributes are read as the HTML tokenizer reads them, in time
+  linear in the size of the template (#263): a few dozen characters under a `templates`
+  directory, a PNG or `<a ` followed by 40 letters, stopped the analysis. A tag a template
+  leaves open is read to its end and its attributes are checked; a quoted value left open
+  stays quoted to the end of the template.
+- A `<script>` or `<style>` block or an end tag a template leaves open runs to the end of
+  the template, and a variable inside it is refused, even where the page ends there
+  (#272). A template that ends inside such a construct or a tag is not established where
+  it is included, since the markup after the include continues it, and a template
+  extending another ends where that one ends.
+- A comment ends where a browser ends it (`-->`, `--!>`, at once for `<!-->` and
+  `<!--->`), and one left open hides the rest of the template (#272). A comment holding
+  template tags may end at any of them, since an include there may close it and a
+  condition around its `<!--` may leave it out, or run to its close when they render
+  nothing: it is read on from its first tag, and that reading must be in HTML data right
+  after each later tag and right after the close (#278). Such a comment left open does
+  not end in HTML data.
+
+### Performance
+
+- Collecting the filters a template's render reaches walks each template once for each set
+  of blocks the templates extending it override (#279). It followed every path through
+  nested includes: two includes of one template at each of 20 levels took 31 s.
+  A template in a cycle of includes is still walked again wherever the cycle cuts its
+  walk short.
+
+### Documentation
+
+- `docs/usage.md` documents how templates are read and each page is put together, the
+  modules of a directory without `__init__.py`, assignment expressions in annotations,
+  and the rule descriptions and related locations of the SARIF report; `docs/plugins.md`
+  documents `Plugin.rules` and `Finding.related`.
+
 ## 0.23.0 (2026-10-16)
 
 ### Compatibility and migration

{coretrace_python_analyzer-0.23.0 → coretrace_python_analyzer-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: coretrace-python-analyzer
-Version: 0.23.0
+Version: 0.25.0
 Summary: Static security analysis infrastructure for Python code
 Project-URL: Homepage, https://github.com/CoreTrace/coretrace-python-analyzer
 Project-URL: Repository, https://github.com/CoreTrace/coretrace-python-analyzer

{coretrace_python_analyzer-0.23.0 → coretrace_python_analyzer-0.25.0}/docs/plugins.md

@@ -341,6 +341,32 @@ JSON pointer of a value) for a value of a structured file whose line cannot be:
 that reads a finding's line checks which it has, and never invents a line for a
 `FileLocation` (`coretrace_python.source.positions` places JSON and TOML values).
 
+A plugin describes the rules it reports in its optional `rules` attribute: each rule id to a
+`RuleDescription`, a title and what the rule detects. The SARIF report gives them to its
+consumers (`shortDescription` and `fullDescription`), so that GitHub code scanning names and
+explains the alert; a rule the plugin does not describe is listed by its id alone.
+
+```python
+from collections.abc import Mapping
+
+from coretrace_python.findings import RuleDescription
+
+
+class SensitiveLoggingPlugin(SymbolCallDetector):
+    ...
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "sensitive-logging": RuleDescription(
+            "Sensitive data logged",
+            "A logging call at debug level that may write sensitive data to the logs.",
+        ),
+    }
+```
+
+A finding may also point at other places it involves, each a `RelatedLocation` (a span and a
+short message) in its `related` tuple, as a taint flow reaching its sink inside a project
+function points at that sink. The SARIF report lists them as `relatedLocations` and links to
+them from the message.
+
 ## Testing a plugin
 
 Load the plugin directory with the engine and check one source or one project:

{coretrace_python_analyzer-0.23.0 → coretrace_python_analyzer-0.25.0}/docs/usage.md

@@ -67,9 +67,16 @@ coretrace-python-analyzer [--check | --emit-ir [--ssa]] [options] [path]
 ## What is analysed
 
 Given a directory, every `.py` file below it is a module of one project, named after
-its package (`app/views.py` is `app.views`). Two files that would share a name, `a/app.py`
-and `z/app.py` outside any package, are told apart by their path from the root, `a.app`
-and `z.app`, and reported: each carries an `ambiguous-module` note, since a symbol
+its package (`app/views.py` is `app.views`). A directory without `__init__.py` inside a
+package is a portion of it, as Python reads one: `pkg/sub/app.py` is `pkg.sub.app`, and
+its relative imports resolve against `pkg`. A module there can also be imported by the
+name a script run from its directory gives it, `app`: an absolute import from that
+directory reaches what lies beside it first, then what the package's root holds, and
+files sharing only such a name are told apart by the importer's directory. From another
+directory that name answers nothing, as Python finds no such module there: at the
+project root, `import os` is the library even beside a `pkg/sub/os.py`. Two files
+that would share a module name, `a/app.py` and `z/app.py` outside any package, are told
+apart by their path from the root, `a.app` and `z.app`, and reported: each carries an `ambiguous-module` note, since a symbol
 `python.app.main` may name a function of either and an import of `app` resolves only
 from the importer's own directory, and each is covered as `ambiguous` rather than
 analysed. An import of such a name that no file of the importer's own directory answers
@@ -197,6 +204,39 @@ It establishes escaping only when all of the following hold:
   or an attribute name.
 - No Python file of the project sets `autoescape` to `False`.
 
+Templates are read as a browser's HTML tokenizer reads them, in time linear in the size
+of the template. What a template leaves open at its end is checked too, since once the
+template is included it runs into the markup that follows: a tag's attributes are
+checked, a quoted value stays quoted until its quote closes, and a variable in a
+`<script>` or `<style>` block or an end tag left open is refused, even where the page
+ends there and the browser would never run it. A template including one that ends inside
+such a block, a tag or an end tag is not established either: the markup after the
+include continues it. A template extending another ends where that one ends. A comment
+holding template tags may end at any of them, since an include there may close it and a
+condition around its `<!--` may leave it out, or run to its close when they render
+nothing (#278). The markup is read on from its first tag, and that reading must be in
+HTML data right after each later tag and right after the close, where the others
+resume; where it is not, the template is not established. Such a comment left open does
+not end in HTML data, since it may hide what follows.
+
+Each page is also put together as Django renders it, and read once more (#273): the
+templates it extends, each block taking the definition of the most derived one and `{{
+block.super }}` the next one up, and each template it includes in place. What a child's
+block prints inside its parent's `<script>`, or what an include puts inside an
+attribute, is read where it lands. `{{ block.super }}` is put in place only bare: the
+variable `block` named anywhere else, through a filter, a tag or an alias (`{% with
+parent=block %}{{ parent.super }}`), may still print the parent's markup, marked safe,
+and the template is not established. A name several files have, which Django resolves
+through loaders the analyzer does not read, counts as each of them: a page extending it
+must escape with each file, except those already in its chain, which Django leaves out,
+so that a template extending its own name extends another file of it; an include of it
+is accepted only in HTML data, never inside an attribute, a tag, a `<script>` or
+`<style>` block or a comment, and only when each file ends in HTML data, nothing of it
+left open. A template including itself is read the same way. A page beyond 8 MiB once
+put together, or a template with more than 64 pages, or 16 MiB in all, through the files
+the templates it extends may be, is not established, and is listed among the templates
+the analyzer could not read.
+
 The analyzer never assumes escaping where it cannot read the template. That covers a
 template file it cannot read, a template named by an expression, a template found
 through a `DIRS` entry not named `templates`, one shipped by an installed package, one
@@ -334,7 +374,7 @@ the directory of the checked file; a path outside it is printed as it is.
 ```json
 {
   "schema_version": 1,
-  "tool": {"name": "coretrace-python-analyzer", "version": "0.23.0"},
+  "tool": {"name": "coretrace-python-analyzer", "version": "0.25.0"},
   "root": "/home/me/project",
   "findings": [
     {
@@ -398,7 +438,7 @@ bytes. A single-file check lists no components.
 
 ```json
 "tool": {
-  "name": "coretrace-python-analyzer", "version": "0.23.0",
+  "name": "coretrace-python-analyzer", "version": "0.25.0",
   "components": [
     {"kind": "plugin", "name": "curated-advisories", "version": "2026.09.25", "digest": "sha256:…"},
     {"kind": "advisories", "name": "advisories.json", "digest": "sha256:…"}
@@ -412,7 +452,14 @@ several sources define the same advisory, it names the one whose definition is u
 the next section describes.
 
 `--format sarif` prints a SARIF 2.1.0 log, one run with the tool, its rules and one
-result per finding. The root is declared once as the `SRCROOT` original URI base and
+result per finding. Each rule carries a title (`shortDescription`) and what it detects
+(`fullDescription`), so that a code scanning service can explain a finding: the plugin that
+reports a rule describes it, the engine its own notes, and a rule a plugin does not describe
+keeps its id alone. Each result carries the finding's confidence as the `confidence`
+property. A flow that reaches its sink inside a project function is reported at the call, and
+points at the sink as a related location (`relatedLocations`), with the message
+`sink <sink>, reached via <function>`, which the result's message links to. The root is
+declared once as the `SRCROOT` original URI base and
 every location under it is relative to that base, which is what code scanning services
 need to attach results to files. The components of a directory check are the tool's
 `extensions`, their kind and digest in `properties`:
@@ -554,10 +601,18 @@ certain of it:
 - The filter's value is a context variable, directly or through `{% for %}` and
   `{% with %}`, the templates the template includes or extends by a constant name, the
   arguments of the filters before it, or the output of a `{% filter %}` block. A name a
-  tag binds shadows the context, and `{% include ... only %}` passes none of it.
-- The filter renders: a template extending another renders only its blocks, which
-  replace the blocks of that name in what it extends, unless the block renders
-  `{{ block.super }}`, which keeps the parent's content and the filters it applies.
+  tag binds shadows the context, and `{% include ... only %}` passes none of it. A cycle
+  of includes is followed as far as Django may render it: a template reached again on
+  the way applies its filters to what each include binds at every level, as a template
+  including itself with other bindings, or a recursive tree, does (#284).
+- The filter renders: a template extending another renders only its blocks, and only
+  where its chain of parents places them (#285). The root's blocks are placed; a placed
+  block renders its most derived definition, and through `{{ block.super }}` the next
+  ones up, which keep the parent's content and the filters it applies; the blocks a
+  rendered definition holds are placed in turn. A block no template of the chain
+  places never renders, nor does a block whose only placeholder a child replaces. When
+  the chain cannot be followed to a root (a parent named by an expression, not found or
+  in several files, or an extends cycle), every block of the chain counts as placed.
 - One file has the template's name; of two files of the same name, which one renders
   depends on the loaders.
 
@@ -768,7 +823,7 @@ project's behalf would go unseen. Without a lock file, a package is never
 `not_affected`. The document's `@id` derives from its statements, so two runs with the
 same result share it; its `author` is `Unknown Author`, as OpenVEX tools write when they
 cannot know it. Its `tooling` names the analyzer and each component with its digest
-(`coretrace-python-analyzer 0.23.0; curated-advisories 2026.09.25 (sha256:…)`), so the
+(`coretrace-python-analyzer 0.25.0; curated-advisories 2026.09.25 (sha256:…)`), so the
 `@id` changes with the advisory data a statement was decided with.
 
 ## Large projects
@@ -914,7 +969,11 @@ comprehensions, lambdas, nested functions and classes, `global`, `nonlocal`, `de
 assignment expressions (`(y := f(x))`, laid out as an assignment before the statement),
 `yield from`, starred assignment targets (`first, *rest = items`), class keyword arguments
 such as `metaclass=`, `with` targets of any assignable form and `match` with every
-pattern kind. `finally` is modelled on the normal path only. A
+pattern kind. An assignment expression in an annotation binds its name as Python 3.11 to
+3.13 do, where the annotation stands: in a function, the name is a local whether the
+annotation is evaluated or not; at module level, it exists only once the annotation is
+evaluated, so under `from __future__ import annotations` a builtin it names stays the
+builtin. `finally` is modelled on the normal path only. A
 `nonlocal` write made by a nested function flows back to the enclosing variable when the
 enclosing function calls that nested function directly by name; a nested function passed
 around and called elsewhere keeps its writes to itself. Where the nested function may

{coretrace_python_analyzer-0.23.0 → coretrace_python_analyzer-0.25.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "coretrace-python-analyzer"
-version = "0.23.0"
+version = "0.25.0"
 description = "Static security analysis infrastructure for Python code"
 readme = "README.md"
 requires-python = ">=3.11"

{coretrace_python_analyzer-0.23.0 → coretrace_python_analyzer-0.25.0}/src/coretrace_python/__init__.py

@@ -1,4 +1,4 @@
 """CoreTrace's Python static analysis frontend."""
 
-__version__ = "0.23.0"
+__version__ = "0.25.0"
 

{coretrace_python_analyzer-0.23.0 → coretrace_python_analyzer-0.25.0}/src/coretrace_python/bundled/dependency/dependency_policy/dependency_policy.py

@@ -2,17 +2,27 @@
 
 from __future__ import annotations
 
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from typing import ClassVar
 
 from coretrace_python.analysis import AnyAnalysis
 from coretrace_python.dependency import DependencyAnalysis
-from coretrace_python.findings import Confidence, Finding, Severity
+from coretrace_python.findings import Confidence, Finding, RuleDescription, Severity
 from coretrace_python.plugins import ProjectContext, ProjectPlugin
 
 
 class DependencyPolicyPlugin(ProjectPlugin):
     name: ClassVar[str] = "dependency-policy"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "denied-dependency": RuleDescription(
+            "Denied dependency",
+            "A requirement on a package the policy denies.",
+        ),
+        "unpinned-dependency": RuleDescription(
+            "Unpinned dependency",
+            "A requirement without an exact pin, when the policy requires pins.",
+        ),
+    }
     requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({DependencyAnalysis})
 
     def analyze_project(self, ctx: ProjectContext) -> Sequence[Finding]:

{coretrace_python_analyzer-0.23.0 → coretrace_python_analyzer-0.25.0}/src/coretrace_python/bundled/dependency/reachable_vulnerability/reachable_vulnerability.py

@@ -4,7 +4,7 @@ template applies is a call to the function behind it, at the template's line."""
 
 from __future__ import annotations
 
-from collections.abc import Iterator, Sequence
+from collections.abc import Iterator, Mapping, Sequence
 from typing import ClassVar
 
 from coretrace_python.analysis import AnyAnalysis
@@ -17,7 +17,7 @@ from coretrace_python.dependency.correlation import (
     evidence,
     suffix_index,
 )
-from coretrace_python.findings import Confidence, Finding
+from coretrace_python.findings import Confidence, Finding, RuleDescription
 from coretrace_python.interprocedural import CallGraphAnalysis, ExternalSymbol
 from coretrace_python.plugins import ProjectContext, ProjectPlugin
 from coretrace_python.semantic.symbols import SymbolId
@@ -26,6 +26,12 @@ from coretrace_python.source import SourceSpan
 
 class ReachableVulnerabilityPlugin(ProjectPlugin):
     name: ClassVar[str] = "reachable-vulnerability"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "reachable-vulnerability": RuleDescription(
+            "Reachable dependency vulnerability",
+            "The project calls an API that an advisory of a vulnerable requirement affects.",
+        ),
+    }
     requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({DependencyAnalysis, CallGraphAnalysis})
 
     def analyze_project(self, ctx: ProjectContext) -> Sequence[Finding]:

{coretrace_python_analyzer-0.23.0 → coretrace_python_analyzer-0.25.0}/src/coretrace_python/bundled/dependency/vulnerable_dependency/vulnerable_dependency.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from pathlib import PurePath
 from typing import ClassVar
 
@@ -15,13 +15,19 @@ from coretrace_python.dependency.correlation import (
     ruled_out,
     suffix_index,
 )
-from coretrace_python.findings import Confidence, Finding
+from coretrace_python.findings import Confidence, Finding, RuleDescription
 from coretrace_python.interprocedural import CallGraphAnalysis, ExternalSymbol
 from coretrace_python.plugins import ProjectContext, ProjectPlugin
 
 
 class VulnerableDependencyPlugin(ProjectPlugin):
     name: ClassVar[str] = "vulnerable-dependency"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "vulnerable-dependency": RuleDescription(
+            "Vulnerable dependency",
+            "A requirement allows a version that an advisory affects.",
+        ),
+    }
     requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({DependencyAnalysis, CallGraphAnalysis})
 
     def analyze_project(self, ctx: ProjectContext) -> Sequence[Finding]:

{coretrace_python_analyzer-0.23.0 → coretrace_python_analyzer-0.25.0}/src/coretrace_python/bundled/security/code_injection/code_injection.py

@@ -18,11 +18,12 @@ runs depends on what the object exposes, a hotspot."""
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from typing import ClassVar
 
 from coretrace_python.abstract.strings import ModuleStringsAnalysis, leading_text
 from coretrace_python.analysis import AnyAnalysis
-from coretrace_python.findings import Severity
+from coretrace_python.findings import RuleDescription, Severity
 from coretrace_python.findings.refutation import Status, Verdict
 from coretrace_python.hir import nodes
 from coretrace_python.ir.ssa import SSAAnalysis
@@ -42,6 +43,12 @@ _GETATTR = SymbolId("python.builtins.getattr")
 
 class CodeInjectionPlugin(TaintDetector):
     name: ClassVar[str] = "code-injection"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "code-injection": RuleDescription(
+            "Code injection",
+            "Attacker-controlled data chooses code that runs: the code eval or exec runs, the module an import loads, the script runpy runs, or the attribute getattr selects and the program calls.",
+        ),
+    }
     rule_id: ClassVar[str] = "code-injection"
     kind: ClassVar[TaintKind] = TaintKind.CODE
     severity: ClassVar[Severity] = Severity.HIGH

{coretrace_python_analyzer-0.23.0 → coretrace_python_analyzer-0.25.0}/src/coretrace_python/bundled/security/command_injection/command_injection.py

@@ -36,7 +36,7 @@ from typing import ClassVar
 
 from coretrace_python.abstract.strings import ModuleStringsAnalysis, leading_text
 from coretrace_python.analysis import AnyAnalysis
-from coretrace_python.findings import Severity
+from coretrace_python.findings import RuleDescription, Severity
 from coretrace_python.findings.refutation import Status, Verdict
 from coretrace_python.hir import nodes
 from coretrace_python.interprocedural import Arguments
@@ -398,6 +398,12 @@ class _Operands:
 
 class CommandInjectionPlugin(TaintDetector):
     name: ClassVar[str] = "command-injection"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "command-injection": RuleDescription(
+            "Command injection",
+            "Attacker-controlled data reaches a shell or process execution (os.system, subprocess, ...) where it can run or choose a command.",
+        ),
+    }
     rule_id: ClassVar[str] = "command-injection"
     kind: ClassVar[TaintKind] = TaintKind.COMMAND
     severity: ClassVar[Severity] = Severity.HIGH

{coretrace_python_analyzer-0.23.0 → coretrace_python_analyzer-0.25.0}/src/coretrace_python/bundled/security/insecure_deserialization/insecure_deserialization.py

@@ -2,15 +2,22 @@
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from typing import ClassVar
 
-from coretrace_python.findings import Severity
+from coretrace_python.findings import RuleDescription, Severity
 from coretrace_python.plugins import TaintDetector
 from coretrace_python.taint import TaintKind
 
 
 class InsecureDeserializationPlugin(TaintDetector):
     name: ClassVar[str] = "insecure-deserialization"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "insecure-deserialization": RuleDescription(
+            "Insecure deserialization",
+            "Attacker-controlled data reaches a deserializer that can build arbitrary objects or run code: pickle, marshal, dill, jsonpickle, shelve, or a YAML loader without a safe loader.",
+        ),
+    }
     rule_id: ClassVar[str] = "insecure-deserialization"
     kind: ClassVar[TaintKind] = TaintKind.DESERIALIZATION
     severity: ClassVar[Severity] = Severity.CRITICAL

{coretrace_python_analyzer-0.23.0 → coretrace_python_analyzer-0.25.0}/src/coretrace_python/bundled/security/nosql_injection/nosql_injection.py

@@ -5,15 +5,22 @@ sink; model plugins declare them."""
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from typing import ClassVar
 
-from coretrace_python.findings import Severity
+from coretrace_python.findings import RuleDescription, Severity
 from coretrace_python.plugins import TaintDetector
 from coretrace_python.taint import TaintKind
 
 
 class NoSqlInjectionPlugin(TaintDetector):
     name: ClassVar[str] = "nosql-injection"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "nosql-injection": RuleDescription(
+            "NoSQL injection",
+            "Attacker input that may hold a structure, such as a JSON body, reaches a NoSQL query, where an operator such as {\"$ne\": null} matches any value.",
+        ),
+    }
     rule_id: ClassVar[str] = "nosql-injection"
     kind: ClassVar[TaintKind] = TaintKind.NOSQL
     severity: ClassVar[Severity] = Severity.HIGH

{coretrace_python_analyzer-0.23.0 → coretrace_python_analyzer-0.25.0}/src/coretrace_python/bundled/security/open_redirect/open_redirect.py

@@ -10,11 +10,12 @@ unproven, ``"/" + next`` included, stays a vulnerability.
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from typing import ClassVar
 
 from coretrace_python.abstract.strings import ModuleStringsAnalysis
 from coretrace_python.analysis import AnyAnalysis
-from coretrace_python.findings import Severity
+from coretrace_python.findings import RuleDescription, Severity
 from coretrace_python.findings.refutation import Status, Verdict
 from coretrace_python.hir import nodes
 from coretrace_python.ir.ssa import SSAAnalysis
@@ -25,6 +26,12 @@ from coretrace_python.taint.urls import flow_url
 
 class OpenRedirectPlugin(TaintDetector):
     name: ClassVar[str] = "open-redirect"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "open-redirect": RuleDescription(
+            "Open redirect",
+            "Attacker-controlled data chooses the target of an HTTP redirect, which can send the user to another site.",
+        ),
+    }
     rule_id: ClassVar[str] = "open-redirect"
     kind: ClassVar[TaintKind] = TaintKind.REDIRECT
     severity: ClassVar[Severity] = Severity.MEDIUM

{coretrace_python_analyzer-0.23.0 → coretrace_python_analyzer-0.25.0}/src/coretrace_python/bundled/security/path_traversal/path_traversal.py

@@ -2,15 +2,22 @@
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from typing import ClassVar
 
-from coretrace_python.findings import Severity
+from coretrace_python.findings import RuleDescription, Severity
 from coretrace_python.plugins import TaintDetector
 from coretrace_python.taint import TaintKind
 
 
 class PathTraversalPlugin(TaintDetector):
     name: ClassVar[str] = "path-traversal"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "path-traversal": RuleDescription(
+            "Path traversal",
+            "Attacker-controlled data reaches a file system path (open, send_file, os.remove, ...).",
+        ),
+    }
     rule_id: ClassVar[str] = "path-traversal"
     kind: ClassVar[TaintKind] = TaintKind.PATH
     severity: ClassVar[Severity] = Severity.HIGH

{coretrace_python_analyzer-0.23.0 → coretrace_python_analyzer-0.25.0}/src/coretrace_python/bundled/security/plaintext_credentials/plaintext_credentials.py

@@ -5,15 +5,22 @@ a hint, so medium confidence."""
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from typing import ClassVar
 
-from coretrace_python.findings import Confidence, Severity
+from coretrace_python.findings import Confidence, RuleDescription, Severity
 from coretrace_python.plugins import TaintDetector
 from coretrace_python.taint import TaintKind
 
 
 class PlaintextCredentialsPlugin(TaintDetector):
     name: ClassVar[str] = "plaintext-credentials"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "plaintext-credential-storage": RuleDescription(
+            "Plaintext credential storage",
+            "A parameter named like a password is stored in a database without hashing.",
+        ),
+    }
     rule_id: ClassVar[str] = "plaintext-credential-storage"
     kind: ClassVar[TaintKind] = TaintKind.CREDENTIAL
     severity: ClassVar[Severity] = Severity.HIGH

{coretrace_python_analyzer-0.23.0 → coretrace_python_analyzer-0.25.0}/src/coretrace_python/bundled/security/sql_injection/sql_injection.py

@@ -2,15 +2,22 @@
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from typing import ClassVar
 
-from coretrace_python.findings import Severity
+from coretrace_python.findings import RuleDescription, Severity
 from coretrace_python.plugins import TaintDetector
 from coretrace_python.taint import TaintKind
 
 
 class SqlInjectionPlugin(TaintDetector):
     name: ClassVar[str] = "sql-injection"
+    rules: ClassVar[Mapping[str, RuleDescription]] = {
+        "sql-injection": RuleDescription(
+            "SQL injection",
+            "Attacker-controlled data reaches a database statement (cursor.execute, SQLAlchemy text, Django raw, ...) rather than a query parameter.",
+        ),
+    }
     rule_id: ClassVar[str] = "sql-injection"
     kind: ClassVar[TaintKind] = TaintKind.SQL
     severity: ClassVar[Severity] = Severity.HIGH