Threat model

§1 Header

Project: Buildish Site Pipeline.

Version binding: this threat model is versioned alongside the project. A report against project version N is triaged against the threat model shipped with version N, not against the model at a later development commit. (documented)

Version: current unreleased buildish-site-pipeline development branch. (documented)

Date: 2026-08-04. (documented)

Authors: Buildish maintainers. (documented)

Reporting cross-reference: findings that may violate §8 should be reported per this repository’s SECURITY.md disclosure channel. Sections §3 and §9 inform triage, but maintainers make the final scope determination. (documented)

Status: development draft and review aid. No Buildish release has been published; this model must be reviewed again before it is attached to a release. (documented)

Provenance legend: (documented) means supported by repository documentation or code; (maintainer) means confirmed by a maintainer; (inferred) means a draft claim derived from current structure and requiring confirmation.

Buildish Site Pipeline is a Python CLI and package for staging multi-repository documentation-site inputs into a normalized tree and metadata set for downstream renderers. It reads a consumer-owned catalog, optional provider snapshots, component metadata, site pages, docs, and static assets; validates the structural contract; stages normalized outputs; and emits reports and aggregate JSON files that renderers and deployment adapters consume. (documented)

§2 Scope and intended use

Primary intended use cases:

• Validate a trusted workspace’s site catalog, component metadata, publication model, paths, routes, redirects, and provider-derived inputs before staging. (documented)
• Build a staged output tree under site/.stage/ for a downstream renderer or deployment adapter. (documented)
• Keep staged outputs fresh during local editing with site-pipeline watch. (documented)
• Expose effective component source roots for local wrappers or container mount orchestration through site-pipeline component-source-roots. (documented)
• Provide JSON Schema and reference documentation for authored, provider, and emitted pipeline contracts. (documented)

Deployment contexts:

• Local developer workstation CLI. (documented)
• CI CLI, either from a Python environment or the optional container image. (documented)
• In-process Python imports are implementation detail unless a specific model or helper is documented as a public contract. The stable invocation API is the site-pipeline executable. (documented)
• This project is not a network service, daemon, browser sandbox, or renderer. (documented)

Caller and actor expectations:

• The operator invoking the CLI is trusted for the workspace and output location. (documented)
• Repository-authored catalog and component files may be reviewed project input, but are not assumed to be safe HTML or safe filesystem paths until validated. (documented)
• Provider snapshots are external data inputs and are validated as data, not trusted code. (documented)
• Downstream renderers and deployment adapters are separate trusted components responsible for HTML escaping, browser-origin policy, CSP, cookies, storage, and publication. (documented)

Component-family table:

§3 Out of scope

Explicit non-goals:

• Making malicious authored HTML, JavaScript, CSS, or renderer templates safe to publish. Imported active content is trusted browser-executable code. (documented)
• Providing authentication, authorization, secrets management, or tenant isolation for published sites. (documented)
• Securing the downstream renderer, web server, CDN, browser origin, CSP, cookie scope, storage scope, or deployment adapter. (documented)
• Defending against an attacker who controls the local process, Python environment, installed dependencies, shell, container runtime, CI runner, or host filesystem permissions. (inferred)
• Fetching, authenticating, or verifying source repositories, SCM state, or provider APIs. The pipeline consumes local inputs and provider snapshots. (documented)
• Guaranteeing that generated preliminary release-legal drafts replace human release review. (documented)
• Treating test fixtures, generated outputs, dist/, .venv/, caches, and local build artifacts as covered runtime components. (inferred)
• Security of third-party dependencies beyond normal dependency-management and release processes. (inferred)
• Security of non-default or locally modified builds that bypass validation, monkeypatch internals, or call private Python functions directly. (inferred)

§4 Trust boundaries and data flow

The primary trust boundary is the CLI boundary plus the declared workspace and stage-root filesystem boundaries. CLI-local arguments are trusted operator choices; authored and provider documents are parsed as untrusted data and must pass schema, path, route, URL, publication, and size validation before their values influence staged outputs. (documented)

Data flow:

1. The operator invokes site-pipeline with command arguments and optional report/event sinks. (documented)
2. The CLI resolves workspace, catalog, stage, work, report, and watch-event paths relative to the current process and rejects unsafe output combinations. (documented)
3. Catalog, provider snapshot, and component metadata files are read as UTF-8, parsed with safe YAML or JSON loaders, rejected on duplicate keys, and loaded into strict Pydantic models. (documented)
4. Planning resolves component source roots, publication paths, routes, redirects, provider references, limits, and diagnostics. (documented)
5. check stops after validation and report emission; build and watch publish a staged tree only when the stage gate allows it. (documented)
6. Staging copies authored pages/assets and emits normalized front matter, manifests, reports, and aggregate JSON files under the stage root. (documented)
7. A downstream renderer consumes the staged tree and is responsible for HTML rendering and browser-facing security policy. (documented)

Reachability preconditions:

§5 Assumptions about the environment

Runtime assumptions:

• Python 3.13 or newer is available. (documented)
• The process can read declared local inputs and write configured reports, work roots, and stage roots. (inferred)
• Filesystem semantics are close enough to pathlib.Path.resolve() and is_relative_to() expectations for containment checks to be meaningful. (inferred)
• The operator controls CLI arguments, local overrides, and output destinations. (inferred)
• The workspace may contain symlinks, but output targets and staged trees must satisfy the project’s symlink-safety checks. (documented)
• Watch mode assumes local filesystem event delivery by watchfiles and handles SIGINT/SIGTERM for shutdown. (documented)
• The project does not assume concurrent writes by multiple independent pipeline processes to the same stage/work root are safe. (inferred)

No-surprise side effects inventory for the normal staging CLI:

• Reads local files under configured workspace/source roots and selected catalog or provider-snapshot paths. (documented)
• Writes reports to stdout or configured report paths, and watch events to stdout or configured event paths. (documented)
• Writes and replaces staged output under the configured stage root for build and watch. (documented)
• Writes transient work data under the configured work root during staging. (documented)
• Does not fetch source repositories, provider APIs, or remote content during plan, check, build, or watch. (documented)
• Does not execute renderer commands, shell snippets, or repository-authored scripts as part of the stable staging commands. (inferred)
• Does not open listening network sockets in the stable CLI surface described by this model. (inferred)
• Does not install signal handlers except for watch-mode shutdown behavior. (documented)
• Does not treat metadata strings as trusted HTML. (documented)

§5a Build-time and configuration variants

No build-time flag is currently documented as intentionally weakening a §8 security property for normal site-pipeline staging. (inferred)

§6 Assumptions about inputs

General input assumptions:

• Catalog, component metadata, provider snapshots, page front matter, route metadata, redirect metadata, and provider records are data inputs and may be malformed or adversarial within the bounds of local workspace access. (documented)
• CLI filesystem arguments are trusted operator input, but still validated where they select report, event, stage, work, or source locations. (documented)
• Page bodies and static assets can contain active browser content; staging them does not make them safe. (documented)
• Provider snapshots may be large, so documented byte and record defaults matter for availability. (documented)

Per-parameter trust table:

Size, shape, and rate assumptions:

• Mounted metadata payloads are limited to 16 KiB per metadata object after JSON serialization. (documented)
• Diagnostic detail payloads are limited to 8 KiB per details object after JSON serialization, with a reduction rule instead of malformed JSON. (documented)
• Provider snapshot, route, redirect, content-index, watched-directory, and staged-version-context defaults are documented operational limits. (documented)
• Watch mode is intended for local editing cadence, not hostile high-rate event floods. (inferred)

§7 Adversary model

In-scope adversaries:

• A contributor or compromised component repository that can modify authored catalog-referenced content, component metadata, page front matter, page bodies, static assets, redirects, or provider-like data that the operator chooses to stage. (inferred)
• A provider-data source that can supply malformed or oversized provider snapshot records. (inferred)
• A bug-finding tool or reporter that supplies malformed YAML/JSON, paths, redirects, URLs, metadata strings, or page content and claims violation of a stated §8 property. (inferred)

Attacker goals in scope:

• Cause writes outside the configured stage/work/report boundaries. (documented)
• Smuggle local filesystem paths or private workspace details into public staged outputs. (documented)
• Cause unsafe route, URL, redirect, or staged metadata output that violates the documented contract. (documented)
• Cause denial of service through oversized structured inputs beyond documented limits. (documented)
• Cause the stable CLI to execute attacker-controlled local commands or unsafe deserialization payloads. (inferred)

Out-of-scope adversaries:

• An attacker with control over the operator account, shell, Python interpreter, dependency installation, CI runner, container runtime, or host filesystem. (inferred)
• A downstream renderer or deployment adapter that intentionally renders unescaped metadata, publishes active content on an unsafe origin, or ignores staged trustClass and route metadata. (documented)
• A network attacker against a published website, CDN, renderer development server, SCM host, package index, or provider API. (inferred)
• A malicious maintainer modifying source code or release artifacts. (inferred)

§8 Security properties the project provides

§9 Security properties the project does not provide

The project does not provide:

• HTML sanitization for authored page bodies, imported active content, renderer templates, or arbitrary metadata rendered by downstream systems. (documented)
• Browser same-origin isolation, CSP enforcement, cookie policy, local storage isolation, or web-server headers. (documented)
• Authentication, authorization, cryptographic integrity, signatures, or provenance verification for source repositories, provider snapshots, staged outputs, or published content. (documented)
• A sandbox boundary between untrusted repository content and the local operator account running the CLI. (inferred)
• Safe multi-tenant service behavior when exposing the CLI to untrusted network users. (inferred)
• Protection after an attacker controls the local process, Python environment, dependency set, container runtime, CI runner, or filesystem permissions. (inferred)
• Constant-time behavior, secret handling, or cryptographic APIs. (inferred)
• Complete denial-of-service resistance against unbounded local filesystem size, hostile watch-event storms, extremely large static assets, or intentionally expensive downstream rendering. (inferred)
• Security guarantees for generated preliminary legal drafts, release review conclusions, or third-party package metadata quality. (documented)

False-friend properties:

• JSON Schema validation is structural validation, not proof that published content is safe HTML or safe to execute in a browser. (documented)
• trustClass: passive or trustClass: active is a deployment signal, not an isolation mechanism by itself. (documented)
• check validates pipeline contracts; it does not prove that a downstream renderer, theme, web server, or CDN deployment is secure. (documented)
• Provider snapshot validation does not authenticate provider identity or prove that provider data came from an official source. (inferred)
• The optional container image gives a reproducible entrypoint; it is not a sandbox for malicious workspaces unless the operator supplies appropriate container isolation and mounts. (inferred)

Well-known attack classes left to callers or downstream layers:

• XSS through authored HTML, Markdown extensions, imported active trees, or renderer templates must be handled by renderer escaping and deployment policy. (documented)
• Open redirect and unsafe URL publication must be controlled by catalog policy, URL validation, and deployment review. (documented)
• Supply-chain compromise of dependencies, base images, provider snapshots, or component repositories is outside the pipeline’s local staging boundary. (inferred)
• Local secret exfiltration by malicious renderer commands or wrapper scripts is outside this project unless the stable pipeline CLI executes those commands. (inferred)

§10 Downstream responsibilities

Operators and integrators must:

• Report suspected §8 violations through the private security channel in SECURITY.md. (documented)
• Run the CLI only on workspaces and component repositories they intend to trust for local file reads and browser-facing content publication. (inferred)
• Use site-pipeline check before build or publication in automation. (inferred)
• Keep report and watch-event output paths out of staged/work roots and away from unintended public artifacts. (documented)
• Configure downstream renderers to HTML-escape metadata and treat raw HTML as an explicit opt-in outside the core pipeline contract. (documented)
• Apply origin isolation, CSP, cookie, storage, and server policies for active mounted content. (documented)
• Treat provider snapshots as external data and enforce documented size/count limits or local operator-only overrides. (documented)
• Do not expose the CLI directly as a multi-tenant network service or remote build API without an additional isolation layer. (inferred)
• Review optional container image, base image, dependency, and registry posture according to the deployment environment’s supply-chain policy. (inferred)

§11 Known misuse patterns

• Rendering metadata strings as raw HTML because they were accepted by the pipeline schema. This is unsafe; renderers should escape by default. (documented)
• Publishing imported active site trees on the same origin as sensitive pages without deliberate isolation policy. (documented)
• Treating provider snapshots as authenticated source-of-truth data rather than external data loaded from a local file. (inferred)
• Sharing staged reports or aggregate outputs without considering whether they contain repo-relative source paths or redacted local-path placeholders. (inferred)
• Calling private Python modules directly and expecting the same compatibility and threat-model guarantees as the stable CLI. (documented)
• Running multiple pipeline processes against the same stage/work root and treating the result as synchronized. (inferred)

§11a Known non-findings

• A report that a trusted operator can pass a sensitive --workspace-root, --catalog, --report-output, or --unstable-events-output path is not by itself a vulnerability; those are trusted operator-selected CLI parameters per §6. (inferred)
• A report that active HTML/JS/CSS can execute after publication is not by itself a pipeline vulnerability when the content is staged as active content and the downstream deployment shares an origin by policy; see §9. (documented)
• A report against generated files, caches, dist/, .venv/, or test fixtures is out of model unless it is reachable through the supported CLI or staged output contract; see §3 and §4. (inferred)
• A report that preliminary release-legal output requires human review is not a security bug; that limitation is documented and by design. (documented)

§12 Conditions that would change this model

Revise this threat model when the project:

• Adds a new stable CLI command, public Python API, staged output contract, or schema family. (inferred)
• Starts fetching remote repositories, provider APIs, package indexes, or other network resources during stable staging commands. (inferred)
• Adds a preview server, renderer integration, template execution, subprocess runner, plugin system, or user-supplied command hook to the stable CLI. (inferred)
• Changes defaults or operator policy for §5a resource limits, report/event sinks, or stage/work roots. (inferred)
• Changes path normalization, symlink handling, publication finalization, or public-output redaction behavior. (inferred)
• Promotes container-image, release-legal, generated-doc, or helper-script behavior into the core runtime security boundary. (inferred)
• Receives a vulnerability report that cannot be routed to one of the §13 dispositions. Such a report is a model gap, not an ad-hoc exception. (inferred)

§13 Triage dispositions

§14 Optional machine-readable companion

No threat-model.yaml companion is currently maintained. The prose document is canonical. If triage automation is added later, derive a sidecar from §2, §3, §6, §8, §9, §11a, and §13 rather than treating the sidecar as independent policy. (inferred)