docs: consolidate repository documentation map
Jaime Fournier <jaimef@linbsd.org>
5db90b25189fb7d6689e4b310b1c148ad7717b02
--- a/README.md +++ b/README.md @@ -262,31 +262,15 @@ tools/ generators, linters, build and audit helpers vendor/ vendored Chez Scheme tree ``` -Start with these docs: - -- [`docs/JERBOA-LANG.md`](docs/JERBOA-LANG.md) for the language guide. -- [`docs/quickstart.md`](docs/quickstart.md) and - [`docs/tutorial.md`](docs/tutorial.md) for getting oriented. -- [`docs/api-index.md`](docs/api-index.md) for generated API coverage. -- [`docs/libraries.md`](docs/libraries.md) for standard-library notes. -- [`docs/reader-syntax.md`](docs/reader-syntax.md) and - [`docs/pattern-matching.md`](docs/pattern-matching.md) for syntax. -- [`docs/concurrency.md`](docs/concurrency.md), - [`docs/fiber.md`](docs/fiber.md), [`docs/async.md`](docs/async.md), - [`docs/stm.md`](docs/stm.md), and - [`docs/lightweight-concurrency.md`](docs/lightweight-concurrency.md) for concurrency. +Start with the canonical documentation map: + +- [`docs/index.md`](docs/index.md) for the maintained language-repository map. +- [`docs/quickstart.md`](docs/quickstart.md) for installing and running code. +- [`docs/JERBOA-LANG.md`](docs/JERBOA-LANG.md) for the language reference. +- [`docs/libraries.md`](docs/libraries.md) and + [`docs/api-index.md`](docs/api-index.md) for standard-library coverage. - [`docs/security-reference.md`](docs/security-reference.md) and - [`docs/safety-guide.md`](docs/safety-guide.md) for hardening. -- [`docs/release-security.md`](docs/release-security.md) for production - release gates and threat model. -- [`docs/native-rust.md`](docs/native-rust.md), - [`docs/ffi.md`](docs/ffi.md), [`docs/wasm.md`](docs/wasm.md), and - [`docs/slang.md`](docs/slang.md) for native and WASM integration. -- [`docs/build.md`](docs/build.md), [`docs/cross-compile.md`](docs/cross-compile.md), - [`docs/single-binary.md`](docs/single-binary.md), and - [`docs/jpkg-guide.md`](docs/jpkg-guide.md) for builds and packages. -- [`docs/site-publishing.md`](docs/site-publishing.md) for keeping - `jerboa.sh` synchronized with this repository. + [`docs/safety-guide.md`](docs/safety-guide.md) for implemented hardening. ## License --- a/docs/kimi3-security-recommmendations.md +++ b/docs/kimi3-security-recommmendations.md @@ -213,18 +213,18 @@ when" must be answerable from `dist/release-evidence/` in minutes. | Taint tracking + safe sinks | `(std security taint)`, `(jerboa prelude safe)` | exists; safe prelude binds standard file/shell/delete sinks to taint-checking wrappers and taints env/file-content reads; protocol/network source marking remains explicit | security-reference §4 | | Kernel FS confinement (Linux 5.13+, ABI v1–v3) | `(std security landlock)`, `(std os landlock-native)` | real syscalls | security-reference §5 | | Kernel syscall filter (BPF, x86_64 + aarch64 numbers) | `(std security seccomp)`, `(std os seccomp)` | real BPF | security-reference §5 | -| macOS / FreeBSD confinement | `(std security seatbelt)`, `(std security capsicum)` | exist | lib listing | -| Self-confinement (pledge/unveil-style `cage!`) | `(std security cage)` | exists; **absent from security-reference.md** — doc gap | `lib/std/security/cage.ss` | +| macOS / FreeBSD confinement | `(std security seatbelt)`, `(std security capsicum)` | exist | security-reference §5 | +| Self-confinement (pledge/unveil-style `cage!`) | `(std security cage)` | exists; documented in the security module inventory | security-reference §12 | | Privilege-separation pipe channels (no launcher) | `(std security privsep)` | channels only, by design | security-reference §5 | | Launch policy planner + egress policy objects | `(std os limits sandbox)` | passive planner remains `pre-exec-refused`; `(std os limits)` can emit rlimit triples for the worker/aproc backend | [limits.md](limits.md) | | Exec restricted worker facade | `(std security worker)` | exists; pure env, deadline, process-group kill, output caps, audit records, fail-closed refused axes, explicit `sandbox:` axis requests, egress proxy env wiring, and memory rlimits installed pre-exec on supported platforms; native kernel sandbox installation pending | security-reference §5 | | Native async exec launcher (collect-safe) | `(std os aproc)` | exists — the primitive P0-02 should build on | [aproc.md](aproc.md) | -| Parser hardening (depth/size/backtrack budgets: reader, JSON, XML, YAML, DNS, HTTP/2, WS, zlib, base64, hex, CSV, pregexp, format) | various | phases 1–4 done, 42 tests; **phase 5 (FFI audit) not started** | security-reference §7 | +| Parser hardening (depth/size/backtrack budgets: reader, JSON, XML, YAML, DNS, HTTP/2, WS, zlib, base64, hex, CSV, pregexp, format) | various | phases 1–4 done, 42 tests; phase 5 FFI audit inventory has per-site provisional verdicts, with remediation rules still open | security-reference §7; [ffi-audit.md](ffi-audit.md) | | Safe deserialization (tagged-JSON envelope, no native FASL on untrusted paths) | `(std safe-fasl)`, `(std fasl)` (trusted-only) | exists; named raw-read/FASL paths have first triage; broader `load`/REPL/dev-surface classification remains | [safety-guide.md](safety-guide.md) §10 | | Crypto (Rust `ring`: AEAD, HMAC, PBKDF2, scrypt, ChaCha20, digests; CSPRNG from `/dev/urandom`; timing-safe compare; Argon2id via Rust `argon2`) | `(std crypto native-rust)`, `(std crypto password)` et al. | exists; high-level HMAC/AEAD/KDF/password APIs route through Rust native crypto | security-reference §10 | | Secure memory (mlock, guard pages, DONTDUMP/DONTFORK, explicit_bzero, checked secure bytevector view) | `(std crypto secure-mem)` | exists; high-level `secure-bytevector` API plus raw region escape hatch | security-reference §9 | -| Lifetime-scoped secrets with auto-wipe | `(std security secret)` | exists; **absent from security-reference.md** — doc gap | `lib/std/security/secret.ss` | -| Env/secret broker for child processes (allow/deny patterns, redaction) | `(std security env)` | exists; **absent from security-reference.md** — doc gap | `lib/std/security/env.ss` | +| Lifetime-scoped secrets with auto-wipe | `(std security secret)` | exists; documented in the security module inventory | security-reference §12 | +| Env/secret broker for child processes (allow/deny patterns, redaction) | `(std security env)` | exists; documented in the security module inventory | security-reference §12 | | Sanitization (HTML/attr/URL/SQL/path/header) | `(std security sanitize)` | exists | security-reference §12 | | Error classification (opaque client refs) | `(std security errors)` | exists | security-reference §12 | | Audit log (append-only hash-chained JSONL) | `(std security audit)`, `(std security audit-log)` | exists | security-reference §12 | @@ -305,7 +305,7 @@ when" must be answerable from `dist/release-evidence/` in minutes. | Goal | Where we stand | The gap | |---|---|---| | G1 shrink target | Managed core is memory-safe; parsers budgeted; safe prelude exists | FFI surface (91 files / 225 symbols / 432 `unsafe`) never systematically audited (phase 5); `vendor/jsqlite` is C in the TCB; safe prelude not the default entry; import conflict undermines "safe symbol wins" confidence | -| G2 cap blast radius | Capabilities, taint, kernel sandbox, egress policy objects, worker facade, memory rlimit pre-exec path, and authenticated actor transport/envelopes all exist | **No native pre-exec worker backend yet for kernel sandbox controls before child input**; taint source marking/propagation still incomplete; egress proxy wiring pending; `define-syntax` in sandbox | +| G2 cap blast radius | Capabilities, taint, kernel sandbox, egress policy objects, worker facade, memory rlimit pre-exec path, egress proxy env wiring, and authenticated actor transport/envelopes all exist | **No native pre-exec worker backend yet for kernel sandbox controls before child input**; protocol/network taint source defaults and performance measurement remain open | | G3 find it first | 13 harnesses, scanner w/ rule DB, lint | No corpora, no crash regression, no scheduled fuzzing, no standing AI-red-team, no exploit-shaped regression suite | | G4 fail closed | Raw-fork launchers retired correctly; `allow-degraded?` explicit | New controls must keep the invariant; degraded-mode warnings must be test-locked | | G5 recover fast | SBOM/repro/signing gates exist | TCB accounting manual; doc drift (stale tables, undocumented modules); independent-builder reproducibility not yet routine | @@ -954,7 +954,9 @@ fix must add its scanner rule in the same commit (write it into top-level `docs/`, implemented security claims live in `docs/security-reference.md`, dated audits/reviews live under `docs/reviews/`, and this file is only the roadmap/handoff. `SECURITY.md` - points to the same hierarchy. + points to the same hierarchy. `README.md` now points to `docs/index.md` as + the maintained map instead of carrying a parallel long-form documentation + catalogue. - `ai-threat.md`'s comparative table already reflects TUF, signatures, transparency, SBOM, OSV, and content-addressed artifacts; its SQL status now reflects the literal-SQL, parameterized safe-prelude surface.