Advanced Linux kernel local privilege escalation discovery workbench.

What aegis Is

aegis is a static analysis research tool that scans Linux kernel source trees to:

• Map attack surfaces (ioctl handlers, usercopy boundaries, netlink handlers, procfs/sysfs/debugfs, eBPF hooks, namespace-sensitive paths)
• Identify vulnerability candidate patterns (unchecked copy_from_user, user-controlled allocations, missing bounds checks, UAF/double-free patterns, refcount issues, locking imbalances, integer overflows)
• Generate scored, structured findings with evidence and remediation hints
• Produce non-weaponized syzkaller description stubs for manual researcher completion
• Parse kernel sanitizer crash logs (KASAN, KMSAN, UBSAN, KFENCE, lockdep)

What aegis Is Not

• NOT an exploit runner
• NOT a vulnerability scanner for running systems
• NOT a tool for unauthorized access
• NOT a replacement for manual code review or a full compiler-based analysis

All findings are candidates that require manual validation before drawing conclusions.

Installation

Prerequisites

• GCC >= 11 or Clang >= 13
• POSIX-compatible OS (Linux recommended)
• pthreads
• make or cmake

Build with Make

git clone <repo>
cd aegis
make
./aegis version

Build with CMake

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
./build/aegis version

Debug Build (ASan + UBSan)

DEBUG=1 make

Quick Start

aegis scan --kernel ./linux --config .config --target unprivileged

Example Commands

# Core scanning
aegis scan --kernel ./linux --config .config --target unprivileged
aegis scan --kernel ./linux --format json --output report.json
aegis scan --kernel ./linux --format markdown
aegis scan --kernel ./linux --subsystem drivers/net
aegis scan --kernel ./linux --rules AGS-COPY-001,AGS-IOCTL-001
aegis scan --kernel ./linux --min-severity medium
aegis scan --kernel ./linux --jobs 8 --inter-depth 6
aegis scan --kernel ./linux --emit-syzkaller ./out/syz

# Type-aware and assembly analysis
aegis scan --kernel ./linux --clang-backend
aegis scan --kernel ./linux --asm
aegis scan --kernel ./linux --extra-src ./my-driver --extra-src ./my-module
aegis scan --kernel ./linux --fp-threshold 60

# Graph and export formats
aegis scan --kernel ./linux --format codeql --output findings.csv
aegis scan --kernel ./linux --format graphml --output graph.xml
aegis scan --kernel ./linux --format dot --output graph.dot

# Inter-procedural and call graph
aegis inter --kernel ./linux --file drivers/foo/bar.c --function bar_ioctl
aegis graph --kernel ./linux --format dot --output callgraph.dot
aegis callgraph --kernel ./linux --file drivers/foo/bar.c

# Crash and patch analysis
aegis triage --log kasan.txt --kernel ./linux
aegis syzbot --crash syzbot_report.txt
aegis lkml --patch 0001-fix.patch --verbose

# Backport and CVE tracking
aegis backport --kernel ./linux --commit abc123def456
aegis learn --kernel ./linux --commit abc123def456

# Kernel config reachability
aegis kconfig --kernel ./linux --config SECURITY_HARDENED_USERCOPY
aegis kconfig --kernel ./linux --format dot --output kconfig.dot

# Coccinelle semantic patches
aegis cocci --kernel ./linux --script my_check.cocci
aegis cocci --kernel ./linux  # runs built-in security rules

# Lab environment generation
aegis lab --kernel ./linux --output ./lab --syzkaller

# ML training data export
aegis ml --kernel ./linux --output dataset.csv
aegis ml --kernel ./linux --format json --output dataset.json

# Standard utilities
aegis explain FINDING_ID
aegis rules list
aegis hardening --kernel ./linux --file fs/exec.c
aegis version

Example Output

aegis - Linux Kernel Attack Surface & Vulnerability Candidate Scanner
NOTE: All findings are candidates only. Manual validation required.
NOTE: This tool does NOT produce exploits or weaponized code.
=======================================================================

Findings (1):

[high][87%] drivers/foo/bar.c:421 in bar_ioctl_set_cfg() [AGS-COPY-001]
  Interface   : unlocked_ioctl
  Reachability: unprivileged
  Impact      : out-of-bounds
  Exploitab.  : medium
  Evidence:
    - copy_from_user uses user-controlled size
    - size flows into kmalloc and memcpy
    - no visible upper bound check within 25 lines
  Remediation : Check and handle copy_from_user return value.
  Safe steps  : Manually inspect bounds validation. Create syzkaller repro in isolated VM.
  FP note     : Requires manual validation. Pattern matching may produce false positives.

Output Formats

Format	Flag	Description
terminal	--format terminal	ANSI-colored human output (default)
json	--format json	Stable JSON schema (aegis-v1)
markdown	--format markdown	GitHub Flavored Markdown
sarif	--format sarif	SARIF 2.1.0 for GitHub Code Scanning
html	--format html	Self-contained HTML dashboard
codeql	--format codeql	CodeQL CSV export for import into CodeQL databases
graphml	--format graphml	GraphML XML for graph analysis tools
dot	--format dot	Graphviz DOT for call/finding graph visualization

Rule Writing Guide

See docs/RULES.md.

Rules live in rules/*.rules. Each file may contain multiple rules separated by blank lines.

Example:

id: AGS-COPY-001
name: unchecked copy_from_user return value
severity: medium
category: usercopy
pattern: copy_from_user
forbidden_nearby: if,return,goto,!= 0,< 0
window: 8
confidence: +20
remediation: Check and handle copy_from_user return value.
safe_validation: Inspect manually whether partial copy affects trusted kernel state.

Safety and Responsible Disclosure Policy

1. Authorization: Only run aegis on kernel source trees you are authorized to analyze.
2. Validation: All findings require manual validation. Do not treat pattern matches as confirmed vulnerabilities.
3. Disclosure: Follow responsible disclosure. Notify the Linux kernel security team (security@kernel.org) before publishing kernel vulnerability details. Allow reasonable time (typically 90 days) for patch development.
4. No Weaponization: Do not use aegis output to develop exploit code targeting systems you do not own.
5. Isolated Testing: Run any follow-on fuzzing or PoC testing in isolated VMs, never on production systems.
6. Syzkaller Stubs: Syzkaller stubs generated by aegis are incomplete research metadata. They require significant manual work before they can be used for fuzzing and must not be weaponized.

Report aegis bugs and false positives via the project issue tracker.

Analysis Capabilities

Capability	Flag / Command	Details
Tokenizer-based pattern matching	scan	Built-in rule engine across all C source
Full AST + type-aware analysis	--clang-backend	Clang AST subprocess; detects __user pointer params
Inter-procedural taint tracking	--inter-depth N	Tracks user-controlled data across function boundaries
Assembly file analysis	--asm	Detects rdmsr/wrmsr, CR0/CR4 writes, SMEP disable, stack pivots
Out-of-tree module scanning	--extra-src <path>	Scan any number of additional source directories
Work-stealing thread pool	--jobs N	Fine-grained per-file parallelism, no coarse mutex
FP threshold filtering	--fp-threshold N	Drop findings below N% confidence; ML-scored
Clang AST backend	--clang-backend	Subprocess integration; confirms __user taint sources
CodeQL export	--format codeql	CSV import-ready for CodeQL databases
Coccinelle integration	cocci	Run semantic patches (built-in + custom .cocci)
syzbot crash importer	syzbot	Parse KASAN/KMSAN/UBSAN crash reports
LKML patch analyzer	lkml	Security-score unified diffs from LKML
Stable backport checker	backport	Git-based check across 9 stable branches
CVE/fix commit learner	learn	Extract patterns from a fix commit via git diff-tree
Graph database export	--format graphml / dot	GraphML + Graphviz DOT of call/finding graphs
HTML dashboard	--format html	Self-contained interactive report
Containerized lab runner	lab	Generates Dockerfile, QEMU run script, syzkaller config
Kernel config reachability graph	kconfig	Kconfig parser → DOT/GraphML dependency graph
ML-assisted triage	ml	16-feature vector export; logistic-regression scorer