Skip to content

Commit e6ece0f

Browse files
nschaettinschaetti
committed
feat(core): add kernel-enforced agent runtime with policy, audit, and docs
Introduce a syscall-based kernel (fs/proc/net) with deny-by-default policy evaluation, SQLite-backed audit logging, and TFPv1 local agent-op enforcement returning structured OS-like errors (e.g. EACCES). Migrate tooling access through kernel wrappers, add CI host-access lint and Rust coverage/Codecov integration, and publish full user/dev/ops documentation
1 parent 1f3e345 commit e6ece0f

54 files changed

Lines changed: 6093 additions & 110 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/rust.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ on:
88

99
env:
1010
CARGO_TERM_COLOR: always
11+
COVERAGE_MIN_LINES: "30"
1112

1213
jobs:
1314
build:
@@ -16,7 +17,34 @@ jobs:
1617

1718
steps:
1819
- uses: actions/checkout@v4
20+
- name: Tooling host-access lint
21+
run: bash scripts/check_tooling_no_direct_host_access.sh
1922
- name: Build
2023
run: cargo build --verbose
2124
- name: Run tests
2225
run: cargo test --verbose
26+
27+
coverage:
28+
runs-on: ubuntu-latest
29+
permissions:
30+
contents: read
31+
id-token: write
32+
33+
steps:
34+
- uses: actions/checkout@v4
35+
- name: Install cargo-llvm-cov
36+
uses: taiki-e/install-action@cargo-llvm-cov
37+
- name: Generate coverage (lcov + threshold)
38+
run: cargo llvm-cov --workspace --lcov --output-path lcov.info --fail-under-lines $COVERAGE_MIN_LINES
39+
- name: Upload coverage to Codecov
40+
uses: codecov/codecov-action@v5
41+
with:
42+
files: lcov.info
43+
use_oidc: true
44+
fail_ci_if_error: true
45+
verbose: true
46+
- name: Upload coverage report artifact
47+
uses: actions/upload-artifact@v4
48+
with:
49+
name: rust-coverage-lcov
50+
path: lcov.info

‎Cargo.toml‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ serde = { version = "1.0", features = ["derive"] }
1313
serde_yaml = "0.9"
1414
axum = { version = "0.8", features = ["json", "macros"] }
1515
tokio = { version = "1.44", features = ["macros", "rt-multi-thread"] }
16-
rustls = "0.23"
16+
rustls = { version = "0.23", features = ["ring"] }
1717
axum-server = { version = "0.7", features = ["tls-rustls"] }
1818
time = { version = "0.3", features = ["formatting", "parsing"] }
1919
tokio-rustls = "0.26"
@@ -23,3 +23,8 @@ hyper-util = { version = "0.1", features = ["server", "http1", "http2", "tokio",
2323
x509-parser = "0.16"
2424
tracing = "0.1"
2525
tracing-subscriber = { version = "0.3", features = ["fmt", "json"] }
26+
rusqlite = { version = "0.32", features = ["bundled"] }
27+
28+
[dev-dependencies]
29+
rcgen = "0.13"
30+
tempfile = "3.13"

‎README.md‎

Lines changed: 73 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,80 @@
11
# TuringFlow
22

3+
[![Rust CI](https://github.com/nschaetti/TuringFlow/actions/workflows/rust.yml/badge.svg)](https://github.com/nschaetti/TuringFlow/actions/workflows/rust.yml)
4+
[![codecov](https://codecov.io/gh/nschaetti/TuringFlow/branch/main/graph/badge.svg)](https://codecov.io/gh/nschaetti/TuringFlow)
5+
36
<p align="center">
47
<picture>
58
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/nschaetti/TuringFlow/refs/heads/main/images/turingflow_banner.png">
6-
<img src="https://raw.githubusercontent.com/nschaetti/TuringFlow/refs/heads/main/images/turingflow_banner.png" alt="OpenClaw" width="500">
9+
<img src="https://raw.githubusercontent.com/nschaetti/TuringFlow/refs/heads/main/images/turingflow_banner.png" alt="TuringFlow" width="500">
710
</picture>
811
</p>
12+
13+
TuringFlow is an agent transport + runtime foundation with:
14+
15+
- a secure `TFPv1` daemon (`turingflowd`) over mTLS,
16+
- registry/routing/ack/dedupe persistence in SQLite,
17+
- a kernel-style access control model for agent operations,
18+
- CLI tooling for model interactions.
19+
20+
## Current scope
21+
22+
- `turingflowd` API endpoints: health, register, heartbeat, resolve, send, ack.
23+
- Config-driven runtime:
24+
- `config/turingflowd.yaml`
25+
- `config/kingdoms.yaml`
26+
- `config/policies.yaml`
27+
- Kernel syscalls and policy engine:
28+
- `fs.list/read/write`
29+
- `proc.exec`
30+
- `net.http`
31+
- deny-by-default + audit log in SQLite.
32+
33+
## Quick start
34+
35+
Build:
36+
37+
```bash
38+
cargo build
39+
```
40+
41+
Show CLI help:
42+
43+
```bash
44+
cargo run --bin turingflow -- --help
45+
```
46+
47+
Show daemon help:
48+
49+
```bash
50+
cargo run --bin turingflowd -- --help
51+
```
52+
53+
Run daemon (requires valid cert files in config):
54+
55+
```bash
56+
cargo run --bin turingflowd -- --config config/turingflowd.yaml --kingdoms-config config/kingdoms.yaml
57+
```
58+
59+
## Documentation
60+
61+
- User docs: `docs/user/quickstart.md`
62+
- Developer docs: `docs/dev/architecture.md`
63+
- Operations docs: `docs/ops/runbook.md`
64+
- Full index: `docs/README.md`
65+
66+
## Testing
67+
68+
Run all key test suites:
69+
70+
```bash
71+
cargo test --lib
72+
cargo test --test tfpv1_integration
73+
cargo test --test turingflowd_http_integration
74+
```
75+
76+
Tooling security lint (no direct host access in tools perimeter):
77+
78+
```bash
79+
bash scripts/check_tooling_no_direct_host_access.sh
80+
```

‎config/kingdoms.yaml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
version: 1
2+
3+
kingdoms:
4+
- id: kingdom-main
5+
enabled: true
6+
quotas:
7+
max_agents_per_node: 256
8+
max_lease_ttl_ms: 300000
9+
max_message_ttl_ms: 60000
10+
max_payload_bytes: 262144

‎config/policies.yaml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
version: 1
2+
3+
defaults:
4+
decision: deny
5+
6+
principals:
7+
- id: "agent:planner@node-a.local"
8+
rules:
9+
- id: "allow-read-workspace"
10+
effect: allow
11+
syscall: "fs.read"
12+
resource:
13+
path_prefix:
14+
- "/workspace/project"
15+
- id: "allow-list-workspace"
16+
effect: allow
17+
syscall: "fs.list"
18+
resource:
19+
path_prefix:
20+
- "/workspace/project"

‎config/turingflowd.yaml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
version: 1
2+
3+
server:
4+
listen: 0.0.0.0:8443
5+
node_id: turingflowd
6+
7+
tls:
8+
server_cert: certs/turingflowd.crt
9+
server_key: certs/turingflowd.key
10+
client_ca_cert: certs/ca.crt
11+
upstream_ca_cert: certs/ca.crt
12+
upstream_client_cert: null
13+
upstream_client_key: null
14+
15+
security:
16+
replay_window_seconds: 60
17+
18+
routing:
19+
retry_delays_ms: [0, 250, 1000, 3000]
20+
21+
storage:
22+
backend: sqlite
23+
sqlite:
24+
path: data/turingflow.db
25+
26+
limits:
27+
max_payload_bytes: 262144
28+
max_message_ttl_ms: 60000
29+
30+
logging:
31+
format: json
32+
level: info

‎docs/README.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Documentation Index
2+
3+
This directory is split by audience.
4+
5+
- User docs: how to run and use TuringFlow.
6+
- Developer docs: architecture, kernel, API, data model, testing.
7+
- Ops docs: runbook, observability, migrations.
8+
9+
## User
10+
11+
- `docs/user/quickstart.md`
12+
- `docs/user/cli.md`
13+
- `docs/user/daemon.md`
14+
- `docs/user/configuration.md`
15+
- `docs/user/security-model.md`
16+
- `docs/user/troubleshooting.md`
17+
18+
## Developer
19+
20+
- `docs/dev/architecture.md`
21+
- `docs/dev/kernel.md`
22+
- `docs/dev/tfpv1-api.md`
23+
- `docs/dev/storage.md`
24+
- `docs/dev/testing.md`
25+
- `docs/dev/contributing.md`
26+
- `docs/dev/no-direct-host-access.md`
27+
28+
## Operations
29+
30+
- `docs/ops/runbook.md`
31+
- `docs/ops/observability.md`
32+
- `docs/ops/migrations.md`

‎docs/dev/architecture.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Architecture
2+
3+
## High-level modules
4+
5+
- `src/bin/turingflowd.rs`: daemon entrypoint, API routes, mTLS handling.
6+
- `src/tfpv1/*`: protocol types, registry, router, dedupe, config loading.
7+
- `src/tfpv1/storage/*`: SQLite initialization and persistence modules.
8+
- `src/kernel/*`: policy engine, syscall kernel, providers, audit sink.
9+
- `src/commands/*`: CLI command handlers and tooling runtime wrappers.
10+
11+
## Request flow (`send`)
12+
13+
1. Validate request and kingdom quotas.
14+
2. Replay and dedupe checks.
15+
3. Verify source/destination agents.
16+
4. If local agent-op payload, execute via kernel syscalls.
17+
5. Else route message to destination deliver URL.
18+
19+
## Data flow
20+
21+
- Config YAML -> validated structs.
22+
- State persistence -> SQLite tables/migrations.
23+
- Policy decisions -> audit records in `syscall_audit_log`.

‎docs/dev/contributing.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Contributing
2+
3+
## Development workflow
4+
5+
1. Implement change.
6+
2. Add/update tests.
7+
3. Run checks locally.
8+
4. Open PR with rationale and risk notes.
9+
10+
## Local checks
11+
12+
```bash
13+
cargo fmt
14+
cargo check
15+
cargo test --lib
16+
cargo test --test tfpv1_integration
17+
cargo test --test turingflowd_http_integration
18+
bash scripts/check_tooling_no_direct_host_access.sh
19+
```
20+
21+
## Coding expectations
22+
23+
- preserve mTLS and identity guarantees
24+
- preserve deny-by-default semantics
25+
- no direct host access in tools runtime perimeter
26+
- keep error contracts stable (`version`, `error.*`)

‎docs/dev/kernel.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Kernel and Syscalls
2+
3+
The kernel layer provides controlled host access for agent operations.
4+
5+
## Core components
6+
7+
- `ExecutionContext`: trace/kingdom/agent/tool identity context.
8+
- `PolicyEngine`: evaluates `allow/deny` for syscall + resource.
9+
- `Kernel`: façade calling policy then provider.
10+
- Providers:
11+
- `HostFsProvider`
12+
- `HostProcessProvider`
13+
- `HostNetworkProvider`
14+
15+
## Policy semantics
16+
17+
- deny-by-default
18+
- principal priority: `agent_tool` > `agent`
19+
- per-principal rule ordering by priority
20+
- resource matching supports:
21+
- `path_prefix`
22+
- `command_allowlist`
23+
- `host_allowlist`
24+
- `methods`
25+
26+
## Filesystem safety
27+
28+
- canonicalization before access
29+
- parent canonicalization for writes
30+
- reject traversal components (`..`, `.`)
31+
- reject symlink escapes outside root
32+
33+
## Process safety
34+
35+
- allowlist of binaries
36+
- optional allowlist of args per binary
37+
- no shell binaries allowed (`sh`, `bash`, ...)
38+
- no path binaries in command (`/bin/...` rejected)
39+
40+
## Network safety
41+
42+
- allowlist hosts
43+
- allowlist methods
44+
- enforce timeout max
45+
46+
## Error mapping
47+
48+
Kernel uses OS-like codes:
49+
50+
- `EACCES`, `ENOENT`, `EINVAL`, `ETIMEOUT`, `ERATELIMIT`, `EINTERNAL`
51+
52+
In daemon API, these are returned in structured error payloads.

0 commit comments

Comments
 (0)