valvur 0.1.0rc1__tar.gz

valvur-0.1.0rc1/.gitattributes

@@ -0,0 +1,12 @@
+# Normalise line endings in the repo so fingerprints computed on a Windows
+# checkout match those on macOS/Linux. Guards requirement F5.4 at the VCS layer.
+* text=auto eol=lf
+
+# Binary / fixture files must not be munged.
+*.png binary
+*.gif binary
+*.zip binary
+*.gz  binary
+
+# Golden scanner fixtures are byte-exact by definition — never normalise.
+tests/fixtures/golden/** -text

valvur-0.1.0rc1/.gitignore

@@ -0,0 +1,28 @@
+# valvur results — never commit scan output.
+# The Results Folder also self-ignores via .security-scan/.gitignore,
+# but this entry is the visible signal to humans.
+.security-scan/
+
+# Python
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+
+# Secrets and local config
+.env
+.env.*
+!.env.example
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp

valvur-0.1.0rc1/CLAUDE.md

@@ -0,0 +1,225 @@
+# CLAUDE.md — long-term context for this repository
+
+> **Audience:** any AI agent or human joining this project with no prior context.
+> Read this before proposing changes. Written 2026-08-29.
+> **Working name:** `valvur` (Estonian: *guard, watchman*). Provisional until first
+> publish — renaming is one `sed` away and stays cheap until a GitHub repo, PyPI
+> release or Docker push exists.
+
+---
+
+## 1. What this is
+
+A lean, **local-first, fully offline** security scanner for codebases, with a
+first-class focus on **AI-generated code**. It orchestrates best-of-breed open
+source scanners, normalises their findings, ranks them by real-world
+exploitability, and writes an **agent-consumable** results folder into the
+project being scanned.
+
+Delivered primarily as an **MCP tool** the developer adds to their agent (Kiro,
+Claude Code) and invokes deliberately; the CLI is the second way in. The MCP server
+is hand-rolled over stdio with **zero dependencies** (ADR-0015).
+Packaged as one OCI container. Runs on Docker or Podman, locally by default,
+optionally on AWS (ECR/Fargate) using the identical image.
+
+**Status:** spec phase. No application code yet.
+
+## 2. What it is NOT
+
+Be ruthless about this — scope creep here destroys the product:
+
+- **Not a new scanning engine.** Detection is done by Trivy, Gitleaks, Opengrep,
+  Checkov, OSV-Scanner and Syft. We orchestrate, normalise, enrich and present.
+  Never imply proprietary detection. Always credit the scanners.
+- **Not a reachability analyser.** We do not prove a vulnerable function is
+  called. That is a multi-year, per-language effort (Endor Labs / Semgrep Pro
+  territory). Never claim or imply it.
+- **Not an autonomous fixer.** No scan→fix→rescan loop. See §4.
+- **Not a pen-test tool.** No DAST, no exploitation, no network scanning of
+  deployed systems. That is a separate product with a different legal posture
+  (authorisation required) and a blast radius this tool must never have.
+- **Not a code-quality platform.** SonarQube's territory. We do security only.
+
+## 3. The moat — non-negotiable
+
+**The product is defined by what it refuses to do.** Competitors cannot copy
+this without breaking their own business model. Every one of these is a hard
+constraint, not an aspiration. Any feature that trades one away must be
+rejected, however useful it seems.
+
+1. **It never phones home, and that is provable.** `--network=none` on the
+   quick profile. Source is mounted read-only. No account, no API key, no
+   telemetry, ever. A reviewer must be able to *verify* this themselves, not
+   take our word for it.
+2. **The source tree is mounted read-only.** The scanner cannot modify the code
+   it scans — structurally, not by policy.
+3. **Vulnerability data comes from auditable primary sources** (CISA KEV, FIRST
+   EPSS, OSV). No proprietary database, no lock-in, mirrorable for air-gapped
+   use.
+4. **Results never leave the machine and are never committed.**
+
+> If a future proposal improves results by sending data somewhere, that is the
+> moat being traded away. Refuse it, or escalate to the owner explicitly.
+
+## 4. Human-in-the-loop is a safety property, not a UX choice
+
+The developer chooses **which** fixes to apply and **when** to rescan. There is
+no autonomous remediation loop.
+
+Why this is non-negotiable: an agent told to drive findings to zero has a
+cheaper path via deleting code or writing suppressions than via correct fixes.
+"The finding disappeared" is not the same claim as "the vulnerability is fixed"
+— swapping a hash function satisfies the scanner and breaks every stored
+credential. Only a human can distinguish those.
+
+Consequences, already reflected in the architecture:
+- No `scan_and_fix` MCP tool exists. The MCP surface is read-only w.r.t. source.
+- `REMEDIATION.md` is a **proposal**, never an execution script. Each item is
+  independently applicable, because the developer will cherry-pick.
+- Rescan is always an explicit call. No file watchers, no on-save hooks.
+
+## 5. Target market
+
+Primary, in priority order:
+
+1. **Regulated industries that cannot send code to a vendor** — finance,
+   defence, healthcare, government, critical infrastructure. For them, "your
+   dependency manifest is analysed on our servers" ends the procurement
+   conversation.
+2. **Jurisdictions with data-residency requirements** for AI and code-generation
+   tooling. Cloud code-analysis services are typically offered in a handful of
+   regions; anything outside them is non-compliant by construction. A fully
+   offline tool has no residency question to answer.
+3. **Teams shipping AI-generated code** who need checks nobody else runs —
+   slopsquatting, agent-config auditing, hidden Unicode, LLM-output-to-sink
+   taint.
+4. **Individual developers and OSS maintainers** who want one command, no
+   account, useful output in under 60 seconds.
+
+## 6. Locked decisions
+
+Full rationale lives in `docs/adr/`. Do not re-litigate these without a strong
+new argument.
+
+| # | Decision |
+|---|---|
+| [001](docs/adr/0001-thin-host-shim-read-only-container.md) | **Thin host shim + read-only container engine.** MCP server is a small host-side shim; all scanners live in the image; source mounted `:ro`; scratch dir mounted `:rw`; the shim writes results as the developer's own user. Chosen over a fat container (file-ownership chaos across Docker/Podman/rootless/SELinux) and host install (dependency hell). The mount **is** the workspace jail — structural, not validation code. |
+| [002](docs/adr/0002-layered-results-contract.md) | **Layered results contract.** One in-memory findings model projected to several artifacts, each with exactly one consumer. Self-ignoring results folder. See §7. |
+| [003](docs/adr/0003-per-class-finding-identity.md) | **Per-class finding identity.** Fingerprints keyed by each finding class's natural identity, not line numbers. Versioned (`fp_version`). See §8. |
+| [004](docs/adr/0004-opengrep-not-semgrep.md) | **Opengrep, not Semgrep.** Semgrep moved its maintained rules to a licence permitting only internal, non-competing, non-SaaS use (Dec 2024). We publish a scanning tool — that is plausibly a competing use, and redistributing those rules in an image is legally murky. Opengrep is the LGPL-2.1 consortium fork with the same rule syntax. |
+| [005](docs/adr/0005-no-gpl-tools-in-the-image.md) | **No GPL tools deliberately added.** hadolint is GPL-3.0; Checkov and Trivy cover Dockerfiles adequately. *Corrected 2026-08-30:* the original claim was "no GPL component in the image", which no Linux container can satisfy — ours has 12, all base-OS. F10.4 now constrains what we **add**, and requires an SBOM disclosing the rest. |
+| [006](docs/adr/0006-no-graph-database.md) | **No graph database.** Findings are a flat table with predictable queries. The one graph-shaped thing (the dependency tree) arrives free in the SBOM. Visual comprehension is served by `SUMMARY.md` and `REMEDIATION.md`, which render natively everywhere (see ADR-0014). |
+| [007](docs/adr/0007-internal-enrichment-no-external-platform.md) | **Enrichment is internal and has zero external prerequisites.** ~200 lines behind an `EnrichmentProvider` interface: KEV snapshot bundled in the image, EPSS fetched on demand for found CVEs only, degrading to KEV-only when offline. The sibling VulnGraph project is **parked** and must never become a dependency. |
+| [008](docs/adr/0008-no-saas-coupled-dependencies.md) | **No SaaS-coupled dependencies.** `snyk/agent-scan` was rejected despite being credible (Apache-2.0, well-adopted) because it requires `SNYK_TOKEN` and transmits component data to Snyk. Applying this rule to Snyk and waiving it elsewhere would make the principle meaningless. |
+| [009](docs/adr/0009-human-in-the-loop-remediation.md) | **Human-in-the-loop remediation.** valvur proposes, never remediates. No `scan_and_fix` tool, no watchers, no on-save hooks — and a test asserts no such tool *exists in the registry*, so adding one fails the build rather than merely failing review. An agent told to drive findings to zero has a cheaper path via deletion and suppression than via correct fixes. See §4. |
+| [015](docs/adr/0015-hand-rolled-mcp-stdio-transport.md) | **MCP stdio is hand-rolled, zero dependencies.** The official SDK pulls 22 packages — an HTTP server, an OAuth stack and a crypto library — to support transports Kiro and Claude Code do not use. stdio has no listener: the process boundary is the trust boundary. MCP is on the **primary** install path; the CLI is second. |
+| [014](docs/adr/0014-no-html-report.md) | **No `report.html`.** Cut before implementation. The Results Folder is deliberately unshareable (ADR-0011), which removes an HTML report's main advantage over Markdown; rendering untrusted content in a browser was the largest security surface in the contract; and it was the only artifact with no single identified consumer, which is ADR-0002's own rule. F7.8 deferred, F7.15 stays dormant. |
+| [013](docs/adr/0013-checks-run-inside-the-container.md) | **valvur's own Checks run inside the container**, like Scanners. Host-side would put the Dependency Reality Check's registry calls outside `--network=none`, turning ADR-0010's guarantee back into a policy. No new orchestrator protocol was needed: Checks emit JSON and fit the existing adapter contract. |
+| [011](docs/adr/0011-scan-output-never-enters-git.md) | **Scan output never enters git history, on any branch.** Self-ignoring folder + root `.gitignore` + a tracked `pre-commit` hook that refuses staged `.security-scan/` paths (`.gitignore` does not stop `git add -f`). A separate "clean publish branch" was rejected: git objects are repo-wide, so committing on any branch puts results on the remote. |
+| [012](docs/adr/0012-vulnerability-db-lives-outside-the-image.md) | **The vulnerability DB lives outside the image.** Baking Trivy's DB in took the image from 187MB to 1.52GB *and* tied advisory freshness to image release cadence. It now lives in a host cache, mounted at scan time; scans run `--skip-db-update` so `quick` stays offline. |
+| [010](docs/adr/0010-provable-non-exfiltration.md) | **Provable non-exfiltration is a hard constraint.** Not a policy — a testable property, with a regression test that fails if the quick profile touches a socket. This is the product; see §3. |
+
+## 7. Results contract
+
+Written into the scanned project:
+
+```
+.security-scan/
+  .gitignore          # contains "*" — the folder ignores itself
+  SUMMARY.md          # entry point, capped ~200 lines, leads with failures
+  REMEDIATION.md      # ranked proposal: KEV/EPSS order, dependency paths
+  findings.json       # normalised, schema-versioned, secrets redacted
+  results.sarif       # SARIF 2.1.0 for IDEs and tooling
+  sbom.cdx.json       # CycloneDX
+  run.json            # provenance: tool + DB versions, skips, failures
+  state.json          # previous run's fingerprints (local only)
+  raw/                # per-tool output, secrets redacted
+```
+
+Plus `.security-scan.toml` at project root — **committed**, holds suppressions
+with **mandatory expiry dates**.
+
+Rules that must hold:
+- **Self-ignoring folder** is the guarantee results are never committed; a root
+  `.gitignore` entry is added too, as a visible signal to humans.
+- **Secrets are redacted** in every written artifact including `raw/`. Gitleaks
+  emits live credential values; writing those verbatim would have our security
+  tool copy your secrets to a second cleartext location on disk.
+- **Progressive disclosure.** The agent always reads `SUMMARY.md` (bounded),
+  works from `REMEDIATION.md`, queries `findings.json` per finding, and never
+  reads `raw/`. A 40MB scan stays usable because the read path is bounded.
+- **`SUMMARY.md` opens with a machine-facing block** explaining the folder. An
+  agent in someone else's repo meets the output before it ever sees our README.
+- **Fail loudly.** If a scanner crashed, that appears at the top of
+  `SUMMARY.md`. A silent failure manufactures false confidence and is worse
+  than no scan.
+- **Evidence is neutralised, never reproduced raw** (F3.13). An agent reads
+  `SUMMARY.md` first and by instruction. If we quote an injection payload
+  verbatim, we launder an attack out of a file the agent might never have
+  opened into one we tell it to read. Hidden Unicode is escaped; directive
+  text is fenced and labelled untrusted. **valvur must never become the
+  delivery mechanism.**
+- **The same applies to MCP responses** (F9.9). A response reaches an agent's
+  context with no file in between — the most direct injection path valvur has,
+  and the only one the agent cannot decline to read.
+- **In markup, escaping replaces fencing** (F7.15). The `[UNTRUSTED CONTENT]`
+  fence is a textual convention with no effect in HTML, where a payload can
+  execute or hide itself with styling while remaining in the file. Any
+  artifact that renders escapes workspace content so it cannot act as markup,
+  style or script. Dormant since ADR-0014 cut `report.html`; the guard stays in
+  force for whatever renders next.
+- **Clean is explicit.** No findings still writes the folder, with
+  `"status": "clean"`, so an agent can tell "clean" from "never ran".
+
+## 8. Finding identity
+
+Identity is per finding class, keyed on what is naturally stable — never on
+line numbers, which shift on every edit and would make the rescan diff useless.
+
+| Class | Identity |
+|---|---|
+| Dependency CVE | `(ecosystem, package, version, vuln_id)` |
+| Secret | `(rule, path, sha256(secret)[:16])` |
+| IaC misconfig | `(rule, path, resource_address)` |
+| Licence | `(package, license_id)` |
+| Slopsquat / dep-reality | `(ecosystem, package_name)` |
+| SAST / AI-artifact | `(rule, path, sha256(normalised_match), occurrence)` |
+
+Only the last row needs a content hash. Paths are repo-relative so fingerprints
+are byte-identical across machines — suppressions are shared in a committed
+file and must match everywhere.
+
+`fp_version` is a compatibility surface from the first commit: changing the
+algorithm invalidates every suppression in every repo using the tool.
+
+Status diff: `new` / `persisting` / `fixed` / `regressed`, computed against
+`state.json`. A fresh clone has no history and reports everything as `new` —
+correct and honest.
+
+## 9. Working conventions
+
+- **Spec-driven.** [`.kiro/specs/valvur/`](.kiro/specs/valvur/) holds
+  [requirements](.kiro/specs/valvur/requirements.md) →
+  [design](.kiro/specs/valvur/design.md) →
+  [tasks](.kiro/specs/valvur/tasks.md). Requirement IDs (F1.1, N2.1, P5 …) are
+  load-bearing — cited by the design, the tasks and the verification suite.
+  **Never renumber them.**
+- **Vocabulary.** [CONTEXT.md](CONTEXT.md) is the glossary. Use its terms
+  exactly; the `_Avoid_` lists exist because the wrong word erodes a constraint.
+- **Test-driven.** Tests before implementation. Fingerprinting, normalisation
+  and redaction are the highest-value units — write those first.
+- **ADRs** in `docs/adr/`, numbered, with rejected alternatives recorded.
+- **Dogfooding is a release gate.** The tool scans itself; a clean self-scan,
+  signed image, published SBOM and pinned dependencies gate every release.
+  For a security tool the repo is its own best test case, and anything we
+  preach but do not practise is the first thing a reviewer will notice.
+
+## 10. Prohibited without explicit owner approval
+
+- Any network call in the `quick` profile.
+- Any dependency requiring an account, API key or token to function.
+- Any feature that writes to the scanned source tree.
+- Any autonomous remediation.
+- Any claim of reachability analysis, proprietary detection, or coverage we do
+  not have.
+- Bundling GPL-licensed tools into the distributed image.

valvur-0.1.0rc1/CONTEXT.md

@@ -0,0 +1,96 @@
+# valvur
+
+A fully offline security scanner for codebases, with particular attention to how
+AI-generated code fails. It orchestrates third-party scanners, normalises their
+output into a single model, ranks it by real-world exploitability, and writes it
+where a developer or a coding agent can act on it.
+
+## Language
+
+### Scanning
+
+**Scan Run**:
+One complete invocation of valvur against one Workspace, producing one Results Folder.
+_Avoid_: scan, job, execution, analysis
+
+**Workspace**:
+The developer's project being examined. Always mounted read-only; valvur never writes to it.
+_Avoid_: project, repo, target, source directory, codebase
+
+**Profile**:
+The named breadth of a Scan Run — `quick`, `standard` or `deep` — determining which Scanners run and whether any network access is permitted.
+_Avoid_: mode, level, preset, tier
+
+**Scanner**:
+A third-party tool that performs actual detection (Trivy, Gitleaks, Opengrep, Checkov, OSV-Scanner, Syft). valvur never detects anything itself.
+_Avoid_: tool, engine, plugin, analyser
+
+**Check**:
+A detection valvur performs itself rather than delegating to a Scanner — the Dependency Reality Check, AI Artifact scan, pinning hygiene, and Licence Hygiene.
+_Avoid_: rule, test, custom scanner
+
+### Findings
+
+**Finding**:
+One problem identified in the Workspace, attributed to the Scanner or Check that produced it.
+_Avoid_: issue, vulnerability, alert, violation, error, result
+
+**Finding Class**:
+The category a Finding belongs to — dependency vulnerability, secret, IaC misconfiguration, licence, dependency reality, or static analysis. Determines how its Fingerprint is derived.
+_Avoid_: type, kind, category
+
+**Fingerprint**:
+A Finding's stable identity across Scan Runs, derived from its Finding Class's natural key. Never derived from line numbers. Byte-identical across machines.
+_Avoid_: id, hash, key, signature
+
+**Status**:
+A Finding's relationship to the previous Scan Run — `new`, `persisting`, `fixed`, or `regressed`.
+_Avoid_: state, disposition
+
+**Redaction**:
+The replacement of a secret's value with its Fingerprint before any Finding is written to disk. Applies to every written artifact without exception.
+_Avoid_: masking, scrubbing, sanitising
+
+### Prioritisation
+
+**Enrichment**:
+Exploitability information attached to a Finding to rank it — distinct from the severity a Scanner assigns.
+_Avoid_: metadata, context, intel, annotation
+
+**Exploit Signal**:
+Evidence that a vulnerability is exploited in reality rather than in theory: presence in CISA KEV, the KEV ransomware flag, and the FIRST EPSS probability.
+_Avoid_: threat intel, exploit data
+
+**Enrichment Provider**:
+A source of Enrichment behind a common interface. The only Provider is local — a bundled KEV snapshot plus on-demand EPSS lookups.
+_Avoid_: intel source, feed, backend
+
+**Dependency Path**:
+The chain from a direct dependency of the Workspace to a vulnerable transitive one, naming the direct package that must change.
+_Avoid_: dependency chain, transitive path
+
+**Slopsquat**:
+A package registered by an attacker under a name that language models hallucinate. Detected by the Dependency Reality Check, not by any advisory database.
+_Avoid_: typosquat, malicious package
+
+### Output and disposition
+
+**Results Folder**:
+The `.security-scan/` directory written into the Workspace by the host, ignoring itself via its own `.gitignore`. Never committed.
+_Avoid_: output directory, report directory, artifacts
+
+**Provenance**:
+The record of what a Scan Run actually did — Scanner versions, Enrichment age, what was skipped and why, what failed. Makes a clean result falsifiable.
+_Avoid_: metadata, manifest, audit log
+
+**Clean Scan**:
+A Scan Run that completed with no Findings. Still writes a full Results Folder, so it is distinguishable from a Scan Run that never happened.
+_Avoid_: pass, green, empty result
+
+**Remediation Item**:
+A proposed change addressing one or more Findings, ranked by Exploit Signal and independently applicable. A proposal for a human, never an instruction executed automatically.
+_Avoid_: fix, recommendation, action, task
+
+**Suppression**:
+A recorded decision to accept a Finding, keyed by Fingerprint, carrying a mandatory expiry date. Lives in the Workspace and is committed — unlike the Results Folder.
+_Avoid_: ignore, exception, waiver, mute, allowlist entry

valvur-0.1.0rc1/Dockerfile

@@ -0,0 +1,60 @@
+# valvur scanner image.
+#
+# Scanners are pinned to exact versions (F2.2). Non-root, read-only root filesystem,
+# no capabilities (F10.2). No GPL/AGPL components (ADR-0005).
+#
+# The vulnerability DB is deliberately NOT baked in — it is 1.2GB and would tie
+# advisory freshness to image release cadence (ADR-0012).
+
+FROM zricethezav/gitleaks:v8.30.1        AS gitleaks
+FROM aquasec/trivy:0.74.0                AS trivy
+FROM ghcr.io/google/osv-scanner:v2.2.4   AS osv
+FROM anchore/syft:v1.51.1                AS syft
+
+FROM python:3.12-alpine3.22
+ARG TARGETARCH
+ARG VALVUR_VERSION=0.0.0-dev
+LABEL org.opencontainers.image.source="https://github.com/MaverickHQ/valvur"
+LABEL org.opencontainers.image.description="Fully offline security scanner for AI-generated code"
+LABEL org.opencontainers.image.licenses="MIT"
+# Read by the shim to refuse an incompatible pair (F1.9). ADR-0001 accepted two
+# artifacts on condition this check existed.
+LABEL org.opencontainers.image.version="${VALVUR_VERSION}"
+
+COPY --from=gitleaks /usr/bin/gitleaks        /usr/local/bin/gitleaks
+COPY --from=trivy    /usr/local/bin/trivy     /usr/local/bin/trivy
+COPY --from=osv      /osv-scanner             /usr/local/bin/osv-scanner
+COPY --from=syft     /syft                    /usr/local/bin/syft
+
+# Opengrep publishes signed static musllinux binaries but no image. LGPL-2.1, and
+# the consortium fork of Semgrep - see ADR-0004 for why not Semgrep itself.
+ADD --chmod=755 https://github.com/opengrep/opengrep/releases/download/v1.29.0/opengrep_musllinux_x86 /tmp/opengrep_amd64
+ADD --chmod=755 https://github.com/opengrep/opengrep/releases/download/v1.29.0/opengrep_musllinux_aarch64 /tmp/opengrep_arm64
+RUN mv /tmp/opengrep_${TARGETARCH} /usr/local/bin/opengrep && rm -f /tmp/opengrep_*
+
+# Our own rules, licensed with the project. Bundling the community registry would
+# reintroduce exactly the licensing problem ADR-0004 exists to avoid.
+COPY rules /opt/valvur-rules
+
+# valvur's own Checks run in the container, like Scanners (ADR-0013), so the package
+# ships in the image. Last layer: check code changes rebuild only this.
+COPY src/valvur /usr/local/lib/python3.12/site-packages/valvur
+
+# Checkov is Python. Installed into the system environment; no compiler is kept.
+RUN apk add --no-cache --virtual .build gcc musl-dev libffi-dev \
+ && pip install --no-cache-dir checkov==3.2.517 \
+ && apk del .build \
+ && find /usr/local -name '__pycache__' -type d -prune -exec rm -rf {} + 2>/dev/null || true
+
+# Checkov ships an update checker that calls out at startup and writes a cache.
+# Both are disabled explicitly: a scanner that phones home would break the central
+# claim in ADR-0010, and our read-only rootfs caught it only by accident.
+ENV TRIVY_CACHE_DIR=/cache/trivy \
+    PYTHONDONTWRITEBYTECODE=1 \
+    CHECKOV_DISABLE_UPDATE_CHECK=true \
+    HOME=/tmp
+
+RUN adduser -D -u 10001 valvur
+USER 10001:10001
+WORKDIR /workspace
+# No ENTRYPOINT: the shim names a specific scanner binary per adapter.