diff --git a/SECURITY.md b/SECURITY.md index 6ecb9887..3b7b7d44 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,5 +1,12 @@ # Security Policy +## Security Model + +`main` is a landing-page branch with no TEE code; the code that needs auditing +lives on other branches (notably `experimental-web3`). For a brief map of those +scanning targets and the per-platform trust-boundary references, see +[docs/security-model.md](docs/security-model.md). + ## Reporting a Vulnerability We take a very active stance in eliminating security problems in Teaclave. We diff --git a/docs/security-model.md b/docs/security-model.md new file mode 100644 index 00000000..99eae8ef --- /dev/null +++ b/docs/security-model.md @@ -0,0 +1,100 @@ +# Security Model + +This document orients a security reviewer — human or automated/LLM agent — to +**where the code that needs auditing actually lives** in this repository, and to +the trust-boundary references that apply to it. + +It is intentionally brief. It is a **map to scanning targets**, not a full threat +model. The detailed, per-platform trust models live in the SDK repositories (see +[§3](#3-which-trust-model-applies)). + +--- + +## 1. The `main` branch has no TEE code + +`main` is the **landing page** for the Teaclave ecosystem. Its `crates/`, `sgx/`, +and `trustzone/` directories contain only `README.md` showcase pointers — there +is **no enclave, no Trusted Application, and nothing compiled into a TEE** on +this branch. There is therefore no trust boundary or Trusted Computing Base to +audit on `main` itself. A security scan of the Teaclave codebase should target +the branches below, not `main`. + +--- + +## 2. Scanning targets (branches that contain code) + +| Branch | Status | Where the code is | What it is | +|---|---|---|---| +| **`experimental-web3`** | **Active / latest** | `vm/wallet-gateway/` | A TEE-backed crypto-wallet custody gateway — the current focus. **Start here.** | +| `cleanroom` | Prototype (2022) | repo root (`attestation/`, `services/`, `executor/`, `dcap/`, `edl/`, `function/`, `rpc/`, `sdk/` …) | An earlier SGX FaaS-style platform prototype. | +| `legacy` | Deprecated | `services/`, `docs/` | The original Teaclave FaaS framework. Already carries its own security docs: `docs/threat-model.md`, `docs/mutual-attestation.md`, `docs/service-internals.md`, `docs/access-control.md`. | + +### 2.1 `experimental-web3` → `vm/wallet-gateway/` (primary target) + +A multi-crate wallet gateway that custodies keys and signs blockchain +transactions inside a TEE. The **trust boundary is visible in the workspace +layout** — the task runner is split into a trusted and an untrusted half: + +- **Trusted (inside the TEE):** `task-runner-tee` and the key/credential material + it handles (`credential-manager`, the signing/wallet logic). This is the TCB — + private keys and plaintext must never leave it. +- **Untrusted (host / normal world):** `api-server` and `webapi` (the public + client-facing edge), `task-runner-normal`, `db-service` / `db-manager` + (persistence in untrusted storage), `net` (outbound calls to **external, + attacker-influenced** services such as blockchain RPC — `net/.../btc_rpc.rs` — + and price oracles — `net/.../asset_price.rs`), and `authority-server`'s host + surface. + +**Attacker-controlled inputs a scanner should focus on:** +- Every client request entering `api-server` / `webapi`. +- Every response from `net` (blockchain RPC, price feeds) — external data is + untrusted; never base a signing or balance decision on it without validation. +- Everything read back from `db-service` / `db-manager` — persisted data lives in + untrusted storage and must be encrypted/authenticated; treat reads as + adversarial. +- The boundary crossing between `task-runner-normal` and `task-runner-tee`. + +Key questions: do wallet private keys and unencrypted secrets ever cross out of +`task-runner-tee`? Is data persisted by `db-service` sealed/authenticated before +it leaves the TEE? Are external feed responses validated before they influence a +signature or a balance? + +### 2.2 `cleanroom` and `legacy` + +Both are SGX FaaS-style platforms (frontend / management / storage / scheduler / +execution / access-control services, each split into an untrusted `app/` wrapper +and a trusted `enclave/`, joined by mutually-attested TLS). `legacy` already +documents its trust model under `docs/`; `cleanroom` is an earlier prototype of +the same shape. Audit these against the SGX trust model below; do not duplicate +`legacy`'s existing threat-model docs. + +--- + +## 3. Which trust model applies + +The applications on these branches are built on the Teaclave TEE SDKs, so the +**authoritative trust-boundary methodology is the SDK security models** — use +them as the reference when auditing: + +- **Intel SGX targets** (the FaaS platforms, and SGX builds of the gateway): + [Teaclave SGX SDK → `docs/security-model.md`](https://github.com/apache/teaclave-sgx-sdk/blob/main/docs/security-model.md) + — untrusted host vs. enclave, the ECALL/OCALL edge, OCALL results are + untrusted. +- **Arm TrustZone targets:** + [Teaclave TrustZone SDK → `docs/security-model.md`](https://github.com/apache/teaclave-trustzone-sdk/blob/main/docs/security-model.md) + — Normal World vs. Secure World, treat all parameters crossing into the TA as + attacker-controlled. +- **Dependencies linked into any of the above:** + [Teaclave Dependency Crates → `docs/security-model.md`](https://github.com/apache/teaclave-crates/blob/main/docs/security-model.md) + — everything linked into the trusted side is part of the TCB. + +The common rule across all of them: **the TEE side is trusted; everything else — +the host OS, clients, the network, external feeds, and persisted storage — is +attacker-controlled and must be validated at the boundary.** + +--- + +## 4. Reporting vulnerabilities + +Security issues should be reported privately first, per +[`SECURITY.md`](../SECURITY.md), before any public disclosure.