{"id":38968752,"url":"https://github.com/aayushadhikari7/aegis","last_synced_at":"2026-01-18T17:00:47.101Z","repository":{"id":331938287,"uuid":"1132290501","full_name":"aayushadhikari7/aegis","owner":"aayushadhikari7","description":"A local-first WebAssembly sandbox runtime with capability-based security","archived":false,"fork":false,"pushed_at":"2026-01-11T19:21:46.000Z","size":131,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T20:32:23.921Z","etag":null,"topics":["capability-based-security","runtime","rust","sandbox","security","wasm","wasmtime","webassembly"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/aegis-wasm","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aayushadhikari7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-11T17:26:50.000Z","updated_at":"2026-01-11T19:21:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aayushadhikari7/aegis","commit_stats":null,"previous_names":["aayushadhikari7/aegis"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/aayushadhikari7/aegis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aayushadhikari7%2Faegis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aayushadhikari7%2Faegis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aayushadhikari7%2Faegis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aayushadhikari7%2Faegis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aayushadhikari7","download_url":"https://codeload.github.com/aayushadhikari7/aegis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aayushadhikari7%2Faegis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28543495,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T14:59:57.589Z","status":"ssl_error","status_checked_at":"2026-01-18T14:59:46.540Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["capability-based-security","runtime","rust","sandbox","security","wasm","wasmtime","webassembly"],"created_at":"2026-01-17T16:34:59.872Z","updated_at":"2026-01-18T17:00:47.075Z","avatar_url":"https://github.com/aayushadhikari7.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Aegis\n\n**Run untrusted WebAssembly code safely**\n\n[![Crates.io](https://img.shields.io/crates/v/aegis-wasm.svg)](https://crates.io/crates/aegis-wasm)\n[![docs.rs](https://img.shields.io/docsrs/aegis-wasm)](https://docs.rs/aegis-wasm)\n[![Rust](https://img.shields.io/badge/rust-1.85%2B-orange.svg)](https://www.rust-lang.org/)\n[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](#license)\n\n[Installation](#installation) | [CLI Usage](#cli-usage) | [Library Usage](#library-usage) | [Features](#features)\n\n\u003c/div\u003e\n\n---\n\n## What is Aegis?\n\nAegis is a **WebAssembly sandbox** that lets you run untrusted code without risk. The code:\n\n- Cannot access your filesystem (unless you allow it)\n- Cannot access the network (unless you allow it)\n- Cannot use unlimited memory (you set the limit)\n- Cannot run forever (you set the timeout)\n- Cannot crash your application\n\n**Use cases:** Plugin systems, serverless functions, game mods, user-submitted code, CI/CD isolation, safe scripting.\n\n---\n\n## Installation\n\n### CLI Tool\n\n```bash\ncargo install aegis-wasm-cli\n```\n\n### As a Library\n\n```bash\ncargo add aegis-wasm\n```\n\nOr add to your `Cargo.toml`:\n\n```toml\n[dependencies]\naegis-wasm = \"0.1\"\n```\n\n---\n\n## CLI Usage\n\n### Running WebAssembly\n\n```bash\n# Run a function with arguments\naegis run module.wasm --function add -- 5 10\n# Output: Result: 15\n\n# Run the default function (_start or main)\naegis run module.wasm\n\n# Run with resource limits\naegis run module.wasm --function process \\\n    --memory-limit 33554432 \\\n    --fuel-limit 1000000 \\\n    --timeout 10\n\n# Show execution metrics\naegis run module.wasm --function main --metrics\n```\n\n### Granting Permissions\n\nBy default, WASM code has **zero permissions**. You grant what it needs:\n\n```bash\n# Allow reading from /data directory\naegis run module.wasm --allow-read /data\n\n# Allow reading and writing to /tmp\naegis run module.wasm --allow-write /tmp\n\n# Allow logging output\naegis run module.wasm --allow-logging\n\n# Allow access to system clock\naegis run module.wasm --allow-clock\n\n# Combine permissions\naegis run module.wasm \\\n    --allow-read /data \\\n    --allow-write /tmp \\\n    --allow-logging\n```\n\n### Validating Modules\n\nCheck if a WASM file is valid before running:\n\n```bash\naegis validate module.wasm\n# Output: Module is valid\n\naegis validate corrupt.wasm\n# Output: Module is invalid: ...\n```\n\n### Inspecting Modules\n\nSee what a WASM module contains:\n\n```bash\n# Show everything\naegis inspect module.wasm --all\n\n# Show only exports (functions you can call)\naegis inspect module.wasm --exports\n\n# Show only imports (what the module needs)\naegis inspect module.wasm --imports\n```\n\nExample output:\n```\nModule: plugin.wasm\n\nExports (3):\n  add [function]: (i32, i32) -\u003e (i32)\n  multiply [function]: (i32, i32) -\u003e (i32)\n  memory [memory]: 1 pages\n\nImports (1):\n  env.log [function]: (i32) -\u003e ()\n```\n\n### Output Formats\n\n```bash\n# Human-readable (default)\naegis run module.wasm --function add -- 2 3\n\n# JSON output\naegis run module.wasm --function add --format json -- 2 3\n\n# Compact JSON (single line)\naegis run module.wasm --function add --format json-compact -- 2 3\n```\n\n### All CLI Options\n\n```\naegis run \u003cMODULE\u003e [OPTIONS] [-- ARGS...]\n\nOptions:\n  -e, --function \u003cNAME\u003e     Function to call (default: _start or main)\n  --memory-limit \u003cBYTES\u003e    Max memory in bytes (default: 64MB)\n  --fuel-limit \u003cUNITS\u003e      Max CPU fuel units (default: 1B)\n  --timeout \u003cSECONDS\u003e       Max execution time (default: 30s)\n  --allow-read \u003cPATH\u003e       Grant read access to path\n  --allow-write \u003cPATH\u003e      Grant read/write access to path\n  --allow-logging           Enable logging output\n  --allow-clock             Enable clock/time access\n  --metrics                 Show execution metrics\n  -f, --format \u003cFORMAT\u003e     Output format: human, json, json-compact\n  -v, --verbose             Increase verbosity (-v, -vv, -vvv)\n  -q, --quiet               Suppress non-essential output\n```\n\n---\n\n## Library Usage\n\n### Basic Example\n\n```rust\nuse aegis_wasm::prelude::*;\nuse std::time::Duration;\n\nfn main() -\u003e Result\u003c(), AegisError\u003e {\n    // Create a sandboxed runtime\n    let runtime = Aegis::builder()\n        .with_memory_limit(64 * 1024 * 1024)  // 64 MB max\n        .with_fuel_limit(1_000_000_000)        // 1 billion instructions max\n        .with_timeout(Duration::from_secs(30)) // 30 second timeout\n        .build()?;\n\n    // Load a WASM module\n    let module = runtime.load_file(\"plugin.wasm\")?;\n\n    // Create a sandbox and run code\n    let mut sandbox = runtime.sandbox().build()?;\n    sandbox.load_module(\u0026module)?;\n\n    // Call a function\n    let result: i32 = sandbox.call(\"add\", (2i32, 3i32))?;\n    println!(\"2 + 3 = {}\", result);\n\n    Ok(())\n}\n```\n\n### Loading WASM from Different Sources\n\n```rust\n// From a file\nlet module = runtime.load_file(\"plugin.wasm\")?;\n\n// From bytes (e.g., uploaded by user)\nlet wasm_bytes: Vec\u003cu8\u003e = receive_upload();\nlet module = runtime.load_bytes(\u0026wasm_bytes)?;\n\n// From WAT text format (useful for testing)\nlet module = runtime.load_wat(r#\"\n    (module\n        (func (export \"double\") (param i32) (result i32)\n            local.get 0\n            i32.const 2\n            i32.mul\n        )\n    )\n\"#)?;\n```\n\n### Granting Capabilities\n\n```rust\nuse aegis_wasm::prelude::*;\n\nlet runtime = Aegis::builder()\n    .with_memory_limit(64 * 1024 * 1024)\n    .with_fuel_limit(1_000_000_000)\n\n    // Allow reading from specific paths\n    .with_filesystem(FilesystemCapability::read_only(\u0026[\"/data\", \"/config\"]))\n\n    // Allow reading AND writing to specific paths\n    .with_filesystem(FilesystemCapability::read_write(\u0026[\"/tmp/sandbox\"]))\n\n    // Allow logging\n    .with_logging(LoggingCapability::all())\n\n    // Allow clock access\n    .with_clock(ClockCapability::monotonic_only())\n\n    .build()?;\n```\n\n### Registering Host Functions\n\nLet WASM code call your Rust functions:\n\n```rust\nlet mut sandbox = runtime.sandbox().build()?;\n\n// Register a function that WASM can call\nsandbox.register_func(\"env\", \"print_number\", |value: i32| {\n    println!(\"WASM says: {}\", value);\n})?;\n\nsandbox.register_func(\"env\", \"add_numbers\", |a: i32, b: i32| -\u003e i32 {\n    a + b\n})?;\n\nsandbox.load_module(\u0026module)?;\nsandbox.call_void(\"main\")?;\n```\n\n### Getting Execution Metrics\n\n```rust\nlet mut sandbox = runtime.sandbox().build()?;\nsandbox.load_module(\u0026module)?;\n\nlet result: i32 = sandbox.call(\"compute\", (input,))?;\n\n// Check how much resources were used\nlet metrics = sandbox.metrics();\nprintln!(\"Execution time: {:?}\", metrics.duration());\nprintln!(\"Fuel consumed: {}\", metrics.fuel_consumed);\nprintln!(\"Peak memory: {} bytes\", metrics.peak_memory);\n```\n\n### Handling Errors\n\n```rust\nuse aegis_wasm::prelude::*;\n\nmatch sandbox.call::\u003c(i32,), i32\u003e(\"process\", (input,)) {\n    Ok(result) =\u003e println!(\"Success: {}\", result),\n\n    Err(ExecutionError::OutOfFuel { consumed, limit }) =\u003e {\n        println!(\"Code used too much CPU: {} / {}\", consumed, limit);\n    }\n\n    Err(ExecutionError::Timeout(duration)) =\u003e {\n        println!(\"Code took too long: {:?}\", duration);\n    }\n\n    Err(ExecutionError::MemoryExceeded { used, limit }) =\u003e {\n        println!(\"Code used too much memory: {} / {}\", used, limit);\n    }\n\n    Err(ExecutionError::Trap(info)) =\u003e {\n        println!(\"Code crashed: {}\", info.message);\n    }\n\n    Err(e) =\u003e println!(\"Other error: {}\", e),\n}\n```\n\n### Reusing Sandboxes\n\n```rust\nlet mut sandbox = runtime.sandbox().build()?;\nsandbox.load_module(\u0026module)?;\n\n// Process multiple inputs with the same sandbox\nfor input in inputs {\n    let result: i32 = sandbox.call(\"process\", (input,))?;\n    println!(\"Result: {}\", result);\n}\n\n// Or reset and reuse\nsandbox.reset();\nsandbox.load_module(\u0026another_module)?;\n```\n\n---\n\n## Features\n\n### Resource Limits\n\n| Resource | What it Limits | Default |\n|----------|---------------|---------|\n| **Memory** | Max RAM the code can use | 64 MB |\n| **Fuel** | Max CPU instructions (deterministic) | 1 billion |\n| **Timeout** | Max wall-clock time | 30 seconds |\n| **Stack** | Max call stack depth | 512 KB |\n\n### Capabilities (Permissions)\n\n| Capability | What it Allows |\n|------------|---------------|\n| **Filesystem** | Read/write specific directories |\n| **Network** | Connect to specific hosts |\n| **Logging** | Print output |\n| **Clock** | Access system time |\n\n**Principle:** Code has **zero** permissions by default. You explicitly grant what it needs.\n\n### Supported Value Types\n\nThe CLI and library support these WASM types:\n\n| Type | Example |\n|------|---------|\n| `i32` | `42`, `-17` |\n| `i64` | `9999999999` |\n| `f32` | `3.14` |\n| `f64` | `3.141592653589793` |\n\n---\n\n## Security Model\n\n```\n┌─────────────────────────────────────┐\n│         Untrusted WASM Code         │\n├─────────────────────────────────────┤\n│  Capability Layer (Permissions)     │  ← Can it access this resource?\n├─────────────────────────────────────┤\n│  Resource Limiter (Memory/CPU)      │  ← Has it exceeded limits?\n├─────────────────────────────────────┤\n│  Wasmtime Sandbox (Memory Safety)   │  ← Is the code valid?\n└─────────────────────────────────────┘\n```\n\n**Guarantees:**\n1. Code cannot access anything you don't explicitly allow\n2. Code cannot use more resources than you allocate\n3. Code cannot crash your application\n4. Code cannot escape the sandbox\n\n---\n\n## Project Structure\n\n| Crate | Description |\n|-------|-------------|\n| [`aegis-wasm`](https://crates.io/crates/aegis-wasm) | Main library - start here |\n| [`aegis-wasm-cli`](https://crates.io/crates/aegis-wasm-cli) | Command-line tool |\n| [`aegis-core`](https://crates.io/crates/aegis-core) | Low-level engine and sandbox |\n| [`aegis-capability`](https://crates.io/crates/aegis-capability) | Permission system |\n| [`aegis-resource`](https://crates.io/crates/aegis-resource) | Memory/CPU/time limits |\n| [`aegis-host`](https://crates.io/crates/aegis-host) | Host function registration |\n| [`aegis-observe`](https://crates.io/crates/aegis-observe) | Metrics and monitoring |\n\n---\n\n## Requirements\n\n- **Rust 1.85+**\n- Works on Linux, macOS, and Windows\n\n---\n\n## License\n\nDual-licensed under:\n\n- [MIT License](LICENSE-MIT)\n- [Apache License 2.0](LICENSE-APACHE)\n\nChoose whichever you prefer.\n\n---\n\n## Contributing\n\nContributions welcome! Feel free to:\n\n- Open issues for bugs or feature requests\n- Submit pull requests\n- Improve documentation\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[GitHub](https://github.com/aayushadhikari7/aegis)** | **[Crates.io](https://crates.io/crates/aegis-wasm)** | **[Docs](https://docs.rs/aegis-wasm)** | **[Issues](https://github.com/aayushadhikari7/aegis/issues)**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faayushadhikari7%2Faegis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faayushadhikari7%2Faegis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faayushadhikari7%2Faegis/lists"}