{"id":22057135,"url":"https://github.com/capnspacehook/pandorasbox","last_synced_at":"2025-05-12T16:04:10.683Z","repository":{"id":47460280,"uuid":"211887010","full_name":"capnspacehook/pandorasbox","owner":"capnspacehook","description":"An intuitive and encrypted in-memory filesystem (VFS)","archived":false,"fork":false,"pushed_at":"2023-03-07T00:15:15.000Z","size":114,"stargazers_count":94,"open_issues_count":9,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-06-18T21:49:31.325Z","etag":null,"topics":["cryptography","filesystem","golang","information-security","infosec","vfs","virtual-file-system"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/capnspacehook.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-30T15:03:47.000Z","updated_at":"2024-05-20T21:16:32.000Z","dependencies_parsed_at":"2024-06-18T21:37:10.882Z","dependency_job_id":"2f97ce13-6839-49e5-a496-18c2f385ef68","html_url":"https://github.com/capnspacehook/pandorasbox","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capnspacehook%2Fpandorasbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capnspacehook%2Fpandorasbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capnspacehook%2Fpandorasbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capnspacehook%2Fpandorasbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/capnspacehook","download_url":"https://codeload.github.com/capnspacehook/pandorasbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227370654,"owners_count":17770706,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptography","filesystem","golang","information-security","infosec","vfs","virtual-file-system"],"created_at":"2024-11-30T16:16:24.450Z","updated_at":"2024-11-30T16:16:25.095Z","avatar_url":"https://github.com/capnspacehook.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pandoras Box\n\n[![GoDoc](https://godoc.org/github.com/capnspacehook/pandorasbox?status.svg)](https://godoc.org/github.com/capnspacehook/pandorasbox)\n\n`pandorasbox` is a Go package that allows for simple use of both a host's filesystem, and a virtual filesystem.\n\nThe design goal of Pandora's Box is to easily facilitate the use of a transparently-encrypted VFS (virtual filesystem), and the host's filesystem. It does this by providing functions and methods that operate and look the same as the Go standard library `os` package. If you want to interact with the VFS, pass in a path that starts with `vfs://`, and Pandora's Box will automatically use the VFS. Otherwise, the host's filesystem will be used.\n\n## Using Pandora's Box\n\nBecause Pandora's Box has the same interface as the `os` package, giving your code access to a VFS is often as easy as importing `pandorasbox` and replacing `os` calls to `box` calls. Take this super simple function that copies files: \n\n```go\nimport \"os\"\n\nfunc CopyFile(srcFile, dstFile string) error {\n    out, err := os.Create(dstFile)\n    defer out.Close()\n    if err != nil {\n      return err\n    }\n\n    in, err := os.Open(srcFile)\n    defer in.Close()\n    if err != nil {\n    return err\n    }\n\n    _, err = io.Copy(out, in)\n    if err != nil {\n    return err\n    }\n\n    return nil\n}\n```\n\nAll it takes to make this function VFS-friendly is switching from using `os` to `pandorasbox`:\n\n```go\nimport box \"github.com/capnspacehook/pandorasbox\"\n\nfunc init() {\n    box.InitGlobalBox()\n}\n\nfunc CopyFile(srcFile, dstFile string) error {\n    out, err := box.Create(dstFile)\n    if err != nil {\n      return err\n    }\n    defer out.Close()\n\n    in, err := box.Open(srcFile)\n    if err != nil {\n      return err\n    }\n    defer in.Close()\n\n    _, err = io.Copy(out, in)\n    if err != nil {\n      return err\n    }\n\n    return nil\n}\n```\n\n### Global vs. Local VFS\n\nYou probably noticed the call to `box.InitGlobalBox()` in the last example. This has to be called **before** the global VFS can be used. \nFor ease of use, Pandora's box provides a global `Box` that is easily accessible, but in some cases a local `Box` may be desired. If you don't wish to use the global `Box`, don't call `box.InitGlobalBox()`, instead create a locally scoped `Box` by calling `box.NewBox()`. This allows you to easily pass a `Box` into functions or methods or embed a `Box` in a struct.\n\n### `io/ioutil` and `path/filepath` Functions\n\nPandora's Box also provides helper functions that are identical to functions from `io/ioutil` and `path/filepath`. These should be used of the Go standard library packages when using a `Box`. The Pandora's Box versions are VFS-friendly, and will work seamlessly with a VFS, while the Go standard library packages will not. If you're using the global `Box`, the `io/ioutil` functions can be called from the main import: `github.com/capnspacehook/pandorasbox`. If you're using a local `Box`, you'll need to import `github.com/capnspacehook/pandorasbox/ioutil` and pass in your `Box` to those functions.\n\nExample (error handling omitted):\n\n```go \nimport (\n    box \"github.com/capnspacehook/pandorasbox\"\n    \"github.com/capnspacehook/pandorasbox/ioutil\"\n)\n\nfunc init() {\n    box.InitGlobalBox()\n}\n\nfunc WriteFileGlobalBox() {\n    box.WriteFile(\"vfs://file.txt\", []byte(\"Testing testing 1 2 3\"), 0644)\n    data, _ := box.ReadFile(\"vfs://file.txt\")\n    fmt.Println(string(data))\n}\n\nfunc WriteFileLocalBox() {\n    myBox := box.NewBox()\n\n    ioutil.WriteFile(myBox, \"vfs://file.txt\", []byte(\"Testing testing 1 2 3\"), 0644)\n    data, _ := ioutil.ReadFile(myBox, \"vfs://file.txt\")\n    fmt.Println(string(data))\n}\n```\n\n### Forcing use of Host FS/VFS\n\nIf for some reason you need to force the usage of either the host's filesystem or the VFS, Pandora's box has you covered. All of `pandorasbox`'s functions that are in also in `os` have 3 variants: normal, OS, and VFS. The normal variant auto-detirmines what to use based off the input path, as described earlier. The OS and VFS variants force the usage of a specific filesystem. For instance, `pandorasbox.Mkdir()` will auto-detirmine which filesystem to use, while `pandorasbox.OSMkdir()` will always use the host's filesystem, and `pandorasbox.VFSMkdir()` will always use the VFS. \n\n### Memory Safety\n\nAll files in the VFS are encrypted when not in use. When files from the VFS are opened, they are decrypted for the duration of the call that opened them. VFS files are then re-encrypted with a different random key when reading or writing from them is finished. That is, files in the VFS are only decrypted in memory for a brief time while the underlying data needs to be accessed. In other words, calling `Open()` on a VFS file **will not** decrypt it until `Close()` is called on it. It will only be decrypted in memory when it is internally opened by methods like `Read()`, `Write()`, `Truncate()`, etc. And it is immediately closed afterwards. So opening a VFS file and calling `Read()` on it 3 times will decrypt and re-encrypt it 3 times. This is to make sure data is encrypted in memory whenever possible.\n\nFor more information about the exact cryptographic code and algorithms used, refer to this repo: https://github.com/awnumar/memguard.\n\n## Acknowledgements\n\nThanks to AbsFs contributors for the amazing repos, 70% of the code is from repos from [this organization](https://github.com/absfs).\n\nTook some VFS specific tests from [this repo](https://github.com/blang/vfs), thanks to [blang](https://github.com/blang) for some good VFS tests.\n\nThanks to [awnumar](https://github.com/awnumar) for [memguard](https://github.com/awnumar/memguard), he created a great repo that is very easy to use safely.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapnspacehook%2Fpandorasbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcapnspacehook%2Fpandorasbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapnspacehook%2Fpandorasbox/lists"}