coretrace-python-analyzer 0.20.0__tar.gz → 0.22.0__tar.gz

coretrace_python_analyzer-0.22.0/AUTHORS.md

@@ -0,0 +1,7 @@
+# Authors
+
+## Maintainers
+
+- Hugo Payet ([@SizzleUnrlsd](https://github.com/SizzleUnrlsd))
+
+Other contributors are credited in this repository's Git history and pull requests.

{coretrace_python_analyzer-0.20.0 → coretrace_python_analyzer-0.22.0}/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 0.22.0 (2026-10-08)
+
+### Compatibility and migration
+
+- Baselines change format twice in this release, and no baseline is ever converted or rewritten on its own. Without a key, baselines are recorded in schema 3, whose entries hold digests of the text a finding covers instead of that text (#226); with a key, in schema 4, keyed with HMAC-SHA-256 (#235). Schema 1 and 2 files are still read without a key, with exact matching only: an entry identifies a finding on a single line as before, a finding over several lines is reported new, and every run warns on standard error that the file may contain secrets in plain text. While a key is given, only a schema 4 baseline is read: an unkeyed one (schema 1, 2 or 3) stops the check with exit status 2. To migrate, review the findings, then record the baseline explicitly with `--record-baseline` (schema 3, or schema 4 with a key); the old file's secrets remain in the history of a repository that committed it.
+- A keyed baseline needs its key: from the file `--baseline-key-file` names, which must lie outside the analysed directory and be another file than the baseline, or else from `CORETRACE_BASELINE_KEY`; the file comes first. The key is at least 16 bytes, trailing line breaks are not part of it, and an empty variable is an error. Without the key, or with another one, the check stops with exit status 2 and records nothing; recording over a schema 4 baseline without its key is refused too. Rotating the key is an explicit `--record-baseline` under the new key. Generate the key at random (`python -c "import secrets; print(secrets.token_hex(32))"`) and keep it out of the repository: a key a person chooses can be guessed from the baseline (#225).
+- Findings may move or reappear once: dependency and configuration findings of a check given a relative root are now located relative to that root (`uv.lock`, not `proj/uv.lock`) (#212); findings in JSON, TOML and lock files are located at their own line or by a JSON pointer (#222); a vulnerable package pinned in a lock file is located at its own `[[package]]` entry. Baselines recorded before should be recorded again after review.
+- A finding whose line cannot be established has a file location: in the JSON report its `line`, `column`, `end_line` and `end_column` are `null` and a `pointer` field names the value (RFC 6901); its SARIF location has no `region`, the pointer under the location's `properties`; the text report shows `path:` without a line. Inline suppressions apply only to findings at a verified line (#222).
+- `command-injection` severities change: an element of an argument list run without a shell is reported by what the input controls there, `medium` by default, `high` when an option of the program runs it, refuted when a constant prefix keeps it from being an option or an option keeps it as data (#217). The rule id is unchanged; the message of an option injection is titled `Option injection` (#232). Existing suppressions and baselines of the rule keep matching by rule id; baselined findings whose severity changed are still baselined.
+- A file whose syntax is nested more than 200 levels deep (a long chain of `+` or chained calls, which only generated code writes) is reported as a `syntax-error` and not analysed, instead of aborting the whole scan (#234).
+- The cache format changes (14): caches built by an earlier version miss once.
+- Plugin API: `Finding.span` is a `Location`, a `SourceSpan` or a `FileLocation` (#222); `Assessment` gains optional `title` and `metadata` fields (#232). Plugins that read `finding.span.start_line` should check for a `SourceSpan` first.
+
+### Baseline
+
+- `--record-baseline` records the current findings as the baseline even when the file exists; the file (the target of a symbolic link) is replaced atomically, keeping its permissions, only once the analysis succeeded and the report is rendered, so the previous baseline stays in place when the check fails (#235).
+- `--baseline-key-file FILE` gives the key of a schema 4 baseline; `CORETRACE_BASELINE_KEY` gives it otherwise. The key never appears in a report, message or file; a `key_check` value in the baseline tells the key apart without revealing it (#235).
+- An entry is recognised by a digest of the text of every line its finding covers: a secret written over several lines, whose first line does not hold it, is new once its body changes (#223, #226). A finding at a file location is recognised by digests of its value and of its pointer, whose keys may themselves be secrets (#222, #226).
+- Line numbers follow one rule everywhere, as Python counts lines (`\n`, `\r\n` or a lone `\r`, never U+2028 or a form feed), so a fingerprint or a suppression never refers to another line (#222).
+
+### Secrets
+
+- A string expression whose parts are all constant (`+` of strings, `sep.join` of a list or tuple of strings, an f-string whose parts are all constant) is judged as one value, reported once at the whole expression with the strongest finding of the value and its pieces; `PASSWORD = "Zx81kQpL" + "w0RtY7vB" + …` and `TOKEN = "ghp_" + "…"` are now reported. When the whole value is no secret, its pieces are judged on their own, as before (#231).
+- A `.env`, YAML, INI or properties value that continues past its key's line (an open quote, a trailing backslash, deeper indentation) is located over every line it continues on (#226).
+- Password hashes are no longer reported as hardcoded credentials: modular crypt and PHC strings, bcrypt, Werkzeug's `scrypt:`/`pbkdf2:` and Django's encodings; an identifier followed by text of another shape is still a plaintext password (#214).
+- The `url` pattern no longer reports placeholders (`?token=...`, `<token>`) nor an IP address or `localhost` and a port before `@` (proxy specifications); a password runs to the last `@` before the host. A `SecretPattern` may name a `secret` group, which the placeholder check then judges (#215).
+- In `package-lock.json` and `npm-shrinkwrap.json`, the keys of dependency, `requires` and `bin` maps are package or command names, not credential names (#216).
+
+### Command injection
+
+- The command a process starter runs (`subprocess.run`, `call`, `check_call`, `check_output`, `Popen`) is read element by element, with a documented option model for git, ssh, tar, rsync, find, rm, cmd, PowerShell, the shells and the interpreters, wrappers such as sudo, env, xargs and timeout read again with their program's model; the evidence says what the input controls (#217).
+- The finding's `injection` metadata says what the input is when the rule establishes it: `command` (it runs or chooses what runs) or `option` (an option, or the value of an option not established to run it), in the JSON report and as the only `properties` of the SARIF result; it is absent when the kind cannot be established (#232, #236).
+- The script after `pwsh -File` is a file name, however it is spelled (#229). `gtar` is read as GNU tar, `bsdtar` as libarchive's (`-I` names a file of patterns), and a bare `tar`'s `-I`, `--to-command` and `--checkpoint-action` are `high` and kept for review (#230).
+
+### Dependencies
+
+- A vulnerable package pinned in `uv.lock` or `poetry.lock` is located at its own entry, and the message states the evidence: `werkzeug 3.1.5, pinned in uv.lock, is in <3.1.6 (required by flask)` (#222). Requirements of `pyproject.toml` are located at their own element or key, or given a file location.
+- `--advisories` and `--policy` paths, and the root itself, are resolved once, so their findings and notes are located relative to the root whatever the working directory (#212).
+
+### Frontend
+
+- Syntax nested deeper than the analysis follows is rejected before PyHIR is built, and Python 3.11's parser recursion is a parse error of the file, so the rest of the project is still analysed (#234).
+
+### Documentation
+
+- `docs/usage.md` documents keyed baselines, `--record-baseline`, `--baseline-key-file`, file locations and the `injection` metadata; `docs/plugins.md` documents `FileLocation`, `Assessment.title` and `metadata`, and the `secret` group of a `SecretPattern`. Repository governance files (contributing, conduct, authors, security) are added (#204).
+
+## 0.21.0 (2026-09-30)
+
+### Advisories
+
+- An `argument` condition may carry `present: true`: the argument being passed at all, whatever its value, is the condition, as a `\r` in `web.Response(reason=…)` needs `reason` given, constant or not. It names the argument by keyword or position as today and excludes `values` and `default`. A call giving the argument — positionally, by keyword, or through a `**` literal with constant keys, folded into the keywords — meets it even when the value is unknown, so attacker input there makes the call exploitable; a call surely not giving it is ruled out (`app:5 python.aiohttp.web.Response(reason absent)`) and a project passing only such calls stays `not_affected`; a call unpacking `*args` or a `**mapping` whose keys are not written leaves it pending review (#195).
+- A curated entry point may declare `suffixes`, for receivers the engine cannot type: `Item.objects.annotate(...)` derives the project's own `python.app.models.Item.objects.annotate`, which the canonical `python.django.db.models.QuerySet.annotate` entry point never matches. A suffix matches any symbol of the project's own modules ending with a dot plus the suffix, on dot boundaries as a `SuffixSink` matches, never another package's symbol; a queryset chain is declared explicitly (`objects.filter.annotate`), and a suffix is at least two dot-separated names. The finding keeps the advisory's symbol as `entry_point` and the derived one as `symbol`; conditions, `attacker_arguments` and the ruled-out evidence of contradicted calls apply through a suffix as through the exact symbol. An exact advisory sink whose symbol a bundled suffix sink also matches (`objects.extra`) now composes its kinds with the suffix sink's instead of shadowing them (#197).
+- An advisory condition of kind `sequence` says the flaw spans two calls on one receiver: the first call leaves state on the object the entry point — the second call — reuses. It names the `method` the first call must be, by canonical name or `.`-suffix, and, optionally, the argument that call must carry (`{"kind": "sequence", "method": "Session.get", "argument": "verify", "values": ["False"], ...}`), so `s = requests.Session(); s.get(url, verify=False); s.get(other)` marks the second `get` reachable with the prior call as evidence (requests CVE-2024-35195). A receiver followed whole — bound once to the result of a call or a `with` and used only to call its methods — with no matching call on every path to the entry call rules it out (`app.fetch:6 python.requests.Session.get(no prior Session.get on the receiver)`), and a project with only such calls stays `not_affected`. A receiver the engine cannot follow (a parameter, a module-level instance, one passed to another function or mutated through an attribute), a matching call only in a branch or textually later, an unpacking that leaves the first call's arguments undecided, or an entry call that itself carries the named argument — its own prior across the iterations of a loop — leaves the condition pending review (#194).
+
+### Plugins
+
+- `CallSite.prior_calls` records, for a receiver the engine follows whole, the other external calls on the same receiver (`PriorCall`: symbol, location, arguments, and whether it surely executes before this one), in source order; `CallGraph.prior_calls_at` reads it by location, and `check_conditions` takes it to decide `sequence` conditions. The cache format changes.
+
 ## 0.20.0 (2026-09-30)
 
 ### Advisories

coretrace_python_analyzer-0.22.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,130 @@
+# Contributor Covenant Code of Conduct
+
+This policy applies to the CoreTrace Python Analyzer repository and its community spaces.
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+hugo.payet@epitech.eu.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

coretrace_python_analyzer-0.22.0/CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Contributing to CoreTrace Python Analyzer
+
+## Local setup
+
+Python 3.11 or newer is required. Create a virtual environment and install the development dependencies:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -e '.[dev]'
+.venv/bin/python -m mypy
+.venv/bin/python -m pytest
+.venv/bin/python -m ruff check .
+```
+
+The [README](README.md#development) explains the separate network-dependent regression corpus. Update documentation when changing rules, reports or plugin contracts, and describe the checks you ran in your pull request. Keep changes focused and use an English Conventional Commit subject.
+
+Report suspected vulnerabilities through [SECURITY.md](SECURITY.md) rather than a public issue.

{coretrace_python_analyzer-0.20.0 → coretrace_python_analyzer-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: coretrace-python-analyzer
-Version: 0.20.0
+Version: 0.22.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
@@ -53,6 +53,15 @@ semantic resolution of imports and scopes, lowering to a small intermediate
 representation (PyIR), control-flow graphs, SSA, data-flow and abstract interpretation,
 interprocedural summaries, taint and refutation, then plugins and reporters.
 
+## Repository documents
+
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+- [AUTHORS.md](AUTHORS.md)
+- [CHANGELOG.md](CHANGELOG.md)
+- [LICENSE](LICENSE)
+- [SECURITY.md](SECURITY.md)
+
 ## Development
 
 ```bash

{coretrace_python_analyzer-0.20.0 → coretrace_python_analyzer-0.22.0}/README.md

@@ -23,6 +23,15 @@ semantic resolution of imports and scopes, lowering to a small intermediate
 representation (PyIR), control-flow graphs, SSA, data-flow and abstract interpretation,
 interprocedural summaries, taint and refutation, then plugins and reporters.
 
+## Repository documents
+
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+- [AUTHORS.md](AUTHORS.md)
+- [CHANGELOG.md](CHANGELOG.md)
+- [LICENSE](LICENSE)
+- [SECURITY.md](SECURITY.md)
+
 ## Development
 
 ```bash

coretrace_python_analyzer-0.22.0/SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes target `main` and the latest tagged release, when one exists. Older tags are not maintained. Include the exact tag or commit in a report.
+
+## Reporting a vulnerability
+
+Report privately through [GitHub private vulnerability reporting](https://github.com/CoreTrace/coretrace-python-analyzer/security/advisories/new). Do not publish a suspected vulnerability in an issue or pull request.
+
+Include reproduction steps, expected and observed behavior, the affected platform and version, and the possible impact. Remove credentials and other sensitive data from examples.
+
+## Scope
+
+CoreTrace Python Analyzer parses and analyzes source trees and dependency metadata. Reports about crafted input, unsafe file access or report generation should include a sanitized sample and the command used.

{coretrace_python_analyzer-0.20.0 → coretrace_python_analyzer-0.22.0}/docs/plugins.md

@@ -127,6 +127,19 @@ judges by its own criteria. The refutation's
 verdict, which other consumers of the flow such as the advisory correlation read, does
 not change; a rule reading more analyses declares them in its `requires`.
 
+A rule that tells cases of its sinks apart by severity too overrides `assess(ctx,
+function, flow, verdict)`, which returns an `Assessment` of the verdict and the
+severity; by default it pairs `judge`'s verdict with the rule's `severity`. A `hotspot`
+verdict lowers the confidence of the finding, never its severity. An `Assessment` may
+also carry a `title` for the finding's message instead of the rule's, and `metadata`
+the finding carries besides the flow's; the rule id never changes, so suppressions and
+baselines keep matching. `command-injection`
+reads there the command a flow reaches (`coretrace_python.taint.commands`): a shell
+string or the program is `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.
+It sets the `injection` metadata (`command` or `option`, the latter titled `Option
+injection`) only when it establishes what the input is.
+
 ### Security models: `ModelPlugin`
 
 Declares sources, sinks and sanitizers for a library or a framework. A model plugin
@@ -195,8 +208,12 @@ A model plugin may also carry `advisories`, a tuple of `Advisory` values
 symbols, as the shipped `sample-advisories` plugin does. Requirements matching them are
 reported, calls to the affected symbols become reachable vulnerabilities and tainted
 calls become exploitable ones. An advisory's entry points carry `conditions`, of kind
-`argument`, `host`, `semantic` or `keyword_name`, and `attacker_arguments`, decided as
-the [usage guide](usage.md) describes.
+`argument` (on the value, or with `present` on the argument being passed at all),
+`host`, `semantic`, `keyword_name` or `sequence`, and `attacker_arguments`, decided as
+the [usage guide](usage.md) describes. An entry point may also declare `suffixes`,
+matched against the tail of a derived symbol of the project's own modules on dot
+boundaries, as a `SuffixSink` matches, for receivers the engine cannot type (see the
+usage guide).
 
 ### Reclassifying findings: `ProjectPlugin.refine`
 
@@ -251,6 +268,10 @@ class InternalSecrets(SecretDetector):
     credential_names: ClassVar[tuple[str, ...]] = (*DEFAULT_CREDENTIAL_NAMES, "acme_key")
 ```
 
+A pattern whose regex names a `secret` group (`(?P<secret>...)`) is judged on that group:
+a match whose secret is a placeholder (`...`, `<token>`, `${VAR}`, fewer than four
+characters) is not reported, as with credential names.
+
 `entropy_threshold`, `hex_entropy_threshold` and `minimum_length` tune the high-entropy
 rule. Findings carry a redacted preview only.
 
@@ -304,8 +325,12 @@ any analysis result: `SSAAnalysis` (`coretrace_python.ir.ssa`) for the code,
 ## Findings
 
 A `Finding` (`coretrace_python.findings`) has a `rule_id`, a `message`, a `Severity`, a
-`Confidence`, a `SourceSpan` (file, start and end line and column), the enclosing
-`function` and string `metadata`. Rule ids are lower-case words joined by dashes.
+`Confidence`, a location, the enclosing `function` and string `metadata`. Rule ids are
+lower-case words joined by dashes. The location (`span`) is a `SourceSpan` (file, start
+and end line and column) when the line is established, or a `FileLocation` (file and the
+JSON pointer of a value) for a value of a structured file whose line cannot be: a plugin
+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).
 
 ## Testing a plugin
 

{coretrace_python_analyzer-0.20.0 → coretrace_python_analyzer-0.22.0}/docs/usage.md

@@ -56,6 +56,8 @@ coretrace-python-analyzer [--check | --emit-ir [--ssa]] [options] [path]
 | `--import-advisories SRC OUT` | Convert an OSV dump into the local advisory file `OUT`, then exit. |
 | `--fail-on SEVERITY` | Exit with status 1 only when a finding of this severity or above was reported: `info`, `low`, `medium`, `high` or `critical`. Default: any finding. |
 | `--baseline PATH` | The accepted findings: written on the first run, then only findings not recorded there fail the check. |
+| `--baseline-key-file FILE` | With `--baseline`, the file holding the key of a keyed baseline (schema 4), kept out of the analysed directory; read before `CORETRACE_BASELINE_KEY`. |
+| `--record-baseline` | With `--baseline`, record the current findings as the baseline, replacing the file only once the check succeeded. |
 | `--emit-ir` | Print the intermediate representation of `path` instead of checking it. |
 | `--ssa` | With `--emit-ir`, print the static single assignment form. |
 | `--help` | Show the options and exit. |
@@ -84,7 +86,10 @@ get_asgi_application()` in `asgi.py` or `email = forms.EmailField()` in a form c
 calls the analyzer sees, and a module-level `os.system(input())` is a finding in `<module>`.
 A function using syntax outside the supported subset is reported as an
 `unsupported-syntax` note and the other functions are still analysed; a file Python
-itself cannot parse is reported as a `syntax-error`. The coverage line and the JSON
+itself cannot parse is reported as a `syntax-error`, and so is a file whose syntax is
+nested more than 200 levels deep (a chain of hundreds of `+` or chained calls, which only
+generated code writes), which the analyzer does not follow; the other files are still
+analysed. The coverage line and the JSON
 report's per-file detail tell "no findings" from "nothing analysed".
 
 Taint follows values between functions and across files through function summaries,
@@ -115,7 +120,7 @@ variable is not treated that way yet.
 
 | Rule | Reached sink |
 |---|---|
-| `command-injection` | Shell or process execution (`os.system`, `subprocess` with a string, …). |
+| `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, the program itself, or an operand the program runs as a command (after the host for `ssh`, the program of `sudo`, `env`, `xargs`, `timeout`…, any argument of a batch file) is `high`. The script an interpreter runs (`bash run.sh`, `python tool.py`, its first operand when no option such as `-c` gives the code), or the module of `python -m`, is `high` and kept for review: execution is possible, and its exploitability depends on the file the input chooses. The arguments after a script or code are the script's own: options of unknown meaning, reported `medium` (a hotspot after an option of the script), refuted behind a constant prefix. Otherwise 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=…`). A value a documented option takes is judged by what the option does with it, whatever its prefix: run it (`sh -c`, `cmd /c`, `python -c`: `high`), keep it as data (`git commit -m`: refuted). After an option the rule does not know, the finding stays a hotspot to review. A constant prefix that keeps a standalone input from being an option (`f"v{version}"`), or an operand after `--` for a program that honours it, is refuted. Every case keeps the rule id `command-injection`, so suppressions and baselines match whatever the case. When the rule reads the command element by element and establishes what the input is there, the finding's `injection` metadata (in the JSON report, and as the only property of its SARIF result) says so: `command` when the input runs or chooses what runs (a shell string, the program, an operand run as a command, the value of an option that runs it); `option` when it can only reach the program as an option or as the value of an option not established to run it, and the message is then titled `Option injection`. When that cannot be established (an option whose effect is to review, an unknown program or element before the input, a command that is not a list or tuple display, a sink such as `os.system` the rule does not read element by element), the metadata is absent and the title stays `Command injection`. |
 | `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. |
 | `sql-injection` | A database statement (`cursor.execute`, SQLAlchemy `text`, Django `raw`, …). Parameters of a parameterised query are not statements. |
 | `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. |
@@ -215,7 +220,8 @@ The comment also works in requirements files, where a line
 `pyyaml==5.3.1  # coretrace: ignore[vulnerable-dependency]` silences that requirement's
 finding. Suppressed findings are kept apart: the text report counts them, the JSON report
 lists them under `suppressed`, the SARIF log marks them as suppressed in source, and
-they never affect the exit status.
+they never affect the exit status. A comment only suppresses a finding located at a
+verified line; a finding with a file location (see Reports) is never suppressed this way.
 
 ## Adopting the analyzer on an existing code base
 
@@ -227,12 +233,62 @@ coretrace-python-analyzer --check src/ --baseline coretrace-baseline.json
 
 The first run writes the file with every current finding and passes. Later runs set the
 recorded findings apart and fail only on new ones. A finding is recognised by its file,
-its rule, its function and the text of its line, not by its line number, so code inserted
-above it does not make it new; a change to the line itself does. Commit the file and
-shrink it as findings are fixed: an entry without a matching finding is simply unused.
+its rule, its function and the text of every line it covers, not by its line number, so
+code inserted above it does not make it new; a change to its text does, on any of its
+lines, such as the body of a key written over several lines. Commit the file and shrink
+it as findings are fixed: an entry without a matching finding is simply unused.
 Baselined findings are counted in the text report, listed under `baselined` in the JSON
 report and marked `baselineState: unchanged` in the SARIF log, where new results are
-marked `new`.
+marked `new`. A finding with a file location is recognised by the JSON pointer of its
+value and its value instead of the text of a line, so a new value at the same place is a
+new finding. Entries hold a digest of that text, value and pointer, never the text
+itself, so no accepted secret is stored in plain text. That does not make the file
+confidential: a digest does not hide a weak secret from whoever guesses it, since a
+guessed password, hashed with its line, can be checked against the file. Treat the
+baseline as a possibly sensitive file, or key it.
+
+A keyed baseline does not let candidate values be tested without its key. The key comes
+from the file `--baseline-key-file` names, or else from the `CORETRACE_BASELINE_KEY`
+environment variable, as a CI secret; the file comes first when both are given. The check
+refuses a key file inside the analysed directory, however its path is spelled, or the
+baseline itself; keep it out of the whole repository too, which the check cannot tell
+(a hard link escapes it as well). Generate the key at random, for instance with
+`python -c "import secrets; print(secrets.token_hex(32))"`, and share it as a secret
+(a CI secret, a password manager): a key a person chooses can be guessed from the
+baseline. It is at least 16 bytes long, and trailing line breaks are not part of it, from
+the file or the variable alike; an empty variable is an error, as a CI job whose secret
+is missing passes one. Every process of the check, plugins and `--jobs` workers included,
+can read the variable. With a key, the
+baseline is recorded in schema 4: every digest is an HMAC-SHA-256 under the key, and a
+check value, never the key, tells which key recorded it. The key appears in no report,
+message or file the check writes. A schema 4 baseline needs its key: without it, or
+with another, the check stops with an explicit error, exit status 2, and records
+nothing. Recording over a schema 4 baseline without its key is refused too, rather than
+turning it back into an unkeyed one: delete the file to do that explicitly. Without a
+key, baselines are recorded in schema 3, with the guarantee above.
+
+`--record-baseline` records the current findings as the baseline even when the file
+exists, under the key given, if any; the file (the target of a symbolic link) is
+replaced at once, keeping its permissions, only once the analysis succeeded and its
+report is rendered, so the previous baseline stays in place when the check fails. Review the findings
+before recording: they all become accepted. Rotating the key is such a record under the
+new key, once the findings are reviewed; the old key then no longer reads the baseline.
+
+Baselines are written in schema 3, or in schema 4 with a key. A file written by an
+earlier version, in schema 1 or 2, is still read and never rewritten, and the check warns
+on standard error, once per run, that it may contain secrets in plain text: its entries
+hold the text of each
+finding's first line. They match exactly as they did a finding on a single line; a
+finding over several lines, whose other lines they do not hold, is reported as new, and
+so is a finding in a JSON, TOML or lock file that a schema 1 entry, recorded with the
+text of its key's first line, cannot identify with certainty. The exit status depends
+on the findings only. Review such a baseline and its new findings, then migrate it
+explicitly with `--record-baseline`, to schema 3, or to schema 4 with a key. While a key
+is given, only a schema 4 baseline is read: an unkeyed one (schema 1, 2 or 3) stops the
+check with an error, so that it cannot stand in for the keyed one; review it, then record
+it in schema 4 with `--record-baseline`. No baseline is ever converted or rewritten
+without `--record-baseline`. The
+old file's secrets remain in the history of a repository that committed it.
 
 ## Reports
 
@@ -247,7 +303,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.20.0"},
+  "tool": {"name": "coretrace-python-analyzer", "version": "0.22.0"},
   "root": "/home/me/project",
   "findings": [
     {
@@ -267,6 +323,17 @@ the directory of the checked file; a path outside it is printed as it is.
 }
 ```
 
+Lines are counted as Python counts them, by `\n`, `\r\n` or a lone `\r` (never U+2028
+or a form feed), in every report, suppression and baseline. A value of a JSON or TOML
+file, a package of a lock file, or a requirement of `pyproject.toml`, is located at its own line,
+which a separate component establishes from the value's structural path and checks
+against the value. When it cannot (a dotted TOML key, an inline table, a multi-line
+value), the finding gets a file location instead of a guessed line: `line`, `column`,
+`end_line` and `end_column` are `null`, and `pointer` gives the JSON pointer of the value
+in the file (`"/tool/app/api_token"`). The SARIF log gives such a result no `region`,
+with the pointer under the location's `properties`, and the text report shows the file
+alone (`settings.toml: high hardcoded-credential: …`).
+
 `root` is the directory the paths are relative to. A file's `status` is `analysed`,
 `ambiguous` (analysed, but another file has its module name, see above), `syntax-error`
 or `unreadable`; only `analysed` files count in `files_analysed`.
@@ -281,7 +348,7 @@ bytes. A single-file check lists no components.
 
 ```json
 "tool": {
-  "name": "coretrace-python-analyzer", "version": "0.20.0",
+  "name": "coretrace-python-analyzer", "version": "0.22.0",
   "components": [
     {"kind": "plugin", "name": "curated-advisories", "version": "2026.09.25", "digest": "sha256:…"},
     {"kind": "advisories", "name": "advisories.json", "digest": "sha256:…"}
@@ -370,6 +437,29 @@ it is reachable, called or not — `request.form['name']`, `for key in request.f
 `request.form.get('name')` all read it. A function reading it several times is reported
 once, where it first reads it.
 
+An entry point may declare `suffixes`, for receivers the engine cannot type. A project
+reaches `python.django.db.models.QuerySet.annotate` through a manager on its own model,
+`Item.objects.annotate(...)`, whose call derives the project's own symbol
+`python.app.models.Item.objects.annotate` — `Item` is a project class, `objects` an
+attribute the engine does not type — so the canonical entry point never matches. A
+suffix matches any symbol of the project's own modules ending with a dot plus the
+suffix:
+
+```json
+{"symbol": "python.django.db.models.QuerySet.annotate", "justification": "…",
+ "suffixes": ["objects.annotate", "objects.filter.annotate"]}
+```
+
+A queryset chain is declared explicitly: `Item.objects.filter(...).annotate(...)`
+derives `…objects.filter.annotate`, which only the second suffix matches. A suffix is
+at least two dot-separated names, so a bare method name, matching every project method
+of that name, cannot be declared; another package's symbol, such as
+`other_lib.objects.annotate`, never matches. The finding names the advisory's symbol as
+`entry_point` and the derived one as `symbol`, and the entry point's conditions and
+`attacker_arguments` apply through a suffix as through the exact symbol. A project
+attribute chain genuinely ending with a declared suffix matches too — the vulnerable
+version range and the conditions still gate what is reported.
+
 A filter of Django's own libraries that a project template applies is a call to the
 function behind it, placed at the template's line: `{{ bio|striptags }}` calls
 `python.django.template.defaultfilters.striptags`, and so do filters in tag arguments
@@ -471,6 +561,16 @@ a call passing a variable, or unpacking `*args` or `**kwargs`, leaves the condit
 pending review. A `semantic` condition — the document's tags, the platform, the
 template's origin — cannot be decided and is always pending review, never dropped.
 
+An `argument` condition with `"present": true` says the argument being passed at all,
+whatever its value, is the condition, as a `\r` in `web.Response(reason=…)` needs
+`reason` given, constant or not: `{"kind": "argument", "text": "…", "argument":
+"reason", "position": 1, "present": true}`, exclusive with `values` and `default`. A
+call giving the argument — positionally, by keyword, or through a `**` literal with
+constant keys, which is folded into the keywords — meets it even when the value is
+unknown; a call surely not giving it does not reach the vulnerability and is ruled out
+(`(reason absent)`); a call unpacking `*args` or a `**mapping` whose keys the engine
+cannot read leaves it pending review.
+
 A `host` condition says the attacker must choose the host of the URL passed as
 `argument` (or at `position`), as credentials leaking to the host of a crafted URL
 need: `{"kind": "host", "text": "…", "argument": "url", "position": 0}`. It is
@@ -514,6 +614,47 @@ Keys passed through a project wrapper stay pending, and `mapping.update(other)`,
 taint. A literal the function fills after building it (`m = {}; m[alias] = expr`)
 has keys the literal does not write, so the call is not ruled out.
 
+A `sequence` condition says the flaw spans two calls on one receiver: a first call
+leaves state on the object, and the entry point — the second call — reuses it, as
+`Session.get(url, verify=False)` disables certificate verification for the pooled
+connection a later `Session.get(other)` on the same session reuses (requests
+CVE-2024-35195). It names the `method` the first call must be, by canonical name or
+`.`-suffix, and, optionally, the argument that call must carry, read as an argument
+condition reads it:
+
+```json
+{
+  "kind": "sequence",
+  "text": "a prior call on the same session disabled certificate verification",
+  "method": "Session.get",
+  "argument": "verify",
+  "values": ["False"]
+}
+```
+
+The engine follows a receiver bound once in the analysed function to the result of a
+call or a `with` and used only to call its methods. The outcome has three cases:
+
+- A prior call on the same receiver, on every path to the entry call, matches the
+  method and carries a value in `values` (`default` for an absent argument): the
+  condition is met, and the evidence names that call's line.
+- The receiver's whole lifetime is visible and no such prior call can precede — one
+  call alone on the receiver, or the two calls on different receivers: the condition
+  is contradicted, the call is ruled out
+  (`app.fetch:6 python.requests.Session.get(no prior Session.get on the receiver)`)
+  and a project with only such calls stays `not_affected`.
+- Otherwise the condition stays pending review: a receiver the engine cannot follow —
+  a parameter, a module-level instance, one passed to another function or mutated
+  through an attribute such as `s.verify = False` — a prior call whose arguments a
+  `*`/`**` unpacking leaves undecided, or a flow reaching the entry point inside a
+  callee.
+
+Only a prior call on every path to the entry call counts as before it: a matching
+call in a branch that may not run, or a textually later one, leaves the condition
+pending, since a loop may bring it before the entry call. A call that itself carries
+what the condition requires of the first call is never ruled out either: across the
+iterations of a loop it is its own prior.
+
 Every dependency finding records the highest level of evidence established in its
 `level` metadata: `declared` (the requirement allows a vulnerable version), `imported`
 (a module of the package is imported somewhere), `reachable` (an entry point or affected
@@ -577,7 +718,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.20.0; curated-advisories 2026.09.25 (sha256:…)`), so the
+(`coretrace-python-analyzer 0.22.0; curated-advisories 2026.09.25 (sha256:…)`), so the
 `@id` changes with the advisory data a statement was decided with.
 
 ## Large projects

{coretrace_python_analyzer-0.20.0 → coretrace_python_analyzer-0.22.0}/pyproject.toml

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