Repository navigation
Security 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 *
|
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).
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(featurebundled, 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 theToJson/FromJsontraits. - 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/):ReadDirectoryChangesWon Windows, inotify on Linux and FSEvents on macOS (per-file events, one stream per root on a thread running its own CFRunLoop;MustScanSubDirsand the dropped-event flags walk the root), all through ownedexterndeclarations. - Byte scans (
src/scan.rs): SSE2, AVX2 (detected at run time) and NEON versions ofmemchrand the JSON string scan, each tested against its scalar version.unsafeis denied crate-wide and allowed only inplatform(including the child-process priority and kill calls of the code indexer),scanandembed::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.
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.
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.
atlas is licensed under the Apache License 2.0. This wiki is generated from the repository's wiki/ folder at each release; edits made here are replaced by the next release. Report vulnerabilities privately, as SECURITY.md describes.
Getting started
What it saves
Reference
- Tools reference
- Code index
- Semantic search
- Identifiers and freshness
- Memory store and hooks
- Memory tree
- Memory and rule files
- Orchestration
- Discussions
- Project tracking
- Generated indices
- Cross-vault links
Internals