Trust Model

Overview

Bausteinsicht is a local CLI tool that transforms architecture model files (JSONC) into draw.io diagrams. It operates entirely on the local filesystem with the permissions of the invoking user.

Trust Boundaries

Path-Validated: CLI Flags

CLI flags (--model, --template, --output) are provided by the user, but their paths are validated before use: validatePathContainment (cmd/bausteinsicht/root.go) rejects paths containing .. or otherwise escaping the working directory, returning exit code 2 (SEC-001 / SEC-016). This guards against an automated agent with untrusted input reading or writing outside the intended directory. Absolute paths and ordinary relative paths within the tree are accepted; directory-traversal sequences are not.

Resource Limits

To bound large or pathological input, regardless of source:

  • Model size — files larger than 10 MB are rejected (internal/model/loader.go).

  • Hierarchy depth — element nesting deeper than MaxElementDepth (50) is rejected (internal/model/resolve.go, SEC-007).

  • Ambiguous auto-detection — multiple .jsonc files in the working directory abort the command rather than silently selecting one.

Semi-Trusted: Model and Template Files

Model (.jsonc) and template (.drawio) files may come from shared Git repositories or external sources. While they are parsed and validated, they are not sandboxed:

  • Model files are parsed as JSONC. Malformed input produces validation errors, not security issues. The model cannot trigger code execution.

  • Template files are parsed as XML (draw.io format). Only known attributes and elements are read. Arbitrary XML content is ignored.

  • draw.io files (output) are written using the etree XML library. User-controlled strings (titles, descriptions) are XML-escaped during serialization.

Untrusted: Agent / CI Environments

When Bausteinsicht runs inside an AI agent loop or CI pipeline, the caller should apply standard sandboxing:

  • Run in a container or restricted directory

  • Use read-only mounts for input files where possible

  • Limit filesystem access to the project directory

There is no built-in --restrict-to-dir flag. The trust model assumes the user (or their agent framework) controls filesystem boundaries.

External Processes

Bausteinsicht is not a pure in-process transformer — some commands invoke external binaries, resolved from PATH:

  • draw.io — export (PNG/SVG) launches the draw.io CLI (internal/export).

  • git — stale and changelog shell out to git log to derive element history (internal/stale, internal/changelog).

  • bausteinsicht (self) — the LSP server re-executes the bausteinsicht binary for diagnostics (internal/lsp/diagnostics.go).

These binaries are trusted and located via PATH; model and template content never determines which process runs or supplies its arguments. In a hardened environment, control PATH so only the intended binaries are resolved.

Non-Threats

  • No network access — Bausteinsicht makes no HTTP calls, DNS lookups, or socket connections.

  • No code execution from input — The model format (JSONC) and template format (draw.io XML) cannot trigger arbitrary code execution; input content is parsed as data, never evaluated. (The tool does spawn the trusted external binaries listed above, but never ones named or parameterized by model/template content.)

  • No credential handling — Bausteinsicht does not read, store, or transmit credentials.

Related Documents