Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

docs(air-gapped): the TAG guard belongs inside the subshell too

xerj-org7197c433df76
diff --git a/docs/recipes/air-gapped-deployment.md b/docs/recipes/air-gapped-deployment.md
index 091610f4f..8135b1e36 100644
--- a/docs/recipes/air-gapped-deployment.md
+++ b/docs/recipes/air-gapped-deployment.md
@@ -103,14 +103,14 @@ After transfer, set the same approved `TAG` in the enclave and verify before
extracting:
```bash
-: "${TAG:?set TAG to the same operator-approved release tag}"
-VERSION="${TAG#v}"
-STAGE="xerj-${VERSION}-x86_64-unknown-linux-musl"
-ASSET="${STAGE}.tar.gz"
-
(
set -eu
+ : "${TAG:?set TAG to the same operator-approved release tag}"
+ VERSION="${TAG#v}"
+ STAGE="xerj-${VERSION}-x86_64-unknown-linux-musl"
+ ASSET="${STAGE}.tar.gz"
+
work="$(mktemp -d)"
trap 'rm -rf "$work"' EXIT
cp "/opt/xerj-staging/release/$ASSET" "$work/$ASSET"
@@ -179,7 +179,18 @@ one was broken through the handoff rather than through the digest. There is no
handoff now, so nothing later has to be trusted and no exit status has to be
checked.
-**`mktemp -d` runs INSIDE the subshell, under `set -eu`.** It was outside in an
+**Everything runs INSIDE the subshell, under `set -eu` — including the `TAG`
+guard.** Bash does not terminate an *interactive* shell when a `${var:?}`
+expansion fails, so with the guard above the `(` a pasted block printed its
+message and carried on: `VERSION` empty, `ASSET` becoming
+`xerj--x86_64-unknown-linux-musl.tar.gz`, and inside the subshell that variable
+IS set, so `set -u` never fired either. An attacker who can write the staging
+directory needs only to leave that name and a matching `.sha256` beside the
+approved pair, and the block verifies their file against their digest and
+installs it at exit 0. A subshell is not interactive, so the same guard inside
+it ends the block.
+
+**`mktemp -d` runs inside it too.** It was outside in an
earlier version, where a failure was not fatal and its status was never checked:
`work` became the empty string, both `cp` lines failed, and `cd ""` returns 0 in
bash without changing directory — so the block hashed and extracted `$ASSET`
@@ -201,9 +212,12 @@ export TMPDIR="$HOME/xerj-verify"
```
An earlier version of this page said "set `TMPDIR` to a root-owned directory",
-which is worse than no advice: a root-owned directory the attacker cannot write
-is one you cannot write either, so `mktemp` fails — and with the failure
-unchecked, that sentence was itself the trigger for the defect above.
+which is worse than no advice. Root ownership was never the problem — the
+default `/tmp` is root-owned and is exactly right, because the sticky bit stops
+anyone else renaming your work directory. The problem is a directory YOU cannot
+write: `mktemp` then fails, and with that failure unchecked the sentence was
+itself the trigger for the defect above. The property to aim for is writable by
+you and renameable by nobody else.
An attacker who rewrites the archive AND recomputes its `.sha256` still passes,
and always will: that is the one case a checksum cannot answer, and the prose
diff --git a/landing/docs/recipes/air-gapped-deployment.html b/landing/docs/recipes/air-gapped-deployment.html
index 50d422900..32e453970 100644
--- a/landing/docs/recipes/air-gapped-deployment.html
+++ b/landing/docs/recipes/air-gapped-deployment.html
@@ -107,14 +107,14 @@ curl -fL --retry 3 -o "$OUT/release/$ASSET.sha256" "$BASE/$ASSET.sha256"
"$STAGE/xerj" --version
)</pre>
<p>The checksum proves archive integrity against the digest published beside it in the same release; it is not a signature, provenance statement, or attestation. After transfer, set the same approved <code class="inline">TAG</code> and verify before extracting:</p>
-<pre class="code">: "${TAG:?set TAG to the same operator-approved release tag}"
-VERSION="${TAG#v}"
-STAGE="xerj-${VERSION}-x86_64-unknown-linux-musl"
-ASSET="${STAGE}.tar.gz"
-
-(
+<pre class="code">(
set -eu
+ : "${TAG:?set TAG to the same operator-approved release tag}"
+ VERSION="${TAG#v}"
+ STAGE="xerj-${VERSION}-x86_64-unknown-linux-musl"
+ ASSET="${STAGE}.tar.gz"
+
work="$(mktemp -d)"
trap 'rm -rf "$work"' EXIT
cp "/opt/xerj-staging/release/$ASSET" "$work/$ASSET"
@@ -141,7 +141,7 @@ ASSET="${STAGE}.tar.gz"
sudo install -m 0755 "$STAGE/xerj" /opt/xerj/bin/xerj
echo "installed $ASSET ($want)"
)</pre>
- <p><strong>The archive is copied once, then hashed and extracted from that copy.</strong> Earlier versions opened the archive twice at the staging path &mdash; once by <code class="inline">sha256sum</code>, once by <code class="inline">tar</code> &mdash; and anyone who can write that directory swaps the file between the two opens. Copying first collapses that to a single read. <strong><code class="inline">mktemp -d</code> runs inside the subshell, under <code class="inline">set -eu</code></strong>: outside it, a failed <code class="inline">mktemp</code> left <code class="inline">work</code> empty, <code class="inline">cd ""</code> returned 0 without moving, and the block silently hashed and extracted from whatever directory the operator was in &mdash; the double read again, at exit 0. <strong>The work directory must be writable by you and nobody else.</strong> The default sticky <code class="inline">/tmp</code> is fine; if yours is not, <code class="inline">install -d -m 0700 "$HOME/xerj-verify"</code> and point <code class="inline">TMPDIR</code> there. This page previously advised a <em>root-owned</em> directory, which an unprivileged operator cannot write &mdash; that advice was itself the trigger for the defect above.</p>
+ <p><strong>The archive is copied once, then hashed and extracted from that copy.</strong> Earlier versions opened it twice at the staging path &mdash; once by <code class="inline">sha256sum</code>, once by <code class="inline">tar</code> &mdash; and anyone who can write there swaps the file between the two opens. <strong>Everything runs inside the subshell under <code class="inline">set -eu</code>, including the <code class="inline">TAG</code> guard.</strong> Bash does not terminate an <em>interactive</em> shell when a <code class="inline">${var:?}</code> expansion fails, so with the guard outside the block a paste printed its message and carried on with an empty version &mdash; and an attacker who can write the staging directory need only leave a file of that name beside the approved one. A subshell is not interactive, so the guard ends the block. <strong>The work directory must be writable by you and renameable by nobody else.</strong> The default sticky <code class="inline">/tmp</code> is exactly right; if yours is not, <code class="inline">install -d -m 0700 "$HOME/xerj-verify"</code> and point <code class="inline">TMPDIR</code> there. This page once advised a <em>root-owned</em> directory: root ownership was never the problem (<code class="inline">/tmp</code> is root-owned), a directory you cannot write is &mdash; <code class="inline">mktemp</code> then fails, and with that failure unchecked the advice was itself the trigger.</p>
<h2>2. Configure the base lexical node</h2>
<p>Create the service account first, then install only the staged binary. No model directory is needed for lexical mode:</p>