From def79b0b292c30e516009ae97114f2ccca30a8f3 Mon Sep 17 00:00:00 2001 From: Marcin Gasperowicz Date: Sun, 30 Aug 2026 21:37:28 +0100 Subject: [PATCH 1/3] docs(adr): propose Monk kit for Live deployment and packaging Adds ADR-0001 recording Monk Kit as the intended hosted Live deploy/packaging path. Status stays Proposed and documentation-only. Addresses review feedback on PR #63: - Keeps current Live (operator workstation flow) and intended Live visibly separate; no claim that Tripwire is deployable via Monk today - States the five-vendor Live baseline (Supabase, Modal, Snyk, Cisco, Tessl) as required, not optional - Splits in-cluster (bootstrap, dashboard, HTTPS ingress) from SaaS (Supabase/PostgREST, Modal, scanner engines) - Defines when Kit v1 is done, with missing scanner credentials as an incomplete deploy - Records coexistence with today's docs and an explicit not-decided-here list Unreserves 0001 in the ADR catalog and logs a DECISIONS row. Co-Authored-By: Claude Opus 5 --- .../adr/0001-monk-deployment-and-packaging.md | 165 ++++++++++++++++++ docs/adr/README.md | 9 +- docs/plan/DECISIONS.md | 1 + 3 files changed, 171 insertions(+), 4 deletions(-) create mode 100644 docs/adr/0001-monk-deployment-and-packaging.md diff --git a/docs/adr/0001-monk-deployment-and-packaging.md b/docs/adr/0001-monk-deployment-and-packaging.md new file mode 100644 index 0000000..3a75389 --- /dev/null +++ b/docs/adr/0001-monk-deployment-and-packaging.md @@ -0,0 +1,165 @@ +# ADR-0001: Monk kit for Live deployment and packaging + +- **Status:** Proposed +- **Date:** 2026-08-11 (updated 2026-08-30) +- **Deciders:** Tripwire maintainers +- **Tags:** deployment, packaging, monk, supabase, modal + +> **This is a proposal, not a shipped capability.** Nothing here is implemented +> on `main`. Until this ADR is accepted **and** the Kit is built, the supported +> Live path remains the operator workstation flow: clone the repo, fill a local +> `.env`, run the setup commands, point the dashboard at hosted Supabase and +> Modal. See [QUICKSTART](../../QUICKSTART.md) and +> [setup-commands](../user-guide/setup-commands.md). Tripwire is **not** +> currently deployable or redistributable via Monk. + +**Monk**, in one line: a packaging and deploy runtime that consumes a *Kit* — a +manifest, templates, and secrets — and provisions the described stack. + +## Context + +Tripwire's Live path today assumes an operator workstation. That works for +contributors who already have the tooling, but it does not make the project +**immediately deployable** or **redistributable as a package**. + +We want a packaging and deploy story where: + +1. Anyone can pull this repo and ask Monk to deploy Tripwire on their cloud. +2. Once published to the Monk registry, users can install Monk and ask to deploy + Tripwire without assembling the stack by hand (public container images + become part of that publish path). +3. As the project grows, the template lives in this repo; shipping a new version + is committing an updated template and publishing images from CI. + +Supabase is the current Live database because the product relies on PostgREST +today ([ADR-0004](./0004-supabase-system-of-record.md)). Supporting other +databases would need application changes; once that exists, alternate DB +backends are natural **package flavors** rather than forks of the whole project. + +## Decision + +**Package Tripwire as a Monk Kit** and treat Monk as the intended path that takes +a user from zero to a running Live instance, *once implemented*. + +### The Live baseline is five vendors + +A packaged Live instance is **Supabase, Modal, Snyk, Cisco, and Tessl** — not +just a dashboard and a database. Credentials for all five are **required** input +to a Kit deploy. Scanner credentials for Snyk, Cisco, and Tessl are not +optional, and a missing scanner key is not an acceptable Live outcome: it makes +the deploy incomplete. + +Cisco is one vendor with two credential shapes — the LLM-backed Skill/MCP +Scanner keys, or the paid AI Defense APIs — and **at least one is required**. +Cisco is not droppable from the baseline. + +Ossprey is **outside** the Kit v1 baseline: the adapter is credential-gated and +RESEARCH-labeled, and access provisioning is still open, so it cannot be a +required input yet ([STATUS](../STATUS.md)). + +### What runs in the cluster, what stays SaaS + +| Location | Components | +|---|---| +| **In the cluster** | Bootstrap, the dashboard, HTTPS ingress | +| **Outside (SaaS)** | Supabase (PostgREST), Modal, and the three scanner engines | + +Modal remains an external SaaS dependency. It is **not** a cluster workload; the +Kit deploys a Modal app and holds its tokens as secrets. + +### Intended user path (after implementation) + +1. Install Monk. +2. Ask Monk to deploy Tripwire (from this repo; later from the Monk registry). +3. Monk collects the required secrets for all five vendors. +4. Monk wires providers and provisions the required services and compute. +5. Monk bootstraps the instance (schema, Modal app, dashboard config). +6. Monk hands back an HTTPS URL to the running instance. + +### Kit v1 is done when + +- Credentials for all five vendors are collected. +- Supabase is provisioned and wired. +- The schema is applied. +- The Modal app is deployed with scanner secrets. +- The HTTPS Live dashboard can read PostgREST. + +If scanner credentials are missing, the deploy is **incomplete** — not a +successful Live instance. + +## Coexistence with today's docs + +The Monk path is **additive** until it is implemented. The workstation flow +(local `.env`, CLI, QUICKSTART) stays the documented and supported Live path, +and remains valid for development afterward. No existing operator +documentation changes on the strength of this ADR alone; docs move only when +the Kit actually ships. + +## Not decided here + +Out of scope for this ADR: Kit YAML and Dockerfiles, registry publication, +authentication and identity providers, other database backends, teaching the +CLI to target an instance URL, locking a cloud vendor, and the implementation +plan itself. Those belong in follow-up slices under `docs/plan`. + +## Consequences + +### Expected benefits + +- The project becomes **immediately deployable** via Monk. +- The project becomes **packaged**: pull the repo → tell Monk to deploy on your + cloud. +- Registry publication is a natural next step, with images published to a + public registry as part of release. +- Template evolution stays in-repo; new versions are template commits plus image + publishes from CI. +- The **same template** can run an official hosted instance and spin up + **isolated ephemeral environments** during development, so people and agents + can acceptance-check a live system without sharing one long-lived stack. +- Other database backends can later appear as package flavors once the app can + talk to them. + +### Costs and open questions + +- Hosted Live depends on Monk for provisioning, secrets, and ingress — by design. +- Requiring five vendors raises the bar for a successful deploy relative to the + Minimum Viable Live (Supabase + Modal) documented in + [env-vars](../user-guide/env-vars.md). That is deliberate: a packaged instance + should not ship with partial scanner coverage. +- Bootstrap and image-publish details are implementation work after this ADR is + accepted; they should stay invisible to the intended user path above. +- Flavoring non-Supabase databases is deferred until the application boundary + allows it. + +## Alternatives considered + +### A. Document-only Live (status quo) + +Keep README / user-guide as the only Live path (local `.env`, CLI, Modal CLI). + +**Rejected for redistribution:** it does not produce a deployable package and +still requires a fully tooled operator machine. It remains the supported path +until this ADR is implemented. + +### B. Hand-rolled CI/CD without Monk as the product path + +Maintain cloud-specific Actions or Terraform as the primary deploy story. + +**Not the primary path.** The next step after a working Kit is the opposite +direction: **Monk generates** the CI/CD action that deploys to an existing +cluster. Secrets remain handled by Monk; the workflow needs cluster coordinates +and the Kit's manifest and templates. Custom pipelines remain possible for +advanced operators, but they are not the default we are packaging toward. + +## References + +- Live capabilities and honesty: [docs/STATUS.md](../STATUS.md) +- Architecture containers and service inventory: [docs/ARCHITECTURE.md](../ARCHITECTURE.md) +- Current Live path: [QUICKSTART.md](../../QUICKSTART.md) · + [setup-commands](../user-guide/setup-commands.md) · + [env-vars](../user-guide/env-vars.md) +- Operator Modal setup today: [modal-setup](../user-guide/modal-setup.md) +- Operator Supabase setup today: [supabase-setup](../user-guide/supabase-setup.md) +- Supabase as system of record: [ADR-0004](./0004-supabase-system-of-record.md) +- Modal for isolated scanner execution: [ADR-0003](./0003-modal-isolated-scanner-execution.md) +- Planning log: [docs/plan/DECISIONS.md](../plan/DECISIONS.md) diff --git a/docs/adr/README.md b/docs/adr/README.md index 8cdb862..4386a7f 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -9,12 +9,13 @@ quality gates. Status values: **Proposed**, **Accepted**, **Deprecated**, **Superseded**. -Number **0001** is reserved and omitted from this catalog while a Proposed -**Monk Live packaging / deployment** draft remains under review on a side -branch (not merged to `main`). Published records start at **0002**. +**0001** is **Proposed**, not Accepted: it records an intended Monk packaging / +deployment path that is **not implemented**. The supported Live path remains the +operator workstation flow. Records **0002** and above are Accepted. | ADR | Title | Status | |-----|-------|--------| +| [0001](./0001-monk-deployment-and-packaging.md) | Monk Kit for Live deployment and packaging | Proposed | | [0002](./0002-node-cli-python-sandbox-split.md) | Node CLI and Python sandbox as separate runtimes | Accepted | | [0003](./0003-modal-isolated-scanner-execution.md) | Modal for isolated scanner execution | Accepted | | [0004](./0004-supabase-system-of-record.md) | Supabase/Postgres as system of record | Accepted | @@ -32,5 +33,5 @@ branch (not merged to `main`). Published records start at **0002**. | [0016](./0016-tiered-router-sie-model-studio.md) | Tiered post-scan router via SIE and Model Studio | Accepted | | [0017](./0017-claude-code-agent-guard-integration.md) | Claude Code Agent Guard integration (amends ADR-0015) | Accepted | -0002–0016 are retrospective Accepted records of decisions already visible in +0002–0017 are retrospective Accepted records of decisions already visible in docs, git history, and production entry points. diff --git a/docs/plan/DECISIONS.md b/docs/plan/DECISIONS.md index dd98ed7..be4bbd5 100644 --- a/docs/plan/DECISIONS.md +++ b/docs/plan/DECISIONS.md @@ -194,3 +194,4 @@ | 2026-08-25 | slice/42-quality-score-tabs | sync-docs | TRAIL/PROGRESS/gate-evidence/slice-42 + ARCHITECTURE + STATUS + README aligned to three-tab delta. APPLIED | | 2026-08-25 | sync-docs | Slice 28 feature-delta discoverability | PROGRESS execution-order 🔀; ARCHITECTURE Wave H Phase 1; docs hub + reading-router-results Tessl quality ↔ `/tw-verify` Quality; STATUS PROPOSED/Future SUPERSEDED for Phase 1. APPLIED | | 2026-08-25 | sync-docs | Slice 28 Sources attribution | Discoverability: agent-hooks README, docs hub, ARCHITECTURE/STATUS Wave H, reading-router-results, slice stub, tw-verify skill intro — Quality=Tessl / Status=Cisco+Snyk. Contract + verify.py already had Sources. README/AGENTS NO_CHANGE. APPLIED | +| 2026-08-30 | packaging | ADR-0001 Proposed | Monk Kit as the intended hosted Live deploy/packaging path — five-vendor baseline (Supabase, Modal, Snyk, Cisco, Tessl) required; in-cluster bootstrap + dashboard + HTTPS ingress, Modal stays SaaS. Formal record: `docs/adr/0001-monk-deployment-and-packaging.md`. Proposal only — not implemented; workstation Live path unchanged. PROPOSED | From 5f1b6dd56c80ce2af7c1154f630469174cc79f9f Mon Sep 17 00:00:00 2001 From: Marcin Gasperowicz Date: Tue, 1 Sep 2026 15:08:01 +0100 Subject: [PATCH 2/3] docs(adr): address review round 2 on ADR-0001 - Clarify that "Modal is not a cluster workload" means no Modal container runs in-cluster, not that Modal is unconfigured: the cluster reaches out to Modal, which spins the sandboxes - Kit collects OSSPREY_API_KEY as an optional pass-through secret; Ossprey stays out of the required baseline while access provisioning is open - Promote isolated ephemeral environments into the Decision as a co-equal motivation, with the mechanism named (separate Kit deploy, isolated credentials, configured by the Monk agent from one template) - Add Alternative C comparing Helm, Kustomize, and Terraform, and say what Monk gives that they do not - Note that Monk's CI/CD generation is an existing capability, while Tripwire's adoption of it is follow-up work - DECISIONS row uses the branch name in the second column Co-Authored-By: Claude Opus 5 --- .../adr/0001-monk-deployment-and-packaging.md | 71 ++++++++++++++++--- docs/plan/DECISIONS.md | 2 +- 2 files changed, 61 insertions(+), 12 deletions(-) diff --git a/docs/adr/0001-monk-deployment-and-packaging.md b/docs/adr/0001-monk-deployment-and-packaging.md index 3a75389..5bdf8a3 100644 --- a/docs/adr/0001-monk-deployment-and-packaging.md +++ b/docs/adr/0001-monk-deployment-and-packaging.md @@ -41,6 +41,16 @@ backends are natural **package flavors** rather than forks of the whole project. **Package Tripwire as a Monk Kit** and treat Monk as the intended path that takes a user from zero to a running Live instance, *once implemented*. +Two motivations carry equal weight. The first is redistribution: pull the repo, +tell Monk to deploy, get a Live instance. The second is **isolated ephemeral +environments** — each ephemeral instance is a separate Kit deploy with isolated +credentials, configured by the Monk agent from the single in-repo template. The +same template that runs an official hosted instance can therefore spin up +throwaway instances for development and review, so contributors and agents can +acceptance-check a live system without sharing one long-lived stack. For a +project with this much agent-driven workflow, that is a first-class reason to +package, not a side effect of it. + ### The Live baseline is five vendors A packaged Live instance is **Supabase, Modal, Snyk, Cisco, and Tessl** — not @@ -53,9 +63,12 @@ Cisco is one vendor with two credential shapes — the LLM-backed Skill/MCP Scanner keys, or the paid AI Defense APIs — and **at least one is required**. Cisco is not droppable from the baseline. -Ossprey is **outside** the Kit v1 baseline: the adapter is credential-gated and -RESEARCH-labeled, and access provisioning is still open, so it cannot be a -required input yet ([STATUS](../STATUS.md)). +Ossprey sits just outside that baseline. The Kit **collects `OSSPREY_API_KEY` +as an optional secret** and passes it through to the sandbox, so a keyed +operator gets Ossprey coverage on a Kit deploy. It is not a required input: +the adapter is credential-gated and RESEARCH-labeled, and access provisioning +is still open, so a deploy must not fail for want of an Ossprey key +([STATUS](../STATUS.md)). ### What runs in the cluster, what stays SaaS @@ -64,8 +77,12 @@ required input yet ([STATUS](../STATUS.md)). | **In the cluster** | Bootstrap, the dashboard, HTTPS ingress | | **Outside (SaaS)** | Supabase (PostgREST), Modal, and the three scanner engines | -Modal remains an external SaaS dependency. It is **not** a cluster workload; the -Kit deploys a Modal app and holds its tokens as secrets. +Modal remains an external SaaS dependency. "Not a cluster workload" means no +Modal container runs inside the cluster — it does **not** mean Modal is +unconfigured. The Kit holds Modal tokens as secrets and deploys the Modal app +during bootstrap; at scan time the cluster reaches **out** to Modal, which +spins up the sandboxes on its own infrastructure. Scanner engines are reached +the same way. ### Intended user path (after implementation) @@ -113,9 +130,8 @@ plan itself. Those belong in follow-up slices under `docs/plan`. public registry as part of release. - Template evolution stays in-repo; new versions are template commits plus image publishes from CI. -- The **same template** can run an official hosted instance and spin up - **isolated ephemeral environments** during development, so people and agents - can acceptance-check a live system without sharing one long-lived stack. +- Isolated ephemeral environments for development and review, from the same + template as the hosted instance (see the Decision above). - Other database backends can later appear as package flavors once the app can talk to them. @@ -147,9 +163,42 @@ Maintain cloud-specific Actions or Terraform as the primary deploy story. **Not the primary path.** The next step after a working Kit is the opposite direction: **Monk generates** the CI/CD action that deploys to an existing -cluster. Secrets remain handled by Monk; the workflow needs cluster coordinates -and the Kit's manifest and templates. Custom pipelines remain possible for -advanced operators, but they are not the default we are packaging toward. +cluster. That generation is an existing Monk capability, not a future one — +but Tripwire does not use it yet, and adopting it is follow-up work outside +this ADR. Secrets remain handled by Monk; the workflow needs cluster +coordinates and the Kit's manifest and templates. Custom pipelines remain +possible for advanced operators, but they are not the default we are packaging +toward. + +### C. Helm, Kustomize, or Terraform + +The obvious alternatives. Each solves part of the problem; none covers the +whole path from "pull the repo" to "HTTPS Live instance", which is what this +ADR is choosing. + +- **Secrets are first-class in Monk.** It collects, stores, and injects them — + including values *generated during provisioning*, such as the Supabase + service-role and anon keys, which do not exist until the project is created. + Helm and Kustomize template manifests and defer secrets to an external store; + wiring a generated credential into the next step is the operator's problem. +- **Monk provisions the managed SaaS.** The Supabase entity creates the project; + it does not merely template a reference to one that already exists. Helm and + Kustomize cannot provision off-cluster services at all. Terraform can, but + then Terraform provisions and something else deploys and something else holds + secrets — three tools where the Kit is one. +- **Versioned Kit plus a registry.** A manifest with versioned templates and a + registry install path is what makes "install Monk, deploy Tripwire" work + without assembling the stack by hand. Helm has charts and repositories but no + provisioning story; Terraform has modules and a registry but no packaged + runtime. +- **Ephemeral environments from one template.** The Monk agent configures each + ephemeral instance as a separate Kit deploy with isolated credentials from the + same in-repo template — the motivation named in the Decision. Reproducing that + on the alternatives means maintaining a parallel path for dev environments. + +**Not rejected as tooling.** Helm or Terraform could sit *under* a future +deployment if that ever helps; the point is that neither is the packaging and +distribution unit this ADR needs. ## References diff --git a/docs/plan/DECISIONS.md b/docs/plan/DECISIONS.md index b473014..de845cb 100644 --- a/docs/plan/DECISIONS.md +++ b/docs/plan/DECISIONS.md @@ -194,6 +194,6 @@ | 2026-08-25 | slice/42-quality-score-tabs | sync-docs | TRAIL/PROGRESS/gate-evidence/slice-42 + ARCHITECTURE + STATUS + README aligned to three-tab delta. APPLIED | | 2026-08-25 | sync-docs | Slice 28 feature-delta discoverability | PROGRESS execution-order 🔀; ARCHITECTURE Wave H Phase 1; docs hub + reading-router-results Tessl quality ↔ `/tw-verify` Quality; STATUS PROPOSED/Future SUPERSEDED for Phase 1. APPLIED | | 2026-08-25 | sync-docs | Slice 28 Sources attribution | Discoverability: agent-hooks README, docs hub, ARCHITECTURE/STATUS Wave H, reading-router-results, slice stub, tw-verify skill intro — Quality=Tessl / Status=Cisco+Snyk. Contract + verify.py already had Sources. README/AGENTS NO_CHANGE. APPLIED | -| 2026-08-30 | packaging | ADR-0001 Proposed | Monk Kit as the intended hosted Live deploy/packaging path — five-vendor baseline (Supabase, Modal, Snyk, Cisco, Tessl) required; in-cluster bootstrap + dashboard + HTTPS ingress, Modal stays SaaS. Formal record: `docs/adr/0001-monk-deployment-and-packaging.md`. Proposal only — not implemented; workstation Live path unchanged. PROPOSED | +| 2026-08-30 | docs/adr-monk-deployment-packaging | ADR-0001 Proposed | Monk Kit as the intended hosted Live deploy/packaging path — five-vendor baseline (Supabase, Modal, Snyk, Cisco, Tessl) required; in-cluster bootstrap + dashboard + HTTPS ingress, Modal stays SaaS. Formal record: `docs/adr/0001-monk-deployment-and-packaging.md`. Proposal only — not implemented; workstation Live path unchanged. PROPOSED | | 2026-08-31 | wave-N-review | GWT reviewer blockers fixed (slices 55/56/57) | nw-acceptance-designer-reviewer returned 3 BLOCKED slices. Applied fixes: 55 dep header + GWT-55.3 placement locked to adjacent-copy + GWT-55.5 inlined D3/D4/D8 text; 56 GWT-56a locked to prerequisites.md + GWT-56b/c/d rewritten to artifact-presence assertions + GWT-56f added (B.4 scanner×input-type matrix); 57 GWT-57a.2 concrete exclusion list + GWT-57b.1 module names inlined. APPLIED | | 2026-08-31 | wave-N-review | Docs reviewer blockers fixed (audit report) | nw-documentarist-reviewer: B.4 scanner×input-type matrix (confirmed P1/M) added as seq-8 (56-f) in execution queue; setup-commands DIVIO collapse (pre-existing, not Wave N) added to Not-Now list as Wave O tech debt; DIVIO 'Adopted — partial' row expanded with enumeration; temporal disclaimer at line 8 clarified (reviewed against main + pre-merge slice-44 branch). APPLIED | From 5449d7099d94782515bfd8f93c04e46b69d1daf2 Mon Sep 17 00:00:00 2001 From: Marcin Gasperowicz Date: Tue, 8 Sep 2026 18:05:08 +0100 Subject: [PATCH 3/3] docs(adr): rewrite ADR-0001 Decision around the 3-tier vendor model MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tier 1 (Supabase, Modal) gates any deploy — this is MVL. Tier 2 (Snyk, Cisco, Tessl) is required for full scanner coverage. Tier 3 (SIE, Alibaba Model Studio, Ossprey) is env-var pass-through only, with no provisioning and no power to fail a deploy. Kit v1 "done" is now defined at two levels — MVL-complete and full-coverage-complete — and the partial-coverage signalling question moves into open questions. Ossprey folds into Tier 3 rather than sitting outside the baseline. Cisco keeps its two-credential-shapes clause. Co-Authored-By: Claude Opus 5 --- .../adr/0001-monk-deployment-and-packaging.md | 79 ++++++++++++------- docs/plan/DECISIONS.md | 2 +- 2 files changed, 52 insertions(+), 29 deletions(-) diff --git a/docs/adr/0001-monk-deployment-and-packaging.md b/docs/adr/0001-monk-deployment-and-packaging.md index 5bdf8a3..6501750 100644 --- a/docs/adr/0001-monk-deployment-and-packaging.md +++ b/docs/adr/0001-monk-deployment-and-packaging.md @@ -1,7 +1,7 @@ # ADR-0001: Monk kit for Live deployment and packaging - **Status:** Proposed -- **Date:** 2026-08-11 (updated 2026-08-30) +- **Date:** 2026-08-11 (updated 2026-09-08) - **Deciders:** Tripwire maintainers - **Tags:** deployment, packaging, monk, supabase, modal @@ -51,31 +51,45 @@ acceptance-check a live system without sharing one long-lived stack. For a project with this much agent-driven workflow, that is a first-class reason to package, not a side effect of it. -### The Live baseline is five vendors - -A packaged Live instance is **Supabase, Modal, Snyk, Cisco, and Tessl** — not -just a dashboard and a database. Credentials for all five are **required** input -to a Kit deploy. Scanner credentials for Snyk, Cisco, and Tessl are not -optional, and a missing scanner key is not an acceptable Live outcome: it makes -the deploy incomplete. - -Cisco is one vendor with two credential shapes — the LLM-backed Skill/MCP -Scanner keys, or the paid AI Defense APIs — and **at least one is required**. -Cisco is not droppable from the baseline. - -Ossprey sits just outside that baseline. The Kit **collects `OSSPREY_API_KEY` -as an optional secret** and passes it through to the sandbox, so a keyed -operator gets Ossprey coverage on a Kit deploy. It is not a required input: -the adapter is credential-gated and RESEARCH-labeled, and access provisioning -is still open, so a deploy must not fail for want of an Ossprey key +### The Live vendor baseline is tiered + +A packaged Live instance is more than a dashboard and a database — but not every +vendor gates a deploy. Three tiers: + +| Tier | Vendors | Required for | Kit handling | +|---|---|---|---| +| **1** | Supabase, Modal | Any deploy at all | Provisioned and wired by the Kit | +| **2** | Snyk, Cisco, Tessl | Full scanner coverage | Credentials collected; engines reached as SaaS | +| **3** | SIE (Superlinked), Alibaba Model Studio, Ossprey | Optional routing and research coverage | Env-var pass-through only, no provisioning | + +**Tier 1** is the Minimum Viable Live already documented in +[env-vars](../user-guide/env-vars.md): Supabase plus Modal. Without Tier 1 +credentials there is no deploy. + +**Tier 2** turns an MVL instance into a full-coverage one. A Tier-1-only deploy +is a *valid but partial* Live instance: it runs, and it scans with whatever +engines are keyed. Cisco is one vendor with two credential shapes — the +LLM-backed Skill and MCP Scanner keys, or the paid AI Defense APIs — and at +least one of the two is needed for Cisco coverage. + +**Tier 3** vendors are collected as pass-through secrets and nothing more: the +Kit provisions nothing for them, and a deploy never fails for want of one. +`SIE_ENDPOINT` and `SIE_API_KEY` enable the tiered router; `DASHSCOPE_API_KEY` +and `ALIBABA_OPENAI_BASE_URL` enable Model Studio escalation; +`OSSPREY_API_KEY` enables the credential-gated, RESEARCH-labeled Ossprey +malware adapter, whose access provisioning is still open ([STATUS](../STATUS.md)). +These tier boundaries — and the Kit specifics behind them — are revisitable +once the actual Monk configuration lands in the repo. This ADR is the intent +record, not the implementation contract. + ### What runs in the cluster, what stays SaaS | Location | Components | |---|---| | **In the cluster** | Bootstrap, the dashboard, HTTPS ingress | -| **Outside (SaaS)** | Supabase (PostgREST), Modal, and the three scanner engines | +| **Outside (SaaS)** | Supabase (PostgREST), Modal, the three scanner engines, and the Tier 3 endpoints | Modal remains an external SaaS dependency. "Not a cluster workload" means no Modal container runs inside the cluster — it does **not** mean Modal is @@ -88,21 +102,30 @@ the same way. 1. Install Monk. 2. Ask Monk to deploy Tripwire (from this repo; later from the Monk registry). -3. Monk collects the required secrets for all five vendors. +3. Monk collects the Tier 1 secrets it needs to deploy at all, plus whichever + Tier 2 and Tier 3 secrets the operator holds. 4. Monk wires providers and provisions the required services and compute. 5. Monk bootstraps the instance (schema, Modal app, dashboard config). 6. Monk hands back an HTTPS URL to the running instance. ### Kit v1 is done when -- Credentials for all five vendors are collected. +**MVL-complete** — the deploy succeeds and hands back a Live instance: + +- Tier 1 credentials (Supabase, Modal) are collected. - Supabase is provisioned and wired. - The schema is applied. -- The Modal app is deployed with scanner secrets. +- The Modal app is deployed with whatever scanner secrets were supplied. - The HTTPS Live dashboard can read PostgREST. -If scanner credentials are missing, the deploy is **incomplete** — not a -successful Live instance. +**Full-coverage-complete** — MVL-complete, and additionally: + +- Tier 2 credentials (Snyk, Cisco, Tessl) are collected and reach their engines. +- Tier 3 keys, where the operator has them, are passed through to the sandbox. + +An MVL-complete deploy is a successful Live instance with **partial scanner +coverage**; only full-coverage-complete gives an operator every scanner +Tripwire can run. ## Coexistence with today's docs @@ -138,10 +161,10 @@ plan itself. Those belong in follow-up slices under `docs/plan`. ### Costs and open questions - Hosted Live depends on Monk for provisioning, secrets, and ingress — by design. -- Requiring five vendors raises the bar for a successful deploy relative to the - Minimum Viable Live (Supabase + Modal) documented in - [env-vars](../user-guide/env-vars.md). That is deliberate: a packaged instance - should not ship with partial scanner coverage. +- Tier 1 alone produces a valid Live instance with partial scanner coverage. + Open question: how that instance signals its partial coverage to the operator + — a deploy summary, a dashboard surface, or both. Live honesty rules today + live in [STATUS](../STATUS.md). - Bootstrap and image-publish details are implementation work after this ADR is accepted; they should stay invisible to the intended user path above. - Flavoring non-Supabase databases is deferred until the application boundary diff --git a/docs/plan/DECISIONS.md b/docs/plan/DECISIONS.md index de845cb..211d801 100644 --- a/docs/plan/DECISIONS.md +++ b/docs/plan/DECISIONS.md @@ -194,6 +194,6 @@ | 2026-08-25 | slice/42-quality-score-tabs | sync-docs | TRAIL/PROGRESS/gate-evidence/slice-42 + ARCHITECTURE + STATUS + README aligned to three-tab delta. APPLIED | | 2026-08-25 | sync-docs | Slice 28 feature-delta discoverability | PROGRESS execution-order 🔀; ARCHITECTURE Wave H Phase 1; docs hub + reading-router-results Tessl quality ↔ `/tw-verify` Quality; STATUS PROPOSED/Future SUPERSEDED for Phase 1. APPLIED | | 2026-08-25 | sync-docs | Slice 28 Sources attribution | Discoverability: agent-hooks README, docs hub, ARCHITECTURE/STATUS Wave H, reading-router-results, slice stub, tw-verify skill intro — Quality=Tessl / Status=Cisco+Snyk. Contract + verify.py already had Sources. README/AGENTS NO_CHANGE. APPLIED | -| 2026-08-30 | docs/adr-monk-deployment-packaging | ADR-0001 Proposed | Monk Kit as the intended hosted Live deploy/packaging path — five-vendor baseline (Supabase, Modal, Snyk, Cisco, Tessl) required; in-cluster bootstrap + dashboard + HTTPS ingress, Modal stays SaaS. Formal record: `docs/adr/0001-monk-deployment-and-packaging.md`. Proposal only — not implemented; workstation Live path unchanged. PROPOSED | +| 2026-08-30 | docs/adr-monk-deployment-packaging | ADR-0001 Proposed | Monk Kit as the intended hosted Live deploy/packaging path — tiered vendor baseline: Tier 1 Supabase + Modal (MVL, required for any deploy), Tier 2 Snyk + Cisco + Tessl (full scanner coverage), Tier 3 SIE + Alibaba Model Studio + Ossprey (env-var pass-through, no provisioning); in-cluster bootstrap + dashboard + HTTPS ingress, Modal stays SaaS. Kit v1 done at two levels (MVL-complete, full-coverage-complete). Formal record: `docs/adr/0001-monk-deployment-and-packaging.md`. Proposal only — not implemented; workstation Live path unchanged. PROPOSED | | 2026-08-31 | wave-N-review | GWT reviewer blockers fixed (slices 55/56/57) | nw-acceptance-designer-reviewer returned 3 BLOCKED slices. Applied fixes: 55 dep header + GWT-55.3 placement locked to adjacent-copy + GWT-55.5 inlined D3/D4/D8 text; 56 GWT-56a locked to prerequisites.md + GWT-56b/c/d rewritten to artifact-presence assertions + GWT-56f added (B.4 scanner×input-type matrix); 57 GWT-57a.2 concrete exclusion list + GWT-57b.1 module names inlined. APPLIED | | 2026-08-31 | wave-N-review | Docs reviewer blockers fixed (audit report) | nw-documentarist-reviewer: B.4 scanner×input-type matrix (confirmed P1/M) added as seq-8 (56-f) in execution queue; setup-commands DIVIO collapse (pre-existing, not Wave N) added to Not-Now list as Wave O tech debt; DIVIO 'Adopted — partial' row expanded with enumeration; temporal disclaimer at line 8 clarified (reviewed against main + pre-merge slice-44 branch). APPLIED |