Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
- chore(deps): build against OpenShell v0.1.8 (`openshell-policy-schema`, `openshell-policy`); docs and generated policy headers now name v0.1.8. The gateway validator now rejects `websocket_credential_rewrite: true` on `protocol: rest` (covered by a test); `--scaffold-profiles` skeletons explain the v0.1.8 credential placement rule (credentials go only where the profile declares them); `diff-logs` needs no change for the OCSF `device.container.*` move; the RUSTSEC-2026-0459 ignore stays (v0.1.8 still pins `sqlx` 0.9.0)
- fix(actions): `setup` and `check` resolve `version: latest` to the newest release tag before the cache step and key the cache on that tag, so a new stable release is installed instead of the first cached binary; `check` gets a `cache` input like `setup` (#77)
- 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
Expand Down
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -349,6 +349,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.8 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.
Expand Down
98 changes: 98 additions & 0 deletions src/lint.rs
Original file line number Diff line number Diff line change
Expand Up @@ -520,6 +520,17 @@ pub fn lint(scan: &Scan, cfg: &Config) -> Vec<Finding> {
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
Expand Down Expand Up @@ -685,6 +696,9 @@ pub fn lint(scan: &Scan, cfg: &Config) -> Vec<Finding> {
}
}
}
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)));
Expand Down Expand Up @@ -720,6 +734,90 @@ pub fn lint(scan: &Scan, cfg: &Config) -> Vec<Finding> {
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<String> {
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<Finding> {
static RE: OnceLock<Regex> = 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<String>)> = 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`.
Expand Down
25 changes: 25 additions & 0 deletions src/validate.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<String> {
let h = host.trim_matches(|c| c == '[' || c == ']');
let v4 = h.parse::<std::net::Ipv6Addr>().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
Expand Down Expand Up @@ -387,6 +397,9 @@ pub fn check_document(doc: &PolicyDocument) -> (Vec<String>, Vec<String>) {
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"));
Expand Down Expand Up @@ -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());
Expand Down
66 changes: 66 additions & 0 deletions tests/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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}"
);
}
Loading