Skip to main content

Crate milo_guards_code

Crate milo_guards_code 

Source
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? read gives the Acts 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 an Act::Unread and 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? understand holds 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 is Understanding::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("…") inside exec("…")) 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 code as bytes (from its input, or the bytes literal given to exec, eval or compile), 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 specifier is a data: 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 specifier is 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, a file: URL, one that goes up from where the code runs). A relative ./x.js and an installed package (fs, node:fs, lodash) are not. The reader finds code that loads one as an Act::Downloaded or an Act::Loads; this is the same answer for a specifier a caller meets outside the code, such as a --import option.
read
Read code in language: what it does to files and what it runs.
understand
Whether code is read whole: nothing in it is outside the allow-list.
understand_python2
Whether code that Python 2 runs is read whole: the same subset as understand for Language::Python, but with only sys and errno to import. time and itertools are shared files of Python 2’s lib-dynload, which the import path reaches after the folder the code runs in, and builtins is no built-in module there (it is __builtin__), so a file of that name in the folder would run.