hackscan 0.1.0__tar.gz

hackscan-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+* text=auto eol=lf
+*.bat text eol=crlf

hackscan-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv run --group dev ruff check .
+      - run: uv run --group dev ruff format --check .
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          - os: windows-latest
+            python: "3.12"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv run --group dev pytest
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - name: Install the wheel in a clean environment and scan
+        run: |
+          uv venv /tmp/smoke
+          uv pip install --python /tmp/smoke dist/*.whl
+          /tmp/smoke/bin/hackscan --version
+          /tmp/smoke/bin/hackscan scan tests/corpus --format sarif -o /tmp/corpus.sarif
+      - name: Dogfood - HackScan scans its own source
+        run: /tmp/smoke/bin/hackscan scan src --fail-on high

hackscan-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Release
+
+# Publishes to PyPI when a tag like v0.1.0 is pushed. Uses PyPI trusted publishing
+# (OIDC): no API token is stored in the repository. One-time setup on pypi.org:
+# add a "pending publisher" for project `hackscan`, owner/repo of this repository,
+# workflow `release.yml`, environment `pypi`.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+      - name: Check the tagged commit is on main
+        run: |
+          git fetch origin main
+          git merge-base --is-ancestor "$GITHUB_SHA" origin/main || {
+            echo "tag ${GITHUB_REF_NAME} points to a commit that is not on main"; exit 1; }
+      - name: Check tag matches package version
+        run: |
+          version=$(uv run --no-project python -c "import re,pathlib;print(re.search(r'__version__ = \"(.+)\"', pathlib.Path('src/hackscan/__init__.py').read_text()).group(1))")
+          test "v${version}" = "${GITHUB_REF_NAME}" || { echo "tag ${GITHUB_REF_NAME} != v${version}"; exit 1; }
+      - run: uv run --group dev pytest
+      - run: uv build
+      - name: Smoke-test the wheel in a clean environment
+        run: |
+          uv venv /tmp/smoke
+          uv pip install --python /tmp/smoke dist/*.whl
+          /tmp/smoke/bin/hackscan --version
+          /tmp/smoke/bin/hackscan scan tests/corpus --format sarif -o /tmp/out.sarif
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

hackscan-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.sarif
+!tests/fixtures/**/*.sarif
+.hackscan-cache/

hackscan-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khaled Awad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hackscan-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.5
+Name: hackscan
+Version: 0.1.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
+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. |
+| **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. |
+| **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.
+
+## 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 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. |
+| `--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. |
+| `--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
+```
+
+### 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.
+
+## 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
+
+```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@v3
+  if: always()
+  with:
+    sarif_file: hackscan.sarif
+```
+
+## Limitations
+
+- Taint analysis is intra-procedural: values arriving through function parameters are
+  candidates, not confirmations (inter-procedural analysis is on the roadmap).
+- Python only. Imported tools may cover other languages; their findings are passed through.
+
+## 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/PROJECT.md

@@ -0,0 +1,272 @@
+# Project: HackScan (plan v2)
+
+> v2 supersedes the Antigravity draft (`~/.gemini/antigravity/scratch/vulnhawk/PROJECT.md`).
+> Changes driven by a Codex + Claude review on 2026-10-08: usable scanner first, LLM optional,
+> reuse mature scanners as inputs/baselines instead of re-implementing them.
+
+## Positioning
+HackScan is a Python SAST **orchestrator + verifier**, not a Semgrep/CodeQL competitor.
+Value = (1) own AST+taint engine for core injection classes, (2) ingest & dedupe findings from
+mature scanners, (3) taint-based confirmation, (4) optional local-LLM triage and fix suggestions,
+(5) clean SARIF for GitHub Code Scanning.
+
+## Architecture
+```
+ own engine (AST + taint) ──┐
+ Semgrep CE SARIF (opt)   ──┤
+ Gitleaks JSON (secrets)  ──┼─► normalize → dedupe → taint-confirm → [LLM triage] → [fix gen] → CLI / SARIF
+ CodeQL SARIF (opt, BYO)  ──┘
+```
+1. **Pass 1 – AST rules** (`analyzers/ast_pass`): candidate sinks per rule, plugin-based.
+2. **Pass 2 – Taint** (`analyzers/taint_pass`): intra-procedural in MVP; framework-aware sources
+   (Flask `request.*`, Django `request.GET/POST/body`, FastAPI handler params), rule-specific sanitizers.
+3. **Importers** (`importers/`): SARIF (Semgrep, CodeQL, Bandit) and Gitleaks JSON → `Finding`.
+   External tools are invoked only if present on PATH; never bundled.
+4. **Dedupe** (`core/dedupe`): merge findings sharing (file, region overlap, CWE); keep provenance list.
+5. **Pass 3 – LLM triage** (`analyzers/llm_pass`, optional): Ollama, structured JSON output, schema-validated.
+6. **Pass 4 – Remediation** (`analyzers/remediate`, optional): fixes as exact edits, validated by re-parse.
+7. **Output** (`cli`, `ui`, `sarif`): Click CLI, Rich output (plain mode for CI), SARIF 2.1.0.
+
+## Core Contract: `Finding` (schema_version = 1)
+| Field | Type | Notes |
+|---|---|---|
+| `id` | str | Stable fingerprint: sha256(`vuln_class` + rel_path + enclosing function qualname + normalized sink expression). Vendor-independent, survives line shifts and importer order. |
+| `vuln_class` | enum | Canonical class: `sqli`, `cmdi`, `codei`, `weak_crypto`, `secret`, `other:<cwe>`. Mapped from rule_id/CWE via `core/taxonomy.py`; unmappable imports get `other:<cwe or tool:rule>`. |
+| `rule_id` | str | Primary rule, e.g. `HS-SQLI-001`, or `semgrep:<id>` for imported. All contributing rule ids kept in `related_rules`. |
+| `cwe` | list[str] | Used for dedupe and SARIF taxa |
+| `severity` | enum | critical/high/medium/low |
+| `location` | Region | rel path, start/end line+col (1-based lines, 1-based cols per SARIF) |
+| `snippet` | str | Display only; never used for identity |
+| `sink` | str | Source text of the sink at `location`, read from the file by the producer; input to the fingerprint (falls back to `snippet` only if empty) |
+| `sources` | list[str] | Provenance: `hackscan`, `semgrep`, `codeql`, `gitleaks`, ... |
+| `status` | enum | `candidate`, `confirmed`, `suppressed` |
+| `suppression` | Optional[str] | Reason: `taint:constant_input`, `taint:sanitized`, `llm:false_positive`, `inline:hackscan-ignore` |
+| `confidence` | int 0-100 | Rule-specific; see policy below |
+| `evidence` | list[Evidence] | Taint trace steps, LLM rationale (each tagged with producer) |
+| `fix` | Optional[Fix] | `edits: list[{region, replacement}]` + derived unified diff; only if validated |
+
+**Dedupe / merge policy** (deterministic, independent of importer order)
+- Merge key: (`vuln_class`, rel_path, overlapping region — column-aware, `end_column` exclusive,
+  missing columns = whole line). Clustering is **not transitive** — invariant: every pair of findings
+  in a cluster overlaps. Findings are visited smallest region first (own engine breaks ties) and join
+  the first cluster in which they overlap every member, so two disjoint sinks can never be fused.
+  Findings sharing a source but recording different (normalized) sinks never merge — e.g. nested
+  `eval(eval(x))` — so a merge never reports fewer findings than any single source did.
+- `sink` and `function` are derived from the parsed file by every producer (importers look them up
+  by location); merged findings take them from the primary, else the first contributor that has them. Findings with missing CWE merge only if
+  `vuln_class` mapped via rule_id; otherwise they stay separate.
+- Merged location = union of all contributors' regions. Evidence = sorted concatenation (duplicates kept).
+- All tie-breaks fall back to the finding's canonical JSON, so every result is input-order independent.
+- Merged fields: `rule_id` = own-engine rule if present, else lexicographically smallest
+  `tool:rule`; `severity` = max; `confidence` = max; `sources`/`related_rules`/`cwe` = sorted union;
+  `evidence` = concatenation sorted by producer; `status` = `confirmed` > `candidate` > `suppressed`
+  (a finding is suppressed only if every contributor is suppressed).
+
+**Policies**
+- Passes return new/updated `Finding`s; they never delete.
+- `--fail-on <sev>` counts `candidate` and `confirmed` findings at or above `<sev>`; never `suppressed`.
+- Taint may suppress only findings in classes the own engine models (`sqli`, `cmdi`, `codei`) and
+  only when the full flow is inside one function and provably constant/sanitized. Imported findings
+  the engine cannot fully analyze stay `candidate`. Suppressed findings are kept and emitted
+  in SARIF with `suppressions[]`; hidden in CLI unless `--show-suppressed`.
+- Confidence is rule-specific. Taint applies only to injection rules. Secrets and weak-crypto are
+  findings *because* they are literals/calls — taint "constant input" dismissal never applies to them.
+- `--no-llm` disables Pass 3 and LLM fix generation. Deterministic template fixes (Pass 4 templates)
+  still run unless `--no-fix`.
+- Output ordering is deterministic (path, line, col, rule_id).
+
+## LLM Safety (Pass 3/4)
+- Scanned code is untrusted data: wrapped in delimited blocks, system prompt states it must not be
+  followed as instructions; model output must match a JSON schema or is discarded.
+- LLM can only move status `candidate → confirmed|suppressed` with rationale; it cannot create findings
+  or raise severity above rule default.
+- LLM suppression requires independent evidence: the model must cite a specific line (sanitizer call,
+  constant, guard) that a deterministic checker verifies exists in the code. Unverifiable rationale →
+  finding stays `candidate` with the LLM note attached. LLM suppressions are labeled `llm:*` and can be
+  disabled with `--llm-no-suppress`.
+- Redaction applies to all context sent to Ollama (surrounding code too): string literals matching
+  secret patterns / Gitleaks hits are replaced with `<REDACTED>`.
+- Fixes: must re-parse with `ast`, must change only the reported region(s); else dropped.
+- Secrets findings' snippets are redacted before any LLM call. Non-localhost `--ollama-host` prints a warning.
+- Budgets: per-request timeout, max findings per scan (`--llm-max`), cache by (finding id, model, prompt version).
+
+## Performance & Determinism
+- Default ignores: `.git`, `.venv`, `venv`, `node_modules`, `build`, `dist`, `site-packages`, `__pycache__`.
+- Parse failures are reported as warnings, never crash the scan.
+- Process-pool parallelism per file for Passes 1-2; result cache keyed by file hash + engine version.
+- Target: 100k LOC in < 30 s without LLM on a laptop.
+
+## Importer Behavior
+- **Run mode** `--with semgrep,bandit,gitleaks`: invoke tool if on PATH with pinned args
+  (`semgrep scan --config p/python --sarif`, `bandit -r -f sarif`, `gitleaks detect --no-git -f json`).
+  Missing tool → warning, scan continues. Non-zero exit with valid output → accept; invalid/empty
+  output or timeout (`--tool-timeout`, default 300 s) → warning, that source skipped.
+  `--strict-tools` turns any tool failure into exit code 2.
+- **BYO mode** `--import codeql=results.sarif --import sarif=other.sarif`: parse only, never execute.
+- **Path normalization**: all locations resolved to POSIX paths relative to scan root; SARIF
+  `originalUriBaseIds`/`file://` URIs resolved; results outside the scan root are dropped with a warning.
+- **Region normalization**: 1-based lines/cols; missing end → same as start; missing column → whole line.
+- **Exit codes**: 0 = no failing findings, 1 = `--fail-on` threshold hit, 2 = usage/tool/internal error.
+- **Tests**: one recorded fixture output per tool (Semgrep, Bandit, CodeQL, Gitleaks) in
+  `tests/fixtures/imports/`, plus malformed-input cases.
+
+## Feature Inventory (MVP = M1–M3)
+| # | Feature | Milestone |
+|---|---|---|
+| 1 | Rules: SQL injection, command injection, code injection (`eval`/`exec`) | M1 |
+| 2 | Rule: weak crypto (`md5`/`sha1` in security context) — low severity | M1 |
+| 3 | Plugin ABC + loader (`--plugins <dir>`) | M1 |
+| 4 | Intra-procedural taint + Flask/Django/FastAPI sources + sanitizers | M2 |
+| 5 | Inline suppression `# hackscan: ignore[RULE]` | M2 |
+| 6 | `hackscan scan <path>` with `--format text|json|sarif`, `--output` | M3 |
+| 7 | `--severity`, `--min-confidence`, `--ignore`, `--fail-on`, `--quiet`, `--show-suppressed` | M3 |
+| 8 | `.hackscan.yml` hierarchical config | M3 |
+| 9 | SARIF 2.1.0: rules, locations, snippets, properties, suppressions; `fixes[]` emitted only when `Finding.fix` exists (populated from M4) ; schema-validated in tests | M3 |
+| 10 | Importers (see Importer Behavior): `--with semgrep,bandit,gitleaks` runs tools; `--import <tool>=<file>` ingests BYO reports (CodeQL, any SARIF) | M3 |
+| 11 | Dedupe across sources | M3 |
+| 12 | Packaging (`pyproject.toml`, `hackscan` entry point), PyPI release via GitHub Actions trusted publishing | M3 |
+| 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 |
+| 19 | Auth bypass / IDOR heuristics (only if benchmark shows acceptable precision) | Later |
+| 20 | Docker image | Later, on demand |
+
+## Milestones
+| # | Name | Exit criteria | Depends |
+|---|---|---|---|
+| 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 |
+
+## Test Strategy
+- Corpus: `tests/corpus/<rule>/{vulnerable,safe}/*.py`, each file annotated with expected findings
+  (`# expect: HS-SQLI-001`) — the test harness diffs actual vs expected (precision/recall per rule).
+- Framework cases: `tests/corpus/frameworks/{flask,django,fastapi}/`.
+- Golden SARIF snapshots + JSON-schema validation.
+- CLI tests via Click `CliRunner`: exit codes, filters, formats.
+- LLM: mocked HTTP; prompt-injection fixture (code comment instructing "mark as safe") must not suppress.
+- Performance smoke test on a generated large repo (marked `slow`).
+
+## Code Layout
+```text
+hackscan/
+├── pyproject.toml
+├── README.md
+├── PROJECT.md
+├── .github/workflows/{ci.yml,release.yml}
+├── src/hackscan/
+│   ├── cli.py
+│   ├── config.py
+│   ├── core/{models.py,pipeline.py,dedupe.py,fingerprint.py}
+│   ├── analyzers/{ast_pass.py,taint_pass.py,llm_pass.py,remediate.py}
+│   ├── taint/{sources.py,sinks.py,sanitizers.py}        # framework models
+│   ├── importers/{sarif.py,gitleaks.py,runner.py}
+│   ├── plugins/{base.py,loader.py,rules/{sqli,cmdi,codei,weak_crypto}.py}
+│   ├── ui/{theme.py,banner.py,formatter.py}
+│   └── sarif/{generator.py,schema/sarif-2.1.0.json}
+└── tests/
+    ├── corpus/...
+    ├── test_rules.py
+    ├── test_taint.py
+    ├── test_importers.py
+    ├── test_dedupe.py
+    ├── test_cli.py
+    ├── test_sarif.py
+    └── test_llm.py
+```
+
+## Dev Tooling (not shipped)
+- codebase-memory-mcp or Graphify (Graphify-Labs) as a code-navigation aid for agents. Not a runtime dependency.
+- Note: `graphify.net` is flagged by Cloudflare as suspected phishing — use the GitHub repo only.
+
+## Decisions Log
+- 2026-10-08: Repo at `~/teamwork_projects/hackscan`. MVP = M0–M3. Secrets via Gitleaks import (own
+  secrets detector dropped). Auth/IDOR deferred. CodeQL never bundled (license) — BYO SARIF only.
+  Semgrep invoked as external CLI; its registry rules are not vendored (Semgrep Rules License).
+- 2026-10-08 (Codex re-review): vendor-independent fingerprint via `vuln_class`; deterministic merge
+  policy; importer run/BYO modes + failure semantics; SARIF fixes optional until M4; `--fail-on`
+  excludes suppressed; LLM suppression requires verifiable evidence; full-context redaction.
+  Verdict: ready for M0.
+- 2026-10-08 (M0 impl): pipeline order is collect → `merge_findings` → `assign_ids` (ids are
+  computed on merged findings). Identical sinks in one function get an occurrence suffix (`#n`,
+  ordered by line), so inserting an identical sink earlier in the same function shifts later ids —
+  accepted trade-off. Fingerprint ids prefixed `hs1-` (bump if the recipe changes).
+- 2026-10-08 (Codex M0 code review): anchor-based column-aware clustering (no transitive fusion),
+  `sink` field for fingerprints, union locations, evidence concatenation, canonical-JSON tie-breaks,
+  end-column validation. Round 2: precision-first anchors, union on effective ends, merged
+  findings keep a recorded `sink`; randomized order-independence test.
+- 2026-10-08 (Codex M1 review): **rules report candidates, taint decides.** Rules no longer
+  dismiss findings via flow-insensitive assignment lookups (e.g. a constant assigned under
+  `if False`); every non-constant value at a sink is a candidate (lower confidence when
+  unresolved), and constant/sanitized flows are suppressed by the M2 taint pass. Corpus marks
+  these with `# expect-suppressed:`; the harness enforces the suppression once
+  `TAINT_PASS_ENABLED` is flipped in M2. Name resolution is now scope-aware
+  (`plugins/scopes.py`: function/class/global rules; decorators and defaults evaluate in the
+  enclosing scope). SQLi requires a DB-looking receiver or SQL text in the literal parts.
+  Plugins are type-validated; bad matches and declared source encodings are handled.
+- 2026-10-08 (M2 impl): taint is flow-sensitive within a function — abstract interpretation
+  over statements (branch joins, loop fixpoint, try/except, match, walrus, comprehensions,
+  container mutators) with a `Taint(sources, unknown, safe_for)` lattice. Sinks inside
+  decorators/defaults, lambdas and class bodies are analyzed in their own scopes. Module-level
+  names bound only to constants (and never rebound via `global`) count as constants inside
+  functions — the one deliberate exception to "flow inside one function". Sources: Flask
+  `request.*`, `request`/`req` parameters (Django/DRF/Starlette/FastAPI), route-handler
+  parameters, `input()`, `sys.argv`, `sys.stdin`. Confirmed = +35 confidence with a source
+  trace. Inline suppression reason renamed to `inline:hackscan-ignore` (no spaces).
+- 2026-10-08 (Codex M2 review): fixed five unsound suppressions. Taint values now track
+  mutability (a mutable object that is aliased, mutated, passed to an unmodeled call, stored
+  elsewhere or captured by a nested scope joins `unknown`), shell-quote context
+  (`shlex.quote` safety is dropped when the surrounding string may open a quote), and
+  statements are scanned in evaluation order (walrus/mutation/sink ordering). Module values
+  count as constants only if immutable. `ast.literal_eval` removed from sanitizers.
+  `self.request` (class-based views) is a source. Each case is a regression test that fails
+  on the previous engine.
+- 2026-10-08 (Codex M2 re-review): `except`/`finally` see the join of every state the `try`
+  body passed through; aliases are tracked through calls/constructors (`dict(cmd=parts)`);
+  any transformation of a shell-quoted value (strip/replace/slicing/repr) drops quoting
+  safety. **Policy:** `shlex.quote` protects POSIX shells only (not Windows `cmd.exe`), and
+  the target platform is unknown, so POSIX-quoted commands are never suppressed; they stay
+  candidates at confidence 20 with an explanatory note. (A `--shell posix` option to restore
+  suppression can be added in M3 config.)
+- 2026-10-08 (Codex M2 round 3): `break`/`continue` modeled (paths end at the jump; break
+  states join the loop exit and skip `else`), inner `finally` state propagates to outer
+  handlers. Added `tests/test_taint_fuzz.py`: differential soundness fuzzing — random
+  programs (branches, while/for with break/continue, try/except/finally, raises, early
+  returns, list aliasing, dict wrappers, closures, walrus) are executed with an instrumented
+  `os.system`; any marker reaching a sink the scanner suppressed fails the test. It catches
+  every engine version before this one; a 4,500-program stress run checked 6,743 suppressed
+  sinks with zero unsound results. M2 closed on this evidence.
+- 2026-10-08: **Renamed VulnHawk → HackScan** (PyPI `vulnhawk` is taken by an unrelated
+  project). Package/CLI `hackscan`, rule ids `HS-*`, fingerprint prefix `hs1-`, inline
+  `# hackscan: ignore`, config `.hackscan.yml`, GitHub repo `hackscan`.
+- 2026-10-08 (M3 impl): `hackscan scan` CLI (text/json/sarif, filters, `--fail-on`, exit
+  codes 0/1/2), hierarchical `.hackscan.yml`, process-pool analysis (serial below 16 files;
+  output identical either way), importers for SARIF (Semgrep/Bandit/CodeQL/any) and Gitleaks
+  with run/BYO modes, source-derived `sink`/`function` enrichment and secret redaction,
+  SARIF 2.1.0 export validated against the OASIS schema in tests. Bandit fixture is recorded
+  tool output; Semgrep/CodeQL/Gitleaks fixtures are hand-written to their documented formats
+  (tools unavailable locally). Release via tag-triggered trusted publishing (`release.yml`);
+  CI builds the wheel, installs it in a clean venv, and dogfoods `hackscan scan src`.
+- 2026-10-08 (Codex M3 review + stop-gate): incomplete scans (unparseable/unreadable files,
+  crashing rules) exit 2 unless `--allow-incomplete`, and SARIF sets
+  `executionSuccessful: false`; secrets are redacted after merging from every field of every
+  finding (known Gitleaks values everywhere, all string literals for `secret`-class
+  findings); a start column without an end is a point (no rest-of-line widening);
+  imported findings obey default ignores; remote `file://host/` URIs are rejected;
+  `--output` never overwrites source files and creates parent directories; config keys are
+  an explicit allow-list; malformed Gitleaks entries are skipped with a warning; releases
+  require the tagged commit to be on `main`. SARIF URIs are repository-root-relative (GitHub
+  resolves them that way) and URI-escaped; `--sarif-omit-suppressed` for GitHub uploads,
+  since GitHub does not document `suppressions` support and only reads
+  `primaryLocationLineHash` (computed by `upload-sarif`).
+- 2026-10-08 (Codex final release check): secret-class findings never carry tool text
+  (generic message/evidence; literals and assigned values redacted in snippet/sink);
+  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`).