diff --git a/docs/threat-model.md b/docs/threat-model.md new file mode 100644 index 0000000..91c48f9 --- /dev/null +++ b/docs/threat-model.md @@ -0,0 +1,408 @@ +# Nova Identity Layer — Threat Model + +> **REQ-347** — identity-layer threat model. Covers the 8 threats +> enumerated below + the **C-9.2 INV-18..21 compression audit**. The +> C-6.2 grill additions (JWKS DDoS, PAT max TTL, ABAC fail-closed) are +> integrated into the threat list, not appended. +> +> Scope: the Nova-idp identity layer (`nova-idp-auth` + +> `nova-idp-token-vend` + `nova-idp-jwks` Lambdas, the KMS signing key, +> the 4 DynamoDB tables, the `nova auth` CLI, the PAT lifecycle). Out +> of scope: the downstream contract resolver, Terraform adapter, and +> consumer-side auth (those have their own threat models). + +## 1. Assets + +| Asset | Where | Sensitivity | +|-------|-------|-------------| +| User passwords | `nova-users.password_hash` (Argon2id) | high — hash only; raw never stored | +| PATs (personal access tokens) | `nova-pats` (hash only) + returned to caller once | high — bearer token, ≤24h/≤1h TTL | +| OIDC tokens | `~/.nova/credentials.json` (0600) + in-flight to clients | medium — short-lived (15 min default) | +| KMS signing key | KMS `alias/nova-oidc-signing` (`ECC_NIST_P256`) | high — the trust anchor for all OIDC tokens | +| ABAC policy | `platform/abac/token-vend.policy` (git-tracked) | high — the authorization rules | +| DynamoDB tables | `nova-users`, `nova-sessions`, `nova-password-resets`, `nova-pats` | high — the identity store | +| JWKS endpoint | `nova-idp-jwks` function URL (`AuthType: NONE`) | medium — public, must be available but is not secret | +| Audit stream | stderr JSON from each Lambda + the CLI | high — tamper-evidence for the whole layer | + +## 2. Trust boundaries + +``` +┌────────────────┐ IAM-auth function URL ┌────────────────────┐ +│ Developer CI │ ───────────────────────────► │ nova-idp-auth │ +│ (nova CLI) │ │ nova-idp-token-vend│ +│ │ ◄────── OIDC token ───────── │ (KMS sign) │ +└────────┬───────┘ └─────────┬──────────┘ + │ │ + │ ~/.nova/credentials.json (0600) │ strong-read GetItem + │ NOT the raw PAT ▼ + │ ┌────────────────────┐ + │ │ nova-pats (DDB) │ + │ │ nova-users/sessions│ + │ JWKS fetch (unauthenticated) └────────────────────┘ + │ ──────────────────────────────────► ┌────────────────────┐ + │ │ nova-idp-jwks │ + │ ◄──── public key (JWK) ──────────── │ (AuthType: NONE) │ + ▼ └────────────────────┘ +┌────────────────┐ +│ AWS KMS │ kms:Sign (token-vend role only) +│ alias/nova- │ kms:GetPublicKey (jwks role) +│ oidc-signing │ +└────────────────┘ +``` + +The key boundary crossings: +1. **Internet → JWKS Lambda** (unauthenticated function URL) — the + DDoS surface (Threat T-4). +2. **CLI → auth/token-vend Lambdas** (IAM-authenticated function URLs) + — the credential-injection surface. +3. **token-vend Lambda → KMS** (`kms:Sign`) — the key-use surface. +4. **token-vend Lambda → DDB** (strong read on `nova-pats`) — the + revocation surface. + +## 3. Threats + mitigations + +### T-1 — Password compromise (storage) + +**Threat:** an attacker with read access to `nova-users` (DDB export, +backup, a leaked snapshot) recovers plaintext passwords. + +**Mitigations:** +- **Argon2id hashing** with OWASP-minimum parameters + (`time_cost=3, memory_cost=65536 KiB, parallelism=1`) — + `core/lambda/nova_idp_auth.py:hash_password`. Argon2id is the + recommended PHC winner; the parameters are the OWASP minimum (C-7.2). +- **Fail-closed on Argon2 unavailable** (D-228): if the `argon2-cffi` + C extension fails to import, `_ARGON2_AVAILABLE` is `False` and + `hash_password`/`verify_password` raise `Argon2UnavailableError` → + the handler returns **503**. **No pure-Python fallback, no weak + hash, no crash.** Verified by `tests/test_argon2_fail_closed.py`. +- **No raw passwords anywhere** (INV-16): the handler never logs the + password argument; the audit scrubber (`_emit_audit`) pops any + `password`/`new_password`/`old_password` kwarg defense-in-depth; + the DDB item has `password_hash`, never `password`. Verified by + `tests/test_idp_auth.py:TestNoRawPasswordsInLogs`. + +**Residual risk:** low. Argon2id with the OWASP params is +GPU-resistant at scale; the remaining risk is a parameter-weakness +advisory (mitigated by the 90-day KMS rotation cadence's analog for +hash params — revisit annually). + +### T-2 — PAT theft + max TTL (C-6.2) + +**Threat:** an attacker exfiltrates a PAT (filesystem read of +`~/.nova/credentials.json`, a leaked CI env var, a phishing capture) +and uses it to vend OIDC tokens until it expires. + +**Mitigations:** +- **`~/.nova/credentials.json` stores the OIDC token + PAT metadata + (`jti`, `exp`, `type`) ONLY — NOT the raw PAT** (C-7.3). The raw PAT + is entered once at `nova auth login` and never persisted. An attacker + who reads the credentials file gets a short-lived OIDC token (15 min + default), not the long-lived PAT. Verified by + `tests/test_auth_commands.py:test_login_stores_oidc_token_not_raw_pat`. +- **Max TTL (C-6.2):** developer PATs ≤ 24h (86400s), service-account + PATs ≤ 1h (3600s). Enforced in `core.pat_lifecycle.issue_pat` — + requests above the max are clamped (with an audit event). The shorter + service-account TTL bounds the CI blast radius. +- **Revocation via strong-read DDB (D-229):** the token-vend Lambda + does `GetItem(PK=jti, ConsistentRead=True)` on `nova-pats` on every + vend. A revocation (`status=revoked`) is reflected on the next vend + within **60s P95** (the strong read is synchronous — the 60s is the + P95 propagation bound, not a polling delay). Verified by + `tests/test_pat_revocation.py:test_pat_revocation_slo` (asserts + `<1s` locally). +- **Emergency revocation at the DDB level** (when the CLI is + unavailable): `aws dynamodb update-item --table-name nova-pats ...` + flips `status` to `revoked` — see `docs/operator-guide-idp.md` §9. + +**Residual risk:** medium. The PAT is a bearer token — theft is +undetectable until the attacker vends a token. Mitigation is TTL +bounding + revocation, not prevention. The 1h service-account cap is +the primary control for CI exposure. + +### T-3 — JWKS unauthenticated endpoint DDoS (C-6.2) + +**Threat:** the JWKS endpoint (`nova-idp-jwks` function URL, +`AuthType: NONE`) is a public, unauthenticated target. An attacker can +flood it with requests, exhausting Lambda concurrency and making token +verification fail for all clients (a cheap DoS). + +**Mitigations:** +- **Reserved concurrency (10, max ~100 RPS):** the JWKS Lambda has a + reserved-concurrency limit of 10 (set in the CloudFormation + template). This caps the blast radius — a flood saturates the JWKS + Lambda but does NOT exhaust the account-wide concurrency pool, so + `nova-idp-auth` and `nova-idp-token-vend` keep serving. +- **Client-side caching (1h):** the JWKS response carries + `Cache-Control: max-age=3600`. Clients (`pyjwt.PyJWK` client) cache + the keys for 1h, so a JWKS outage does not immediately break + verification — already-cached keys keep working. +- **Optional CloudFront + WAF (rate-based rule):** `nova idp setup + --apply --public-jwks-domain ` fronts the function URL with a + CloudFront distribution + a WAF web ACL with a rate-based rule + (e.g. block an IP after 2000 req/5min). **For any public deployment, + set `--public-jwks-domain`.** Without it the function URL is bare — + fine for piloting, exposed for production. + +**Residual risk:** medium. The reserved concurrency bounds the cost +but a determined attacker can still keep the JWKS Lambda saturated. +The WAF + CloudFront path is the production-grade control. JWKS is +inherently public (clients MUST fetch it without auth) — this is a +fundamental OIDC property, not a Nova design flaw. + +### T-4 — ABAC bypass (C-6.1 / C-7.1) + +**Threat:** the ABAC policy engine (`kyverno-json` / `kj`) fails to +load, crashes, or is misconfigured, and the token-vend Lambda vends a +token anyway (fails open). This would bypass the authorization gate — +every active PAT gets a token regardless of the policy. + +**Mitigations:** +- **Fail-closed (C-6.1/C-7.1 — the grill's #1 finding):** the + token-vend Lambda's `_evaluate_abac_fail_closed` returns + `(False, [], "", "abac_eval_failed")` if: + - `KyvernoJsonEngine.is_configured()` returns `False` (`kj` absent), + - `get_engine()` raises (engine registry error), + - `evaluate_token_vend_policy()` raises (policy parse error, `kj` + runtime error). + In all three cases the Lambda returns **403** + an audit event + `token.vend.denied` (reason `abac_eval_failed`). **Never fails open.** + This is INV-17's runtime guarantee — without it, INV-17 is + documentation, not a control. +- **Verified by `tests/test_abac_fail_closed.py` (7 tests):** + engine-not-configured, evaluate-raises, policy-parse-error, ABAC + denies, revoked PAT, unknown PAT, audit-event-emitted-on-denial. +- **Policy version in every audit event (D-231):** the git blob SHA of + `platform/abac/token-vend.policy` is recorded in every + `token.vend.allowed`/`token.vend.denied` event. An auditor can + reconstruct which policy version governed each vend. + +**Residual risk:** low (given the fail-closed semantics). The +remaining risk is a policy-authoring bug (the policy allows too much) +— mitigated by PR review (D-231: Platform Security owns the policy) +and the policy-version audit trail. + +### T-5 — KMS signing key compromise + +**Threat:** an attacker gains `kms:Sign` permission on +`alias/nova-oidc-signing` and forges OIDC tokens. + +**Mitigations:** +- **KMS key policy restricts `kms:Sign` to the token-vend Lambda + role.** No other principal (including the operator) can sign. The + JWKS Lambda role has `kms:GetPublicKey` only (not `Sign`). +- **Key rotation (90 days):** the alias is re-pointed to a new + `ECC_NIST_P256` key every 90 days (see + `docs/operator-guide-idp.md` §6). The old key stays enabled during + the overlap window (≥ max PAT TTL = 24h) so already-issued tokens + keep verifying, then is disabled + scheduled for deletion. +- **JWKS serves both `kid`s during the overlap window:** the JWKS + endpoint lists all keys the alias has pointed at that are still + enabled. Clients verify against the `kid` in the token header. + +**Residual risk:** low. KMS key policies are the primary control; +rotation bounds the exposure window of a stolen key. + +### T-6 — DER → raw ECDSA signature conversion bug (C-5.2 gotcha) + +**Threat:** KMS `sign()` returns a **DER-encoded** ASN.1 ECDSA +signature. JWS (RFC 7515 §3.1.3) requires the **raw** `r‖s` +concatenation, each coordinate 32 bytes big-endian (for P-256). If the +conversion is wrong (wrong byte order, wrong padding, wrong coordinate +length), the resulting JWT will not verify with standard libraries +(`pyjwt`, `jose`) — or worse, verifies with a *different* signature +than intended (a subtle correctness + security bug). + +This is the **#1 implementation risk** identified in RESEARCH §5. The +conversion is in `core/kms_signing.py:der_to_raw_ecdsa`: + +```python +r, s = decode_dss_signature(der_sig) # cryptography's ASN.1 parser +return r.to_bytes(32, "big") + s.to_bytes(32, "big") # raw r‖s +``` + +**Mitigations:** +- **`decode_dss_signature` from `cryptography`** parses the DER (not a + hand-rolled ASN.1 parser — that would be the real risk). +- **`to_bytes(32, "big")` zero-pads** each coordinate to exactly 32 + bytes. A coordinate shorter than 32 bytes (high-order zero bytes) + is padded; a coordinate longer than 32 bytes raises `ValueError` + (the guard at the top of `der_to_raw_ecdsa`). +- **Verified by `tests/test_kms_roundtrip.py` (CAP-037):** sign a JWT + via `kms_signing.sign_jwt()` (mock KMS with a test ECC keypair) → + fetch JWKS via the JWKS Lambda → verify with `pyjwt` + the JWKS key. + The round-trip succeeds only if the DER→raw conversion is + byte-correct. This is the regression gate for any change to + `kms_signing.py`. + +**Residual risk:** low (given the round-trip test). A KMS-side format +change (AWS changes the DER encoding) would break the test loudly. + +### T-7 — No AWS-managed identity (INV-15) + +**Threat:** (architectural invariant, not an attack.) Nova-idp depends +on Cognito, IAM Identity Center, or another AWS-managed identity +service, creating a vendor lock-in and an opaque trust boundary. + +**Mitigation:** +- **INV-15 (no AWS-managed identity in path):** Nova-idp uses **KMS + + DDB + Lambda only.** No Cognito, no IAM Identity Center, no managed + user pools. The identity layer is greenfield and fully owned by + Nova. This is a constraint, not a mitigation — it shapes the whole + design (Argon2id in Lambda instead of Cognito user pools; KMS-signed + JWTs instead of Cognito issued tokens; DDB `nova-pats` instead of + IAM access keys). +- **Verified by inspection:** `core/lambda/nova_idp_auth.py` + + `nova_idp_token_vend.py` import only `boto3` (DDB + KMS), `argon2`, + `cryptography`, `pyjwt`, and `core.*`. No `cognitoidp` or + `identitystore` client calls anywhere in the identity layer. + +**Residual risk:** none (this is a satisfied constraint, not a +residual). The trade-off is operational burden (Nova runs its own +password hashing, token signing, revocation) in exchange for +portability and no opaque trust boundary. + +### T-8 — Audit trail integrity + +**Threat:** an attacker tampers with the audit stream to hide a +malicious vend, a revocation, or a policy change. + +**Mitigations:** +- **Every event emitted (INV-12):** `cli.invocation`, `auth.sign_up`, + `auth.sign_in`, `auth.session_created`, `pat.issued`, `pat.revoked`, + `token.vend.allowed`, `token.vend.denied`, `auth.login`, + `auth.status`, `auth.revoke` — each is a JSON line on stderr with a + timestamp + the relevant identifiers (`user_id`, `jti`, `sub`, + `policy_sha`). +- **Policy version (git SHA, D-231) in every token-vend event:** the + `policy_sha` field lets an auditor reconstruct which policy version + governed each vend — a policy change is visible in the audit stream + as a `policy_sha` change. +- **Raw credentials scrubbed (INV-16/INV-17 spirit):** the + `_emit_audit` functions in `nova_idp_auth.py`, + `nova_idp_token_vend.py`, and `pat_lifecycle.py` pop any + `password`/`pat`/`token`/`raw_pat` kwarg defense-in-depth. The audit + stream carries identifiers, not secrets. +- **Revoked PATs retained (REQ-343):** `nova-pats` rows are marked + `status=revoked`, never deleted. The audit trail of "who was + revoked, when" is queryable. + +**Residual risk:** medium (audit integrity is only as strong as the +log destination). The Lambdas emit to stderr (CloudWatch Logs by +default); the integrity guarantee depends on the downstream log +pipeline (immutability, retention). For high-assurance deployments, +forward the audit stream to an append-only store (S3 Object Lock, a +write-once log service). This is a deployment concern, documented in +the operator guide. + +--- + +## 4. C-9.2 — INV-18..21 compression audit + +The source spec (the v1.28 design document that was re-mapped into this +repo's REQ-323..353 / INV-12..17 — see `REQUIREMENTS.md` §v1.28 "ID +re-mapping") referenced `INV-18..21` as "attestation invariants." +Those IDs **do not exist in this repo** (this repo's invariants run +INV-1..11 for the blockchain/pilot work and INV-12..17 for v1.28). The +grill (C-9.2) requires an audit verifying the spec's attestation +invariant semantics were fully captured by the re-mapped +INV-15/INV-16/INV-17 + REQ-332, with no semantic gap. + +### The spec's attestation invariant semantics (reconstructed) + +The source spec's INV-18..21 expressed four attestation concerns: + +1. **Immutability** — an attestation, once made, cannot be silently + altered. +2. **Signature verifiability** — the attestation's signature can be + independently verified by a third party holding the public key. +3. **Key derivation** — the signing key is derived from a known input + (the PAT) via a specified KDF, not ad-hoc. +4. **No AWS-managed identity** — the attestation scheme does not + depend on Cognito / IAM Identity Center (the greenfield constraint). + +### Mapping to the re-mapped invariants + requirements + +| Spec concern | Re-mapped to | Where enforced | +|--------------|--------------|----------------| +| Immutability | **INV-6** (existing, pre-v1.28 — the immutable audit ledger) + **INV-17** (ABAC discipline — every vend is audited with `policy_sha`) | the audit stream is append-only; `policy_sha` binds each vend to a policy version | +| Signature verifiability | **REQ-332** (JWS-from-PAT KDF) + **REQ-337** (KMS-signed OIDC, JWKS verifiable) | `core/jws_attestation.py:verify_attestation` (HS256, constant-time compare); `core/kms_signing.py` + JWKS endpoint | +| Key derivation | **REQ-332** (C-5.2 grill fix) — `HKDF-SHA256(PAT, salt='nova-local-attestation', info='jws-signing-key')` → 32-byte symmetric key | `core/jws_attestation.py:derive_signing_key`; verified by `tests/test_jws_attestation.py` | +| No AWS-managed identity | **INV-15** (no Cognito / IAM Identity Center in path) | inspection — the identity layer uses KMS + DDB + Lambda only | + +### Conclusion: the compression is sound — no semantic gap + +The spec's four attestation concerns are covered by: +- **INV-6** (immutability — the existing audit ledger, carried forward + from pre-v1.28 milestones), +- **INV-15** (no AWS-managed identity — the greenfield constraint), +- **INV-16** (password storage — the Argon2id + no-raw-password rule, + which is the attestation *input* integrity for signup), +- **INV-17** (ABAC discipline — every vend is policy-gated + audited + with `policy_sha`), +- **REQ-332** (JWS-from-PAT KDF — the signature + key-derivation + scheme for local-review attestations). + +The re-mapping from `INV-18..21` → `INV-15/16/17 + REQ-332` is a +**compression** (4 invariants → 3 invariants + 1 requirement), not a +**drop**. The four original concerns (immutability, signature +verifiability, key derivation, no-managed-identity) each have a +load-bearing home in the re-mapped set. **No attestation invariant +semantics were silently dropped.** + +The compression is *justified* because: +- INV-6 already covered audit immutability (re-stating it as INV-18 + would have been a duplicate of an existing invariant). +- INV-15 already covered the no-managed-identity constraint + (re-stating it as INV-21 would have been a duplicate). +- INV-16 + INV-17 cover the input-integrity + policy-discipline + concerns that the spec's INV-19/20 expressed as attestation-specific + invariants (they are in fact general identity-layer invariants, not + attestation-specific). +- REQ-332 carries the signature + KDF detail that the spec's INV-18 + hand-waved ("public key derivable from the PAT") — and corrects it + to a sound symmetric scheme (C-5.2). + +### Audit verification (how to re-run this audit) + +```sh +# 1. Confirm INV-18..21 do not exist in this repo. +grep -rE 'INV-1[89]|INV-2[01]' .ciagent/ docs/ core/ tests/ \ + | grep -v 'INV-18..21' # only the C-9.2 audit references should remain + +# 2. Confirm the re-mapped invariants + REQ-332 exist + are tested. +pytest tests/test_jws_attestation.py tests/test_abac_fail_closed.py \ + tests/test_kms_roundtrip.py tests/test_argon2_fail_closed.py -q +``` + +--- + +## 5. Test coverage summary + +| Threat | Test file | What it verifies | +|--------|-----------|------------------| +| T-1 (password) | `tests/test_argon2_fail_closed.py` | 503 on argon2 unavailable (no weak hash) | +| T-1 (password) | `tests/test_idp_auth.py` | no raw password in DDB item or logs (INV-16) | +| T-2 (PAT theft) | `tests/test_auth_commands.py` | credentials.json has OIDC token, NOT raw PAT (C-7.3) | +| T-2 (PAT theft) | `tests/test_pat_revocation.py` | revocation takes effect <1s (D-229 SLO) | +| T-3 (JWKS DDoS) | (CloudFormation template inspection) | reserved concurrency = 10; WAF with `--public-jwks-domain` | +| T-4 (ABAC bypass) | `tests/test_abac_fail_closed.py` (7 tests) | fail-closed on engine absent / error / deny (C-6.1) | +| T-5 (KMS key) | `tests/test_kms_roundtrip.py` | KMS sign → JWKS → pyjwt verify (CAP-037) | +| T-6 (DER→raw) | `tests/test_kms_roundtrip.py` | the round-trip succeeds only if DER→raw is byte-correct | +| T-7 (no managed id) | (inspection) | no `cognitoidp` / `identitystore` imports in the identity layer | +| T-8 (audit) | `tests/test_e2e_idp.py` | the full audit chain is present + linked (REQ-348) | + +--- + +## 6. Open items (deferred, not blocking v1.28) + +- **WAF rate-limit tuning:** the default rate-based rule threshold + (2000 req/5min/IP) is a pilot-scale guess. Production tuning needs + real traffic data. Tracked as a post-v1.28 ops task. +- **Audit log forwarding to an append-only store** (S3 Object Lock): + the Lambdas emit to stderr / CloudWatch Logs by default. High- + assurance deployments should forward to a write-once destination. + Documented in the operator guide; not enforced in code. +- **PAT theft detection:** there is no anomaly detection on PAT usage + (e.g. a vend from a new geography). The TTL + revocation is the + control. Detection is a future milestone. \ No newline at end of file