Skip to main content

chainguard_sandbox/
files.rs

1//! Reading and writing a sandbox's filesystem: `sbx.files`.
2
3use std::path::Path;
4use std::sync::Arc;
5use std::time::{Duration, SystemTime, UNIX_EPOCH};
6
7use crate::sandbox::{Inner, guest_path, wrap};
8use crate::scripts::*;
9use crate::workspaces::{self, ExecOptions};
10use crate::{Error, Result};
11
12crate::opaque_debug!(Files);
13
14/// "file", "dir" or "symlink".
15#[derive(Debug, Clone, Copy, PartialEq, Eq)]
16pub enum FileType {
17    File,
18    Dir,
19    Symlink,
20}
21
22impl FileType {
23    /// "file", "dir" or "symlink", as the other SDKs spell it.
24    pub fn as_str(&self) -> &'static str {
25        match self {
26            FileType::File => "file",
27            FileType::Dir => "dir",
28            FileType::Symlink => "symlink",
29        }
30    }
31}
32
33impl std::fmt::Display for FileType {
34    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
35        f.write_str(self.as_str())
36    }
37}
38
39/// Describes a written file.
40#[derive(Debug, Clone, PartialEq, Eq)]
41pub struct WriteInfo {
42    pub name: String,
43    pub path: String,
44    pub file_type: FileType,
45}
46
47/// Describes a file, directory or symlink.
48#[derive(Debug, Clone, PartialEq, Eq)]
49pub struct EntryInfo {
50    pub name: String,
51    pub path: String,
52    pub file_type: FileType,
53    pub size: i64,
54    /// Permission bits, e.g. 0o644.
55    pub mode: u32,
56    /// e.g. "rwxr-xr-x".
57    pub permissions: String,
58    pub owner: String,
59    pub group: String,
60    pub modified_time: SystemTime,
61    pub symlink_target: String,
62}
63
64/// One file for [`Files::write_files`].
65#[derive(Debug, Clone, Default)]
66pub struct WriteEntry {
67    pub path: String,
68    pub data: Vec<u8>,
69    /// Permission bits; 0 means 0o644.
70    pub mode: u32,
71}
72
73/// Reads and writes a sandbox's filesystem. Relative paths resolve against /work. Every call is a
74/// small shell program run in the sandbox, so each costs one round trip (about 0.15 s once the
75/// sandbox is warm); batch with [`write_files`](Files::write_files) and
76/// [`upload_dir`](Files::upload_dir) where you can.
77#[derive(Clone)]
78pub struct Files {
79    sb: Arc<Inner>,
80}
81
82struct ScriptOut {
83    stdout: Vec<u8>,
84    code: i32,
85    stderr: Vec<u8>,
86}
87
88/// Maps a script's reserved exit codes to typed errors.
89fn script_error(code: i32, p: &str, stderr: &[u8]) -> Error {
90    match code {
91        EXIT_NOT_FOUND => Error::NotFound {
92            what: "path".into(),
93            name: p.into(),
94        },
95        EXIT_IS_DIR => Error::InvalidPath {
96            path: p.into(),
97            reason: "is a directory".into(),
98        },
99        EXIT_NOT_DIR => Error::InvalidPath {
100            path: p.into(),
101            reason: "not a directory".into(),
102        },
103        _ => {
104            let msg = String::from_utf8_lossy(stderr).trim().to_string();
105            let msg = if msg.is_empty() {
106                format!("exit {code}")
107            } else {
108                msg
109            };
110            Error::other(format!("sandbox: {p}: {msg}"))
111        }
112    }
113}
114
115impl Files {
116    pub(crate) fn new(sb: Arc<Inner>) -> Self {
117        Files { sb }
118    }
119
120    /// Runs a script with args and stdin. A transport error is the error; a non-zero exit is in
121    /// the result.
122    async fn script(&self, script: &str, stdin: Vec<u8>, args: &[&str]) -> Result<ScriptOut> {
123        let (mut out, mut err) = (Vec::new(), Vec::new());
124        let mut argv = vec!["sh".to_string(), "-c".into(), script.into(), "_".into()];
125        argv.extend(args.iter().map(|a| a.to_string()));
126        let res = {
127            let mut fo = |b: &[u8]| out.extend_from_slice(b);
128            let mut fe = |b: &[u8]| err.extend_from_slice(b);
129            let o = ExecOptions {
130                no_dir: true,
131                stdin,
132                stdout: Some(&mut fo),
133                stderr: Some(&mut fe),
134                ..Default::default()
135            };
136            self.sb
137                .client
138                .exec(&self.sb.name, &argv, o)
139                .await
140                .map_err(wrap)?
141        };
142        Ok(ScriptOut {
143            stdout: out,
144            code: res.exit_code,
145            stderr: err,
146        })
147    }
148
149    async fn checked(
150        &self,
151        script: &str,
152        stdin: Vec<u8>,
153        args: &[&str],
154        p: &str,
155    ) -> Result<Vec<u8>> {
156        let r = self.script(script, stdin, args).await?;
157        if r.code != 0 {
158            return Err(script_error(r.code, p, &r.stderr));
159        }
160        Ok(r.stdout)
161    }
162
163    /// A file's contents. A missing file is [`Error::NotFound`].
164    pub async fn read(&self, p: &str) -> Result<Vec<u8>> {
165        let gp = guest_path(p);
166        self.checked(READ_SCRIPT, Vec::new(), &[&gp], &gp).await
167    }
168
169    /// A file's contents as a string (invalid UTF-8 is replaced).
170    pub async fn read_text(&self, p: &str) -> Result<String> {
171        let b = self.read(p).await?;
172        Ok(String::from_utf8(b)
173            .unwrap_or_else(|e| String::from_utf8_lossy(e.as_bytes()).into_owned()))
174    }
175
176    /// Creates or replaces a file (atomically, mode 0644), creating parent directories. Any size
177    /// works: data over 15 MiB is staged in pieces.
178    pub async fn write(&self, p: &str, data: impl Into<Vec<u8>>) -> Result<WriteInfo> {
179        self.write_mode(p, data.into(), 0o644).await
180    }
181
182    async fn write_mode(&self, p: &str, data: Vec<u8>, mode: u32) -> Result<WriteInfo> {
183        let gp = guest_path(p);
184        if data.len() <= MAX_STDIN_PER_EXEC {
185            match self
186                .sb
187                .client
188                .write_file(&self.sb.name, &gp, data, mode)
189                .await
190            {
191                Err(Error::Exit { exit_code: 21, .. }) => {
192                    return Err(Error::InvalidPath {
193                        path: gp,
194                        reason: "is a directory".into(),
195                    });
196                }
197                Err(e) => return Err(wrap(e)),
198                Ok(()) => {}
199            }
200        } else {
201            let tmp = self.stage(&data).await?;
202            self.checked(
203                FINISH_SCRIPT,
204                Vec::new(),
205                &[&tmp, &gp, &format!("{:o}", mode & 0o777)],
206                &gp,
207            )
208            .await?;
209        }
210        Ok(WriteInfo {
211            name: base(&gp),
212            path: gp,
213            file_type: FileType::File,
214        })
215    }
216
217    /// Uploads data to a temporary file in the sandbox, in pieces under the exec stdin limit, and
218    /// returns its path.
219    async fn stage(&self, data: &[u8]) -> Result<String> {
220        let tmp = format!("{STATE_DIR}/upload/{}", crate::workspaces_random_id());
221        let mut off = 0;
222        loop {
223            let end = (off + MAX_STDIN_PER_EXEC).min(data.len());
224            let mode = if off == 0 { "trunc" } else { "append" };
225            self.checked(APPEND_SCRIPT, data[off..end].to_vec(), &[&tmp, mode], &tmp)
226                .await?;
227            if end == data.len() {
228                return Ok(tmp);
229            }
230            off = end;
231        }
232    }
233
234    /// Extracts a gzip'd tar into dir in the sandbox.
235    async fn untar(&self, tgz: Vec<u8>, dir: &str) -> Result<()> {
236        if tgz.len() > MAX_STDIN_PER_EXEC {
237            let tmp = self.stage(&tgz).await?;
238            self.checked(UNTAR_SCRIPT, Vec::new(), &[&tmp, dir], dir)
239                .await?;
240        } else {
241            self.checked(UNTAR_SCRIPT, tgz, &["-", dir], dir).await?;
242        }
243        Ok(())
244    }
245
246    /// Writes several files in one upload (one tar), creating parent directories. Files are
247    /// owned by root.
248    pub async fn write_files(&self, files: Vec<WriteEntry>) -> Result<Vec<WriteInfo>> {
249        let now = SystemTime::now()
250            .duration_since(UNIX_EPOCH)
251            .unwrap_or_default()
252            .as_secs();
253        let zw = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::default());
254        let mut tw = tar::Builder::new(zw);
255        let mut infos = Vec::with_capacity(files.len());
256        let io = |e| Error::io("building the upload", e);
257        for e in &files {
258            let gp = guest_path(&e.path);
259            if gp == "/" {
260                return Err(Error::other(format!(
261                    "sandbox: invalid file path {:?}",
262                    e.path
263                )));
264            }
265            let mode = if e.mode & 0o777 == 0 {
266                0o644
267            } else {
268                e.mode & 0o777
269            };
270            let mut h = tar::Header::new_gnu();
271            h.set_mode(mode);
272            h.set_size(e.data.len() as u64);
273            h.set_mtime(now);
274            h.set_entry_type(tar::EntryType::Regular);
275            tw.append_data(&mut h, gp.trim_start_matches('/'), e.data.as_slice())
276                .map_err(io)?;
277            infos.push(WriteInfo {
278                name: base(&gp),
279                path: gp,
280                file_type: FileType::File,
281            });
282        }
283        let zw = tw.into_inner().map_err(io)?;
284        let tgz = zw.finish().map_err(io)?;
285        self.untar(tgz, "/").await?;
286        Ok(infos)
287    }
288
289    /// The entries of a directory (one level), sorted by name.
290    pub async fn list(&self, p: &str) -> Result<Vec<EntryInfo>> {
291        let gp = guest_path(p);
292        let out = self
293            .checked(LIST_DIR_SCRIPT, Vec::new(), &[&gp], &gp)
294            .await?;
295        parse_entries(&out, &gp)
296    }
297
298    /// Whether a path exists (a dangling symlink counts).
299    pub async fn exists(&self, p: &str) -> Result<bool> {
300        Ok(self
301            .script(EXISTS_SCRIPT, Vec::new(), &[&guest_path(p)])
302            .await?
303            .code
304            == 0)
305    }
306
307    /// Describes a path without following a final symlink.
308    pub async fn get_info(&self, p: &str) -> Result<EntryInfo> {
309        let gp = guest_path(p);
310        let out = self.checked(INFO_SCRIPT, Vec::new(), &[&gp], &gp).await?;
311        one_entry(&out, &gp)
312    }
313
314    /// Creates a directory and its parents. Returns false if it already existed.
315    pub async fn make_dir(&self, p: &str) -> Result<bool> {
316        let gp = guest_path(p);
317        let out = self
318            .checked(MAKE_DIR_SCRIPT, Vec::new(), &[&gp], &gp)
319            .await?;
320        Ok(String::from_utf8_lossy(&out).trim() == "1")
321    }
322
323    /// Deletes a file or a directory tree. A missing path is [`Error::NotFound`].
324    pub async fn remove(&self, p: &str) -> Result<()> {
325        let gp = guest_path(p);
326        self.checked(REMOVE_SCRIPT, Vec::new(), &[&gp], &gp).await?;
327        Ok(())
328    }
329
330    /// Moves a file or directory, creating the destination's parents, and describes it at its new
331    /// path.
332    pub async fn rename(&self, old_path: &str, new_path: &str) -> Result<EntryInfo> {
333        let (op, np) = (guest_path(old_path), guest_path(new_path));
334        let out = self
335            .checked(RENAME_SCRIPT, Vec::new(), &[&op, &np], &op)
336            .await?;
337        one_entry(&out, &np)
338    }
339
340    /// Copies a local file into the sandbox, keeping its permission bits.
341    pub async fn upload(&self, local_path: impl AsRef<Path>, remote_path: &str) -> Result<()> {
342        let lp = local_path.as_ref();
343        let ctx = || lp.display().to_string();
344        let md = tokio::fs::metadata(lp)
345            .await
346            .map_err(|e| Error::io(ctx(), e))?;
347        let data = tokio::fs::read(lp).await.map_err(|e| Error::io(ctx(), e))?;
348        self.write_mode(remote_path, data, perm_bits(&md)).await?;
349        Ok(())
350    }
351
352    /// Copies a file from the sandbox to `local_path`, creating local parent directories.
353    pub async fn download(&self, remote_path: &str, local_path: impl AsRef<Path>) -> Result<()> {
354        let data = self.read(remote_path).await?;
355        let lp = local_path.as_ref();
356        if let Some(d) = lp.parent().filter(|d| !d.as_os_str().is_empty()) {
357            tokio::fs::create_dir_all(d)
358                .await
359                .map_err(|e| Error::io(d.display().to_string(), e))?;
360        }
361        tokio::fs::write(lp, data)
362            .await
363            .map_err(|e| Error::io(lp.display().to_string(), e))
364    }
365
366    /// Copies a local directory tree into `remote_dir` (created if missing), as one tar. Symlinks
367    /// are copied as links; sockets and devices are skipped. Files are owned by root.
368    pub async fn upload_dir(&self, local_dir: impl AsRef<Path>, remote_dir: &str) -> Result<()> {
369        let dir = local_dir.as_ref().to_path_buf();
370        let tgz = tokio::task::spawn_blocking(move || workspaces::tar_gz_dir(&dir, None))
371            .await
372            .map_err(|e| Error::other(format!("sandbox: building the upload: {e}")))??;
373        self.untar(tgz, &guest_path(remote_dir)).await
374    }
375
376    /// Copies a directory tree from the sandbox into `local_dir` (created if missing). Nothing is
377    /// written outside `local_dir`: absolute names and ".." are refused, an entry is never written
378    /// through a symbolic link, and a link that leads outside `local_dir` (directly or through
379    /// other links) is removed and reported as an error.
380    pub async fn download_dir(&self, remote_dir: &str, local_dir: impl AsRef<Path>) -> Result<()> {
381        let gp = guest_path(remote_dir);
382        let out = self.checked(TAR_SCRIPT, Vec::new(), &[&gp], &gp).await?;
383        let dir = local_dir.as_ref().to_path_buf();
384        tokio::task::spawn_blocking(move || crate::untar::extract_tar_gz(&out, &dir))
385            .await
386            .map_err(|e| Error::other(format!("sandbox: extracting: {e}")))?
387    }
388}
389
390#[cfg(unix)]
391fn perm_bits(md: &std::fs::Metadata) -> u32 {
392    use std::os::unix::fs::PermissionsExt;
393    md.permissions().mode() & 0o777
394}
395
396#[cfg(not(unix))]
397fn perm_bits(md: &std::fs::Metadata) -> u32 {
398    if md.permissions().readonly() {
399        0o444
400    } else {
401        0o644
402    }
403}
404
405fn base(p: &str) -> String {
406    let t = p.trim_end_matches('/');
407    if t.is_empty() {
408        return "/".into();
409    }
410    t.rsplit('/').next().unwrap_or(t).to_string()
411}
412
413fn one_entry(out: &[u8], p: &str) -> Result<EntryInfo> {
414    match parse_entries(out, "") {
415        Ok(mut es) if es.len() == 1 => Ok(es.remove(0)),
416        _ => Err(Error::other(format!(
417            "sandbox: unexpected stat output for {p}: {:?}",
418            String::from_utf8_lossy(out)
419        ))),
420    }
421}
422
423/// Decodes stat lines; `base_dir`, if set, is joined with the name.
424pub(crate) fn parse_entries(out: &[u8], base_dir: &str) -> Result<Vec<EntryInfo>> {
425    let text = String::from_utf8_lossy(out);
426    let mut es = Vec::new();
427    for line in text.trim_end_matches('\n').split('\n') {
428        if line.is_empty() {
429            continue;
430        }
431        let malformed = || Error::other(format!("sandbox: malformed entry {line:?}"));
432        let f: Vec<&str> = line.splitn(4, '\t').collect();
433        if f.len() != 4 {
434            return Err(malformed());
435        }
436        let st: Vec<&str> = f[1].split_whitespace().collect();
437        if st.len() != 5 {
438            return Err(malformed());
439        }
440        let p = if base_dir.is_empty() {
441            f[3].to_string()
442        } else {
443            workspaces::guest_path(&format!("{base_dir}/{}", f[3]))
444        };
445        let mode = u32::from_str_radix(st[1], 8).unwrap_or(0) & 0o777;
446        let file_type = match f[0] {
447            "dir" => FileType::Dir,
448            "symlink" => FileType::Symlink,
449            _ => FileType::File,
450        };
451        let mtime: i64 = st[4].parse().unwrap_or(0);
452        es.push(EntryInfo {
453            name: base(&p),
454            path: p,
455            file_type,
456            size: st[0].parse().unwrap_or(0),
457            mode,
458            permissions: permissions(mode),
459            owner: st[2].into(),
460            group: st[3].into(),
461            modified_time: UNIX_EPOCH + Duration::from_secs(mtime.max(0) as u64),
462            symlink_target: f[2].into(),
463        });
464    }
465    Ok(es)
466}
467
468/// "rwxr-xr-x" for 0o755.
469fn permissions(mode: u32) -> String {
470    let mut s = String::with_capacity(9);
471    for shift in [6, 3, 0] {
472        let b = (mode >> shift) & 7;
473        s.push(if b & 4 != 0 { 'r' } else { '-' });
474        s.push(if b & 2 != 0 { 'w' } else { '-' });
475        s.push(if b & 1 != 0 { 'x' } else { '-' });
476    }
477    s
478}
479
480#[cfg(test)]
481mod tests {
482    use super::*;
483
484    #[test]
485    fn parse_entries_vectors() {
486        let out = b"file\t12 644 root root 1700000000\t\ta.txt\ndir\t4096 755 root root 1700000001\t\tsub\nsymlink\t3 777 root root 1700000002\ta.txt\tlink\n";
487        let es = parse_entries(out, "/work").unwrap();
488        assert_eq!(es.len(), 3);
489        assert_eq!(
490            (es[0].path.as_str(), es[0].size, es[0].permissions.as_str()),
491            ("/work/a.txt", 12, "rw-r--r--")
492        );
493        assert_eq!(
494            (es[1].file_type, es[1].name.as_str()),
495            (FileType::Dir, "sub")
496        );
497        assert_eq!(
498            (es[2].file_type, es[2].symlink_target.as_str()),
499            (FileType::Symlink, "a.txt")
500        );
501        assert!(parse_entries(b"file\tbad\t\tx\n", "").is_err());
502    }
503
504    #[test]
505    fn guest_paths() {
506        assert_eq!(guest_path(""), "/work");
507        assert_eq!(guest_path("a/b"), "/work/a/b");
508        assert_eq!(guest_path("/tmp/../etc"), "/etc");
509        assert_eq!(guest_path("./x"), "/work/x");
510    }
511
512    #[test]
513    fn write_files_tar_is_readable() {
514        // The same archive layout write_files sends, read back.
515        let zw = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::default());
516        let mut tw = tar::Builder::new(zw);
517        let mut h = tar::Header::new_gnu();
518        h.set_mode(0o600);
519        h.set_size(2);
520        tw.append_data(
521            &mut h,
522            "work/very/".to_string() + &"long/".repeat(40) + "f",
523            &b"hi"[..],
524        )
525        .unwrap();
526        let tgz = tw.into_inner().unwrap().finish().unwrap();
527        let mut ar = tar::Archive::new(flate2::read::GzDecoder::new(&tgz[..]));
528        let e = ar.entries().unwrap().next().unwrap().unwrap();
529        assert!(e.path().unwrap().to_string_lossy().ends_with("long/f"));
530    }
531}