Skip to content
Open
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 .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ Closes #

- [ ] Branch is named `feat/`, `fix/`, `docs/`, `chore/` or `test/` and commits are signed off (`git commit -s`)
- [ ] `scripts/ci-local.sh` passes (`TOOLCHAIN=1.94 scripts/ci-local.sh`)
- [ ] `scripts/security-local.sh` passes if workflows, dependencies or the OpenShell pin changed
- [ ] Tests added or updated (`tests/cli.rs`, fixtures, golden files)
- [ ] Docs regenerated if directives or flags changed (`scripts/gen-docs.sh`)
- [ ] Docs updated in this PR for every behaviour change (mapping in `AGENTS.md`: `actions/*` → `docs/GITHUB_ACTIONS.md` + `scripts/gen-actions-docs.sh`, CLI → `README.md`, release process → `docs/RELEASING.md`)
Expand Down
6 changes: 3 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,10 @@ jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- name: Install Rust
run: rustup toolchain install 1.94 --profile minimal --component rustfmt,clippy && rustup default 1.94
- uses: actions/cache@v4
- uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
with:
path: |
~/.cargo/registry
Expand All @@ -44,7 +44,7 @@ jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- name: cargo audit
run: cargo install cargo-audit --locked && cargo audit

Expand Down
76 changes: 76 additions & 0 deletions .github/workflows/security.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
name: Security

# Supply-chain and repository hygiene checks (#101):
# actionlint lint every workflow (with shellcheck on `run:` scripts)
# gitleaks scan the full git history for committed secrets
# cargo-deny advisories, licenses, bans and sources for the Rust dependency tree (deny.toml)
# openshell-pin the NVIDIA/OpenShell git pin: Cargo.toml tag = Cargo.lock commit = upstream tag
# Tools are downloaded by scripts/ci-tools.sh at pinned versions and checked against pinned SHA-256 hashes
# (actionlint also against its GitHub build provenance). Run the same checks locally: scripts/security-local.sh
# These jobs are not (yet) required status checks; see .github/rulesets/protect-main.json.

on:
push:
branches: [main]
pull_request:
workflow_dispatch:
# New RustSec advisories appear without any change here.
schedule:
- cron: "23 4 * * 2" # Tuesdays 04:23 UTC

permissions:
contents: read

concurrency:
group: security-${{ github.ref }}
cancel-in-progress: true

jobs:
actionlint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Install actionlint (pinned, sha256 + attestation)
env:
GH_TOKEN: ${{ github.token }}
run: scripts/ci-tools.sh install actionlint --dir "$RUNNER_TEMP/bin"
- name: actionlint
run: actionlint -color

gitleaks:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
persist-credentials: false
- name: Install gitleaks (pinned, sha256)
run: scripts/ci-tools.sh install gitleaks --dir "$RUNNER_TEMP/bin"
- name: gitleaks (full history)
run: gitleaks git --redact --no-banner --exit-code 1 .

cargo-deny:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Install Rust
run: rustup toolchain install 1.94 --profile minimal && rustup default 1.94
- name: Install cargo-deny (pinned, sha256)
run: scripts/ci-tools.sh install cargo-deny --dir "$RUNNER_TEMP/bin"
- name: cargo deny check
run: cargo deny --locked check

openshell-pin:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Verify the NVIDIA/OpenShell pin
env:
GH_TOKEN: ${{ github.token }}
run: scripts/verify-openshell-pin.sh
3 changes: 3 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ subprocesses; add directives with reasons; run `scan`, `generate`, `lint`, `drif
- Never emit a field the pinned `openshell-policy-schema` rejects. `generate` re-parses its own output with
`parse_policy`; tests assert this.
- Generated YAML is written as text (comments with `file:line`) because `serialize_policy` drops comments.
- New dependencies must pass `cargo deny check` (`deny.toml`: allowed licenses and sources); run
`scripts/security-local.sh` after touching workflows, dependencies or the OpenShell pin.
- No secrets anywhere (directives, reasons, fixtures, providers output). Providers use the bare
`--credential KEY` form so values come from the caller's environment.
- Add a test for every new directive, attribute, lint pattern or error message. Fixtures live in
Expand All @@ -41,6 +43,7 @@ A change is not done until the docs that describe it match. Update them in the s
| Pinned OpenShell version (`Cargo.toml`) | every doc that names the version (`git grep -n 'v0\.1\.[0-9]'`) |
| OpenShell tracking (`scripts/openshell-*.sh`, `scripts/upstream-compat.sh`, `openshell-next.yml`, `upstream-compat.yml`) | `docs/DEVELOPING.md` (section 4) and the promotion steps in `docs/RELEASING.md` |
| Branch, issue or CI rules | `CONTRIBUTING.md`, `docs/DEVELOPING.md`, `.github/pull_request_template.md` |
| Security checks (`security.yml`, `deny.toml`, `scripts/ci-tools.sh`, `scripts/verify-openshell-pin.sh`, `scripts/security-local.sh`) | `docs/DEVELOPING.md` (section 4) and `SECURITY.md` ("Supply chain") |
| Anything user-visible | a line under `## [Unreleased]` in `CHANGELOG.md` |

CI enforces the generated parts (`scripts/gen-docs.sh --check`, `scripts/gen-actions-docs.sh --check`); the rest is on
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]

- ci: `Security` workflow (#101): actionlint on the workflows, gitleaks over the full git history, `cargo deny check` with a new `deny.toml` (advisories, licenses, bans, sources), and `scripts/verify-openshell-pin.sh`, which checks that the Cargo.toml OpenShell tag, the Cargo.lock commit and the upstream tag agree; tools are installed by `scripts/ci-tools.sh` at pinned versions with pinned SHA-256 hashes (actionlint also by attestation); `scripts/security-local.sh` runs the same checks locally; `ci.yml` pins `actions/checkout` and `actions/cache` by commit SHA
- 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)
Expand Down
6 changes: 4 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,11 @@ goes through a branch and a pull request.
1. Branch from an up-to-date `main`, named by type: `feat/<name>`, `fix/<name>`, `docs/<name>`, `chore/<name>`
(`test/<name>` for test-only work).
2. Commit with a DCO sign-off: `git commit -s -m "feat: what and why"` (conventional prefixes, small commits).
3. Run `scripts/ci-local.sh` before pushing (`TOOLCHAIN=1.94 scripts/ci-local.sh` pins the toolchain CI uses).
3. Run `scripts/ci-local.sh` before pushing (`TOOLCHAIN=1.94 scripts/ci-local.sh` pins the toolchain CI uses), and
`scripts/security-local.sh` when you touch workflows, dependencies or the OpenShell pin.
4. `git push -u origin <branch>` and open a pull request into `main`.
5. CI must pass (the `check` and `audit` jobs), the branch must be up to date with `main`, and all review
5. CI must pass (the required `check` and `audit` jobs, and the `Security` workflow's `actionlint`, `gitleaks`,
`cargo-deny` and `openshell-pin` jobs), the branch must be up to date with `main`, and all review
conversations must be resolved.
6. Merge with **squash merge** (the only merge method enabled; the PR title becomes the commit message, so use a
conventional title). The head branch is deleted automatically after the merge.
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -368,6 +368,7 @@ the rule; a profile bound to other binaries (the bundled `github` profile is for
cargo fmt --check && cargo clippy --all-targets -- -D warnings
cargo test
scripts/gen-docs.sh --check # docs/CLI.md and docs/DIRECTIVES.md are generated from the code
scripts/security-local.sh # actionlint, gitleaks, cargo deny and the OpenShell pin check
```

Full guide (prerequisites, a hands-on quick start, Docker, the sandbox flow, branch workflow): [docs/DEVELOPING.md](docs/DEVELOPING.md).
Expand Down
11 changes: 11 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,17 @@ OpenShell itself should be reported to the OpenShell project (see its `SECURITY.
- It makes no network calls and never executes the code it scans.
- It does not read or emit secret values. `provider` directives name environment variables only.

## Supply chain

- Every pull request and push to `main`, plus a weekly run, goes through the `Security` workflow: actionlint on the
workflows, gitleaks over the full git history, `cargo deny check` (RustSec advisories, licenses, sources; see
`deny.toml`) and a check that the pinned `NVIDIA/OpenShell` tag, the commit in `Cargo.lock` and the upstream tag
agree. `cargo audit` runs in CI as well.
- Third-party GitHub Actions are pinned by commit SHA. CI tools are downloaded at pinned versions and checked against
pinned SHA-256 hashes.
- Release archives come with `SHA256SUMS` and GitHub build provenance (`gh attestation verify <file> --repo
ilanh/openshell-annotate`, see `docs/RELEASING.md`).

## Supported versions

The latest [pre-release](https://github.com/ilanh/openshell-annotate/releases) tag (currently **v0.1.0-rc.3**)
Expand Down
55 changes: 55 additions & 0 deletions deny.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# cargo-deny configuration (read by `cargo deny check`, which the `cargo-deny` job in .github/workflows/security.yml runs).
# Run locally: `cargo deny check` (or scripts/security-local.sh). Docs: https://embarkstudios.github.io/cargo-deny/
# Every exception below must say why it is needed and when to remove it.

[graph]
all-features = true

[advisories]
# RustSec advisory DB. Vulnerabilities, unmaintained and unsound crates fail the check, yanked versions too.
yanked = "deny"
unmaintained = "all"
# No ignores. RUSTSEC-2026-0459 (libsqlite3-sys 0.37.0, #76), which .cargo/audit.toml ignores, is not reported here:
# cargo-deny checks the resolved build graph, and libsqlite3-sys (OpenShell openshell-crypto -> sqlx -> sqlx-sqlite) is
# only in Cargo.lock, not in any build of this crate (`cargo tree -i libsqlite3-sys --target all` prints nothing).
# cargo audit reads the whole lockfile, which is why it still needs its ignore. Add an entry here only with a reason.
ignore = []

[licenses]
# Permissive licenses the current dependency tree actually uses (from `cargo deny list`), all compatible with
# this crate's Apache-2.0. Anything else (GPL, AGPL, SSPL, unlicensed crates...) fails the check until reviewed.
# r-efi also offers LGPL-2.1-or-later, but it is dual-licensed MIT OR Apache-2.0, so LGPL is not allowed here.
allow = [
"0BSD",
"Apache-2.0",
"Apache-2.0 WITH LLVM-exception",
"BSD-3-Clause",
"CC0-1.0",
"ISC",
"MIT",
"MIT-0",
"Unicode-3.0",
"Unlicense",
"Zlib",
]
confidence-threshold = 0.9
unused-allowed-license = "allow"

[licenses.private]
# The OpenShell crates are unpublished workspace members (version 0.0.0) but carry a license field; check them too.
ignore = false

[bans]
# Duplicate versions are common in this tree (OpenShell pulls its own versions); report, do not fail.
multiple-versions = "warn"
wildcards = "deny"
allow-wildcard-paths = true
highlight = "simplest-path"

[sources]
# Only crates.io and the pinned NVIDIA/OpenShell git repository. The pin itself (tag -> commit in Cargo.lock) is
# checked by scripts/verify-openshell-pin.sh.
unknown-registry = "deny"
unknown-git = "deny"
allow-registry = ["https://github.com/rust-lang/crates.io-index"]
allow-git = ["https://github.com/NVIDIA/OpenShell"]
24 changes: 24 additions & 0 deletions docs/DEVELOPING.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,28 @@ TOOLCHAIN=1.94 scripts/ci-local.sh # pinned like CI; omit TOOLCHAIN to use y

Expected last line: `ci-local: all checks passed`. Optional audit: `cargo install cargo-audit --locked && cargo audit`.

The `Security` workflow (`.github/workflows/security.yml`, #101) adds four jobs. Run them locally with
`scripts/security-local.sh` (expected last line: `security-local: all checks passed`):

| Job | What it checks | Config |
| --- | --- | --- |
| `actionlint` | every workflow, including shellcheck on `run:` scripts | — |
| `gitleaks` | the full git history for committed secrets | gitleaks defaults |
| `cargo-deny` | RustSec advisories, licenses, banned/duplicate crates, allowed sources | `deny.toml` |
| `openshell-pin` | the Cargo.toml OpenShell tag, the Cargo.lock commit and the upstream tag agree | `scripts/verify-openshell-pin.sh` |

The tools come from `scripts/ci-tools.sh install actionlint gitleaks cargo-deny` (Linux x86_64), which downloads pinned
versions and refuses an archive whose SHA-256 differs from the hash pinned in the script; actionlint is also checked
with `gh attestation verify --repo rhysd/actionlint` (gitleaks and cargo-deny publish no attestations). To bump a
tool, change its version and hash together. A new license in the dependency tree fails `cargo-deny` until it is
reviewed and added to `deny.toml`. Pin every third-party action by full commit SHA with the version in a comment
(`uses: owner/action@<sha> # vX.Y.Z`); actionlint does not enforce this, review does.

CI never downloads OpenShell binaries: it builds the policy crates from the `NVIDIA/OpenShell` git tag. OpenShell's
release attestations cover its built packages, which can be built from another commit than the tag (v0.1.8's .deb came
from 22209de, the tag is f3d9765), so the `openshell-pin` job checks the source pin instead and reports whether GitHub
verified the commit's signature.

Clippy gains new lints with every Rust release. If it fails on a newer toolchain but passes on 1.94, fix the lint in a
separate commit (CI will keep using 1.94 until the pin is bumped on purpose in `ci.yml`, `Dockerfile` and `Cargo.toml`).

Expand Down Expand Up @@ -149,6 +171,8 @@ Fixes for breakage on the new OpenShell go in a `fix/<name>` branch off `openshe
`cargo audit` ignores are listed in `.cargo/audit.toml`, each with its advisory and the condition for removing it.
Today that is `RUSTSEC-2026-0459` (`libsqlite3-sys` pinned by OpenShell's `sqlx`, #76): whenever you bump the OpenShell
pin, run `cargo tree -i libsqlite3-sys --target all` and drop the ignore once it resolves to 0.39.0 or newer.
`cargo deny` needs no such ignore (`deny.toml` has none): it checks only crates in the build graph, and
`libsqlite3-sys` is in `Cargo.lock` but not built. Any advisory ignore added to `deny.toml` needs a `reason`.

## 5. Try it on a tiny project

Expand Down
70 changes: 70 additions & 0 deletions scripts/ci-tools.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
#!/usr/bin/env bash
# Install the pinned security tools that .github/workflows/security.yml uses, verifying each download.
# scripts/ci-tools.sh install <actionlint|gitleaks|cargo-deny>... [--dir DIR] # default DIR: ~/.local/bin
# Linux x86_64 only (the CI runner). Each archive must match the SHA-256 pinned below; this is stricter than checking
# against the release's own checksum file, because a replaced release asset and its checksum file would both change.
# actionlint publishes GitHub build provenance, so it is also checked with `gh attestation verify` when `gh` supports
# it (set VERIFY_ATTESTATION=0 to skip). gitleaks and cargo-deny publish no attestations (checked 2026-11-17).
# To bump a tool: change its version and hash together, taken from the release's checksum file, in one PR.
set -euo pipefail

declare -A VERSION=(
[actionlint]=1.7.12
[gitleaks]=8.30.1
[cargo-deny]=0.21.0
)
declare -A SHA256=(
[actionlint]=8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8
[gitleaks]=551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb
[cargo-deny]=a2170b854ff697e79e39c4c538981c9c1bdd803addbae6719a4cb66b4585a903
)

url() {
local v="${VERSION[$1]}"
case "$1" in
actionlint) echo "https://github.com/rhysd/actionlint/releases/download/v$v/actionlint_${v}_linux_amd64.tar.gz" ;;
gitleaks) echo "https://github.com/gitleaks/gitleaks/releases/download/v$v/gitleaks_${v}_linux_x64.tar.gz" ;;
cargo-deny) echo "https://github.com/EmbarkStudios/cargo-deny/releases/download/$v/cargo-deny-$v-x86_64-unknown-linux-musl.tar.gz" ;;
esac
}

install_tool() {
local tool="$1" dir="$2" tmp archive want got
[ -n "${VERSION[$tool]:-}" ] || { echo "unknown tool: $tool" >&2; exit 2; }
tmp="$(mktemp -d)"
archive="$tmp/$tool.tar.gz"
curl -fsSL --retry 3 --retry-delay 2 -o "$archive" "$(url "$tool")"
want="${SHA256[$tool]}"
got="$(sha256sum "$archive" | cut -d' ' -f1)"
if [ "$got" != "$want" ]; then
echo "::error::$tool ${VERSION[$tool]}: SHA-256 mismatch (got $got, want $want); not installed" >&2
exit 1
fi
echo "$tool ${VERSION[$tool]}: sha256 ok ($got)"
if [ "$tool" = actionlint ] && [ "${VERIFY_ATTESTATION:-1}" = 1 ]; then
if gh attestation --help >/dev/null 2>&1; then
gh attestation verify "$archive" --repo rhysd/actionlint >/dev/null
echo "$tool: attestation ok (built by rhysd/actionlint)"
else
echo "::warning::gh has no 'attestation' command (needs gh >= 2.49); skipped the actionlint provenance check"
fi
fi
tar -xzf "$archive" -C "$tmp"
mkdir -p "$dir"
install -m 0755 "$(find "$tmp" -type f -name "$tool" | head -n 1)" "$dir/$tool"
rm -rf "$tmp"
}

[ "${1:-}" = install ] || { echo "usage: $0 install <actionlint|gitleaks|cargo-deny>... [--dir DIR]" >&2; exit 2; }
shift
dir="$HOME/.local/bin"
tools=()
while [ $# -gt 0 ]; do
case "$1" in
--dir) dir="$2"; shift 2 ;;
*) tools+=("$1"); shift ;;
esac
done
[ "${#tools[@]}" -gt 0 ] || { echo "no tool given" >&2; exit 2; }
for t in "${tools[@]}"; do install_tool "$t" "$dir"; done
if [ -n "${GITHUB_PATH:-}" ]; then echo "$dir" >>"$GITHUB_PATH"; fi
14 changes: 14 additions & 0 deletions scripts/security-local.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
#!/usr/bin/env bash
# Run the checks of .github/workflows/security.yml locally: actionlint, gitleaks, cargo-deny and the OpenShell pin.
# scripts/security-local.sh
# Needs actionlint, gitleaks and cargo-deny on PATH (any recent version; on Linux x86_64, `scripts/ci-tools.sh install
# actionlint gitleaks cargo-deny` installs the exact CI versions into ~/.local/bin). shellcheck, if installed, is used
# by actionlint for `run:` scripts.
set -euo pipefail
cd "$(dirname "$0")/.."
run() { printf '\n==> %s\n' "$*"; "$@"; }
run actionlint
run gitleaks git --redact --no-banner --exit-code 1 .
run cargo deny --locked check
run scripts/verify-openshell-pin.sh
echo; echo "security-local: all checks passed"
Loading
Loading