If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/aya-rs/aya shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 19 active contributors
• Distributed ownership (top contributor 28% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live aya-rs/aya repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/aya-rs/aya.

What it runs against: a local clone of aya-rs/aya — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in aya-rs/aya | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of aya-rs/aya. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/aya-rs/aya.git
#   cd aya
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of aya-rs/aya and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "aya-rs/aya(\\.git)?\\b" \\
  && ok "origin remote is aya-rs/aya" \\
  || miss "origin remote is not aya-rs/aya (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "aya/Cargo.toml" \\
  && ok "aya/Cargo.toml" \\
  || miss "missing critical file: aya/Cargo.toml"
test -f "aya-obj/src/btf/mod.rs" \\
  && ok "aya-obj/src/btf/mod.rs" \\
  || miss "missing critical file: aya-obj/src/btf/mod.rs"
test -f "aya-ebpf-macros/src/lib.rs" \\
  && ok "aya-ebpf-macros/src/lib.rs" \\
  || miss "missing critical file: aya-ebpf-macros/src/lib.rs"
test -f "ebpf/aya-ebpf/Cargo.toml" \\
  && ok "ebpf/aya-ebpf/Cargo.toml" \\
  || miss "missing critical file: ebpf/aya-ebpf/Cargo.toml"
test -f "aya-build/src/lib.rs" \\
  && ok "aya-build/src/lib.rs" \\
  || miss "missing critical file: aya-build/src/lib.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/aya-rs/aya"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Aya is a pure-Rust eBPF library that enables running user-supplied programs inside the Linux kernel without depending on libbpf or bcc. It provides BTF (BPF Type Format) support for compile-once-run-everywhere binaries, function call relocation, global data maps, and async support (tokio/async-std), allowing developers to write kernel-level observability and security tools entirely in Rust. Monorepo split into three tiers: (1) Core runtime crates: aya/, aya-obj/ (ELF/object parsing), aya-build/ (compile-time helpers); (2) Feature crates: aya-log/, aya-tool/, ebpf-panic/; (3) eBPF target crates in ebpf/ (aya-ebpf, aya-ebpf-bindings, aya-ebpf-cty) built with special RUSTFLAGS; (4) Procedural macros in aya-ebpf-macros/ for annotations like #[kprobe], #[fentry], #[map]; (5) Integration tests in test/ with both Rust and eBPF code. Workspace resolver = "2" ensures proper dependency isolation.

Systems engineers and Rust developers building kernel-level observability tools, security monitoring, network packet processing, and tracing utilities who want to avoid C/libbpf complexity and deploy self-contained binaries across different Linux distributions and kernel versions without recompilation.

Production-ready and actively maintained. The project has comprehensive CI (GitHub Actions in .github/workflows/ci.yml and gen.yml), a structured workspace with 18+ member crates, extensive test coverage across integration-test and integration-ebpf, documentation site (aya-rs.dev), and Discord community. Regular releases are managed via RELEASE.md, indicating stable versioning practices.

Low risk for core eBPF functionality. The codebase has been established long enough to have governance (GOVERNANCE.md, MAINTAINERS.md) and security policies (SECURITY.md). Main risks are: eBPF is Linux-kernel-version-sensitive (mitigated by BTF support), and the library depends on precise kernel interfaces that can break across versions. Dependency count appears moderate per workspace.dependencies snippet. No obvious single-maintainer bottleneck evident from governance structure.

Active development visible: aya-ebpf-macros has multiple hook types (kprobe, fentry, fexit, lsm, cgroup_* variants, flow_dissector, perf_event, btf_tracepoint), BTF map support, and tracepoint macros. CI workflow runs on every commit. The project maintains synchronized kernel image downloads (download_kernel_images.sh) for testing against multiple kernel versions, indicating ongoing kernel compatibility work.

Clone and set up: git clone https://github.com/aya-rs/aya && cd aya. Install Rust 1.87.0+. For eBPF targets, run: RUSTFLAGS="--cfg bpf_target_arch=x86_64" cargo build --target bpfel-unknown-none -p aya-ebpf. For userspace: cargo build -p aya. Run tests: cargo xtask (see xtask/ member for test orchestration). CI config at .github/workflows/ci.yml shows the full test matrix.

Daily commands: Userspace example: cargo run -p aya --example <name>. Build eBPF program: From ebpf/aya-ebpf or integration-ebpf, run with target flags: RUSTFLAGS="--cfg bpf_target_arch=x86_64" cargo build --target bpfel-unknown-none. Integration tests: cargo xtask test (xtask orchestrates kernel image setup via .github/scripts/download_kernel_images.sh). CI matrix in ci.yml tests multiple kernel versions (see .github/workflows/ci.yml for full matrix).

• aya/Cargo.toml — Root workspace manifest defining all member crates and their interdependencies; critical for understanding the modular architecture of the eBPF library.
• aya-obj/src/btf/mod.rs — BTF (BPF Type Format) module handling; essential for eBPF object file parsing and type information that enables portable eBPF programs across kernel versions.
• aya-ebpf-macros/src/lib.rs — Procedural macros entry point for all eBPF program annotations (#[xdp], #[kprobe], etc.); every eBPF developer must understand macro expansion patterns.
• ebpf/aya-ebpf/Cargo.toml — eBPF-side crate defining the runtime library for programs running in kernel space; foundational for writing eBPF code.
• aya-build/src/lib.rs — Build-time helpers for compiling eBPF programs; required for understanding the compile-time workflow and object file generation.
• aya-log/src/lib.rs — User-space logging infrastructure for eBPF programs; demonstrates the pattern for kernel-to-userspace data communication.
• CONTRIBUTING.md — Contribution guidelines and development workflow; sets expectations for code style, testing, and submission process.

Add a New eBPF Program Type Hook

1. Create a new macro module in aya-ebpf-macros/src/ (e.g., lsm_cgroup.rs) implementing the hook-specific signature validation and entry point generation (aya-ebpf-macros/src/lib.rs)
2. Add the macro invocation to the lib.rs proc_macro export using #[proc_macro_attribute], following the pattern of existing macros like #[xdp] or #[kprobe] (aya-ebpf-macros/src/lib.rs)
3. Update aya-ebpf kernel-space crate to re-export any new helpers or context types needed by the hook (ebpf/aya-ebpf/Cargo.toml)
4. Add integration test fixtures in test/integration-ebpf/ demonstrating the new hook type (test/integration-ebpf)

Add Support for a New eBPF Map Type

1. Define the map type in aya-ebpf-macros/src/map.rs, adding validation for map parameters and macro expansion logic (aya-ebpf-macros/src/map.rs)
2. Add userspace loader support in aya/src/, implementing the MapData variant and loading logic for the kernel to recognize the map type (aya/Cargo.toml)
3. Update aya-obj/src/btf/mod.rs if the map requires BTF-based definition or CO-RE relocation support (aya-obj/src/btf/mod.rs)
4. Add integration tests in test/integration-test/ validating map creation, access, and cleanup (test/integration-test)

Add Kernel Binding Generation for New Architecture

1. Update .github/workflows/gen.yml to include the new architecture target (e.g., loongarch64) in the bindgen matrix (.github/workflows/gen.yml)
2. Generate bindings by running xtask bindgen and commit the generated output to aya-obj/src/generated/linux_bindings_<arch>.rs (aya-obj/src/generated)
3. Update aya-ebpf-bindings/Cargo.toml to conditionally include the new arch-specific module using cfg(target_arch = '...') (ebpf/aya-ebpf-bindings/Cargo.toml)

Add a New Logging Format or Parser

1. Extend aya-log-common/src/lib.rs with new log level, format metadata, or serialization traits (aya-log-common/src/lib.rs)
2. Add macro expansions in aya-log-ebpf-macros/src/expand.rs to generate kernel-side code for the new format (aya-log-ebpf-macros/src/expand.rs)
3. Implement parser logic in aya-log-parser/src/lib.rs to deserialize the new format from kernel ring buffer (aya-log-parser/src/lib.rs)
4. Add userspace formatter in aya-log/src/lib.rs to display parsed logs in the desired output format (aya-log/src/lib.rs)

• Rust — Memory safety without garbage collection; zero-cost abstractions; strong type system enables compile-time verification of eBPF program correctness and prevents common kernel subsystem misuse.
• Procedural Macros (syn/quote) — Provides ergonomic, declarative syntax for eBPF programs while hiding boilerplate context marshalling, attribute parsing, and function signature transformation required by the kernel.
• BTF (BPF Type Format) + CO-RE (Compile Once – Run Everywhere) — Enables portable eBPF binaries across kernel versions by encoding type information and performing in-kernel relocations at load time, eliminating need to recompile per kernel version.
• ELF object file parsing — Standard format allows integration with existing LLVM/Clang toolchain and enables aya to parse compiled eBPF binaries, extract metadata, and apply relocations

Critical: eBPF programs must be compiled with special target flags: RUSTFLAGS="--cfg bpf_target_arch={arch}" --target bpfel-unknown-none (or bpfeb for big-endian). Omitting this is a common build failure. Kernel version sensitivity: Even with BTF, some hooks (e.g., LSM, BPF LSM cgroup) require specific kernel configs; test against target kernel via .github/scripts/download_kernel_images.sh. Workspace members must be built separately: eBPF crates are excluded from default-members; use cargo xtask or explicit member selection. Edition is 2024 (Rust 1.87.0+); older Rust versions will fail silently on dependencies. Map access from userspace requires explicit type casting (see aya-log patterns); type mismatches cause runtime load failures, not compile errors.

• BPF Type Format (BTF) — BTF enables Aya's core differentiator: compile-once-run-everywhere; it encodes type metadata allowing kernel to rewrite pointers and structure offsets at load time, eliminating per-kernel recompilation
• eBPF Program Hooks (kprobe, fentry, LSM, cgroup, tracepoint) — Different hooks attach eBPF code to different kernel execution points (function entry/exit, security hooks, cgroup events); macro implementations in aya-ebpf-macros map Rust annotations to these hook types
• ELF Object Relocation and BTF Relocation — Aya's aya-obj parses ELF binaries and applies BTF-guided relocations at load time; this is how kernel adjusts offsets for function pointers, struct members, and global variables without recompiling
• BPF Maps (Ring Buffer, Hash Map, Per-CPU Arrays) — Maps are the primary IPC mechanism between kernel eBPF programs and userspace; aya-ebpf-macros/src/map.rs defines ergonomic Rust abstractions, and aya/src/ provides safe userspace access patterns
• Syscall-driven eBPF Loading (bpf() syscall) — Aya loads eBPF programs via the bpf() syscall (not libbpf); understanding BPF_PROG_LOAD, BPF_MAP_CREATE, BPF_OBJ_PIN helps debug loading failures and explains why Aya avoids C dependencies
• Procedural Macros for Code Generation — aya-ebpf-macros/ uses procedural macros (#[kprobe], #[map], #[lsm]) to generate boilerplate (context struct, map registration); understanding macro expansion explains Aya's ergonomic advantage over raw eBPF
• Cross-compilation to bpfel/bpfeb Targets — eBPF programs compile to bpfel (little-endian) or bpfeb targets, not x86_64; Aya requires RUSTFLAGS and --target flags; this is the most common build gotcha for new contributors

• libbpf/libbpf-rs — Rust bindings to libbpf (the C eBPF library); Aya's main alternative and inspiration, but Aya avoids the C dependency for pure Rust deployments
• torvalds/linux — Linux kernel source; eBPF syscall interface, BTF spec, and hook definitions are defined here; essential reference for understanding kernel-side behavior
• cilium/ebpf — Go eBPF library with similar goals (pure-language, no libbpf); provides comparison point for cross-language eBPF ergonomics and design decisions
• aya-rs/awesome-aya — Curated list of projects using Aya; ecosystem companion showing real-world applications (observability, security, networking tools)
• ebpf-io/ebpf.io-website — eBPF.io community resource and specification reference; provides foundational eBPF concepts and compatibility matrices Aya depends on

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for aya-ebpf-macros proc-macro expansion edge cases

The aya-ebpf-macros crate has 20+ macro implementations (kprobe, fentry, xdp, etc.) but lacks comprehensive integration tests verifying correct BPF section generation and attribute validation. New contributors could add tests validating edge cases like invalid attribute combinations, missing required fields, and proper error message generation. This improves reliability of the macro system which is critical to the entire eBPF compilation pipeline.

• [ ] Review existing macro implementations in aya-ebpf-macros/src/ to identify untested edge cases
• [ ] Create tests/macro_expansion_tests.rs in aya-ebpf-macros/ with trybuild or similar testing framework
• [ ] Add test cases for attribute validation (e.g., invalid kprobe names, conflicting cgroup_skb directions)
• [ ] Add test cases for proper BPF section name generation across different architectures
• [ ] Update CI in .github/workflows/ci.yml if needed to run the new test suite

Add workspace-level dependency audit and update aya-build/Cargo.toml to match minimum MSRV

The workspace.package specifies rust-version = '1.87.0' but there's no automated checking to ensure all dependencies maintain MSRV compatibility. The aya-build crate (critical for compilation) should have explicit MSRV validation. Creating a cargo-msrv check in CI and documenting per-crate MSRV requirements in a new MSRV.md file would prevent silent MSRV regressions from dependency updates.

• [ ] Create MSRV.md documenting minimum Rust version for each workspace member
• [ ] Add a new GitHub Action workflow .github/workflows/msrv-check.yml using cargo-msrv or cargo-minimal-versions
• [ ] Update .github/workflows/ci.yml to run MSRV checks on PRs that modify Cargo.toml
• [ ] Document MSRV requirements in CONTRIBUTING.md section for dependency updates
• [ ] Audit current Cargo.toml dependencies for any already incompatible with 1.87.0

Add missing platform-specific eBPF target tests in test/integration-ebpf/

The workspace mentions building for multiple architectures (aarch64, arm, riscv64, s390x, x86_64, etc.) in Cargo.toml comments, but the integration-ebpf test coverage appears limited to commonly-tested targets. Adding platform-specific smoke tests for less common targets (loongarch64, mips64, powerpc64) in the test suite would catch architecture-specific compilation failures early and improve cross-platform reliability.

• [ ] Review test/integration-ebpf/ structure to understand existing test organization
• [ ] Create architecture-specific test modules for mips64, loongarch64, and powerpc64 targets
• [ ] Add minimal eBPF programs that compile to each architecture to validate target support
• [ ] Update .github/workflows/ci.yml or create new workflow to build for less common targets on specific triggers
• [ ] Document in CONTRIBUTING.md how to test architecture-specific builds locally

• Add integration test coverage for the btf_tracepoint macro (aya-ebpf-macros/src/btf_tracepoint.rs exists but may lack corresponding test-case in test/integration-ebpf); this exercises lesser-tested hook types and benefits from fresh eyes on test design.
• Document the BTF relocation process in a code-level guide within aya-obj/src/lib.rs or add rustdoc examples showing how to inspect relocations; currently missing concrete examples of what BTF does at relocation time.
• Create a migration guide from aya < 0.13 to current in CONTRIBUTING.md covering breaking changes in map macros (map.rs vs. btf_map.rs); helps new contributors understand API evolution and unblocks adoption docs.

The Aya project demonstrates good security practices overall. Strengths include: (1) Dual MIT/Apache-2.0 licensing with transparency, (2) Explicit security policy with Private Vulnerability Reporting enabled, (3) Well-structured workspace with clear separation of concerns (user-space vs eBPF crates), (4) Recent Rust MSRV (1.87.0), (5) No hardcoded secrets or credentials detected in available files, (6) No obvious injection vectors or misconfigurations. Minor concerns include flexible dependency version specifiers and the inherent security complexity of eBPF program execution. No critical vulnerabilities detected in the static analysis.

• Low · Incomplete dependency version locking — Cargo.toml - workspace.dependencies. Several workspace dependencies use flexible version specifiers (e.g., 'version = "1"') without pinning patch versions. While this allows security updates to be picked up, it may introduce unexpected breaking changes in minor versions if upstream crates don't follow semver strictly. The workspace uses resolver = '2' which helps but doesn't fully mitigate this. Fix: Consider using more restrictive version specifiers (e.g., '1.x.y' with a minimum patch version) for critical dependencies, or use a lockfile (Cargo.lock) in version control for binary crates.
• Low · Outdated Rust MSRV — Cargo.toml - workspace.package. The workspace specifies rust-version = '1.87.0' which was released in February 2025. While relatively recent, projects should periodically review and update MSRV to benefit from security improvements in the Rust compiler itself. Fix: Establish a policy for MSRV updates (e.g., supporting the last 2-3 stable releases) and review quarterly. Document the MSRV rationale.
• Low · eBPF code security context unclear — aya-ebpf/* and ebpf/* directories. This is an eBPF framework allowing execution of kernel-space code. The security boundary between userspace and BPF programs is critical. While the codebase structure suggests awareness of this (separate eBPF crates), the verifier constraints and sandboxing guarantees need careful review in actual code. Fix: Ensure comprehensive documentation of eBPF program validation, kernel verifier integration, and security guarantees. Consider security audits of the verifier integration code.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.