Metadata-Version: 2.4
Name: trust-boundary-mapper
Version: 0.8.3
Summary: Score every trust-boundary crossing in your infrastructure — YAML, Terraform, Compose, Kubernetes
Author-email: Sean P <tbm@mapleclose.ca>
License: MIT
Project-URL: Homepage, https://github.com/Datasculptures/trust-boundary-mapper
Project-URL: Source, https://github.com/Datasculptures/trust-boundary-mapper
Project-URL: Issues, https://github.com/Datasculptures/trust-boundary-mapper/issues
Keywords: security,trust-boundary,terraform,kubernetes,compose,architecture,infrastructure,scoring
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: click<9.0,>=8.1
Requires-Dist: jsonschema<5.0,>=4.0
Requires-Dist: pillow<12.0,>=10.0
Dynamic: license-file

# Trust Boundary Mapper

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

---

## Quickstart

```bash
# 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)

```bash
pipx install trust-boundary-mapper
tbm --version
```

### pip in a virtual environment

```bash
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](https://github.com/Datasculptures/trust-boundary-mapper/releases):

| 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](RELEASING.md) for details.

### From source

```bash
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:

```bash
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](DEVELOPING.md) — architecture, scoring methodology, all CLI flags, phase history
- [CHANGELOG.md](CHANGELOG.md) — version history
- [RELEASING.md](RELEASING.md) — PyPI publication runbook
- [GitHub Issues](https://github.com/Datasculptures/trust-boundary-mapper/issues)
