This is an automated email from the ASF dual-hosted git repository.
m4sterchain pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/teaclave.git
The following commit(s) were added to refs/heads/main by this push:
new d769ed40 docs: add security model mapping branch scanning targets
d769ed40 is described below
commit d769ed40ea6b9a77e88401d85c32e8c450088f16
Author: zf <[email protected]>
AuthorDate: Tue Jun 9 15:24:25 2026 +0800
docs: add security model mapping branch scanning targets
main is a landing-page branch with no TEE code, so a security scan must
target the branches that contain code. Adds docs/security-model.md, a
brief orientation that maps those scanning targets: experimental-web3
(the active vm/wallet-gateway TEE-backed wallet custody gateway, with its
task-runner-tee vs. task-runner-normal trust split), the cleanroom SGX
FaaS prototype, and the deprecated legacy FaaS framework (which already
has its own threat-model docs). Points to the per-platform SDK security
models (SGX, TrustZone, crates) as the authoritative trust-boundary
references, and links the doc from SECURITY.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
---
SECURITY.md | 7 ++++
docs/security-model.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 107 insertions(+)
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.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
