OSS-CRS Documentation
Welcome to the OSS-CRS documentation. This guide covers everything from getting started to building your own Cyber Reasoning System.
For a quick introduction and setup instructions, see the project README.
Getting Started
| Topic | Description |
|---|---|
| Quick Start | Install prerequisites and run your first CRS in minutes |
| Setup Command | Configure system for enhanced resource management (cgroup-parent support) |
| CRS Development Guide | Build or integrate your own CRS into the OSS-CRS framework |
| CRS Registry | Browse available CRSs ready to use out of the box |
Configuration Reference
| Config File | Description |
|---|---|
CRS Compose (crs-compose.yaml) | Orchestration config — define CRS entries, resources, and ensemble campaigns |
CRS (crs.yaml) | Per-CRS config — prepare, build, and run phases for a single CRS |
Target Project (project.yaml) | Target project setup — OSS-Fuzz format and project.yaml schema |
LLM (litellm_config.yaml) | LiteLLM config file format for internal mode (provider routing, API keys, custom endpoints) |
Architecture & Design
| Document | Description |
|---|---|
| Architecture Overview | System design, component diagram, and lifecycle walkthrough |
| Parallel Builds and Runs | Build/run isolation with --build-id and --run-id |
| libCRS | CRS communication library — submit/fetch seeds, PoVs, and patches |
| LLM Providers | LiteLLM proxy setup for local and remote models |
Key Concepts
CRS Lifecycle
Every CRS campaign follows three phases managed by oss-crs:
- Prepare — Pull CRS source repositories and build Docker images (
oss-crs prepare) - Build Target — Compile the target project and run each CRS's target build pipeline (
oss-crs build-target). Pass--incremental-buildto create Docker snapshots for faster rebuilds. - Run — Launch all CRSs and shared infrastructure via Docker Compose (
oss-crs run). Pass--incremental-buildto use snapshot images for ephemeral rebuild containers.
CRS Isolation
Each CRS runs in its own containerized environment with strict resource boundaries:
- CPU — Pinned to specific cores via
cpuset - Memory — Hard memory cap via
mem_limit - LLM Budget — Per-CRS dollar-denominated limits enforced by LiteLLM
- Network — Private Docker network per CRS; shared network for infrastructure access
Run oss-crs setup to enable cgroup-parent mode for flexible resource sharing within each CRS.
Ensemble Campaigns
Multiple CRSs can be composed in a single crs-compose.yaml to run simultaneously. Each CRS operates independently with its own resource allocation, and results are aggregated automatically.
Contributing
See CONTRIBUTING.md for guidelines on contributing to OSS-CRS.