vulntrack 0.2.0b1__tar.gz

vulntrack-0.2.0b1/.env.example

@@ -0,0 +1,20 @@
+# Secrets only. Everything else is in vulntrack.toml.
+# Copy to .env (gitignored) — or export these directly; a real environment
+# variable always wins over the file.
+#
+# One password per Harbor project, project name uppercased:
+#   [projects.domino] in vulntrack.toml  ->  HARBOR_DOMINO_PASSWORD
+#
+# Anything that is not a letter or digit becomes an underscore, so the name stays
+# exportable from a shell (a dash is a syntax error in `export`):
+#   [projects.my-project]                ->  HARBOR_MY_PROJECT_PASSWORD
+# For a name of your own choosing, set password_env on the project in the TOML.
+HARBOR_DOMINO_PASSWORD=
+HARBOR_LIBRARY_PASSWORD=
+
+# Azure blob store (only when `store` is az://…); the SDK reads these itself.
+# AZURE_STORAGE_CONNECTION_STRING=
+
+# Any vulntrack.toml key can also be overridden here, VULNTRACK_ prefixed:
+# VULNTRACK_STORE=/tmp/vt-store
+# VULNTRACK_CONCURRENCY=8

vulntrack-0.2.0b1/.gitignore

@@ -0,0 +1,22 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+*.egg-info/
+site/
+.claude/
+
+# the two configuration files; .example templates are committed
+vulntrack.toml
+.env
+
+# runtime stores
+vt-store/
+vt-data/
+
+# mapping packs are yours; packs.example/ is the template
+packs/
+
+# legacy: superseded by .env
+harbor-credentials.txt

vulntrack-0.2.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 brunnelu
+
+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.

vulntrack-0.2.0b1/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.5
+Name: vulntrack
+Version: 0.2.0b1
+Summary: Assess Harbor/Trivy findings with stacked, auditable CVSS environmental rules (git NDJSON store)
+Author-email: brunnelu <6707792+brunnelu@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: cvss>=3.6
+Requires-Dist: httpx>=0.27
+Requires-Dist: polars>=1.17
+Requires-Dist: pydantic-settings>=2.14.2
+Requires-Dist: pydantic>=2.7
+Requires-Dist: streamlit>=1.45
+Requires-Dist: tenacity>=9.1.4
+Requires-Dist: textual>=8.2.8
+Description-Content-Type: text/markdown
+
+# vulntrack
+
+Assess Harbor/Trivy findings with a **stacked, auditable rules engine**.
+Persistence is **append-only parquet in blob storage** (Azure container, or a local
+path). Collect spec: **[vulntrack/task.md](vulntrack/task.md)**; architecture:
+**[docs/index.md](docs/index.md)** (its section 7 on storage is superseded by task.md).
+What changed and what is still open: **[WORKLOG.md](WORKLOG.md)**.
+
+## Quickstart
+
+```bash
+uv sync
+cp vulntrack.toml.example vulntrack.toml   # settings
+cp .env.example .env                       # HARBOR_<PROJECT>_PASSWORD
+
+uv run vulntrack collect --no-submit        # progress bar on a terminal; --no-progress off
+
+# -v logs every HTTP request (httpx's own line)
+uv run vulntrack -v collect --no-submit
+
+# map extra columns onto the frame — deployments, KEV, owners, anything
+cp -r packs.example packs
+uv run vulntrack packs list      # resolution order and the dependency graph
+uv run vulntrack packs check     # duplicates, collisions, coverage, dead rules
+
+# Textual TUI — walk residue by finding PK, apply rules (recommended)
+uv run vulntrack ui
+
+# same flow without TUI
+uv run vulntrack assess
+uv run vulntrack assess CVE-2024-0001 --set MA=N --because "…"
+
+# optional browser UI
+uv run vulntrack ui --web
+```
+
+## Data model: PK, joins, assessments
+
+### Occurrence primary key (source row)
+
+Every finding from Harbor is one row with this identity:
+
+```text
+project
+project_version     # if you maintain one; else empty
+cve
+image               # repository without tag
+image_tag           # part of PK as you see it in the world
+digest              # part of PK (immutable content); usually hidden in UI
+package
+package_version
+```
+
+That whole key is the **occurrence**. Digests are long — keep them in the
+data, **do not put them in the default table columns** (optional short
+prefix on drill-down / copy).
+
+Today’s names: `image_repository` ≈ `project/image`, `installed_version` ≈
+`package_version`, `tags` ≈ `image_tag`.
+
+### Augmented columns (joins — not PK)
+
+Anything else is **joined on**, not part of the source PK. Joins come from
+**packs**: one TSV per mapping in `packs/`, keyed on a column the frame already
+has — including a column an earlier pack produced. See `packs.example/`.
+
+```text
+image  ──join──►  packs/deployments.tsv  ──►  image_kind, in_use, exposure, …
+cve    ──join──►  packs/kev.tsv          ──►  kev, …
+image  ──join──►  packs/projects.tsv     ──►  project_id
+                     └─join──►  packs/project-tiers.tsv  ──►  tier, data_class
+```
+
+The order is derived from the key columns, never the filenames; a key nothing
+produces, a cycle, or two rows with the same key is an error that names the pack.
+A pack never adds a row — a mapping row matching nothing is reported by
+`vulntrack packs check`, not merged in. Every value a pack writes lands in
+`mapping_trail` beside the `reasoning`, and `vulntrack explain <digest> <cve>`
+walks one value back through the chain to the image it came from.
+
+`image_kind` is **not** a Harbor field and **not** part of the PK. It is
+augmented data: you maintain `image → image_kind` (and friends); we left-join
+it onto occurrences before rules run. Missing join → null → class rules do
+not match until the register is filled.
+
+Same pattern later for KEV, distro status, etc.: new pack, join key, new
+column, null when unknown.
+
+### Assessment (computed, not stored)
+
+```text
+occurrence (+ joined columns)  +  ordered rules  →  env vector, severity, reasons
+```
+
+Recomputed every time. No assessment table in git — only rules + inputs.
+
+### How people actually assess (the product loop)
+
+In practice almost all **new** work is **per CVE**:
+
+1. Open a CVE still in residue (Critical/High after the stack).
+2. See which occurrence rows / joined context it covers (images, tags,
+   packages, versions — digest hidden).
+3. Write **one rule** with:
+   - `when`: at least `cve = …`, plus whatever else is true  
+     (e.g. only workspace via joined `image_kind`, only one package, …)
+   - `set`: environmental metrics (and/or terminal severity)
+   - `because`: **custom reasoning text** (the audit trail)
+4. Save → recompute → matching rows leave residue; continue.
+
+You are not maintaining a spreadsheet of assessments. You add **rules with
+reasons**; the PK table only shows *where* that rule applies after the join
+and stack.
+
+Broad posture rules (`project.*`, `workspace.posture`) stay few and shared.
+Residue work is mostly `cve.…` rules with a human `because`.
+
+### What the UI should show
+
+```text
+Queue:      residue grouped or listed by CVE (work list)
+Detail:     description + joined facts + occurrence rows for that CVE
+            (PK columns; digest hidden)
+Applied:    which rules already fired / current env result
+Write:      scope (CVE ± package ± image ± image_kind) + metrics + because
+```
+
+Showing every PK row is fine at residue scale (~hundreds). Collapsing
+identical env outcomes is optional sugar — not required to understand the
+model.
+
+### Rules vs PK (important)
+
+| Prefer in `when` | Avoid in `when` |
+|---|---|
+| `cve`, `package`, `image`, joined `image_kind` | `digest` (breaks on rebuild) |
+| other joined facts you trust | bare `image_tag` unless the claim is really tag-specific |
+
+Tag and package_version **are** part of the occurrence PK (inventory truth).
+Rules still usually **omit** them so one decision covers rebuilds; only add
+them when the claim is truly version- or tag-specific.
+
+### Mapping today
+
+| surface | role |
+|---|---|
+| `vulntrack ui` | walk residue, write per-CVE rules |
+| `vulntrack assess` | same in pure CLI |
+| `vulntrack rate` | dump rated occurrences (includes digest) |
+| `vulntrack packs list` | pack resolution order and the dependency graph |
+| `vulntrack packs check` | lint the packs — non-zero on error, for CI |
+| `vulntrack explain <digest> <cve>` | rules fired, their inputs, and the mapping chain |
+
+## Layout
+
+| path | role |
+|---|---|
+| `vulntrack/engine/` | frame + packs, stacking rules, CVSS env score |
+| `vulntrack.toml` | every setting (gitignored; template `.example`) |
+| `packs/*.tsv` | mapping packs joined onto the frame (template `packs.example/`) |
+| `.env` | every secret — `HARBOR_<PROJECT>_PASSWORD` |
+| `vulntrack/settings.py` | env → `.env` → `vulntrack.toml` → defaults |
+| `vulntrack/store.py` | append-only parquet store, SCD2 views |
+| `vulntrack/harbor.py` | Harbor client + collect job |
+| `vulntrack/task.md` | collect-layer spec — read this before changing either |
+| `vulntrack/tui.py` | Textual assess UI |
+| `vulntrack/ui/` | optional Streamlit |
+| `vt-store/` | runtime data (gitignored) |

vulntrack-0.2.0b1/WORKLOG.md

@@ -0,0 +1,128 @@
+# Worklog
+
+Running record of what changed and what is still open, so the work can be followed
+without reading every diff. Newest entry first. Design rationale lives in
+[plan.md](plan.md); the collect-layer spec lives in [vulntrack/task.md](vulntrack/task.md).
+
+## Where the work lives
+
+| branch | tip | state |
+|---|---|---|
+| `worktree-packs-mapping-chain` | `92c1ebf` (2026-08-31) | **current line of work.** Chained mapping packs. 77 tests pass. |
+| `ingest-blob-collect-layer` | `b1516d9` (2026-07-29) | superseded — its uncommitted working tree is committed here as `43aa273` |
+| `worktree-purpose-docs` | `c527bb8` (2026-07-25) | 8 documentation commits, **never merged anywhere** — see open work |
+| `implement-stacking-engine` | `d2eb6ee` (2026-07-25) | historical |
+| `main` | `c1c5021` (2026-07-23) | last release line: Streamlit UI + Harbor scan CSRF fix |
+
+The main checkout at the repo root still sits on `ingest-blob-collect-layer` with a
+large uncommitted diff. That diff is **not lost** — it is commit `43aa273` on this
+branch, verified identical. Continue here, not there.
+
+## Open work
+
+Ordered by what blocks what.
+
+0. **Make the installed package self-contained** (see `docs/packaging.md`). Under a
+   wheel, `cli._project_root()` is `site-packages/`, so `app.py` and
+   `store/rules.ndjson` resolve to nothing: `vulntrack ui --web` fails and there is no
+   default ruleset. Needs a decision, not a patch — move `app.py` into the package and
+   find it via `importlib.resources`; source the ruleset from the config/state dir.
+   Blocks any non-beta release.
+1. **Decide rules versioning** (plan.md §5.5, §8.4). Rules are the last un-audited
+   input: `rules.ndjson` is rewritten in place by the UI, so an as-of replay would
+   replay old packs against *today's* rules. Either record a git commit per run, or
+   make rules a store table (recommended — same shape as packs). **This is a decision,
+   not code, and it blocks 2 being worth building.**
+2. **Packs as an SCD2 store table** (plan.md §5.4, step 6). Gives change history,
+   tombstones and as-of replay for mapping tables.
+3. **Run fingerprint** (plan.md §5.5, step 7). `run_id` + sha256 of each pack file and
+   of the ruleset, stored with every rated output, so an exported spreadsheet ties back
+   to the inputs that produced it.
+4. **Answer plan.md §8 open questions 1, 5** — outer-join intent, and whether a pack is
+   always a file or may eventually be a SQL/API query fetched at collect time. Q2, Q3
+   and Q4 were settled by the implementation (manifest at `packs/packs.toml`; duplicate
+   keys are a hard error; rules versioning still open as item 1 above).
+5. **Decide the fate of `worktree-purpose-docs`.** Eight commits rewriting the
+   architecture docs around the data rather than the code — including the rating model
+   correction and the asset-class CVSS work. Unmerged and drifting; either fold into
+   this branch or retire it deliberately.
+6. **Merge path back to `main`.** `main` is six weeks behind and predates the rating
+   rewrite, the blob store and the chain.
+
+## Log
+
+### 2026-09-07 — beta release 0.2.0b1, to exercise the PyPI workflow
+
+Version bumped in `pyproject.toml` and `vulntrack/__init__.py`. `uv build` +
+`uvx twine check` pass locally on both artifacts; 77 tests pass.
+
+Two packaging defects surfaced while checking what would actually be published:
+
+- **The sdist was shipping gitignored `packs/`.** Hatchling's default file selection
+  swept in untracked working-directory files, and `packs/` holds the real
+  `image_repository → project_id → tier` mappings. A local `uv build` would have made
+  them permanently public. Fixed with an explicit
+  `[tool.hatch.build.targets.sdist] include`. CI builds from a clean checkout and never
+  saw this. The wheel was never affected.
+- **The installed package is not self-contained** — `cli._project_root()` is
+  `Path(__file__).parent.parent`, which is `site-packages/` under a wheel, so `app.py`
+  and `store/rules.ndjson` both resolve to paths that do not exist there. Not fixed;
+  see open work item 0. This is why the release is a beta.
+
+Wrote `docs/packaging.md` — the doc `publish.yml` has always pointed at and which had
+never existed, so the one-time Trusted Publishing setup was undocumented.
+
+**Workflow result — [run 34118819161](https://github.com/brunnelu/vulntrack/actions/runs/34118819161):
+`build` passed, `publish` failed on `invalid-publisher`.** So the answer is that the
+PyPI publisher was never registered — the credentials were not added. Everything on the
+GitHub side is correct; the OIDC claims the run presented are exactly the values
+`docs/packaging.md` says to register:
+
+    repository        brunnelu/vulntrack
+    workflow_ref      .github/workflows/publish.yml
+    environment       pypi
+
+The `pypi` GitHub environment did not exist beforehand and was created by this run, as
+expected. Nothing was uploaded, and `0.2.0b1` is therefore still an unused version
+number on PyPI — re-dispatching the same workflow after the registration will publish
+it. **Blocked on the pypi.org registration, which needs the maintainer's account.**
+
+### 2026-09-07 — surveyed the state, started this log
+
+No code changed. Established where the work actually is:
+
+- The newest branch is `worktree-packs-mapping-chain`; adopted it as the line of work.
+- Verified the repo root's uncommitted diff is captured byte-for-byte by `43aa273`
+  here, so nothing is stranded in the main checkout.
+- Confirmed the chain resolves from data, not filenames: `packs list` against
+  `packs.example/` orders `project-tiers` after `projects` because it keys on
+  `project_id`, a column `projects` produces.
+- Test suite: 77 passed.
+
+### 2026-08-31 — chained mapping packs (`92c1ebf`)
+
+Implements plan.md steps 1–5 and 9. A pack may key on a column another pack produced
+(`image_repository → project_id → tier`), and the order is derived from the key columns
+by fixpoint, so renaming a file cannot change the result.
+
+The join is the small part; the rest is making failure loud, because a broken chain
+otherwise re-rates findings with no diff, no error and a plausible-looking reasoning
+string:
+
+- left join only — a mapping row matching nothing is a lint result, never a frame row
+- declared keys in `packs/packs.toml`; canonical-name inference stays as the fallback,
+  so an un-chained folder needs no manifest
+- duplicate key rows are an error listing the offending values, not `keep="last"`
+- `mapping_trail` beside `reasoning`: which pack wrote each value and on which key,
+  with an explicit `[default]` entry where the heuristic guessed — silence would not
+  distinguish a guess from a fact
+- `vulntrack packs list` / `packs check` (non-zero exit, for CI) / `vulntrack explain`
+
+New: `vulntrack/engine/packs.py` (384 lines), `tests/test_packs.py`,
+`tests/test_cli_packs.py`.
+
+### 2026-08-31 — snapshot of the rating rewrite and blob collect layer (`43aa273`)
+
+Committed what had been sitting uncommitted in the main checkout: `engine/cvss_env.py`
+and `engine/pipeline.py` replaced by `engine/rating.py`; the blob-backed append-only
+store; the Harbor collect layer; `packs.example/`.

vulntrack-0.2.0b1/app.py

@@ -0,0 +1,23 @@
+"""vulntrack UI — st.navigation.
+
+    uv run vulntrack ui
+"""
+
+import streamlit as st
+
+st.set_page_config(page_title="vulntrack", layout="wide", initial_sidebar_state="expanded")
+
+from vulntrack.ui import pages_assess, pages_images, pages_rules, pages_scans  # noqa: E402
+
+st.navigation(
+    {
+        "Assess": [
+            st.Page(pages_assess.page, title="Assess", url_path="assess", default=True),
+            st.Page(pages_rules.page, title="Rules", url_path="rules"),
+        ],
+        "Estate": [
+            st.Page(pages_images.page, title="Images", url_path="images"),
+            st.Page(pages_scans.page, title="Scans", url_path="scans"),
+        ],
+    }
+).run()

vulntrack-0.2.0b1/docs/HANDOFF.md

@@ -0,0 +1,160 @@
+# Handoff — continue here next session
+
+**Date:** 2026-07-25  
+**Branch:** `implement-stacking-engine` (tracks `origin/implement-stacking-engine`)  
+**PR:** https://github.com/brunnelu/vulntrack/pull/2 → `main`  
+**HEAD:** `5b73804` — UI: st.navigation, Assess input, keep all Harbor CVSS vectors  
+**Tests:** `uv run pytest` → **43 passed**
+
+**Directive for the next agent/session:**  
+More code is not the goal. Prefer fewer, clearer mechanisms. The user has already pushed back on bloat, on proxy rabbit-holes, and on TSV-for-rules. **Do not add features to “look busy.”** Decide, simplify, or document — then implement the minimum.
+
+**Product direction (KISS):**
+- Rule = `when` + `set{metrics}` + `because` (+ optional terminal severity).
+- **Primary UI: Textual TUI** (`uv run vulntrack ui`) — select → apply rule → residue shrinks.
+- **Identity (see readme):** occurrence PK includes tag + package_version + digest (digest hidden in UI). `image_kind` etc. are **joined** packs, not source PK. Assess = mostly per-CVE rules + custom `because`; ratings computed, not stored.
+- CLI `assess` same loop; Streamlit only via `ui --web`.
+
+---
+
+## What this project is
+
+**vulntrack** turns Harbor/Trivy scan output into **environmental severities** with an **auditable reason chain**, using a **stack of rules**. Ratings are **not stored**; they are recomputed from versioned inputs.
+
+Product name is **vulntrack** only (not streamlit-editor).
+
+Target design: `docs/index.md` (architecture). Implementation is a partial realization of that doc.
+
+---
+
+## Current shape (lean inventory)
+
+| Piece | Role | Notes |
+|---|---|---|
+| `vulntrack/engine/` | Pure rules + CVSS env score | Core value. Keep small. |
+| `vulntrack/gitstore.py` | NDJSON under `vt-data/` | Works; **user may prefer TSV** (not done). |
+| `vulntrack/collect.py` | Stateless Harbor collect + scan ledger | OK. |
+| `vulntrack/harbor.py` | Client + report parse | Multi-vector parse added; **recollect needed** for store. |
+| `vulntrack/webpath.py` | code-server `proxy` / `absproxy` | Painful history; **UI access works for the user** — do not reopen unless broken. |
+| `vulntrack/ui/` + `app.py` | Streamlit multipage | `st.navigation` restored; Assess still **not liked**. |
+| `store/rules.ndjson` | Seed rules | Shipped defaults. |
+| `vt-data/` | Runtime store (gitignored) | NDJSON; not committed. |
+| Old Delta `data/` | **Deleted** | No migration path; reassess from Harbor. |
+
+**Removed on purpose:** Delta Lake, SCD2, hierarchical `resolve`, half-built `rating_rules`, mock-first product path, legacy Excel assessments pipeline.
+
+---
+
+## How to run (today)
+
+```bash
+cd /home/coder/projects/personal/streamlit-editor
+uv sync
+cp vulntrack.toml.example vulntrack.toml   # settings
+cp .env.example .env                       # HARBOR_<PROJECT>_PASSWORD
+
+uv run vulntrack collect --no-submit   # harvest into vt-data/
+uv run vulntrack rate --residue-only   # CLI summary
+uv run vulntrack ui                    # Streamlit
+uv run pytest
+```
+
+**UI / code-server:**  
+`VSCODE_PROXY_URI=https://code-server.bru.lu/proxy/{{port}}/`.  
+CLI defaults to **absproxy** + `baseUrlPath=absproxy/<port>` (port default **4000**).  
+Open the URL the CLI prints (e.g. `https://code-server.bru.lu/absproxy/4000/`).  
+Nested paths like `…/proxy/N/proxy/N/` = old wrong `baseUrlPath` + cached 301s — private window or new port.
+
+User stated they **can access the UI**; stop spending cycles on proxy debugging unless something is actually broken for them.
+
+---
+
+## What works
+
+- Flat in-memory rate pipeline: findings + images + deployments + ordered rules → env severity + reason chain.
+- Collect from real Harbor; gitstore write; scan ledger append.
+- Seed stack: project MAV, workspace MA/MC/MPR/MS, not-in-use, DoS signal, KEV last.
+- Measured effect (order of magnitude): ~22k findings → ~50–50-ish Critical/High CVEs after stack (recompute after recollect).
+- Multi-vector **parse** in code: all Harbor CVSS sources → `cvss_vectors` JSON (+ convenience columns). **Existing vt-data rows may still lack `cvss_vectors` until recollect.**
+- Streamlit `st.navigation` pages: Assess (default), Rules, Overview, Images, Scans.
+- Config: one `vulntrack.toml`; one robot password per project in `.env` (or the environment).
+
+---
+
+## Open product decisions (user-driven — do these first, not more glue)
+
+### 1. Storage format
+
+- **Now:** sorted **NDJSON** under `vt-data/`.
+- **User:** “maybe better storage; **TSV might be an option**.”
+- **Engineering preference:** one format, human-diffable, spreadsheet-friendly if TSV; avoid dual NDJSON+TSV forever.
+- **Not done.** Next session should **choose** TSV vs NDJSON (or TSV for rules/deployments only) and migrate once — not add a third backend.
+
+### 2. Rule model / authoring
+
+- **Now:** JSON-ish rules (`when` predicates + `then` effects + `because`), CLI + Assess form that builds them.
+- **User:** “**I do not like the way you propose rules.**”
+- **Also disliked:** radio-button page nav (fixed to `st.navigation`); earlier “propose rules” / over-automated downrank framing.
+- **Not done.** Next session should redesign rule **representation and UX** with the user *before* coding more form widgets. Possible lean directions (examples only — agree first):
+  - Rules as a **TSV/table** the user edits (columns: id, when_*, metric, value, because, enabled).
+  - Closer to original Assess flow (severity + reason + simple scope) that **emits** one clear rule row, not a DSL form.
+  - Fewer effects; metric-only rules as default.
+- **Do not** add rule mining, AI proposals, or more rule kinds until the core format is agreed.
+
+### 3. Data model hygiene
+
+- `cvss_vectors` on findings after recollect; normalize CVE text in `cves.*`.
+- Deployments still often **inferred** from `*-environment` names if register empty — fine as bootstrap, not as silent policy.
+
+---
+
+## Explicit non-goals for the next session
+
+- No more proxy/absproxy archaeology unless the user cannot open the UI.
+- No Delta/SCD2/“restore old stack.”
+- No second web framework (FastAPI UI was tried and dropped for Streamlit).
+- No CI/packaging/linter sprawl.
+- No expanding the engine with EPSS/KEV/distro packs until storage + rules feel right.
+- No large UI redesigns without agreeing the rule model.
+
+---
+
+## Hard-won constraints (do not re-litigate)
+
+1. **Assessment is the product** — environmental score + reasons; not “dismiss by no-fix.”
+2. **Rules stack**; score **once** at the end from accumulated metrics.
+3. Prefer **CVSS environmental metrics** over blanket severity overrides.
+4. **No blanket MUI/MAC** as free levers; residue is often AV:N/AC:L/UI:N by selection.
+5. **Image identity without tag** for register/rules so new digests inherit.
+6. **Git-only persistence** for the new design; ratings not stored as authority.
+7. Workspace posture (example): MA:N, MC:L, MPR:L, MS:U — domain-owned by the user, not the model.
+
+---
+
+## Suggested start next week (minimal)
+
+1. Read this file + `docs/index.md` §1–2 and §6 (rating).
+2. Skim `vulntrack/engine/` and `gitstore.py` only — not the whole UI.
+3. **With the user, decide:**
+   - Store: NDJSON → **TSV** (or hybrid)?  
+   - Rules: what does a rule look like on disk and in the Assess UI?
+4. Implement **only** that decision (one storage format + one rule shape), delete what becomes redundant.
+5. Recollect from Harbor; verify multi-vector rows and residue.
+
+---
+
+## Credentials / secrets (do not commit)
+
+- `.env` — one `HARBOR_<PROJECT>_PASSWORD` per project, and nothing else; gitignored.
+  Exported environment variables override it, so CI needs no file.
+- `vulntrack.toml` — every non-secret setting; gitignored, template committed as
+  `vulntrack.toml.example`. Points at Harbor `https://harbor.bru.lu`, projects
+  `domino` and `library`, store `vt-store`.
+- Superseded and removed: `config.toml`, `harbor/credentials.txt`,
+  `harbor-credentials.txt`, `.streamlit/config.toml`.
+
+---
+
+## One-line summary
+
+**Independent vulntrack on git NDJSON + stacking engine + Streamlit is on PR #2; stop bloating — next work is storage format (likely TSV) and a rule model the user actually accepts.**