autOScan Engine

Shared grading engine for C lab submission analysis

Core engine and cloud grading service used by autOScan apps and tools

---

Cloud Service

This repo also ships the cloud grading service used by the Web Agent. For service setup, deployment, environment variables, and HTTP API details, see CLOUD_SETUP.md.

Features

• Submission discovery from root folders
• Parallel compilation pipeline with worker controls
• Single-process execution with args/stdin/test-case support
• Multi-process execution: spawns every configured executable concurrently and returns one buffered result per scenario
• Always-on Valgrind validation for leaks, reachable memory, memory errors, and open file descriptors
• Sandboxed environment for grading untrusted submissions
• Interactive terminal sessions: up to 4 shell panes per submission sharing one sandbox, so processes from different panes can IPC
• Banned function scanning with file/line/column/snippet evidence
• Similarity analysis via C token fingerprinting
• AI-pattern detection against dictionary fingerprints
• Policy parsing and validation helpers
• Public Go facade package (pkg/engine) for autOScan apps/tools

---

Installation

Requires: Go 1.25+, gcc, valgrind

go build ./...
go test ./...   # tests live in tests/ and need no sandbox

Usage

As a Go Module

go get github.com/autoscan-lab/autoscan-engine@latest

import (
  "context"

  engine "github.com/autoscan-lab/autoscan-engine/pkg/engine"
  "github.com/autoscan-lab/autoscan-engine/pkg/policy"
)

p, _ := policy.Load("/path/to/policy.yaml")
runner, _ := engine.NewRunner(p, engine.WithWorkers(4))
report, _ := runner.Run(context.Background(), "/path/to/submissions", engine.RunnerCallbacks{})
_ = report

Multi-process execution

For policies with run.multi_process.enabled: true, use the executor directly:

executor := engine.NewExecutorWithOptions(p, binaryDir, false)
result := executor.ExecuteMultiProcess(ctx, submission)
// or, with a scenario override:
result = executor.ExecuteMultiProcessScenario(ctx, submission, scenario)

Every executable in run.multi_process.executables is launched concurrently. The call blocks until each process exits (or ctx is cancelled) and returns one *domain.MultiProcessResult with buffered stdout/stderr per process.

Package Layout

autOScan-engine/
├── pkg/engine/            # Public facade API
├── pkg/domain/            # Shared engine models/results
├── pkg/policy/            # Policy models/loading/helpers
├── pkg/ai/                # AI dictionary parsing/validation
├── internal/engine/       # Engine internals (compile/run/sandbox)
├── internal/terminal/     # Interactive terminal sessions (pane-host, tokens)
└── tests/                 # Black-box tests over the exported surfaces

---

Sandboxing

Student submissions are untrusted code, so the engine compiles and runs each one inside an isolated sandbox.

A submission that crashes or runs out of memory is reported as crashed, not passed.

---

Runtime Paths

Engine runtime behavior is compatible with:

~/.config/autoscan/
├── libraries/
├── test_files/
├── expected_outputs/
└── banned.yaml

When embedding the engine, set Policy.ConfigDir or load with policy.LoadWithGlobalsFromConfigDir.

For HTTP service setup, required environment variables, and Fly deployment, see CLOUD_SETUP.md.

---

License

MIT