Security

This page covers the supported versions, how to report a vulnerability, what the integrity values in a .urna file prove, how the reader treats a file you did not build, and every place where urna opens a network connection.

Supported versionsCopy Anchor Link

Fixes land on the latest minor release line only.

There is no 0.4.0 release: that version was never tagged, and its changes first shipped in 0.5.0. See the changelog.

Report a vulnerabilityCopy Anchor Link

Do not open a public GitHub issue for a security problem. Use one of these private channels:

• The private vulnerability report form: https://github.com/hoffresearch/urna/security/advisories/new
• Email: brenner@hoffresearch.com

The maintainer aims to acknowledge a report within 72 hours and to publish a fix or mitigation within 14 days for confirmed reports. Coordinated disclosure is preferred, and reporters who ask for credit get it.

A useful report includes:

• The file_hash and content_hash of the .urna involved (urna stats <file> prints both).
• The simd_backend and the platform (urna stats prints the backend).
• The exact CLI or Python invocation.
• A minimal reproducer if you have one. A synthetic .urna is fine; the fixtures under crates/urna-format/tests/fixtures/ in the repository are a starting point.
• A proposed mitigation, if you have one.

In scopeCopy Anchor Link

• A malformed .urna file that makes the Rust runtime hit undefined behavior, read out of bounds, panic or abort.
• A citation collision: two distinct chunks that produce the same chunk_id.
• A content_hash collision under the v1 hash domain separation.
• A text query path (search-text, ask, retrieve) that skips the model_hash check without an explicit skip flag. The only skip flag is urna search-text --skip-model-hash-check. search-space takes a raw vector and checks the hash only when you pass --expect-model-hash.
• A path that runs model-repository code (trust_remote_code presets) without the explicit opt-in, or that runs a pinned preset's code file whose SHA-256 is outside the pinned allowlist. See model code.
• Secrets or credentials committed to the repository.

Out of scopeCopy Anchor Link

• Low recall on a particular corpus, or HNSW recall below your expectation. That is tuning; see search paths.
• The BM25 tokenizer on CJK, Thai and Lao text. It is a documented limitation, listed in known limits.
• Size differences between compressed and raw builds.
• Vulnerabilities in the upstream sentence-transformers or Hugging Face stack. Report those upstream first.
• Weaknesses of an embedding model itself, such as false positives or biased recall.
• Operator choices, such as building a corpus with the placeholder model_hash and then querying it with --skip-model-hash-check.

What the hashes proveCopy Anchor Link

A .urna file carries several integrity values. All of them are unkeyed SHA-256: they detect corruption, not tampering.

The header and section checksums are 8-byte prefixes, not full sha256:<64 hex> strings. urna inspect --json prints a section checksum as 16 hex characters with no prefix. The footer hash and the reported file_hash are two different numbers: the footer excludes itself, the reported value covers every byte. The manifest is covered by the footer hash only, so editing a manifest field changes file_hash and leaves content_hash and every citation unchanged. The layouts and preimages are in hashes and citations and hashes.

"Verifiable" means integrity, not authenticity. Anyone who edits a file can recompute every value above, and the file carries no signature; the manifest authors field is free text. urna validate passing proves the bytes are internally consistent. It does not prove who built the file. To trust a corpus, get its file_hash from its publisher over a channel you already trust and compare it with urna stats or sha256sum.

Treat a downloaded .urna as untrusted inputCopy Anchor Link

Opening a file runs the parser on bytes you did not write. Safety against a hostile file rests on that parser's memory safety, so give an unknown .urna the same care as any untrusted input.

What the reader checksCopy Anchor Link

When the runtime opens a file (MmapUrnaFile::open, used by ask, retrieve, every search verb and the Python urna.open), it checks, in order:

• The magic (URNA, or the legacy NEST), the header version, the header checksum, and that the recorded file size equals the real size.
• For each section: that its encoding is legal for its class, that its offset is 64-byte aligned and inside the file, and its checksum.
• That the manifest parses and passes its rules, then the footer hash.
• That the manifest and header agree on embedding_dim and n_chunks, that all six required sections are present, that the embeddings section has the exact size its dtype implies, and that the search_contract section matches the manifest field by field.
• That no embedding value is NaN or infinite, and the same for each multimodal band and for a full-precision rerank slab when present.
• That the HNSW, BM25, graph and media payloads decode, with every count read from the file bounded by the remaining bytes before it sizes an allocation.

What the reader does not checkCopy Anchor Link

• Section ids it does not know. An unknown or reserved id loads when its encoding is legal for its class and its checksum matches.
• Duplicate section ids (the first match wins) and sections that overlap each other, the table or the manifest. Only bounds and alignment are checked.
• The header flags and reserved bytes, and a section table offset other than 128.
• Whether a file is honest. The checks prove consistency; they cannot tell a crafted file from a real one.

urna validate runs a subset of the open path: the byte-level checks, the NaN walk over the main embeddings, the contract decode and a SHA-256 proof of every inlined media blob. It does not decode the HNSW, BM25, graph or overlay payloads and does not NaN-check the multimodal bands. A file with a malformed index payload and a valid checksum passes validate and fails to open. Both paths read every byte: validate loads the whole file into memory, and open maps it and hashes all of it.

Hardening in the parserCopy Anchor Link

• clippy::unwrap_used and clippy::undocumented_unsafe_blocks are denied across the workspace (tests exempt from the first).
• urna-format, the crate that parses the container, has no unsafe block, and CI runs its tests under miri on a nightly schedule.
• unsafe in urna-runtime is limited to the SIMD kernels, the Mmap::map call in mmap_file.rs and the posix_madvise call in mmap_cold.rs. Every block carries a // SAFETY: comment, and the SIMD dispatchers check slice lengths with assert!, kept in release builds.
• Header-derived sizes are overflow-checked, payload cursors check need > remaining, and every score sort puts NaN last.
• A deterministic mutation harness runs under cargo test, four cargo-fuzz targets run for 90 seconds each on every pull request and push to main, and a nightly job soaks each target for 30 minutes. The first runs found and fixed five classes of malformed-file bug, including a count claim that asked the allocator for 31 GB from a 90-byte payload.

Queries run local PythonCopy Anchor Link

ask, retrieve and search-text start a Python process to embed the query, and doctor starts one for a test embed. The file does not supply that code, but where the code comes from depends on your working directory:

• The embedder script is looked up in a checkout layout first (python/... under the current directory, then under its parent), and only then in the installed payload. A checkout in your working directory or its parent wins.
• The interpreter is URNA_PYTHON, else the venv urna setup created, else the nearest .venv/bin/python in the current directory or up to three parents, else python3. The choice is printed on stderr as [urna] embedder interpreter: <path>.
• --embedder on ask, retrieve and search-text runs whatever script you name.

Run queries from a directory you trust, or pin URNA_PYTHON. The manifest's embedding_model picks between the potion script and the registry script; a registry preset that needs remote code still requires your opt-in.

urna media --export checks each inlined blob against its SHA-256 in blob_refs before writing it, and writes only the last component of the blob's URI, so a hostile URI cannot write outside the export directory.

Where urna opens a network connectionCopy Anchor Link

The Rust runtime never opens a socket, and the urna binary links no network stack. Queries are answered from the memory-mapped file. These are the places where a connection does happen:

For an install with no network at all, see air-gapped install and queries. The design is explained in offline by construction.

Model code and remote codeCopy Anchor Link

Five registry presets need trust_remote_code: jina-v5-omni-nano, jina-v5-omni-small, wemm-2b, wemm-4b and wemm-9b. A build loads them only when the spec lists the preset in [output] allow_remote_code. The query, bench and UI-bridge scripts load them only when URNA_ALLOW_REMOTE_CODE names the preset (a comma list). A manifest cannot grant this by naming a model.

Only wemm-2b pins its remote code: five files with fixed SHA-256 values, and a changed or missing file is refused. jina-v5-omni-nano, jina-v5-omni-small, wemm-4b and wemm-9b have no pins, so the opt-in is their only gate. A pinned hash identifies a version; it does not make the code safe. Review the files before you trust a new pin, and build in an isolated environment when the model directory is not fully trusted. Each sentence-transformers model runs in its own worker process, which keeps models apart from each other and is not a sandbox. See choose and bring embedding models.

Release provenanceCopy Anchor Link

• Release tags are annotated and SSH-signed. tag-verify.yml checks the signature against .github/allowed_signers before the release archives build.
• The five binary archives carry a per-file .sha256 and a SLSA build provenance attestation (gh attestation verify <archive> --repo hoffresearch/urna).
• The binaries embed their dependency tree (cargo auditable), the release ships a CycloneDX SBOM (urna.cdx.xml), and Cargo.lock is committed.
• cargo deny checks advisories, licenses and sources in CI.
• The PyPI wheels for 0.5.0 and 0.5.1 carry no PEP 740 attestations, and the npm package carries registry signatures but no npm provenance.

The per-artifact commands are in verify what you installed.