hackscan 0.1.0__tar.gz → 0.3.0__tar.gz

hackscan-0.3.0/.github/workflows/hackscan.yml

@@ -0,0 +1,22 @@
+name: HackScan
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./
+        with:
+          path: src
+          fail-on: high
+          # Fork pull requests get a read-only token, so the Code Scanning upload is skipped there.
+          upload-sarif: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}

{hackscan-0.1.0 → hackscan-0.3.0}/.gitignore

@@ -11,3 +11,10 @@ htmlcov/
 *.sarif
 !tests/fixtures/**/*.sarif
 .hackscan-cache/
+
+# Local tool caches/sandbox scratch (never packaged)
+.uv-cache/
+.test-tmp/
+
+# benchmark downloads
+benchmarks/.cache/

hackscan-0.3.0/.pre-commit-hooks.yaml

@@ -0,0 +1,9 @@
+- id: hackscan
+  name: HackScan
+  description: Scan the repository for Python security findings.
+  language: python
+  entry: hackscan scan
+  args: [".", "--fail-on", "high"]
+  pass_filenames: false
+  types: [python]
+  require_serial: true

hackscan-0.3.0/PKG-INFO

@@ -0,0 +1,340 @@
+Metadata-Version: 2.5
+Name: hackscan
+Version: 0.3.0
+Summary: Python SAST orchestrator: own AST + taint engine, imports Semgrep/Bandit/CodeQL/Gitleaks, dedupes, emits SARIF.
+Project-URL: Source, https://github.com/kahledawad2019-netizen/hackscan
+Project-URL: Issues, https://github.com/kahledawad2019-netizen/hackscan/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: sarif,sast,security,static-analysis,taint-analysis,vulnerability-scanner
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=13.7
+Description-Content-Type: text/markdown
+
+# HackScan
+
+**A Python security scanner that verifies what it reports.** HackScan finds injection
+sinks with its own AST engine, then runs a flow-sensitive taint analysis to decide, per
+finding, whether untrusted input really reaches it. It can also ingest Semgrep, Bandit,
+CodeQL and Gitleaks results, merge duplicates across tools, and emit one SARIF report.
+
+```text
+$ hackscan scan app/
+HIGH     confirmed  views.py:10:9  HS-SQLI-001  [100%]
+    SQL query is built with string formatting/concatenation.
+    | cursor.execute("SELECT * FROM sales WHERE year = " + year)
+    > Untrusted request data (`request.GET`) at line 8.
+    > Untrusted input reaches the sink.
+```
+
+## Why another scanner?
+
+| | HackScan |
+|---|---|
+| **Verdicts, not just matches** | Every injection candidate is **confirmed** (untrusted source reaches it, with a trace), **suppressed** (provably constant or sanitized on every path), or left as a **candidate** for review. |
+| **Sound suppression** | A finding is only dismissed if *every* path is safe. Branches, loops (`break`/`continue`), `try`/`except`/`finally`, aliasing and mutation of lists/dicts, closures and `:=` are modeled. A differential fuzzer executes thousands of random programs to check that no dismissed sink ever receives attacker input. |
+| **Across functions and files** | A sink fed by a function parameter is confirmed when a caller anywhere in the scanned code passes untrusted data (directly or through other functions), or when a called function returns it; the trace names the source file and line. |
+| **Framework-aware** | Sources: Flask `request.*`, Django/DRF/Starlette/FastAPI request objects (incl. `self.request`), route-handler parameters, `input()`, `sys.argv`. |
+| **One report from many tools** | Imports Semgrep, Bandit, CodeQL (SARIF) and Gitleaks; deduplicates by vulnerability class and location, keeping every tool as provenance. |
+| **Fixes you can apply** | Mechanical, validated fix suggestions: parameterized queries (driver-aware placeholders), argument lists instead of shell strings, `ast.literal_eval`, SHA-256. Each is an exact edit that re-parses; ambiguous cases get no fix rather than a wrong one. |
+| **Optional local-LLM triage** | `--llm` asks a local Ollama model about remaining candidates. It can confirm, but may only suppress by citing a line that HackScan verifies itself (an allow-list guard, constant or sanitizer that holds on every path). Code is treated as untrusted data; secrets are redacted. |
+| **CI-ready** | SARIF 2.1.0 (validated against the OASIS schema) for GitHub code scanning, `--fail-on` exit codes, stable fingerprints that survive code moves. |
+
+## Install
+
+```bash
+pip install hackscan        # or: uv tool install hackscan / pipx install hackscan
+```
+
+Python 3.10–3.13, any OS. No network access and no LLM needed (`--llm` is opt-in).
+
+## Usage
+
+```bash
+hackscan scan .                                   # text report
+hackscan scan . --format sarif -o hackscan.sarif  # for GitHub code scanning
+hackscan scan . --fail-on high                    # exit 1 on open high/critical findings
+hackscan scan . --format json --show-suppressed   # everything, machine-readable
+hackscan scan . --with bandit,semgrep,gitleaks    # also run these tools if installed
+hackscan scan . --import codeql=results.sarif     # merge a report you already have
+hackscan scan . --show-fixes                      # include fix suggestions as diffs
+hackscan scan . --llm --model qwen2.5-coder:7b    # triage candidates with local Ollama
+hackscan rules                                    # list rules
+```
+
+| Option | Meaning |
+|---|---|
+| `--severity`, `--min-confidence` | Report filters. |
+| `--fail-on SEV` | Exit 1 if an open (candidate/confirmed) finding is at least `SEV`. Suppressed findings never count. `never` turns off a threshold set in `.hackscan.yml`. |
+| `--ignore GLOB` | Skip paths (`tests/*`, `**/migrations/**`, `legacy`). `.venv`, `node_modules`, `build`, ... are always skipped. |
+| `--with TOOLS` / `--import FMT=FILE` | Run external tools / import reports (`sarif`, `semgrep`, `bandit`, `codeql`, `gitleaks`). A missing or failing tool is a warning unless `--strict-tools`. |
+| `-o FILE` | Write the report to `FILE`. Never overwrites anything except a previous HackScan report. |
+| `--plugins DIR` | Load custom rules (see below). |
+| `--allow-incomplete` | Do not exit 2 when some files cannot be analyzed (they are still listed). |
+| `--no-taint` | Pattern matching only. |
+| `--show-fixes` / `--no-fix` | Print suggested fixes as diffs / do not generate fixes (fixes are also in JSON and SARIF `fixes`). |
+| `--llm`, `--model`, `--ollama-host` | Opt-in LLM triage of candidates via Ollama (default `http://localhost:11434`). |
+| `--llm-max`, `--llm-timeout`, `--llm-no-suppress` | LLM budget (default 20 findings, 60 s/request); let the LLM confirm/annotate but never suppress. |
+| `--color auto\|always\|never` | Rich terminal output; `auto` uses it only on an interactive terminal (not in CI, pipes or with `NO_COLOR`). |
+| `--jobs N` | Worker processes (default: automatic). |
+
+Exit codes: `0` OK, `1` `--fail-on` threshold reached, `2` usage/config/plugin error or
+an **incomplete scan** (a file could not be parsed or read, or an `--import` report
+could not be loaded; use `--allow-incomplete` to accept). A `--with` tool that is missing
+or exits with an error is a warning, or exit `2` with `--strict-tools`. An incomplete scan is never reported as a pass, and SARIF marks it with
+`executionSuccessful: false`.
+
+### Configuration
+
+`.hackscan.yml` files are discovered from the filesystem root down to the scanned
+directory and merged (nearest wins; `ignore` lists accumulate). CLI options override them.
+
+```yaml
+ignore: [tests/*, "**/migrations/**"]
+severity: medium
+min-confidence: 40
+fail-on: high
+with: [bandit]
+import:
+  codeql: codeql-results.sarif
+plugins: security/rules
+llm: false
+llm-model: qwen2.5-coder:7b
+```
+
+### LLM triage
+
+`--llm` sends each remaining *candidate* (never confirmed or suppressed findings) with
+its surrounding function to a local Ollama model and asks for a verdict:
+
+- **true positive**: the finding becomes *confirmed* (+15 confidence); a suggested fix is
+  kept only if the patched file parses and a re-scan shows the finding gone and nothing new.
+- **false positive**: only accepted if the model cites a line that HackScan verifies runs
+  on every path and makes the value safe: an allow-list guard (`if x not in {...}: return`,
+  `if not x.isdigit(): raise`, or `if not x.isdecimal(): raise`), a constant, or a
+  class-appropriate sanitizer. `isnumeric()`, `isalnum()`, `isalpha()`, and
+  `isidentifier()` do not qualify. Otherwise the reasoning is attached as a note and
+  the finding stays open.
+- Code is fenced with a random per-request token and treated as untrusted data; replies
+  must match a JSON schema; secret-looking values are redacted; answers are cached.
+
+Use a non-reasoning instruct or coder model. Measured on a CPU-only laptop (~30 s per
+finding): `qwen3:4b-instruct-2507` judged a real injection, a bypassable length check and
+an allow-list guard correctly; `qwen2.5-coder:3b` never suppressed but also missed the
+allow-list guard (larger models do better). Reasoning models such as `deepseek-r1` often
+spend their whole output budget thinking, which HackScan reports as "no answer" and
+leaves the finding open. In the same test both small models obeyed a comment in the
+scanned code telling them to answer "false positive"; the deterministic evidence check
+rejected it and the finding stayed open. That check, not the model, decides suppression.
+
+### Suppressing a finding
+
+```python
+os.system(cmd)  # hackscan: ignore[HS-CMDI-001]
+```
+
+Suppressed findings stay in SARIF output (as `suppressions`) so they remain auditable;
+use `--sarif-omit-suppressed` when uploading to GitHub, which does not honor them.
+
+Secrets are never echoed: findings of class `secret` (from any tool) have generic
+messages and redacted snippets, and values reported by Gitleaks are scrubbed from all
+output, including warnings.
+
+## Benchmark
+
+**Labeled suite.** Flask, Django, FastAPI and CLI code with 26 vulnerable sinks and 24
+look-alike safe traps (SQL, command and code injection, weak crypto), scored per function;
+each tool runs the configuration in its Version column (Bandit: all checks; Semgrep CE:
+the `p/python` ruleset; CodeQL: `python-security-extended`; HackScan: no options)
+([methodology and caveats](benchmarks/README.md), [full results](benchmarks/RESULTS.md)):
+
+| Tool | Version | TP | FP | FN | Precision | Recall | F1 |
+|---|---|---:|---:|---:|---:|---:|---:|
+| HackScan | 0.3.0 | 23 | 7 | 3 | 77% | 88% | 82% |
+| HackScan (confirmed only) | 0.3.0 | 18 | 2 | 8 | 90% | 69% | 78% |
+| Bandit | bandit[sarif]==1.9.4 | 24 | 19 | 2 | 56% | 92% | 70% |
+| Semgrep CE | semgrep==1.180.0 (p/python sha256:31c1dfa46e8d) | 16 | 6 | 10 | 73% | 62% | 67% |
+| CodeQL | CodeQL 2.27.2 (codeql/python-queries@1.8.12, security-extended) | 20 | 1 | 6 | 95% | 77% | 85% |
+
+**Known-vulnerable apps.** [vulpy](https://github.com/fportantier/vulpy),
+[PyGoat](https://github.com/adeyosemanputra/pygoat) and
+[DVPWA](https://github.com/anxolerd/dvpwa) at pinned commits; every report reviewed by
+hand. There is no complete ground truth, so recall is relative to the 21 distinct
+vulnerabilities any tool found ([details](benchmarks/APPS.md)):
+
+| Tool | Reports | TP | FP | Vulns found | Precision | Relative recall |
+|---|---:|---:|---:|---:|---:|---:|
+| HackScan | 18 | 15 | 3 | 15 | 83% | 71% |
+| HackScan (confirmed only) | 6 | 6 | 0 | 6 | 100% | 29% |
+| Bandit | 32 | 16 | 16 | 16 | 50% | 76% |
+| Semgrep CE | 12 | 11 | 1 | 11 | 92% | 52% |
+| CodeQL | 15 | 15 | 0 | 14 | 100% | 67% |
+
+CodeQL is the most precise; Bandit finds a little more but about half of its reports are
+noise. HackScan sits in between: higher recall than CodeQL and Semgrep, higher
+precision than Bandit. Its misses are weak ciphers (DES, RC4, ECB, unauthenticated
+modes), which its rule does not cover yet, and flows it does not follow (`self`
+attributes, ambiguous module names). Its false positives are sinks it cannot prove safe (allow-list
+guards, functions only called with constants). The suite is small and written by
+HackScan's authors, so treat both tables as a sanity check rather than a ranking.
+
+## Rules
+
+| Rule | Detects | Severity |
+|---|---|---|
+| `HS-SQLI-001` | Non-constant SQL reaching DB-API `execute*`, Django `raw`, SQLAlchemy `text`, pandas `read_sql` | high |
+| `HS-CMDI-001` | Non-constant commands reaching `os.system`, `os.popen`, `subprocess.*(shell=True)`, ... | high |
+| `HS-CODEI-001` | Non-constant input to `eval`, `exec`, `compile` | high |
+| `HS-CRYPTO-001` | MD5/SHA-1 (unless `usedforsecurity=False`) | low |
+
+Sanitizers recognized: numeric/UUID conversions (all classes), `psycopg` `sql.Identifier`
+/`sql.Literal` (SQL). `shlex.quote` is POSIX-only, so quoted commands are kept as
+low-confidence candidates rather than suppressed.
+
+### Custom rules
+
+```python
+# security/rules/pickle_rule.py
+from hackscan.core.models import Severity
+from hackscan.plugins import Match, RulePlugin
+
+
+class PickleLoads(RulePlugin):
+    rule_id = "ACME-PICKLE-001"  # the HS- prefix is reserved
+    name = "pickle-loads"
+    description = "pickle.loads on untrusted data"
+    severity = Severity.HIGH
+    cwe = ("CWE-502",)
+
+    def check(self, node, ctx):
+        if "pickle.loads" in ctx.call_names(node):
+            yield Match(node, "pickle.loads call")
+```
+
+## GitHub Actions
+
+The repository is a composite action (available from v0.3.0). It installs HackScan, writes
+SARIF, uploads it to GitHub Code Scanning and then fails the job if the `fail-on` threshold
+was hit, so findings appear in the Security tab even on a failing run.
+
+```yaml
+permissions:
+  contents: read
+  security-events: write   # needed for the Code Scanning upload
+  actions: read            # needed for the upload in private repositories
+
+jobs:
+  hackscan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: kahledawad2019-netizen/hackscan@v0.3.0
+        with:
+          path: src
+          fail-on: high
+```
+
+| Input | Default | Meaning |
+|---|---|---|
+| `path` | `.` | File or directory to scan |
+| `version` | *(empty)* | HackScan version from PyPI; empty installs the action's own checkout |
+| `fail-on` | `high` | Fail at this severity or above; empty passes `--fail-on never` (HackScan 0.3.0+), so findings never fail the job but crashes and errors still do |
+| `args` | *(empty)* | Extra CLI arguments, word-split without globbing; pass only trusted values |
+| `sarif-file` | `hackscan.sarif` | Report path |
+| `upload-sarif` | `true` | Upload to Code Scanning (skip it for fork pull requests, whose token is read-only) |
+
+Outputs: `sarif-file` and `exit-code` (0, 1 = threshold hit, 2 = error). The action sets up
+Python 3.12 on the runner. Without the action:
+
+```yaml
+- run: pipx install hackscan
+- run: hackscan scan . --format sarif --sarif-omit-suppressed -o hackscan.sarif --fail-on high
+- uses: github/codeql-action/upload-sarif@v4
+  if: always()
+  with:
+    sarif_file: hackscan.sarif
+```
+
+## pre-commit
+
+```yaml
+repos:
+  - repo: https://github.com/kahledawad2019-netizen/hackscan
+    rev: v0.3.0
+    hooks:
+      - id: hackscan
+```
+
+The hook runs `hackscan scan . --fail-on high` once per commit that touches Python files. It
+scans the whole repository (the CLI takes a single path), so `.hackscan.yml` `ignore` globs
+apply as usual.
+
+## Limitations
+
+- Taint analysis follows calls across functions and files only to *confirm* findings: a
+  sink fed by a parameter is confirmed when some caller in the scanned code passes
+  untrusted data, or when a called function returns it. It never suppresses a finding
+  (callers outside the scan are unknown). Only undecorated module-level functions bound
+  once are linked (same module, `import`/`from ... import`, relative imports and
+  re-exports); methods, nested functions, decorated functions, modules with a star
+  import, `*args`/`**kwargs` call sites and module names that match more than one file
+  are not followed. Sources are not tracked through object attributes or globals. The
+  result of a call is assumed to carry its arguments, so a helper that sanitizes them
+  (`def clean(x): return int(x)`) does not prevent a confirmation.
+- Findings in a function (or module) that itself uses `:=` are never suppressed, only
+  confirmed or left as candidates: an assignment expression can rebind a name in the
+  middle of an expression, which the statement-level analysis does not order. Sinks in
+  the body of a generator expression are never suppressed either (it runs later), nor
+  are values produced by one. Module-level constants are trusted only when bound exactly
+  once and the module never writes its namespace dynamically (`globals()`, `vars()`,
+  `exec`, `eval`, `__dict__`, star imports); `global`/`nonlocal` names are never trusted.
+- Mutable objects (lists, dicts, sets) are tracked by variable name. Mutation through
+  direct aliases, method calls (`d.get(k).append(x)`), bound methods
+  (`add = parts.append`), conditional receivers and comprehension items is modeled;
+  aliases created in less direct ways (stored in another object's attribute or in a
+  container and mutated through it later, returned from a helper, reached through
+  `getattr`) may be missed, so a constant suppression involving such code deserves review.
+- Python only. Imported tools may cover other languages; their findings are passed through.
+- Fix suggestions are deliberately conservative: many vulnerable lines get none. Command
+  fixes (argument lists) are only offered for programs whose arguments are inert data
+  (`cat`, `ls`, `grep`, `head`, ...): many others run operands or options as
+  commands (`sh -c`, `npx PKG`, `git -c alias=!cmd`, `tar --to-command`). They are also
+  not offered when a value directly follows a flag; put `--` before operands to get one.
+  A value starting with `-` can still be read as an option, so review command fixes. No
+  fix is offered for a call that contains a secret, or for SQL containing comments.
+- SQL fixes are not offered for unquoted values inside parentheses, double-quoted
+  identifiers, or SQL text containing backslashes, `$`, backticks or brackets;
+  redaction of values that coincide with identifiers or tool metadata is best-effort.
+- String and bytes literals assigned to secret-looking names (`api_key`, `password`, `token`, ...)
+  are masked in snippets, the LLM context and fix diffs. Their values are also removed
+  from imported messages and evidence before output or LLM triage when the value is
+  secret-like (at least eight characters with a digit or symbol, or at least sixteen
+  characters). Known secrets in proposed fixes cause the fix to be omitted. Imported
+  findings for files that cannot be parsed have no source snippet.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+```
+
+See [PROJECT.md](PROJECT.md) for the design, milestones and decision log.
+
+## License
+
+MIT

{hackscan-0.1.0 → hackscan-0.3.0}/PROJECT.md

@@ -128,9 +128,9 @@ mature scanners, (3) taint-based confirmation, (4) optional local-LLM triage and
 | 13 | Ollama triage pass with graceful offline fallback | M4 |
 | 14 | Template + LLM remediation as validated edits; diff view | M4 |
 | 15 | Rich "Matrix" TUI (banner, spinners, tables); auto-off in CI / `--quiet` | M4 |
-| 16 | Inter-procedural & cross-file taint (own call graph from `ast`) | M5 |
-| 17 | Benchmark harness vs Bandit / Semgrep CE / CodeQL; published precision/recall | M5 |
-| 18 | GitHub Action (uploads SARIF to Code Scanning), pre-commit hook | M5 |
+| 16 | Inter-procedural & cross-file taint (own call graph from `ast`) | M5 ✅ |
+| 17 | Benchmark harness vs Bandit / Semgrep CE / CodeQL; published precision/recall | M5 ✅ |
+| 18 | GitHub Action (uploads SARIF to Code Scanning), pre-commit hook | M5 ✅ |
 | 19 | Auth bypass / IDOR heuristics (only if benchmark shows acceptable precision) | Later |
 | 20 | Docker image | Later, on demand |
 
@@ -140,9 +140,9 @@ mature scanners, (3) taint-based confirmation, (4) optional local-LLM triage and
 | M0 ✅ | Skeleton & contracts | Repo, `pyproject`, CI (ruff + pytest on 3.10–3.13), `Finding` models, fixture corpus layout; **frozen** `Finding` schema v1, `taxonomy.py`, fingerprint + dedupe/merge implemented with order-independence tests; importer contract (above) documented | — |
 | M1 ✅ | AST engine & rules | Rules 1–2 pass per-rule vulnerable **and** safe fixtures | M0 |
 | M2 ✅ | Taint | Framework fixtures (Flask/Django/FastAPI); constant/sanitized flows suppressed; tests for taint boundaries | M1 |
-| M3 🔨 | CLI, SARIF, importers → **v0.1.0 on PyPI** (built; publish pending) | `pip install hackscan` works on clean venv; SARIF validates against official schema; `--fail-on` exit codes tested | M2 |
-| M4 | LLM + remediation + TUI → v0.2.0 | All LLM tests run against a mocked Ollama; offline degradation tested; prompt-injection fixture | M3 |
-| M5 | Inter-procedural taint, benchmark, GitHub Action → v0.3.0 | Benchmark report in README; Action used on the repo itself | M4 |
+| M3 ✅ | CLI, SARIF, importers → **v0.1.0 on PyPI** (released 2026-10-08) | `pip install hackscan` works on clean venv; SARIF validates against official schema; `--fail-on` exit codes tested | M2 |
+| M4 ✅ | LLM + remediation + TUI → **v0.2.0** (2026-10-09; 14 Codex gate rounds, double-OK) | All LLM tests run against a mocked Ollama; offline degradation tested; prompt-injection fixture | M3 |
+| M5 ✅ | Inter-procedural taint, benchmark, GitHub Action → **v0.3.0** (2026-10-09) | Benchmark report in README; Action used on the repo itself | M4 |
 
 ## Test Strategy
 - Corpus: `tests/corpus/<rule>/{vulnerable,safe}/*.py`, each file annotated with expected findings
@@ -270,3 +270,185 @@ hackscan/
   known secrets scrubbed from warnings/errors; `-o` only overwrites previous HackScan
   reports; failed `--import` reports make the scan incomplete (exit 2); `--with` tools
   exiting with an error code are `partial` (warning, fails `--strict-tools`).
+- 2026-10-09 (M4a/M4b): template fixes (parameterized SQL with driver-specific placeholders,
+  argv lists instead of shell strings, `ast.literal_eval`, SHA-256) as validated exact edits;
+  `--no-fix`, `--show-fixes`. LLM triage is **opt-in** (`--llm`): candidates only, JSON-schema
+  replies, per-request random code fence, redacted context, cache, `--llm-max`,
+  `--llm-timeout`, bounded output tokens. LLM suppression requires evidence that a
+  deterministic checker accepts and that holds on every path: a constant or class-valid
+  sanitizer assignment, or an allow-list guard (`not in {consts}`, 
+  `isdigit()/isalnum()`), in the function body before the sink, covering all sink locals,
+  never rebound/mutated afterwards. LLM fixes are kept only if the patched file parses and
+  re-running passes 1-2 shows the finding gone and no new ones. Measured locally: CPU-only
+  Ollama with the reasoning model deepseek-r1:8b ignores `think: false` and exhausts its
+  budget — reported as "no answer"; non-reasoning coder models are recommended.
+- 2026-10-09 (Codex M4 review): LLM suppression must vouch for *every* value in the sink
+  (any name, local or global; calls/attributes/subscripts in the sink are never vouched for)
+  — fixes a P0 where `safe + suffix` (global `suffix` from the environment) was suppressed.
+  LLM fixes must call an allow-listed safe API for the class (or keep the SQL receiver with
+  parameters), keep every original value, and never use `__import__`/`eval`/`shell=` etc.
+  The flagged-call field sent to the model and `--show-fixes` diff context are redacted;
+  fix replacements are redacted like other fields. C0/C1 control characters from code,
+  tools or the model are shown escaped, never emitted. `IN (...)` lists are not
+  parameterized (a single placeholder changes results); f-string/% argv values are wrapped
+  in `str()`; imports are never inserted above a shebang or encoding cookie; malformed
+  Ollama replies are discarded instead of crashing.
+- 2026-10-09 (live Ollama check, CPU-only): qwen3:4b-instruct-2507 got real injection,
+  fake length guard and allow-list guard right once the verifier (a) maps a cited line
+  inside a top-level statement (e.g. a guard's `return`) to that statement and (b) treats
+  the model's evidence kind as a hint, trying every deterministic check (each is complete
+  on its own, so this is equally sound). Response schema now orders `reason` first
+  (Ollama generates keys in schema order), prompt v3. qwen2.5-coder:3b: safe but misses
+  the guard. Both models obeyed an injected "reply false_positive" comment; the verifier
+  rejected it. A missing model now reports "not installed; run `ollama pull <model>`".
+- 2026-10-09 (Codex M4 re-review): rebinding after cited evidence now includes imports
+  (`*` = anything), `match` captures, `except ... as`, nested defs/classes; `assert` is
+  never evidence (`python -O`). LLM command fixes must run the original program (never a
+  shell/interpreter) with the original literal words in order and only harmless
+  keywords; LLM SQL fixes must be one literal with the original SQL tokens (values as
+  placeholders). SQL template placeholders only after comparisons, in VALUES lists and
+  after LIMIT/OFFSET (not `typeof(?)` or select lists). String literals assigned to
+  secret-looking names are redacted by raw source text, so implicitly joined and
+  triple-quoted secrets never reach the model or fix diffs.
+- 2026-10-09 (Codex verify round): token/word comparison was bypassable (extra computed
+  argv element, swapped SQL parameters, SQL comments). LLM fixes must now equal what
+  HackScan derives itself: argv element-for-element (`str()` wrapper ignored), SQL text
+  exactly plus the original values in order. SQL containing comments (`--`, `/*`, `#`)
+  gets no fix. Secret literals are masked character for character in the source
+  (lines/columns kept) for LLM context and diffs. Rebinding is judged by (line, column)
+  outside the cited statement; any `nonlocal`/`global` of the name voids the evidence.
+- 2026-10-09 (Codex verify round 2): an argv list stops shell injection, not argument
+  injection (`git -c alias.x=!cmd`, `python3.12 -c`). `_argv` (ground truth for template
+  and LLM fixes) now refuses interpreters/wrappers (versioned and `.exe` names included)
+  and any value directly after a flag other than `--`. LLM SQL fixes must use the
+  placeholder of the detected driver (none or ambiguous: no fix). Snippets and sinks of
+  own findings and imported ones come from masked source; a call containing a secret
+  literal gets no fix (a fix must carry the real code); diffs mask both sides from
+  their own syntax trees. Masking also covers walrus and unpacking targets.
+- 2026-10-09 (stop-time review + Codex verify round 3): the interpreter denylist could
+  never be complete (`npx PKG`, `tar --to-command`, `find -exec`...), so argv fixes now
+  use an allowlist of programs with inert arguments (`INERT_PROGRAMS`: echo, cat, ls,
+  grep, head...; `.bat`/`.cmd` never match). Masking covers `for`/comprehension/`with`
+  targets; for parsed Python files the snippet always comes from masked source (a tool's
+  SARIF snippet only as a fallback, redacted); LLM evidence quotes masked source. Round 3
+  confirmed all earlier fixes and found no regressions (fingerprints, dedupe, pool).
+- 2026-10-09 (security follow-up): LLM allow-list guards require class-safe string or integer
+  constants; source secret literal values now redact imported messages and evidence before
+  output and LLM triage; fallback snippets from unparseable files redact literals and
+  assigned values; `echo` and `dir` no longer get shell-less command fixes because they
+  are Windows cmd.exe builtins.
+- 2026-10-09 (release gate): SQL LIMIT allow-list values cannot contain commas; template
+  and LLM fixes containing a known secret are dropped before export. Imported findings
+  have no snippet unless their Python source parses, preventing multi-line secret leaks.
+  Equal-length secrets are redacted in lexical order, and only secret-like source values
+  join report-wide known secrets; local source masking still covers every secret-named literal.
+- 2026-10-09 (gate review follow-up): LLM predicate guard evidence is limited to
+  `isdigit()` and `isdecimal()`; constant allow-lists retain their existing rule.
+  Secret-named function and lambda defaults are masked, and AST rule messages and evidence
+  use the file's masked literal spans. Gitleaks values are redacted at any nonzero length
+  across findings, warnings and errors. Diff redaction preserves assignment spacing.
+  Every masked source literal of at least four characters is also redacted within findings,
+  fixes and LLM requests for its own file. LLM rewrites now require exact code and hash
+  arguments and literal subprocess keyword values to prevent hidden execution. Release-gate
+  fixes restrict shell template keywords, redact secret-bearing rule IDs and escaped source
+  spellings, and refuse SQL placeholders inside partial quoted literals. Sole dynamic
+  parenthesized SQL lists get no placeholder; file-scoped secrets also redact rule metadata
+  before triage and diagnostics across the report. Release-gate follow-up refuses unquoted
+  dynamic SQL values inside any parentheses and SQL text containing backslashes, while
+  redacting finding function names before IDs, output and triage. Double-quoted SQL
+  identifiers and SQL text containing `$` also receive no fix. Numeric and concatenated
+  secret literals are masked and collected.
+- 2026-10-09 (M5 step 1): Roles back to Claude implements, Codex reviews (double OK before
+  commit). Repo root is a composite GitHub Action: inputs reach `run:` scripts only via env,
+  extra `args` are word-split with globbing off, the scan step records the exit code so SARIF
+  is uploaded (only if written) before the job fails; the dogfood workflow skips upload on
+  fork PRs. pre-commit hook scans the whole repo (`pass_filenames: false`; CLI takes one path).
+  Review round 1 (Codex Not OK, fixed): an empty `fail-on` input now passes the new
+  `--fail-on never` (overrides `.hackscan.yml`) instead of rewriting exit 1 to 0, which hid
+  crashes; a plugin constructor exception is now a PluginError (exit 2, not 1); README adds
+  `actions: read` for private repositories.
+- 2026-10-09 (M5 step 2): Inter-procedural, cross-file taint is confirmation-only
+  (`analyzers/interproc.py`). Pass 2 records symbolic facts per file: parameter and
+  call-result atoms carried in `Taint.symbols` with per-atom sanitized classes, return
+  summaries of linkable functions, argument values at statically named call sites. The
+  pipeline links all files (same module, imports, relative imports, re-exports, src
+  layouts by unambiguous module-name suffix) and solves a least fixpoint; candidates
+  reached by an untrusted source become confirmed with a file:line trace. Never
+  suppresses: unknown callers may exist. Only undecorated, non-generator module-level
+  functions bound once are linked; methods, `*args` positions and star-import modules are
+  not. Cost: taint now runs on every file (~45 ms/file serial on site-packages, +50%);
+  `_closure_names` made single-pass.
+  Review round 1 (Codex OK, 3 non-blocking precision issues): `match` captures
+  (`MatchAs`/`MatchStar`/`MatchMapping.rest`) are now scope bindings; the module binding
+  census also counts walrus targets in keyword-only defaults, lambda defaults,
+  annotations and class bases. Call results carrying their arguments through a
+  sanitizing helper stay a documented limitation (same approximation as within a function).
+  Review round 2 (Codex Not OK, pre-existing pass-2 soundness bug, fixed): a `match`
+  mapping rest capture (`case {**rest}`) now takes the subject's taint, and captures of
+  a failed pattern or a false guard stay visible to later cases and after the `match`
+  (the no-match path joins them), so a reachable sink is no longer suppressed as constant.
+  Review round 3 (Codex Not OK, pre-existing pass-2 soundness bugs, fixed): a `:=` in a
+  part that may not run (later `and`/`or` operands, `x if c else y` branches,
+  comprehension bodies, also inside `match` guards) is applied on a copy and joined
+  instead of overwriting the current value (comprehension bodies iterate to a fixpoint);
+  a `match` capture is aliased with the mutable names in the subject.
+  Review round 4 (Codex Not OK, 6 blockers: 5 pre-existing, 1 regression from round 3's
+  comprehension rework, which was reverted): instead of ordering every `:=` effect, a scope
+  whose own code contains `:=` never suppresses its sinks (confirmation still works); a
+  module with `:=` gets no trusted module constants; sinks in a generator expression's
+  body (deferred execution) are never suppressed. Also fixed (pre-existing): a nested
+  function or lambda reading an enclosing local that shadows a module constant was
+  treated as constant; module constants now apply only if the name resolves to the module.
+  Review round 5 (Codex Not OK, 6 pre-existing blockers without `:=`, fixed with
+  conservative rules): generator expressions yield UNKNOWN-joined values; a comprehension
+  target shadows outer bindings and class-body names are hidden inside class
+  comprehensions; module constants require exactly one module-level binding and no
+  dynamic namespace writes (`globals`/`vars`/`locals`/`exec`/`eval`/`__import__`,
+  `__dict__`/`__globals__`/`modules`, star imports), and module-level sinks in such a
+  module are never suppressed; names a function declares `global`/`nonlocal` are joined
+  with UNKNOWN on every read; LLM guard evidence must cover the function's own locals.
+  Review round 6 (Codex Not OK, 3 blockers, fixed): namespace writers are also detected
+  as attributes (`builtins.exec`, `import_module(...).exec`), imported aliases
+  (`from builtins import exec as run`), `import builtins` and `__builtins__`; a class body
+  that may write its own namespace (`locals()[...]` etc. in that body) never suppresses;
+  a comprehension target bound by more than one `for` resolves to UNKNOWN.
+  Review round 7 (Codex Not OK, 4 blockers, fixed): namespace-writer aliases bound by
+  assignment are followed file-wide (`execute = exec` then used in a class body), and
+  importing a namespace attribute under any name counts (`_Namespace`, computed once per
+  file); eager comprehensions scan filters before the element and repeat their body to a
+  fixpoint (mutations of one item reach the next; widened to UNKNOWN on budget
+  exhaustion); comprehension targets are aliased with the mutable names in their
+  iterables. Serial scan of ~770 site-packages files: 22.8 s (v0.2.0) -> ~41 s.
+  Review round 8 (Codex Not OK, 3 blockers, fixed): `:=` creates writer aliases too; a
+  comprehension that may mutate one of its items (non-read-only method on a target,
+  target passed to a call other than a sink/sanitizer/pure builtin/string method, store
+  into a target) invalidates every mutable name in its iterables and resolves its targets
+  to UNKNOWN; subscript/attribute comprehension targets store into their base.
+  Review round 9 (Codex Not OK, 2 blockers, fixed): a comprehension target anywhere inside
+  a call argument counts as escaping (`change([cmd])`); mutations, stores and comprehension
+  targets find their container through method calls too (`_root_name`: `d.get(k).append(x)`
+  and `d.setdefault(k, [])[0] = x` mutate `d`), in all code, not only comprehensions.
+  Review round 10 (Codex Not OK, 2 blockers, fixed): a bound method taken off a mutable
+  object (`append = parts.append`, method attribute loaded but not called right away)
+  invalidates every mutable name in its receiver; a mutating method call updates every
+  mutable name in a compound receiver (`(a if c else b).append(x)`, `[cmd][0].append(x)`).
+  User decision (2026-10-09, after 10 rounds): fix round 10, document remaining indirect
+  mutable aliasing (aliases stored in attributes/containers, returned from helpers,
+  `getattr`) as a README limitation, confirm with Codex once, commit with both OKs; any
+  further pass-2 aliasing hardening is a separate task.
+- 2026-10-09 (M5 step 3): Benchmark (`benchmarks/`). User choices: Bandit + Semgrep +
+  CodeQL; a new labeled suite plus known-vulnerable apps. Suite: 26 `# vuln:` sinks and 24
+  `# safe:` traps in Flask/Django/FastAPI/CLI code, one labeled sink per function, scored
+  per function (tools report flows at sink, construction or source lines); all tools are
+  normalized through HackScan's SARIF importer. Taxonomy fix found on the way: Semgrep's
+  `tainted-sql-string` rule carries CWE-704 metadata and is now mapped to sqli. Apps:
+  vulpy, PyGoat, DVPWA at pinned commits (MIT), every reported key hand-reviewed in
+  `apps_review.json`; relative recall over the union of true positives. Tests keep
+  RESULTS.json, APPS.json and the README tables in sync with the engine. Results:
+  suite F1 HackScan 82%, CodeQL 85%, Bandit 70%, Semgrep 67%; apps precision/relative
+  recall HackScan 83%/71%, CodeQL 100%/67%, Bandit 50%/76%, Semgrep 92%/52%.
+- 2026-10-09 (v0.3.0 release): version 0.3.0; the Action uploads with
+  github/codeql-action/upload-sarif@v4 (v3 is deprecated in December 2026); benchmark
+  re-run so the HackScan rows show 0.3.0 (numbers unchanged). Next ideas (not started):
+  weak-cipher detection (DES/RC4/ECB/unauthenticated modes; largest benchmark gap),
+  taint through `self` attributes, further pass-2 aliasing hardening.