Unix-AGB — Aletheion Guard Bridge

A proposed stateful security runtime for Linux that turns system behavior into persistent causal state and compiles it into deterministic enforcement policies.

Unix-AGB is designed as an additional security layer over Ubuntu/Linux, not as a new kernel or a replacement for AppArmor, Linux Security Modules, BPF, audit logs, SIEM, or EDR. Its central separation of responsibilities is:

Linux / Ubuntu             observation, identity, isolation, enforcement
AppArmor / LSM / BPF       stable base policy and security hooks
Aletheion Guard Bridge     state orchestration and policy control plane
ASM-CM                     bounded causal/associative state
Canonical Event Store      exact facts, authorization, and provenance
Optional LLM reader        human-readable explanation outside the hot path

Status

This repository contains the Gate 0 architecture, versioned contracts, and an audit-only functional skeleton plus two controlled Linux laboratory proofs. The proofs observe real subprocesses and demonstrate a gateway decision causing an external seccomp broker to return EACCES; neither is a production daemon or a system-wide policy service.

Unix-AGB remains experimental research and is not a production security system. Security efficacy, production performance, state compactness, and detection claims have not been established.

Read the complete Portuguese specification: docs/Unix_AGB_Architecture_Specification_PTBR.md.

Design principles

• keep neural inference and LLMs out of the synchronous syscall hot path;
• treat the canonical event store, not neural state, as historical truth;
• isolate state by process, user, service, container, agent, tenant, or session;
• authorize before resolving evidence or sending it to a reader;
• allow AGB state to maintain or restrict base privileges, never expand them;
• preserve deterministic enforcement through cached, versioned policy;
• fail safely when state, checkpoints, event sequences, or runtimes are invalid;
• require measured improvement over deterministic and statistical baselines.

Planned evolution

Phase 0  Ubuntu observer, canonical events, audit-only evaluation
Phase 1  AGB runtime, ASM-CM integration, persistence and namespaces
Phase 2  explicit policy engine and dry-run decision cache
Phase 3  narrow AppArmor/BPF-LSM/cgroup enforcement pilot
Phase 4  security runtime for AI agents
Phase 5  Ubuntu-derived developer preview
Phase 6  optional minimal kernel work only if measurements justify it

See ROADMAP.md for gates and deliverables.

Repository map

configs/       example runtime configuration
docs/          architecture decisions and operational contracts
fixtures/      deterministic synthetic event sequences
python/        fake ASM Unix-socket service for integration work
schemas/v1/    versioned JSON Schema contracts
scripts/       synthetic generator and plumbing benchmark
src/           Rust gateway, store, state, policy, enforcer, and CLI
tests/         Python contract and fake-ASM tests

Key documents: contracts, event model, namespaces, persistence, runtime stack ADR, threat model, and benchmark protocol.

Gate 0 quickstart

Requirements: Rust stable and Python 3.11 or newer. No privileged Linux hooks are used in this milestone.

make test
python3 scripts/generate_synthetic_events.py --count 3 \
  | cargo run --quiet --bin agb-gateway -- --store var/events.jsonl
cargo run --quiet --bin agbctl -- status
cargo run --quiet --bin agbctl -- events tail --limit 3

Run the fake ASM boundary as a separate Unix-domain JSONL service:

PYTHONPATH=python python3 -m agb_fake_asm.server \
  --socket var/run/fake-asm.sock

make benchmark measures only the deterministic fake-engine plumbing. It is not evidence of security efficacy or production performance.

make benchmark-gate2 runs the frozen 40-trajectory Gate 2 experiment across event-local, sequence-rule, sliding-window, and deterministic stateful-proxy modes. It also proves restart, corrupt-snapshot rejection, sequence-gap abstention, and namespace isolation. Mode D is an integration seam for a future ASM-CM backend; it is not learned state and cannot support an ASM efficacy claim.

To run Mode D with the real promoted ASM-CM checkpoint, create the optional environment with python3 -m venv .venv && .venv/bin/pip install -r requirements-asm.txt, then provide the external checkpoint and source fingerprints:

ASM_CM_CHECKPOINT=/path/to/checkpoint_final.pt \
ASM_CM_CHECKPOINT_SHA256=<sha256> \
ASM_SOURCE_ROOT=/path/to/ASM/src \
ASM_SOURCE_REVISION=<git-commit> \
make benchmark-gate2-asm-cm

The Make target uses CUDA by default. Set ASM_DEVICE=cpu explicitly on hosts without a compatible GPU. The checkpoint is deliberately not copied into Unix-AGB or committed.

make benchmark-gate2-multiseed runs the adversarial v2 corpus over exactly three promoted checkpoints. It requires ASM_CM_SEED{1,2,3}_CHECKPOINT and matching ASM_CM_SEED{1,2,3}_SHA256 variables in addition to the ASM source root and revision. The report separates ingest/query latency and records peak CUDA allocated/reserved bytes.

Collect normalized BPF events and build unlabeled candidates first:

AGB_BPFTRACE_COMMAND="sudo bpftrace" make capture-independent-events
make build-independent-candidates

Candidate generation classifies each exact executable into a separate evaluation queue. With a system-wide capture, list protected executables as a comma-separated set; every other executable becomes external telemetry:

AGB_COVERAGE_SCOPE=system-wide \
AGB_PROTECTED_EXECUTABLES="/absolute/path/to/protected-agent,/absolute/path/to/workload" \
make build-independent-candidates

Protected candidates use security-efficacy; external candidates use false-positive-monitoring. The review UI exposes both as separate queues, and only the former can contribute to Gate 2 promotion. Existing valid reviews are preserved when make build-review-queue regenerates a queue.

Telemetry coverage is separate from data-use permission. A future first-run flow will let the user independently allow, ask, or deny local file reads, external networking, file-content egress, and derived-content egress, with optional per-application and destination rules. Until that enforcement exists, a benign file.open review means only that the observed local read is allowed; it never authorizes transmission. The normative design is documented in docs/persistence.md.

Candidate construction divides long process histories into contiguous windows of at most 256 events (AGB_MAX_TRAJECTORY_EVENTS). Derived sequences restart at one, while provenance.source_sequence preserves the canonical source position. Every window from the same exact process identity is assigned to the same split, preventing cross-split namespace leakage. The builder fingerprints the exact collector and normalizer sources in addition to recording the Git commit, so uncommitted collector changes cannot masquerade as the clean commit. AGB_COLLECTOR_REVISION remains available only for an externally attested collector revision.

The sudo prefix is only needed when the current user lacks tracingfs/BPF privileges; delegated capabilities can be used instead. The command fails without replacing an earlier capture if permission is denied or no events are seen. By default the laboratory observer captures the complete host. Set AGB_CAPTURE_UID to a numeric UID only when an authorized collection must be deliberately restricted. The runner translates the system-wide -1 sentinel to a non-option positional value before invoking bpftrace. The collector excludes its own PID to prevent observer feedback, and any kernel-reported lost event count invalidates the capture instead of publishing incomplete causal evidence. Production setup will require a persisted choice among system-wide, protected-only, and allowlist; outside-scope activity means “not observed”, never “safe”. The complete consent and coverage contract is defined in docs/persistence.md.

Review var/telemetry/trajectory-candidates.jsonl independently, then write one JSONL decision per candidate to var/telemetry/trajectory-reviews.jsonl:

{"trajectory_id":"candidate:...","label":"benign","label_source":"review:case-123","family":"developer-build"}

Replace candidate:... with each exact candidate ID. The preassigned split cannot be changed. Exporting fails if any candidate is missing a review or a review names an unknown candidate. Then run:

For large captures, make build-review-queue streams the candidate file and creates a compact review-queue.jsonl plus a review template. Every REVIEW_REQUIRED value must be independently replaced; those placeholders are deliberately rejected by the exporter.

make review-server serves the same interface only on 127.0.0.1 and writes each validated click atomically to AGB_REVIEWS. It uses a per-process CSRF token, sends no telemetry to the network, and stops with Ctrl+C.

make export-reviewed-corpus
AGB_INDEPENDENT_CORPUS="$PWD/var/telemetry/reviewed-trajectories.jsonl" make freeze-independent-corpus

The validator rejects synthetic provenance, sequence gaps, duplicate event IDs, mixed namespaces within a trajectory, and namespace overlap between calibration and test. Unix-AGB ships the contract and tooling, not a fabricated “real” dataset. Paths under var/telemetry may contain sensitive process and resource metadata and are intentionally not committed.

After independent review and freezing, make benchmark-gate2-multiseed-independent runs the three promoted ASM-CM seeds against only the frozen test split. It requires the same three checkpoint/source variables as the adversarial multi-seed target plus AGB_INDEPENDENT_CORPUS.

A fail-closed protected laboratory corpus can be collected with make protected-corpus-lab. It launches equal benign and suspicious instances of the dedicated Rust workload, connects suspicious cases only to a loopback listener, opens a local canary without transmitting its contents, and labels the canary as sensitive through explicit collector policy. The command rejects lost BPF events, missing PIDs, incomplete causal chains, or unexpected executables. Outputs remain local under var/telemetry/protected-lab/; this controlled corpus complements but does not replace diverse natural workloads.

Reproducible causal proof

The first controlled proof uses two isolated processes that perform the same terminal action: opening /run/secrets/api-token. Their prior histories differ:

benign      exec → local configuration read → credential read  → shadow ALLOW
suspicious  exec → external network connect → credential read  → shadow DENY

Run make causal-proof. The executable verifies that the terminal operation and resource are identical before accepting the divergent outcome, and prints the causal evidence IDs used in each decision. The backend remains fake and reports applied: false; this is a reproducible proof of trajectory-dependent policy behavior, not real Linux enforcement or learned causal inference.

The live laboratory slice is available with make live-proof. It launches two real Rust subprocesses, observes execve, openat, and connect through strace, sends normalized events through the gateway, and installs a process-local Landlock read denial only after the shadow decision. The report is written to var/live-proof/REPORT.json. This is cooperative laboratory evidence, not production telemetry or system-wide enforcement.

The first external-enforcement laboratory proof is make seccomp-proof. It uses a separate broker process and seccomp user notification to deny openat with EACCES for the restricted case. The broker now sends the real trajectory to agb-gateway, which persists three events and returns the causal policy decision before the kernel response. Reports and gateway JSONL stores are written to var/seccomp-proof/. It is limited to one disposable file and does not install a system-wide policy.

The enforcement edge also includes a versioned, expiring decision-cache primitive in python/agb_fake_asm/policy_cache.py. Cache misses never invent an allow decision; policy revision changes and TTL expiry invalidate entries. make seccomp-proof now performs two identical protected opens and reports the second request as a cache hit.

make linux-capabilities reports whether the host exposes the prerequisites for the next observer step. The BPF laboratory observer is defined in scripts/observe_live_bpf.bt; it observes execve, openat, and connect without blocking them. The external enforcement boundary and its promotion criteria are documented in docs/ADR-0002-external-enforcement.md.

Scientific and security posture

The project must compare trajectory-aware state against strong baselines, including static Linux/AppArmor policy, deterministic sequence rules, sliding-window correlation, and conventional risk scoring. Automatic broad enforcement is out of scope until false positives, recovery, resource bounds, namespace isolation, rollback, and enforcement latency are demonstrated.

See PRIOR_ART.MD for lineage and non-claims.

Naming and trademarks

“Unix-AGB” is a working project name. UNIX® is a registered trademark of The Open Group. This project does not claim UNIX certification or endorsement.

Authorship and licensing

Copyright © 2026 Felipe Maya Muniz.

Licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only). Commercial licensing is also available from AletheionAGI for organizations that require proprietary integration, closed-source deployment, or alternative licensing terms. Alternative terms apply only to Unix-AGB components that AletheionAGI is legally entitled to license. Linux, Ubuntu, AppArmor, BPF/eBPF, dependencies, and other third-party components remain under their original licenses and must be handled separately.

See LICENSE, LICENSE-COMMERCIAL.md, NOTICE, COPYRIGHT, and AUTHORS.md.

Commercial licensing: contact@aletheionagi.com.