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
2 changes: 1 addition & 1 deletion .cargo/audit.toml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
ignore = [
# RUSTSEC-2026-0459: libsqlite3-sys 0.37.0 (C SQLite CVE-2026-119375), fixed in >= 0.39.0.
# https://rustsec.org/advisories/RUSTSEC-2026-0459 - tracked in https://github.com/ilanh/openshell-annotate/issues/76
# Transitive and not upgradable from this repo: OpenShell v0.1.7 openshell-crypto -> sqlx 0.9.0 -> sqlx-sqlite =0.9.0
# Transitive and not upgradable from this repo: OpenShell v0.1.7 and v0.1.8 openshell-crypto -> sqlx 0.9.0 -> sqlx-sqlite =0.9.0
# (exact pin) -> libsqlite3-sys 0.37.0. openshell-annotate does not use SQLite itself.
# Remove this entry once an OpenShell release bumps sqlx/libsqlite3-sys and we move the pin to it.
"RUSTSEC-2026-0459",
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ subprocesses; add directives with reasons; run `scan`, `generate`, `lint`, `drif

## When changing this tool
- Build/test: `cargo build && cargo test` (Rust 1.94+). The schema crate is a git dependency pinned to the
OpenShell `v0.1.7` tag (see `Cargo.toml`, `Cargo.lock` pins the commit). Update the tag deliberately and re-run
OpenShell `v0.1.8` tag (see `Cargo.toml`, `Cargo.lock` pins the commit). Update the tag deliberately and re-run
the golden tests. `openshell-next` builds against the newest upstream tag, prereleases included, and is moved by
`.github/workflows/openshell-next.yml`; fixes that need the newer OpenShell go there, fixes valid on the current pin
go to `main` (see `docs/DEVELOPING.md`, "Tracking the next OpenShell release").
Expand Down
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]

- 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
- docs: README try-path and install notes for early testers; feedback issue template and Discussions contact link; Contributor Covenant; SECURITY.md supported versions
Expand Down
10 changes: 5 additions & 5 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 3 additions & 3 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,10 @@ repository = "https://github.com/ilanh/openshell-annotate"
authors = ["Ilan Harel"]

[dependencies]
# Pinned to the OpenShell v0.1.7 tag; Cargo.lock records the exact commit.
openshell-policy-schema = { git = "https://github.com/NVIDIA/OpenShell", tag = "v0.1.7" }
# Pinned to the OpenShell v0.1.8 tag; Cargo.lock records the exact commit.
openshell-policy-schema = { git = "https://github.com/NVIDIA/OpenShell", tag = "v0.1.8" }
# Same tag. Schema parsing accepts policies the gateway later rejects; this crate is that validator.
openshell-policy = { git = "https://github.com/NVIDIA/OpenShell", tag = "v0.1.7" }
openshell-policy = { git = "https://github.com/NVIDIA/OpenShell", tag = "v0.1.8" }
anyhow = "1"
clap = { version = "4", features = ["derive"] }
ignore = "0.4"
Expand Down
2 changes: 1 addition & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# syntax=docker/dockerfile:1.7
# Build: scripts/docker-build.sh (or: docker build -t openshell-annotate:dev .)
#
# `openshell-policy-schema` is a git dependency on https://github.com/NVIDIA/OpenShell (tag v0.1.7, commit pinned
# `openshell-policy-schema` is a git dependency on https://github.com/NVIDIA/OpenShell (tag v0.1.8, commit pinned
# in Cargo.lock), fetched by cargo during the build, so no local OpenShell checkout is needed.
FROM rust:1.94-bookworm AS build
WORKDIR /build
Expand Down
12 changes: 8 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ un-annotated calls, and gates CI on drift.
> **Independent community project.** openshell-annotate is not affiliated with, endorsed by, or sponsored by
> NVIDIA. It uses NVIDIA OpenShell's public policy schema crate (Apache-2.0) to validate what it generates.

Early pre-release **v0.1.0-rc.3** (targets OpenShell policy schema v1, `openshell-policy-schema` @ v0.1.7).
Early pre-release **v0.1.0-rc.3** (targets OpenShell policy schema v1, `openshell-policy-schema` @ v0.1.8).
Licensed under Apache-2.0.

## Try it in two minutes
Expand Down Expand Up @@ -136,7 +136,7 @@ stderr. Exit codes and `--deny-warnings` do not depend on the format.

### Files the image keeps outside OpenShell's baseline (`generate --image`)

OpenShell 0.1.7 only lets the sandbox read `/usr /lib /etc /app /var/log /proc /dev/urandom` (plus the workspace when
OpenShell 0.1.8 only lets the sandbox read `/usr /lib /etc /app /var/log /proc /dev/urandom` (plus the workspace when
`include_workdir` is on) once a `filesystem_policy` exists, and it does not log filesystem denials
([NVIDIA/OpenShell#4270](https://github.com/NVIDIA/OpenShell/issues/4270)), so an application under `/opt/<app>` fails with a bare
`EACCES`. `generate --image IMAGE` inspects the image (docker, then podman: WORKDIR, ENTRYPOINT, CMD, and the directory
Expand Down Expand Up @@ -310,7 +310,11 @@ exclude = [] # files diff-logs never picks as the place for a sugg
cloud APIs only. For every credential nothing declares (reported as `unmapped`), `generate --scaffold-profiles DIR` writes
`DIR/<env-lowercased-with-hyphens>.yaml`: the credential, and the endpoints, `access` and binaries taken from the `egress`
directives in the file that declares it (`tls=skip` endpoints get `allow_uninspected_credentials: true`, which OpenShell
requires). Files that already exist are kept. Review the auth style, then check and import it:
requires). Files that already exist are kept. Review the auth style, then check and import it. The skeleton sends the
credential as a bearer token in `Authorization`; since OpenShell v0.1.8 a credential is substituted only where the profile
declares it ([NVIDIA/OpenShell#4886](https://github.com/NVIDIA/OpenShell/pull/4886)), so an API that takes it in another header
(`x-api-key`), a query parameter or a URL path needs `auth_style: header|query|path` with `header_name`, `query_param` or
`path_template`:

```
openshell-annotate generate -o openshell/policy.yaml --providers-out openshell/providers.sh --scaffold-profiles openshell/profiles
Expand Down Expand Up @@ -346,7 +350,7 @@ the rule; a profile bound to other binaries (the bundled `github` profile is for
listed in `[lint] ignore_hosts`.
- JS regex literals are not parsed; Python docstrings are strings (directives must be `#` comments).
- 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
- `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.
A helper spawned by an allowed binary (git -> git-remote-http) is matched through its parent.
- Semantic checks mirror `openshell-policy::validate_sandbox_policy` (documented rules) but the authoritative
Expand Down
2 changes: 1 addition & 1 deletion ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Order matters: each milestone builds on the previous one. Nothing is published (
## 2. Docker image (publish)
- **Scope:** small runtime image with the binary (tree-sitter grammars compiled in; distroless/cc base, 34.9 MB), entrypoint `openshell-annotate`, workdir `/src`.
- **Deliverables:** multi-stage `Dockerfile`, `scripts/docker-build.sh` (local tag `openshell-annotate:dev`, no OpenShell checkout needed), then, after approval, a publish workflow to a registry (ghcr.io) with version tags.
- **Depends on:** a public home for the repo (the `openshell-policy-schema` dependency now resolves from the public OpenShell repo at tag v0.1.7, so the build is portable). Publishing to a registry needs the maintainer's approval.
- **Depends on:** a public home for the repo (the `openshell-policy-schema` dependency now resolves from the public OpenShell repo at tag v0.1.8, so the build is portable). Publishing to a registry needs the maintainer's approval.

## 3. GitHub Action + GitLab CI template
- **Scope:** run `lint --deny-warnings` and `drift --policy openshell/policy.yaml` on every pull/merge request; fail with annotations.
Expand Down
16 changes: 9 additions & 7 deletions docs/DEVELOPING.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@ build that downloads crates takes longer.

| Needed for | What |
|---|---|
| everything | Git, a C compiler (`build-essential` / Xcode command line tools: the tree-sitter grammars are C), network access to crates.io and github.com (the OpenShell schema crate is a git dependency pinned to the `v0.1.7` tag) |
| everything | Git, a C compiler (`build-essential` / Xcode command line tools: the tree-sitter grammars are C), network access to crates.io and github.com (the OpenShell schema crate is a git dependency pinned to the `v0.1.8` tag) |
| build and test | Rust **1.94** or newer through [rustup](https://rustup.rs). CI pins 1.94 |
| Docker image (optional) | Docker with BuildKit |
| sandbox flow (optional) | the `openshell` CLI and `openshell-prover` at 0.1.7, a running OpenShell gateway, and Docker (see section 7) |
| sandbox flow (optional) | the `openshell` CLI and `openshell-prover` at 0.1.8, a running OpenShell gateway, and Docker (see section 7) |

```
rustup toolchain install 1.94 --profile minimal --component rustfmt,clippy
Expand Down Expand Up @@ -95,7 +95,7 @@ sorts after its own prereleases (`latest`, `latest-stable`, `list`, `pinned`, `n
### Tracking the next OpenShell release (`openshell-next`)

`openshell-next` is the one long-lived branch besides `main`. It is `main` plus the OpenShell pin moved to the newest
upstream tag, prereleases included (for example `v0.1.8-pre.3` while `main` is on `v0.1.7`), plus any fix that only
upstream tag, prereleases included (for example `v0.1.9-pre.3` while `main` is on `v0.1.8`), plus any fix that only
makes sense on that version. It exists so the next OpenShell is integrated, and its breakage fixed, before it ships as
stable. A draft pull request `openshell-next` → `main` and an issue labelled `openshell-next` track it; the issue gets a
comment for every new upstream tag.
Expand Down Expand Up @@ -198,8 +198,10 @@ openshell-annotate diff-logs path/to/sandbox.log --write # inserts directives a
# otherwise writes openshell/observed-egress.sh (scanned like any source: review or delete it)
```

Sample logs for both formats are in `tests/fixtures/logs/`. Filesystem denials are not logged by OpenShell 0.1.7, so
`diff-logs` only sees network and L7 events.
Sample logs for both formats are in `tests/fixtures/logs/`. Filesystem denials are not logged by OpenShell 0.1.8, so
`diff-logs` only sees network and L7 events. It reads no sandbox attribution fields, so OpenShell v0.1.8 moving
`container.uid`/`container.name` to `device.container.*` (NVIDIA/OpenShell#5048) needs no change; the OCSF fixture
is real v0.1.7 output.

## 6. Docker image

Expand All @@ -224,7 +226,7 @@ scripts/flow.sh /path/to/project --diff-logs sandbox.log # + diff-logs
scripts/flow.sh /path/to/project --image my-image:tag --run-seconds 30 --exercise exercise.js -- sleep 600
```

It needs `openshell` and `openshell-prover` 0.1.7 on PATH and a connected gateway (`openshell status` shows `Connected`), and
It needs `openshell` and `openshell-prover` 0.1.8 on PATH and a connected gateway (`openshell status` shows `Connected`), and
`OPENSHELL_ANNOTATE=/path/to/binary` if the binary is not on PATH. The image's interpreter paths must be real executables
(not symlinks) and match `[languages]` in `openshell-annotate.toml`, because OpenShell matches the resolved binary path.
A bare `sleep` workload produces no traffic and so no events: drive the sandbox with `--exercise FILE.js` (run with `node -e`),
Expand Down Expand Up @@ -270,4 +272,4 @@ public repo or a paid plan). `.github/rulesets/protect-openshell-next.json` bloc
| `docs are stale` | run `scripts/gen-docs.sh` and commit `docs/` |
| `docs/GITHUB_ACTIONS.md is out of date with actions/*/action.yml` | run `scripts/gen-actions-docs.sh` and commit it; add a `BEGIN/END actions-docs <name>` section for a new action |
| sandbox probes get `403` from `api.github.com` | unauthenticated GitHub API rate limit (60 requests per hour per IP), not a policy decision; wait for the reset or use another host |
| `openshell-prover: not found` in `flow.sh` | install the OpenShell 0.1.7 tools; the static commands (`scan`, `generate`, `lint`, `drift`, `diff-logs`) do not need them |
| `openshell-prover: not found` in `flow.sh` | install the OpenShell 0.1.8 tools; the static commands (`scan`, `generate`, `lint`, `drift`, `diff-logs`) do not need them |
2 changes: 1 addition & 1 deletion docs/DIRECTIVES.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ Attributes:
| Attribute | Values | Repeatable | Meaning |
|---|---|---|---|
| `access` | `read-only \| read-write \| full` | no | OpenShell access preset; turns on request inspection (protocol defaults to `rest`). Mutually exclusive with `allow`. For `protocol=mcp` the preset is not written out (MCP rejects access presets); it is emitted as `mcp.allow_all_known_mcp_methods: true`. |
| `protocol` | `rest \| websocket \| graphql \| mcp \| json-rpc \| tcp` | no | L7 protocol. `tcp` is uninspected L4 and cannot be combined with `access`/`allow`/`deny`. `rest`, `websocket`, and `graphql` need `access` or `allow` (a protocol alone is rejected). `mcp` never emits `access`; an `access` value becomes `mcp.allow_all_known_mcp_methods: true`. |
| `protocol` | `rest \| websocket \| graphql \| mcp \| json-rpc \| tcp` | no | L7 protocol. `tcp` is uninspected L4 and cannot be combined with `access`/`allow`/`deny`. `rest`, `websocket`, and `graphql` need `access` or `allow` (a protocol alone is rejected). `mcp` never emits `access`; an `access` value becomes `mcp.allow_all_known_mcp_methods: true`. Since OpenShell v0.1.8 a `rest` endpoint answers WebSocket upgrade requests with 403, so a WebSocket client needs `protocol=websocket`. |
| `enforce` | `enforce \| audit` | no | Enforcement mode for inspected endpoints (default from `[policy] enforcement`, itself defaulting to `enforce`). |
| `allow` | `METHOD:/path \| query \| mutation \| subscription` | yes | Explicit allowed request, e.g. `GET:/v1/**`. Repeatable. Implies inspection. For `protocol=graphql` the value is `query`, `mutation`, or `subscription`, optionally `:operationName`. That is emitted as `rules[].allow.operation_type` and only for GraphQL. |
| `deny` | `METHOD:/path \| query \| mutation \| subscription` | yes | Request subtracted from what is allowed. Repeatable; needs `allow` or `access`. For `protocol=graphql` the value is an operation type (`query`, `mutation`, or `subscription`), emitted as `deny_rules[].operation_type` and only for GraphQL. |
Expand Down
6 changes: 6 additions & 0 deletions docs/RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,12 @@ release" note to the tracking issue. To bring it to `main`:
workflow create the issue at the next upstream tag; it links a compare view for opening the PR.
5. Cut a release of openshell-annotate as usual if users should get the new pin.

If `openshell-next` has already moved past the stable tag (to the next release's prereleases) before you promote, bump
`main` directly instead: on a branch from `main`, run `scripts/openshell-next.sh bump vX.Y.Z`, do step 2 there and open a
PR with `Closes #<tracking issue>` (OpenShell v0.1.8 went this way). `sync` keeps the newer pin when it merges `main`, so
`openshell-next` stays on the prerelease; retitle the draft tracking PR for the next version or close it and let step 4
replace it.

Never promote a prerelease pin to `main`: stable openshell-annotate releases build against stable OpenShell only.

## Installing
Expand Down
2 changes: 1 addition & 1 deletion examples/polyglot/openshell/policy.yaml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Generated by openshell-annotate @VERSION@ - DO NOT EDIT. Change the @openshell directives in source and regenerate.
# Validated against openshell-policy-schema and the OpenShell v0.1.7 gateway validator. Each entry's comment gives the reason and source file:line.
# Validated against openshell-policy-schema and the OpenShell v0.1.8 gateway validator. Each entry's comment gives the reason and source file:line.
# Startup-only sections (filesystem_policy, landlock, process) need a sandbox recreate to change; network_policies are live.
version: 1
filesystem_policy:
Expand Down
Loading
Loading