{"id":51018538,"url":"https://github.com/yasindce1998/aegis-shadow","last_synced_at":"2026-06-21T14:00:56.767Z","repository":{"id":364341296,"uuid":"1224355814","full_name":"yasindce1998/aegis-shadow","owner":"yasindce1998","description":"A dual-module eBPF security research framework demonstrating offensive rootkit techniques (Shadow) and defensive runtime auditing (Aegis) for Linux kernel exploration.","archived":false,"fork":false,"pushed_at":"2026-06-12T15:59:17.000Z","size":127,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-12T17:29:28.302Z","etag":null,"topics":["bpf","bpftool","cyber-security","ebpf","ebpf-programs","intrusion-detection","kernel-hacking","linux-kernel","offensive-security","rootkit","runtime-security","systemprogramming","xdp"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yasindce1998.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-29T07:46:54.000Z","updated_at":"2026-06-12T15:59:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yasindce1998/aegis-shadow","commit_stats":null,"previous_names":["yasindce1998/aegis-shadow"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/yasindce1998/aegis-shadow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yasindce1998%2Faegis-shadow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yasindce1998%2Faegis-shadow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yasindce1998%2Faegis-shadow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yasindce1998%2Faegis-shadow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yasindce1998","download_url":"https://codeload.github.com/yasindce1998/aegis-shadow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yasindce1998%2Faegis-shadow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34610832,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bpf","bpftool","cyber-security","ebpf","ebpf-programs","intrusion-detection","kernel-hacking","linux-kernel","offensive-security","rootkit","runtime-security","systemprogramming","xdp"],"created_at":"2026-06-21T14:00:55.943Z","updated_at":"2026-06-21T14:00:56.761Z","avatar_url":"https://github.com/yasindce1998.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n![Aegis-Shadow Logo](assets/logo.svg)\n\n[![License](https://img.shields.io/badge/license-Educational-red.svg)](LICENSE)\n[![Rust](https://img.shields.io/badge/rust-nightly-orange.svg)](https://www.rust-lang.org/)\n[![eBPF](https://img.shields.io/badge/eBPF-CO--RE-blue.svg)](https://ebpf.io/)\n[![Kernel](https://img.shields.io/badge/kernel-5.10+-green.svg)](https://www.kernel.org/)\n\n\u003c/div\u003e\n\n---\n\n## Overview\n\nAegis-Shadow is an educational research project that demonstrates both offensive and\ndefensive uses of Linux eBPF technology. It consists of two modules:\n\n- **Shadow** (Offense): An eBPF-based rootkit with 47+ features spanning process hiding,\n  XDP-based C2 with ChaCha20 encryption and HMAC authentication, file obfuscation,\n  credential harvesting, DNS exfiltration, ICMP covert channels, network namespace hiding,\n  eBPF program cloaking, container escape probes, anti-forensics bytecode wiping, plus\n  9 advanced modules: hypervisor evasion, polymorphic engine, phantom network stack,\n  cross-container lateral movement, DMA covert channels, behavioral AI camouflage,\n  supply chain persistence, dead man's switch, and BPF parasitism.\n- **Aegis** (Defense): A runtime detection engine with 14 eBPF-based detection modules\n  plus intelligent user-space analysis including anomaly scoring, attack chain\n  correlation, calibration-based baselines, auto-detach of malicious programs,\n  process containment, honeypot maps, and hot-reloadable configuration.\n\n## Warning\n\n**This project is for educational and research purposes only.**\n\n- ALL development and testing MUST occur within isolated virtual machines.\n- NEVER run the offensive module on production systems, shared networks, or systems you do not own.\n- The VM MUST use a host-only network adapter during testing.\n- Do NOT distribute compiled rootkit binaries.\n\n## Requirements\n\n- **Host**: macOS/Linux with UTM, QEMU, or VirtualBox\n- **Guest VM**: Ubuntu 24.04 LTS, Linux Kernel 6.8+\n- **Rust**: Nightly toolchain\n- **Tools**: bpf-linker, bpftool, clang, llvm, libelf-dev\n\n## Quick Start\n\n```bash\n# 1. Set up VM and verify environment\nbash verify-env.sh\n\n# 2. Build everything\nmake build\n\n# 3. Start offensive rootkit (loads core features)\nsudo ./target/release/offense --iface eth0 --hide-pid 1234\n\n# 4. Run defense detection (in another terminal)\nsudo ./target/release/defense --all-modules --verbose\n\n# 5. Stop programs\n# Press Ctrl+C in each terminal, or:\nsudo pkill offense\nsudo pkill defense\n```\n\n## Project Structure\n\n| Directory | Purpose |\n|---|---|\n| `common/` | Shared data structures and constants (`#![no_std]`) |\n| `offense-ebpf/` | Kernel-space rootkit eBPF programs (47+ features) |\n| `offense/` | User-space rootkit loader and CLI |\n| `defense-ebpf/` | Kernel-space defensive eBPF probes (11 detectors) |\n| `defense/` | User-space detection engine and CLI |\n| `xtask/` | Build automation |\n| `integration-tests/` | Adversarial offense-vs-defense test suite |\n\n## Usage\n\n### Offense (Rootkit)\n\nThe offense module loads the core 13 rootkit features automatically on startup. Additional features are enabled via flags:\n\n```bash\n# Basic usage - loads core features\nsudo ./target/release/offense --iface eth0\n\n# With extended features enabled\nsudo ./target/release/offense \\\n    --iface eth0 \\\n    --hide-pid 1234 \\\n    --obfuscate-inode 98765 \\\n    --monitor-tty 136:0 \\\n    --pin-maps \\\n    --enable-icmp-exfil \\\n    --enable-container-probe\n```\n\n**Available flags:**\n\n| Flag | Description |\n|---|---|\n| `--iface \u003cname\u003e` | Network interface for XDP/TC attachment |\n| `--verbose` | Enable debug-level logging |\n| `--hide-pid \u003cpid\u003e` | Add a PID to the hidden process list on startup |\n| `--obfuscate-inode \u003cinode\u003e` | Add an inode to the file obfuscation list |\n| `--monitor-tty \u003cmajor:minor\u003e` | Monitor a TTY device for credential harvesting |\n| `--spoof-ppid \u003cpid:fake_ppid\u003e` | Spoof a process's parent PID |\n| `--timestomp \u003cinode:atime:mtime:ctime\u003e` | Set fake timestamps (epoch seconds) |\n| `--pin-maps` | Pin BPF maps to `/sys/fs/bpf/shadow` for persistence |\n| `--enable-netns-hide` | Enable network namespace hiding |\n| `--enable-bpf-cloak` | Enable eBPF program cloaking (hides own prog IDs) |\n| `--enable-module-mask` | Enable kernel module masquerading in /proc/modules |\n| `--enable-memfd` | Enable memory-only payload staging (memfd + execveat) |\n| `--enable-syslog-strip` | Enable syslog write stripping |\n| `--wipe-bytecode` | Activate anti-forensics bytecode wipe (programs become no-ops) |\n| `--enable-icmp-exfil` | Enable ICMP covert channel exfiltration |\n| `--enable-socket-clone` | Enable socket cloning / connection shadowing |\n| `--enable-cred-relay` | Enable credential relay over C2 |\n| `--enable-container-probe` | Enable container escape probes |\n| `--enable-hypervisor-evasion` | Enable hypervisor detection and evasion (CPUID, hypercall, TSC) |\n| `--enable-polymorphic` | Enable polymorphic engine (bytecode morphing, pattern rotation) |\n| `--enable-phantom-stack` | Enable phantom network stack (invisible TCP connections) |\n| `--enable-container-lateral` | Enable cross-container lateral movement via cgroup/namespace abuse |\n| `--enable-dma-covert` | Enable DMA covert channel (IOMMU, PCIe TLP, NIC exfil) |\n| `--enable-behavioral-ai` | Enable behavioral AI camouflage (syscall profiling, activity throttling) |\n| `--enable-supply-chain` | Enable supply chain persistence (package manager hooking, binary patching) |\n| `--enable-deadman-switch` | Enable dead man's switch (heartbeat monitor, scorched earth wipe) |\n| `--enable-bpf-parasitism` | Enable BPF parasitism (prog scanning, tail-call injection, array hijack) |\n\n### Defense (Detection Engine)\n\nThe defense module enables detection modules via flags and provides intelligent alert analysis:\n\n```bash\n# Enable all detection modules\nsudo ./target/release/defense --all-modules\n\n# Enable specific modules with hot-reload config\nsudo ./target/release/defense \\\n    --ghost-maps \\\n    --syscall-latency \\\n    --bytecode-check \\\n    --prog-inventory \\\n    --memfd-detect \\\n    --honeypots \\\n    --config /etc/aegis/config.json \\\n    --output /tmp/alerts.json\n\n# With active response enabled\nsudo ./target/release/defense --all-modules \\\n    --auto-detach \\\n    --auto-contain \\\n    --threshold 3\n```\n\n**Available flags:**\n\n| Flag | Description |\n|---|---|\n| `--verbose` / `-v` | Enable debug-level logging |\n| `--output` / `-o` | Path to write JSON alert records |\n| `--threshold` / `-t` | Alert severity threshold: 1=Low, 2=Medium (default), 3=High, 4=Critical |\n| `--all-modules` | Enable all detection modules |\n| `--ghost-maps` | Enable ghost map detection |\n| `--syscall-latency` | Enable syscall latency monitoring |\n| `--bytecode-check` | Enable bytecode integrity checking |\n| `--hidden-process` | Enable hidden process detection |\n| `--suspicious-hooks` | Enable suspicious hook detection |\n| `--prog-inventory` | Enable eBPF program inventory (ID gap detection) |\n| `--syscall-anomaly` | Enable syscall argument anomaly profiling |\n| `--net-baseline` | Enable network behavior baseline |\n| `--memfd-detect` | Enable memory-backed execution detection |\n| `--map-audit` | Enable BPF map content auditing |\n| `--tracepoint-monitor` | Enable tracepoint coverage monitoring (rapid detach detection) |\n| `--auto-detach` | Automatic detachment of malicious BPF programs |\n| `--auto-contain` | Automatic process containment via cgroups |\n| `--honeypots` | Enable honeypot BPF maps |\n| `--calibration-period` | Baseline calibration duration in seconds (default: 60) |\n| `--config` | Path to runtime config JSON file (hot-reloaded every 5s) |\n\nFor detailed usage examples, see [USAGE.md](USAGE.md)\n\n## Running Tests\n\n```bash\n# Run integration tests (user-space, no root required)\ncargo test -p integration-tests\n\n# Run automated test scripts (requires root, in VM)\nsudo ./tests/test_offense.sh\nsudo ./tests/test_defense.sh\n\n# Or use Makefile\nmake test\n```\n\nFor manual testing procedures, see [USAGE.md](USAGE.md#testing)\n\n## License\n\nThis project is provided for educational purposes only. See Section 13 of the PRD\nfor full safety and legal guidelines.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyasindce1998%2Faegis-shadow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyasindce1998%2Faegis-shadow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyasindce1998%2Faegis-shadow/lists"}