Expand description
Reads code of another language and says what it is certain to do:
read and understand.
A shell line can hand an interpreter code (python3 -c, node -e), and
an agent can write a script or run a snippet directly. The code does what
the shell commands that do the same would do, so what matters to a guard
is which files it deletes, writes, reads and moves, and what it runs. This
crate reads Python and JavaScript (Node, Bun and Deno) with their own
tree-sitter grammars and answers two questions of a piece of code:
- What is it certain to do?
readgives theActs the code makes, in the order it makes them: a delete, a write, a read, a move, a program started, an environment changed, each with the paths it names. What the reader cannot follow comes out as anAct::Unreadand the other acts of code it does not run as written (a call it has no row for, code loaded from the network), never left out. - Does it understand the code?
understandholds the code to a strict allow-list: a few plain statements whose every call, name and import is on a short list that only computes. Code outside it isUnderstanding::NotUnderstood, and a caller must not take “no acts” for “does nothing” for such code. The acts are kept whatever the code looks like; that it is understood is what makes finding none safe.
The reader judges nothing. Whether a delete of a path is risky is the
caller’s, which turns an act into what it already judges: a delete is
rm -rf PATH, a write a write to that path, a command line a script a
shell reads. It does no I/O and reads no environment: a path is the text
the code gives, never what is on disk, and the same code gives the same
answer on every machine. Code it cannot read is not understood, never
understood by default, and nothing it is given makes it panic or run past
its limits (see MAX_DEPTH, MAX_TREE_DEPTH and MAX_LEN).
use milo_guards_code::{read, understand, Act, Arg, Language, Understanding};
// A snippet that computes is understood, and does nothing to a file.
let code = "print(1 + 1)";
assert!(read(Language::Python, code).acts.is_empty());
assert_eq!(
understand(Language::Python, code),
Understanding::Understood { imports: true },
);
// A delete is an act with the path it names, kept whatever the code is.
let code = "import shutil\nshutil.rmtree('/home/me')";
let reading = read(Language::Python, code);
assert!(matches!(&reading.acts[..], [Act::Remove(Arg::Known(path))] if path == "/home/me"));
assert_eq!(understand(Language::Python, code), Understanding::NotUnderstood);
// A name only known when the code runs is an argument it does not know.
let reading = read(Language::JavaScript, "require('fs').rmSync(process.argv[1])");
assert!(matches!(&reading.acts[..], [Act::Remove(Arg::Unknown(_))]));Structs§
- Reading
- Everything one piece of code does.
Enums§
- Act
- What reading code found, in the order the code gives it.
- Arg
- One value the code hands to a call, as far as the reader knows it.
- Language
- The languages whose code is read.
- Understanding
- Whether the code is read whole (see
understand).
Constants§
- MAX_
DEPTH - How deep code may run code (
exec("…")insideexec("…")) before the reader stops following it. - MAX_LEN
- The longest code a caller should hand the reader: it reads in time that grows with the code, and the strings it works out from names are held to a few times this. A caller refuses longer code before it reads (the shell guard’s limit on a line is the same number).
- MAX_
TREE_ DEPTH - How deep a parse tree is walked before the code is too nested to read: walking deeper would risk overflowing the stack.
Functions§
- declares_
other_ encoding - Whether Python, when it reads
codeas bytes (from its input, or the bytes literal given toexec,evalorcompile), honours a coding declaration that decodes it to other text than the reader sees: it always reads the text as UTF-8. UTF-8 itself, and the ASCII-compatible encodings for a text that is all ASCII, read the same. Such code is not read: a caller that hands Python code its input does not take it for understood. - is_
data_ url - Whether the module
specifieris adata:URL, whose code runs where it is written, so no one reads it elsewhere. As the URL parser reads it, leading control characters and spaces and any tab or newline are dropped, and the scheme has no case. - is_
foreign_ module - Whether the module
specifieris loaded from outside the workspace: from the network (https:,http:) or a registry that downloads it (jsr:,npm:), or from a file that is not the workspace’s own (an absolute path, one in the home directory, afile:URL, one that goes up from where the code runs). A relative./x.jsand an installed package (fs,node:fs,lodash) are not. The reader finds code that loads one as anAct::Downloadedor anAct::Loads; this is the same answer for a specifier a caller meets outside the code, such as a--importoption. - read
- Read
codeinlanguage: what it does to files and what it runs. - understand
- Whether
codeis read whole: nothing in it is outside the allow-list. - understand_
python2 - Whether
codethat Python 2 runs is read whole: the same subset asunderstandforLanguage::Python, but with onlysysanderrnoto import.timeanditertoolsare shared files of Python 2’slib-dynload, which the import path reaches after the folder the code runs in, andbuiltinsis no built-in module there (it is__builtin__), so a file of that name in the folder would run.