Trust Boundary Mapper

Score every trust-boundary crossing in your infrastructure and emit an opinionated security report — in under a minute, entirely offline.

---

Quickstart

# Install
pipx install trust-boundary-mapper

# Run in any directory that contains infrastructure files
tbm

# Or score explicitly
tbm score docker-compose.yml --output report.html --serve

After tbm score completes, --serve opens the report in your browser automatically. Press Ctrl-C to stop the local server.

---

What TBM does

TBM reads an architecture description — YAML, Terraform state, Docker Compose, or Kubernetes manifests — and scores every communication edge between components using a trust-boundary thinness formula:

T(u, v) = (α + (1 − α) · A) · (w_s · S + w_b · B)

where A is authentication strength, S is data sensitivity, and B is blast radius (how many components are reachable downstream). High T means a thin trust boundary — the edge is a security concern.

The output is a self-contained HTML report you can open in any browser, a printable one-page client deliverable, and a machine-readable JSON export. Everything runs locally. No data leaves your machine.

---

Supported inputs

Format	Auto-detected?	Introduced
Hand-written YAML (native schema)	.yaml / .yml with version: 1	v0.1
Terraform state (terraform show -json)	.json	v0.2
Docker Compose	compose.yml, docker-compose.yml	v0.3
Kubernetes manifests (file or directory)	apiVersion: + kind: in YAML	v0.4
Kubernetes RBAC resources	Bundled with Kubernetes input	v0.6

---

Example output

══════════════════════════════════════════════════════════════════════════════════
         TRUST BOUNDARY ANALYSIS — THREE-TIER WEB APPLICATION
                    2025-04-14T10:32:00Z
══════════════════════════════════════════════════════════════════════════════════
  Input: three_tier.yaml   α=0.10  w_s=0.50  w_b=0.50  mesh=collapsed

  CRITICAL (T ≥ 0.60)
  ────────────────────────────────────────────────────────────────────────────────
  web → api          T=0.680  auth=network_only  data=pii      B=0.50
  api → db           T=0.625  auth=bearer_tls    data=secrets  B=0.25

  MODERATE (0.30 ≤ T < 0.60)
  ...

The full HTML report includes a live vis-network graph, sortable tables, and per-edge remediation guidance.

---

Installation options

pipx (recommended — isolated, always on PATH)

pipx install trust-boundary-mapper
tbm --version

pip in a virtual environment

python -m venv .venv && source .venv/bin/activate
pip install trust-boundary-mapper
tbm --version

Single binary (no Python required)

Download the pre-built binary for your platform from the Releases page:

Platform	File
Windows (x64)	tbm-0.7.1-windows-x64.exe
Linux (x64)	tbm-0.7.1-linux-x64
macOS (Apple Silicon)	tbm-0.7.1-macos-arm64

Note: OS security warnings are expected for unsigned binaries. On macOS: right-click → Open. On Windows: More info → Run anyway. See RELEASING.md for details.

From source

git clone https://github.com/Datasculptures/trust-boundary-mapper
cd trust-boundary-mapper
pip install -e .

---

Zero-config quickstart

Running tbm with no arguments in a directory that contains infrastructure files detects the input automatically:

$ tbm
Detected Compose input: ./docker-compose.yml
Would run: tbm score docker-compose.yml --output tbm-report.html --serve
Run this? [Y/n]

Supported auto-detection:

• compose.yml or docker-compose.yml → Compose
• *.tfstate (single match) → Terraform state
• *.tbm.yaml or tbm.yaml → native YAML
• k8s/ or manifests/ directory with .yaml files → Kubernetes

---

Diff mode

Compare two versions of your architecture to surface regressions:

tbm diff \
  --before before/infra.json \
  --after  after/infra.json \
  --output diff-report.html \
  --json   diff-report.json \
  --regression-severity critical

Exit code 13 if any edge was added or worsened to critical severity. Exit code 14 if before and after graphs share no component IDs.

---

Exit codes

Code	Meaning
0	Success
2	Input validation error
3	Path-traversal or size-cap violation
4	Internal error
5	Malformed Terraform state
6	No mappable resources
7	Malformed Compose / Kubernetes manifest
13	Diff regression detected
14	Diff no-overlap

---

Security posture

TBM is designed for offline, air-gapped use:

• No network calls, ever. All assets (vis-network JS) are vendored.
• No telemetry, no analytics, no crash reporting.
• 10 MB input file size cap before any parsing.
• yaml.safe_load only — YAML tag injection is rejected.
• Input paths validated against CWD to prevent path traversal.

---

Full documentation

• DEVELOPING.md — architecture, scoring methodology, all CLI flags, phase history
• CHANGELOG.md — version history
• RELEASING.md — PyPI publication runbook
• GitHub Issues