From 52cd6eda8003f9e2567eb5879dff9ef9f883d8fc Mon Sep 17 00:00:00 2001 From: Ilan Harel Date: Mon, 16 Nov 2026 14:09:46 +0200 Subject: [PATCH] feat(lint): warn about OpenShell v0.1.8 WebSocket-on-rest and IPv4-mapped hosts Closes #95 - ws:// / wss:// URL literals whose host is declared only by an inspected rest egress directive: REST endpoints answer WebSocket upgrades with 403 since OpenShell v0.1.8 (NVIDIA/OpenShell#5336). - IPv4-mapped IPv6 hosts (::ffff:a.b.c.d) in egress directives and policy files: evaluated as IPv4 since v0.1.8 (NVIDIA/OpenShell#5101). - README: symlinked filesystem paths fail launch since v0.1.8 (NVIDIA/OpenShell#5278) and cannot be detected statically. Signed-off-by: Ilan Harel --- CHANGELOG.md | 1 + README.md | 6 +++ src/lint.rs | 98 +++++++++++++++++++++++++++++++++++++++++++++++++ src/validate.rs | 25 +++++++++++++ tests/cli.rs | 66 +++++++++++++++++++++++++++++++++ 5 files changed, 196 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ed0e611..26d2869 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ version section and adds the squash-merged PR titles since the previous tag. Ver ## [Unreleased] +- feat(lint): warn about OpenShell v0.1.8 pitfalls: `ws://`/`wss://` URL literals declared only by a `rest` egress (REST endpoints answer WebSocket upgrades with 403), and IPv4-mapped IPv6 hosts (`::ffff:a.b.c.d`, evaluated as IPv4) in egress directives and policy files; README notes that symlinked filesystem paths (fail launch since v0.1.8) cannot be detected statically - ci: the `openshell-next` workflow also runs at 07:17 UTC as a backup for the 04:17 UTC schedule, because GitHub may delay or drop a scheduled run; both slots share one concurrency group and no-op when the pin is unchanged - docs: README try-path and install notes for early testers; feedback issue template and Discussions contact link; Contributor Covenant; SECURITY.md supported versions - ci: `openshell-next` branch automation: a daily workflow merges main into `openshell-next`, moves its OpenShell pin to the newest upstream tag (prereleases included), runs the tests and reports on the tracking issue; `scripts/openshell-tags.sh` and `scripts/openshell-next.sh` do the same by hand diff --git a/README.md b/README.md index 49c83f1..e65e601 100644 --- a/README.md +++ b/README.md @@ -345,6 +345,12 @@ the rule; a profile bound to other binaries (the bundled `github` profile is for people (`help`, `usage`, `msg`, `message`, `error`, `doc`, ...). Real calls are still flagged. A host that still shows up can be listed in `[lint] ignore_hosts`. - JS regex literals are not parsed; Python docstrings are strings (directives must be `#` comments). +- OpenShell v0.1.8 changes that lint checks: a `ws://`/`wss://` URL literal whose host is declared only by an inspected + `rest` egress is a warning (REST endpoints answer WebSocket upgrades with 403, NVIDIA/OpenShell#5336; use + `protocol=websocket`), and an IPv4-mapped IPv6 host (`::ffff:203.0.113.7`) in a directive or a `--policy` file is a warning + (it is evaluated as IPv4, NVIDIA/OpenShell#5101). A WebSocket client with a computed URL or behind an SDK is not seen. + Filesystem policy paths that go through a symlink inside a writable directory now fail sandbox launch + (NVIDIA/OpenShell#5278); the symlink lives in the image, so lint cannot see it: put the symlink's target in `@openshell fs`. - Filesystem/process/landlock are startup-only in OpenShell; drift labels them `startup`. - `diff-logs` only sees network and L7 events: OpenShell 0.1.7 does not log Landlock/filesystem denials (upstream #4270), log delivery is batched and best-effort (wait a few seconds after the workload; absence of an event is not proof), and `NET:REFUSE` lines carry no binary. diff --git a/src/lint.rs b/src/lint.rs index f7032f1..212082e 100644 --- a/src/lint.rs +++ b/src/lint.rs @@ -520,6 +520,17 @@ pub fn lint(scan: &Scan, cfg: &Config) -> Vec { for m in validate::check_directive(d) { out.push(directive_finding(&d.file, d.line, m)); } + if let Kind::Egress { host, .. } = &d.kind { + if let Some(m) = validate::host_warning(host) { + out.push(Finding::new( + d.file.clone(), + d.line, + Severity::Warning, + "directive", + m, + )); + } + } } let provider_envs: BTreeSet<&str> = scan .directives @@ -685,6 +696,9 @@ pub fn lint(scan: &Scan, cfg: &Config) -> Vec { } } } + if cfg.lint.categories.is_empty() || cfg.lint.categories.iter().any(|c| c == "net") { + out.extend(websocket_on_rest(scan, cfg)); + } if cfg.lint.fs_dynamic == "summary" && !dyn_fs.is_empty() && !fs_roots.is_empty() { let total: usize = dyn_fs.iter().map(|d| d.1.len()).sum(); dyn_fs.sort_by(|a, b| b.1.len().cmp(&a.1.len()).then(a.0.cmp(&b.0))); @@ -720,6 +734,90 @@ pub fn lint(scan: &Scan, cfg: &Config) -> Vec { out } +/// L7 protocol an `egress` directive emits: its `protocol=`, else `rest` when `access=` or `allow=` turns on +/// inspection, else `None` (L4 passthrough). +fn egress_protocol(d: &Directive) -> Option { + if let Some(p) = d.attr("protocol") { + return Some(p.to_ascii_lowercase()); + } + (d.attr("access").is_some() || d.attrs.multi.contains_key("allow")).then(|| "rest".to_string()) +} + +/// Warns about `ws://` / `wss://` URL literals whose host and port are declared only by inspected `rest` egress +/// directives. Since OpenShell v0.1.8 (NVIDIA/OpenShell#5336) a REST endpoint answers WebSocket upgrade requests +/// with 403, so these clients need `protocol=websocket`. Comment-only lines and excluded files are skipped. +fn websocket_on_rest(scan: &Scan, cfg: &Config) -> Vec { + static RE: OnceLock = OnceLock::new(); + let re = RE.get_or_init(|| { + Regex::new(r"\b(wss?)://([A-Za-z0-9][A-Za-z0-9.\-]*[A-Za-z0-9])(?::(\d+))?").unwrap() + }); + let egress: Vec<(&Directive, &str, &[u16], Option)> = scan + .directives + .iter() + .filter_map(|d| match &d.kind { + Kind::Egress { host, ports } => { + Some((d, host.as_str(), ports.as_slice(), egress_protocol(d))) + } + _ => None, + }) + .collect(); + let mut out = Vec::new(); + for src in &scan.sources { + if excluded(&src.rel, cfg) { + continue; + } + let ignored = |line: usize| { + scan.directives.iter().any(|d| { + d.file == src.rel + && matches!(d.kind, Kind::Ignore) + && d.covers().contains(&"net") + && (d.file_scoped() || (d.line <= line && line - d.line <= cfg.lint.window)) + }) + }; + for (i, raw) in src.lexed.raw.iter().enumerate() { + if src.lexed.code.get(i).is_some_and(|c| c.trim().is_empty()) || ignored(i + 1) { + continue; + } + for c in re.captures_iter(raw) { + let host = c[2].to_ascii_lowercase(); + let port: u16 = c + .get(3) + .and_then(|m| m.as_str().parse().ok()) + .unwrap_or(if &c[1] == "wss" { 443 } else { 80 }); + let matching: Vec<_> = egress + .iter() + .filter(|(_, h, ports, _)| { + crate::diff_logs::host_matches(h, &host) && ports.contains(&port) + }) + .collect(); + let Some((d, ..)) = matching.iter().find(|e| e.3.as_deref() == Some("rest")) else { + continue; + }; + if matching.iter().any(|e| e.3.as_deref() != Some("rest")) { + continue; + } + out.push( + Finding::new( + src.rel.clone(), + i + 1, + Severity::Warning, + "net", + format!( + "WebSocket URL {}://{host}:{port} is declared as `protocol=rest` ({}:{}); OpenShell v0.1.8+ answers WebSocket upgrades on REST endpoints with 403: use `protocol=websocket` (with `access=` or `allow=`)", + &c[1], d.file, d.line + ), + ) + .at(Some(Span { + col: c.get(0).unwrap().start(), + end: Some(c.get(0).unwrap().end()), + })), + ); + } + } + } + out +} + /// Project-wide declarations the AST lint checks call sites against. struct Ctx<'a> { /// Credentials declared by `provider` directives or `[providers].expect`. diff --git a/src/validate.rs b/src/validate.rs index c918bcc..da7513b 100644 --- a/src/validate.rs +++ b/src/validate.rs @@ -69,6 +69,16 @@ pub fn check_host(host: &str) -> Result<(), String> { Ok(()) } +/// Returns a warning when `host` is an IPv4-mapped IPv6 address such as `::ffff:203.0.113.7`. +/// +/// Since OpenShell v0.1.8 (NVIDIA/OpenShell#5101) transparent TCP connections to such destinations are evaluated as +/// IPv4, so a rule has to name the IPv4 address. Brackets are ignored. +pub fn host_warning(host: &str) -> Option { + let h = host.trim_matches(|c| c == '[' || c == ']'); + let v4 = h.parse::().ok()?.to_ipv4_mapped()?; + Some(format!("`{host}` is an IPv4-mapped IPv6 address; OpenShell v0.1.8+ evaluates these destinations as IPv4, so the rule never matches: use `{v4}`")) +} + /// Checks a `filesystem_policy` path; `write` is true for `read_write` entries. /// /// # Errors @@ -387,6 +397,9 @@ pub fn check_document(doc: &PolicyDocument) -> (Vec, Vec) { if let Err(m) = check_host(&ep.host) { errs.push(format!("{at}: {m}")); } + if let Some(m) = host_warning(&ep.host) { + warns.push(format!("{at}: {m}")); + } } if ep.port != 0 && !ep.ports.is_empty() { errs.push(format!("{at}: `port` and `ports` are mutually exclusive")); @@ -466,6 +479,18 @@ mod tests { assert!(check_host("bad host").is_err()); } + #[test] + fn ipv4_mapped_hosts_warn() { + assert!(host_warning("::ffff:203.0.113.7") + .unwrap() + .contains("use `203.0.113.7`")); + assert!(host_warning("[::FFFF:203.0.113.7]").is_some()); + assert!(host_warning("::ffff:cb00:7107").is_some()); + assert!(host_warning("203.0.113.7").is_none()); + assert!(host_warning("2001:db8::1").is_none()); + assert!(host_warning("api.example.com").is_none()); + } + #[test] fn fs_paths() { assert!(check_fs_path("/workspace/data", true).is_ok()); diff --git a/tests/cli.rs b/tests/cli.rs index 1fb56fe..7fb98f2 100644 --- a/tests/cli.rs +++ b/tests/cli.rs @@ -2206,3 +2206,69 @@ fn diff_logs_reads_openshell_0_1_7_ocsf_1_8_0_records() { assert_eq!(o.status.code(), Some(1), "{}", err(&o)); golden("diff_logs_ocsf_1_8_0_plain.txt", &out(&o)); } + +/// OpenShell v0.1.8 (NVIDIA/OpenShell#5336): a REST endpoint answers WebSocket upgrades with 403, so lint warns +/// about `ws://`/`wss://` URLs declared only by an inspected `rest` egress, and not once `protocol=websocket` is used. +#[test] +fn lint_warns_about_websocket_urls_on_rest_egress() { + let t = tempfile::tempdir().unwrap(); + let js = |attrs: &str| { + format!( + "// @openshell egress stream.acme-w.dev:443 {attrs} reason=\"live feed\"\nconst ws = new WebSocket(\"wss://stream.acme-w.dev/feed\");\n// wss://stream.acme-w.dev/in-a-comment\n" + ) + }; + std::fs::write(t.path().join("feed.js"), js("access=read-only")).unwrap(); + let s = out(&run(t.path(), &["lint", "--format", "compact"])); + assert!( + s.contains("feed.js:2: warning[net]: WebSocket URL wss://stream.acme-w.dev:443 is declared as `protocol=rest` (feed.js:1)"), + "{s}" + ); + assert!(!s.contains("feed.js:3"), "comment lines are skipped: {s}"); + std::fs::write( + t.path().join("feed.js"), + js("protocol=websocket access=read-only"), + ) + .unwrap(); + let s = out(&run(t.path(), &["lint", "--format", "compact"])); + assert!(!s.contains("WebSocket URL"), "{s}"); + // L4 passthrough (no inspection) is not affected + std::fs::write(t.path().join("feed.js"), js("")).unwrap(); + let s = out(&run(t.path(), &["lint", "--format", "compact"])); + assert!(!s.contains("WebSocket URL"), "{s}"); +} + +/// OpenShell v0.1.8 (NVIDIA/OpenShell#5101) evaluates IPv4-mapped IPv6 destinations as IPv4: lint warns about such +/// hosts in a policy file. +#[test] +fn lint_policy_warns_about_ipv4_mapped_hosts() { + let t = tempfile::tempdir().unwrap(); + std::fs::write(t.path().join("a.js"), "console.log(1)\n").unwrap(); + std::fs::write( + t.path().join("p.yaml"), + "version: 1\nnetwork_policies:\n db:\n endpoints:\n - host: \"::ffff:203.0.113.7\"\n port: 5432\n binaries:\n - path: /usr/bin/psql\n", + ) + .unwrap(); + let o = run( + t.path(), + &["lint", "--format", "compact", "--policy", "p.yaml"], + ); + let s = out(&o); + assert!( + s.contains("IPv4-mapped IPv6 address") && s.contains("use `203.0.113.7`"), + "{s}{}", + err(&o) + ); + // and in an egress directive + std::fs::write( + t.path().join("a.js"), + "// @openshell egress [::ffff:203.0.113.7]:5432 reason=\"db\"\nconsole.log(1)\n", + ) + .unwrap(); + let s = out(&run(t.path(), &["lint", "--format", "compact"])); + assert!( + s.contains( + "a.js:1: warning[directive]: `[::ffff:203.0.113.7]` is an IPv4-mapped IPv6 address" + ), + "{s}" + ); +}