Skip to content

Commit 009b5c1

Browse files
jboldjbold
committed
docs: add security roadmap and session log for testing/stability work
1 parent a1857ea commit 009b5c1

2 files changed

Lines changed: 290 additions & 0 deletions

File tree

‎SECURITY_ROADMAP.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# Security Roadmap
2+
3+
Last updated: 2026-02-08
4+
5+
This roadmap is the shortest path from "secure architecture" to "defensible production security posture" for exoclaw.
6+
7+
## Current Baseline
8+
9+
- Strong foundations already in place:
10+
- WASM plugin isolation and capability scoping (`src/sandbox/mod.rs`).
11+
- Loopback default bind and token requirement on non-loopback (`src/gateway/server.rs`).
12+
- Constant-time token comparison (`src/gateway/auth.rs`).
13+
- Secure credential file permissions (`src/secrets.rs`, `src/fs_util.rs`).
14+
- CI test/security jobs for Rust tests, wasm UI tests, E2E, and dependency checks (`.github/workflows/test-suite.yml`).
15+
16+
- Known gaps before production claim:
17+
- TLS termination not implemented in gateway.
18+
- OpenTelemetry and security observability still pending.
19+
- No formal rate limiting/abuse throttling layer.
20+
- No plugin signature verification or trusted plugin provenance policy.
21+
- No explicit RBAC scope model for RPC methods.
22+
23+
## Target Posture
24+
25+
- P0: Safe private beta on trusted networks.
26+
- P1: Internet-exposed beta with strong guardrails.
27+
- P2: Production-grade posture for enterprise-style review.
28+
29+
## P0 Controls (Ship First)
30+
31+
- Transport and exposure:
32+
- Require TLS termination at ingress for any non-loopback deployment.
33+
- Require token auth for all non-loopback binds with startup hard-fail.
34+
- Add WebSocket origin allowlist for browser clients.
35+
36+
- Auth hardening:
37+
- Support token rotation with active+next token validation window.
38+
- Add max token length and strict JSON shape checks on connect.
39+
- Add auth failure cooldown per source IP/session key.
40+
41+
- Abuse prevention:
42+
- Add request body/message size limits.
43+
- Add per-IP and per-session rate limits for `chat.send`.
44+
- Add connection and in-flight stream caps to prevent memory exhaustion.
45+
46+
- Security logging:
47+
- Emit structured security audit events for auth pass/fail, plugin denied capability, rate-limit hits, and stream timeout.
48+
- Include request id, session key, remote address, and method name in every audit event.
49+
- Add panic hook + fatal event breadcrumb in logs.
50+
51+
- CI security gates:
52+
- Keep existing `cargo audit` and `cargo deny`.
53+
- Add secret scanning gate (for example `gitleaks`) on pull requests.
54+
- Add fuzz/safety tests for JSON-RPC parsing and SSE stream parser edge cases.
55+
56+
- Definition of done for P0:
57+
- All non-loopback deployments run behind TLS ingress with auth token.
58+
- PRs fail on secrets, dependency CVEs, and security test regressions.
59+
- Malformed/oversized websocket payloads are rejected safely and tested.
60+
61+
## P1 Controls (Internet Beta)
62+
63+
- Plugin trust and supply chain:
64+
- Enforce plugin signing (signature + digest) before load.
65+
- Maintain allowlist of trusted plugin publishers.
66+
- Persist plugin provenance metadata and verify at startup.
67+
68+
- Authorization model:
69+
- Introduce method-level scopes (for example `chat:send`, `plugin:list`, `admin:*`).
70+
- Require explicit scope binding per token.
71+
- Add deny-by-default policy for admin/control methods.
72+
73+
- Data and secret hardening:
74+
- Encrypt persisted session/history store at rest once DB persistence lands.
75+
- Move API key handling to OS keyring option for local mode.
76+
- Add key rotation command with audit trail.
77+
78+
- Runtime hardening:
79+
- Add bounded queues and backpressure instrumentation for hot paths.
80+
- Add circuit breakers around provider calls and webhook adapters.
81+
- Add host egress allowlist mode for outbound HTTP.
82+
83+
- CI/CD hardening:
84+
- Generate SBOM on every release artifact.
85+
- Add release signing and provenance attestation.
86+
- Block merge without passing security checks and at least one human review.
87+
88+
- Definition of done for P1:
89+
- Only signed plugins can load in default mode.
90+
- Tokens are scoped and least-privilege by default.
91+
- Release artifacts are reproducible, signed, and accompanied by SBOM.
92+
93+
## P2 Controls (Production / Enterprise)
94+
95+
- Advanced controls:
96+
- Optional mTLS for service-to-service traffic in distributed deployments.
97+
- WAF/edge policy templates for exposed gateway endpoints.
98+
- Region-aware key management and secret escrow policy.
99+
100+
- Detection and response:
101+
- OpenTelemetry traces + metrics + logs with SIEM export path.
102+
- Alerting playbooks for auth abuse, token anomalies, plugin denial spikes, and provider failure storms.
103+
- Incident response runbook and recovery drill cadence.
104+
105+
- Resilience and compliance:
106+
- Backup/restore procedures for persistent state.
107+
- Data retention and deletion policy with automated enforcement.
108+
- Security chaos testing and regular threat-model refresh.
109+
110+
- Definition of done for P2:
111+
- Incident MTTR and detection SLIs are tracked and stable.
112+
- Security controls are continuously tested in CI and in staging drills.
113+
- External review can trace controls from policy to code to evidence.
114+
115+
## Coverage and Quality Targets
116+
117+
- Line coverage:
118+
- Keep minimum backend coverage gate at 70% now.
119+
- Raise to 80% after P1 controls land.
120+
- Raise to 85% for security-critical modules (`gateway/auth`, `gateway/protocol`, `sandbox`, `agent/providers`).
121+
122+
- Must-have security test classes:
123+
- Auth bypass and malformed handshake cases.
124+
- JSON-RPC parser robustness and type confusion cases.
125+
- SSE framing/parser fuzz tests (CRLF/LF/CR variants, truncation, long frames).
126+
- Plugin capability denial and sandbox escape regression tests.
127+
- Rate-limit and queue-exhaustion behavior tests.
128+
129+
## CI/CD Enforcement Policy
130+
131+
- Required PR checks:
132+
- `Rust + Coverage`
133+
- `Dependency Security`
134+
- `WASM UI Tests`
135+
- `Playwright E2E`
136+
- `Secrets Scan`
137+
- `Security Regression Tests`
138+
139+
- Branch protection:
140+
- No direct push to `main`.
141+
- No bypass merge except repository admin emergency policy.
142+
- Require at least one code review approval.
143+
144+
## Module-by-Module Implementation Plan
145+
146+
- `src/gateway/server.rs`:
147+
- Add websocket origin checks, body size guards, connection caps, and rate-limit middleware.
148+
- Add structured remote peer extraction and audit event emission.
149+
150+
- `src/gateway/auth.rs`:
151+
- Add rotating token set support and strict handshake schema validation.
152+
- Add explicit auth error codes for observability and client UX.
153+
154+
- `src/gateway/protocol.rs`:
155+
- Add method scope checks and deny-by-default for privileged methods.
156+
- Add central request validation and max payload constraints.
157+
158+
- `src/sandbox/mod.rs`:
159+
- Add plugin signature verification and trusted publisher policy checks.
160+
- Log capability denials with stable event codes.
161+
162+
- `src/agent/providers.rs`:
163+
- Add circuit breaker state and retry budget boundaries.
164+
- Emit security/abuse telemetry around timeout and failure patterns.
165+
166+
- `.github/workflows/test-suite.yml`:
167+
- Add `secrets-scan` and `security-regressions` jobs as required checks.
168+
- Publish security test artifacts for failed runs.
169+
170+
## 30/60/90 Day Execution
171+
172+
- By 2026-03-10:
173+
- Complete all P0 controls and required tests.
174+
- Enforce branch protection with full required checks.
175+
176+
- By 2026-04-09:
177+
- Complete P1 plugin signing, method scopes, and release provenance.
178+
- Raise coverage target to 80%.
179+
180+
- By 2026-05-09:
181+
- Complete P2 telemetry + incident response + resilience drills.
182+
- Publish a security posture report mapped to this roadmap.

‎session-log-2026-02-08-exoclaw-testing-gateway-stability.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Session Log: Testing Rollout + Gateway Stability
2+
3+
Date: 2026-02-08
4+
Repo: `exoclaw`
5+
6+
## Session Goals
7+
8+
- Stand up a full test stack for Rust + WASM + Leptos.
9+
- Diagnose and fix gateway chat instability (first message works, later messages hang).
10+
- Validate CI/PR gates and merge stabilized changes.
11+
- Assess architecture posture versus OpenClaw and document a security path.
12+
13+
## Work Completed
14+
15+
### 1) Full Testing Suite and CI Gates
16+
17+
- Added layered testing workflow and documentation:
18+
- `TESTING.md`
19+
- `scripts/test-rust.sh`
20+
- `scripts/test-wasm-ui.sh`
21+
- `scripts/test-e2e.sh`
22+
- `scripts/test-all.sh`
23+
24+
- Added CI workflow with required jobs:
25+
- Rust tests + coverage gate
26+
- Dependency security (`cargo-audit`, `cargo-deny`)
27+
- WASM UI tests (`wasm-pack` / `wasm-bindgen-test`)
28+
- Playwright E2E
29+
- File: `.github/workflows/test-suite.yml`
30+
31+
- Added supporting artifacts:
32+
- Playwright config and E2E specs
33+
- WASM UI tests
34+
- Coverage/security config files (`deny.toml`, `.cargo/audit.toml`)
35+
36+
### 2) Gateway Protocol + Streaming Stability Fixes
37+
38+
- Root cause fixed:
39+
- The agent event channel could fill during streaming tool runs, causing deadlock because provider output was not drained concurrently.
40+
41+
- Key fixes:
42+
- Concurrent provider/event draining with `tokio::select!` in `src/agent/mod.rs`.
43+
- Regression test for high-volume streaming drain behavior:
44+
- `run_with_tools_drains_stream_while_provider_is_running`
45+
- Numeric JSON-RPC `id` handling regression covered in `tests/protocol_test.rs` (`ping_accepts_numeric_id`).
46+
- SSE parsing hardening for framing variants and stream timeout behavior in `src/agent/providers.rs`.
47+
- Improved websocket/gateway diagnostics and stream frame logging in `src/gateway/protocol.rs` and `src/gateway/server.rs`.
48+
- UI websocket resilience and timeout/close handling improvements in `ui/src/ws.rs`.
49+
50+
### 3) Validation and Merge
51+
52+
- Validation commands run:
53+
- `cargo test`
54+
- `./scripts/test-wasm-ui.sh`
55+
- `./scripts/test-e2e.sh`
56+
57+
- PR/merge outcomes:
58+
- `dd97b30` — Phase 2 test suite + CI security gates (#6)
59+
- `a1857ea` — Streaming deadlock fix + websocket/SSE hardening (#7)
60+
- Both are now on `main`.
61+
62+
## Operational Notes from Debugging
63+
64+
- Running gateway in a detached background process required proper `nohup/setsid` handling in this environment.
65+
- Recommended foreground debug run:
66+
67+
```bash
68+
RUST_LOG=info,exoclaw::gateway::protocol=debug,exoclaw::gateway::server=debug,exoclaw::agent::providers=debug cargo run -- gateway 2>&1 | tee /tmp/exoclaw.log
69+
```
70+
71+
- Recommended detached run:
72+
73+
```bash
74+
setsid nohup env NO_COLOR=true RUST_LOG=info,exoclaw::gateway::protocol=debug,exoclaw::gateway::server=debug,exoclaw::agent::providers=debug cargo run -- gateway </dev/null >/tmp/exoclaw.log 2>&1 &
75+
```
76+
77+
## Size / Scope Snapshot
78+
79+
- `target/release/exoclaw`: ~23 MB
80+
- `target/debug/exoclaw`: ~365 MB
81+
- exoclaw code footprint (current rough local count): ~9k LOC
82+
- openclaw local source footprint (rough local count): ~603k LOC
83+
84+
Debug-vs-release size spread is expected for Rust due to symbols, debug info, and lower optimization in dev profile.
85+
86+
## Security/Architecture Assessment Outcome
87+
88+
- Direction is strong:
89+
- Rust runtime
90+
- capability-scoped WASM plugins
91+
- loopback-by-default gateway
92+
- token auth on non-loopback bind
93+
94+
- Not yet a full production security claim:
95+
- TLS termination, advanced observability, and additional control layers still needed.
96+
97+
- Added roadmap:
98+
- `SECURITY_ROADMAP.md` with P0/P1/P2 controls, definitions of done, CI enforcement policy, and 30/60/90 day milestones.
99+
100+
## Recommended Next Steps
101+
102+
- Implement P0 controls from `SECURITY_ROADMAP.md`:
103+
- websocket origin and payload-size limits
104+
- rate limiting / abuse controls
105+
- structured security audit events
106+
107+
- Make security checks branch-protection required alongside current test suite.
108+

0 commit comments

Comments
 (0)