ExecSurface

ExecSurface learns an accepted runtime execution surface, runs the same command later, and reports execution behavior that appeared, disappeared, or changed.

It is intended for CI pipelines, dependencies, developer tools and AI-assisted workflows where source review alone does not show every runtime effect.

Public Alpha: Linux x86_64 only. Release candidate version: 0.1.0-alpha.4.

Self-service: no signup, API key, meeting, or AETHER X approval is required.

Start here

Choose the path that matches your environment.

A. Linux x86_64 — no Rust required (recommended first run)

Download the published release, verify its checksum, and install it in your user path:

VERSION=v0.1.0-alpha.4
TARGET=x86_64-unknown-linux-gnu
ASSET="execsurface-${VERSION}-${TARGET}.tar.gz"

curl -fLO "https://github.com/AETHERXGLOBAL/execsurface/releases/download/${VERSION}/${ASSET}"
curl -fLO "https://github.com/AETHERXGLOBAL/execsurface/releases/download/${VERSION}/${ASSET}.sha256"
sha256sum -c "${ASSET}.sha256"
tar -xzf "${ASSET}"

mkdir -p "$HOME/.local/bin"
install -m 0755 "execsurface-${VERSION}-${TARGET}/execsurface" "$HOME/.local/bin/execsurface"
export PATH="$HOME/.local/bin:$PATH"

execsurface --version
execsurface doctor

Then run the controlled PASS → REVIEW walkthrough in Five-Minute Start.

B. Rust already installed

cargo install execsurface --locked
execsurface --version
execsurface doctor

The crates.io channel is published only after the immutable GitHub release and stable Action gates succeed. See crates.io Publishing.

C. Add it to a GitHub Actions project

First generate conservative starter files from your project directory:

execsurface init --command "cargo test --locked" --github-actions

init creates a starter policy and workflow. It does not run your target command and does not create a baseline automatically.

The generated workflow uses the stable public-alpha Action channel:

AETHERXGLOBAL/execsurface@v0.1

Do not use @main as the normal consumer path. See the GitHub Action guide.

First real project

Replace the example command with the command you actually want to monitor.

execsurface doctor
execsurface init --command "cargo test --locked" --github-actions
execsurface learn -- /bin/bash -lc 'cargo test --locked'
execsurface check --policy execsurface-policy.json -- /bin/bash -lc 'cargo test --locked'

Review execsurface-policy.json, .github/workflows/execsurface.yml, and execsurface.lock.json before committing them.

If doctor fails, follow the action it prints and see Troubleshooting. doctor never elevates privileges, changes ptrace settings, or weakens host security settings.

What a result means

Result	Exit code	Meaning
PASS	0	comparison/evaluation completed with no review/block finding
ERROR	2	evidence/comparison/policy could not be established
REVIEW	10	one or more findings require review
BLOCK	20	one or more findings matched blocking policy

ExecSurface does not infer that drift is malicious. It reports observed drift and evaluates the explicit policy you selected.

What is observed

The current Linux x86_64 native ptrace reference backend can produce evidence for descendant process spawn/exec, pathname access attempts, successful-open file descriptor identity, covered fd-attributed read/write effects, rename/delete operations in the covered syscall set, network connect destinations, trace-time relative/openat/openat2 path semantics, causal executable chains, and explicit observer incompleteness.

Incomplete evidence cannot silently become PASS.

The portable ptrace guard may conservatively mark some clone/thread concurrency incomplete even when exact fd-table sharing is not proven. Raw observation v2 does not retain enough CLONE_FILES detail to certify exact sharing, so this guard intentionally trades possible false incompleteness for preventing the known false-completeness class. This is not an exact shared-FD attribution repair.

Security boundary

ExecSurface detects observed execution-surface drift under its recorded observer and policy.

It is not antivirus, EDR, malware detection, a sandbox, or a proof that a program is safe.

The governing boundaries are:

NO EXECUTION-SURFACE DRIFT ≠ PROGRAM IS SAFE
OBSERVED BEHAVIOR ≠ ALL POSSIBLE BEHAVIOR
NO OBSERVED NETWORK ≠ NETWORK ACCESS IS IMPOSSIBLE
TRACE COMPLETENESS DEPENDS ON THE OBSERVATION BACKEND

The default evidence boundary excludes file contents, environment values, stdin, network payloads and full child argv values.

The public correctness-reference backend is native ptrace. eBPF/BPF-LSM work remains research-only/non-default and is not the public PASS/learn/check backend.

See Security Policy and Troubleshooting.

Baseline is not policy

The baseline answers what canonical execution surface was accepted. The policy answers what drift should be allowed, reviewed or blocked. A new baseline is not automatically an approval decision.

Independent evaluation

Use Self-Service Start, Five-Minute Start, Independent Evaluation, and Technical Evaluation Pack. Negative, partial, unsupported-environment, usability and performance-problem results are welcome. A self-evaluation PASS is not evidence of independent adoption.

Distribution and verification

The public alpha distribution surfaces are:

checksum-verified GitHub Release binary for Linux x86_64;
cargo install execsurface --locked for Rust users after registry publication;
GitHub Action AETHERXGLOBAL/execsurface@v0.1 after stable-channel promotion.

For maximum Action pinning after release, use AETHERXGLOBAL/execsurface@v0.1.0-alpha.4.

Optional GitHub build provenance verification:

gh attestation verify "$ASSET" -R AETHERXGLOBAL/execsurface

A valid attestation links the artifact to its build source/workflow. It does not prove the binary is safe.

Documentation

Developing ExecSurface

cargo fmt --all -- --check
cargo clippy --locked --workspace --all-targets -- -D warnings
cargo test --locked --workspace --all-targets
cargo run -p execsurface -- --version
cargo run -p execsurface -- doctor

Architecture-affecting changes remain evidence-gated. See CONTRIBUTING.md and GOVERNANCE.md.

License

Apache-2.0. See LICENSE and NOTICE.

execsurface-normalize 0.1.0-alpha.4