Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
80 lines (55 loc) · 1.86 KB

CONTRIBUTING.md

File metadata and controls

80 lines (55 loc) · 1.86 KB
Raw

Contributing

Development Setup

evalbox uses Nix for a reproducible dev environment:

nix develop

This provides the Rust toolchain, GCC (for test payloads), Python, and Go.

Building

cargo build

Testing

Fast checks (CI)

# Runs via nix: clippy, fmt, unit tests, docs
nix flake check

Or manually:

cargo clippy --all-targets -- -D warnings
cargo fmt --check
cargo test --lib
cargo doc --no-deps

Full test suite (requires user namespaces)

nix run .#test-all

Or manually:

cargo build -p evalbox-sandbox
cargo test -p evalbox-sandbox --test security_tests --ignored -- --test-threads=1

The security tests require Linux with user namespaces enabled. They compile C payloads that attempt real exploit techniques (CVEs, syscall abuse, escape vectors) and verify the sandbox blocks them.

Running specific test categories

cargo test -p evalbox-sandbox --test security_tests seccomp -- --ignored
cargo test -p evalbox-sandbox --test security_tests filesystem -- --ignored
cargo test -p evalbox-sandbox --test security_tests network -- --ignored
cargo test -p evalbox-sandbox --test security_tests cve -- --ignored
cargo test -p evalbox-sandbox --test security_tests resources -- --ignored

Project Structure

evalbox/                  # Public API, language runtimes
evalbox-sandbox/          # Sandbox orchestration, isolation
evalbox-sys/              # Low-level Linux syscall wrappers

See docs/ARCHITECTURE.md for details.

Pull Requests

  • Run nix flake check before submitting
  • Security-related changes should include tests in crates/evalbox-sandbox/tests/security/
  • Keep the seccomp whitelist minimal: don't add syscalls without justification

Security

Found a vulnerability? See SECURITY.md for reporting instructions.