Skip to content

Security model

Brandon White edited this page Nov 17, 2026 · 5 revisions

Threat model

The client is a language model acting on text it read, some of it written by other agents. It may be confused or prompt-injected. It is not a local attacker with a shell; anything with a shell already has the files. The server must make the worst instruction it can follow cheap to undo:

Risk Defence
Data leaves the machine no network client: no HTTP client or DNS in the source or the dependency graph, and one socket, the PR events listener (atlas pr-events serve, command line only), bound to 127.0.0.1 only, which never connects out and accepts a delivery only under its repository's HMAC-SHA256 secret, held in memory (test no_network_code checks Cargo.lock and src/). Two things reach the network, both through the system curl, started with an argument list (no shell), fetching https URLs (--proto =https, redirects included; an update URL may also be http to loopback, for testing) and sending nothing but the request: the model download at setup and first start, and the update check at session start (off with atlas settings off update). Neither runs at query time. atlas pr-events serve (command line only) also runs gh: one gh webhook forward per repository, which creates a webhook on it and relays its events over GitHub's own websocket, and gh api to list the repository's hooks and delete the cli hooks atlas saw its forwarders make (never another), each with an argument list, no shell; the per-repository secret goes to gh on its command line, visible to same-user processes while it runs, rotated at each start
Reading or writing outside the vaults roots fixed at launch; paths checked lexically and again after canonicalisation (below)
Reaching Obsidian config, git, trash any path component starting with . is refused, before and after canonicalisation
Losing notes no delete or rename tool exists; creates are exclusive; edits need the current sha (replace_section) or are additive
Torn or interleaved writes temp file + rename in the same folder; all writers take the SQLite write lock first; a file that changed between read and write is refused
Silent changes every write must state a reason, and lands in the writes table and in the append-only state/writes.jsonl: time, tool, vault, path, sha before and after, client name, pid, reason; write_log reads it back
Prompt-shaped output tool descriptions are short and factual. instructions is one line naming the served vaults and sources, then a fixed paragraph of atlas's own workflow habits (atlas::tools::GUIDE: recall before asking, journal to your lane, write a handoff before your final answer whenever work is left for later; a test caps its tokens). No user rule or note text is injected there. Note text comes back as written, in plain text under a vault:path sha256=... bytes=N line (Tools reference), or as a JSON string with format: "json". Nothing marks it as data, so this is no defence against prompt-shaped text in a note: treat a vault as trusted as your own prompts
Resource exhaustion reads capped at 1 MiB, write payloads at 256 KiB, search results at 200, listings at 2,000, messages at 4 MiB, regex programs at 20,000 instructions and a search's backtracking state at 256 Mibit (32 MiB, freed after the search; a regex search past it is refused, naming the note, the line and what to narrow), globs at 128 bytes and 8 *

Path confinement (src/paths.rs)

A request names vault + a relative path. Refused before touching the disk: absolute paths, leading / or \, UNC, any : (drive prefixes and NTFS :stream names), NUL and control characters, . and .. components, empty components, any component starting with ., components ending in . or space (Windows strips them), < > " | ? *, Windows device names (CON, NUL, COM1, ...), paths over 512 bytes, and for notes anything not ending in .md. Then each folder is canonicalised and must stay under the canonical root, and so must the file, with no dot component in the canonical remainder; so a symlink or junction inside a vault that points outside it, or into .obsidian, is refused (tested with a real junction on Windows and a symlink on Linux). The rescan walker never follows links at all.

Not defended, by design: a hard link placed inside a vault by someone with a shell (it is indistinguishable from a file), and a local process racing a symlink swap between the check and the open (that process could write the target itself).

Dependencies

Two direct dependencies, each a named exception to the rule that atlas owns its code. They bring their own transitive crates (rusqlite brings libsqlite3-sys, hashlink, bitflags and others, and cc to build SQLite), and Cargo.lock lists every one:

  • rusqlite (feature bundled, so the SQLite C library is compiled in and no system SQLite is loaded): the durable store.
  • ed25519-compact, default features off, so it brings no dependency of its own: the signature check on release manifests (src/update.rs). Signing and verification are not hand-written curve arithmetic.

No dev-dependencies. Everything else is owned:

  • JSON (src/json.rs): a strict parser (nesting at most 128, no byte order mark, no lone surrogates, numbers that fit), a writer, json! and the ToJson/FromJson traits.
  • Regular expressions (src/regex.rs): a documented subset (classes, \b, ^ $, groups including (?P<name>), alternation, {m,n}, * + ? and their lazy forms, (?i) (?m) (?s) at the start) run by a bounded backtracker that records every (instruction, position) it tried, so no pattern can take more than program length times text length steps; that record is bounded at 256 Mibit per search (a search past it is refused), and a pattern with no alternative to explore needs none. Anything outside the subset is refused with an error naming it. The module docs hold the table.
  • Change notification (src/platform/): ReadDirectoryChangesW on Windows, inotify on Linux and FSEvents on macOS (per-file events, one stream per root on a thread running its own CFRunLoop; MustScanSubDirs and the dropped-event flags walk the root), all through owned extern declarations.
  • Byte scans (src/scan.rs): SSE2, AVX2 (detected at run time) and NEON versions of memchr and the JSON string scan, each tested against its scalar version. unsafe is denied crate-wide and allowed only in platform (including the child-process priority and kill calls of the code indexer), scan and embed::gemm, each block with its invariant written beside it.
  • Protocol Buffers and SCIP (src/protobuf.rs, src/scip.rs), the WGSL scanner (src/wgsl.rs) and the sentence embedder (src/embed/) are owned as well (see Code index and Semantic search).

Cargo.lock also lists wasm-bindgen, js-sys and sqlite-wasm-rs: they are rusqlite dependencies for the wasm32 target only and are not compiled on Windows or Linux. SHA-256 is hand-rolled (src/sha256.rs, FIPS 180-4 test vectors) to avoid a hashing dependency.

Updates

An update is trusted only after two checks: the release manifest's ed25519 signature against the public key built into atlas (src/update.rs), then the downloaded binary's SHA-256 against the signed manifest. A newer version is never replaced by an older one, a pinned version (update.pin) is never replaced, and a binary built from source never checks. Manifest URLs must be https, or http to a real loopback address. How releases are signed is on Releasing.

Read-only sources

Sources are not vaults: no write tool can name one (each resolves its target through the vault set), and src/sources.rs has no code that opens a file for writing (test no_write_tool_can_reach_a_source calls every write tool against every source and compares bytes and mtimes, and checks the module text). The walker never follows a symlink or junction, never enters a dot folder, and stays as deep as the globs reach; a file is opened only after its canonical path is checked to be under the canonical root.

Deny-list, fixed in code (sources::is_denied), checked before a file is stat'ed and again before it is opened, and refused in a config's globs. It holds for sources, for vaults (a denied note or folder is not walked, indexed, read or written, by name or through a link), for the CLI file tools (atlas digest, atlas crop), and for files Claude Code reads (never kept as a slice handle or read again from disk). The output of a Bash or PowerShell command, atlas run or Grep is not kept as a handle when the command names a denied file (sources::command_names_denied; for Grep, its path or glob), or a word in it is a link to one. This catches named files only: a shell command can hide a path (F=.e; cat ${F}nv, a link reached after cd), and handles for shell output in general stay. It over-matches on purpose, so grep credentials src gets no handle either, which costs a digest and no secret. A handle already stored stays until it expires (7 days). The names: .env, .env.*, *.env, *.pem, *.key, *.p12, *.pfx, *.jks, *.keystore, *.kdbx, *.asc, *.gpg, id_rsa*, id_dsa*, id_ecdsa*, id_ed25519*, credentials, credentials.*, *.credentials, .netrc, _netrc, .npmrc, .pypirc, secrets.*, secretsdata.json (podman's file secret driver keeps every secret's value there, in plain JSON), *.secret. The name rules (id_rsa* and the other key names, credentials, credentials.*, _netrc, secrets.*, secretsdata.json) do not apply to a .md note or to a folder name, so Secrets.md and a credentials/ folder are served; the extension and .env rules, dot names and the check of the name a link resolves to apply everywhere. Only .md, .markdown and .txt are indexed at all.

Clone this wiki locally