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/ayoubfaouzi/al-khaser 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.

WAIT — Mixed signals — read the receipts

• Last commit 5w ago
• 29+ active contributors
• Distributed ownership (top contributor 38% of recent commits)
• GPL-2.0 licensed
• CI configured
• ⚠ GPL-2.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{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 ayoubfaouzi/al-khaser repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ayoubfaouzi/al-khaser.

What it runs against: a local clone of ayoubfaouzi/al-khaser — 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 ayoubfaouzi/al-khaser | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 68 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ayoubfaouzi/al-khaser. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ayoubfaouzi/al-khaser.git
#   cd al-khaser
#
# 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 ayoubfaouzi/al-khaser and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "al-khaser/Al-khaser.cpp" \\
  && ok "al-khaser/Al-khaser.cpp" \\
  || miss "missing critical file: al-khaser/Al-khaser.cpp"
test -f "al-khaser/AntiDebug/pch.h" \\
  && ok "al-khaser/AntiDebug/pch.h" \\
  || miss "missing critical file: al-khaser/AntiDebug/pch.h"
test -f "al-khaser/AntiVM/Generic.cpp" \\
  && ok "al-khaser/AntiVM/Generic.cpp" \\
  || miss "missing critical file: al-khaser/AntiVM/Generic.cpp"
test -f "al-khaser/AntiAnalysis/process.cpp" \\
  && ok "al-khaser/AntiAnalysis/process.cpp" \\
  || miss "missing critical file: al-khaser/AntiAnalysis/process.cpp"
test -f "al-khaser/AntiDump/ErasePEHeaderFromMemory.cpp" \\
  && ok "al-khaser/AntiDump/ErasePEHeaderFromMemory.cpp" \\
  || miss "missing critical file: al-khaser/AntiDump/ErasePEHeaderFromMemory.cpp"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 68 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~38d)"
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/ayoubfaouzi/al-khaser"
  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).

Al-khaser is a proof-of-concept malware application that demonstrates 50+ real-world anti-analysis and anti-sandbox evasion techniques used by actual malware in the wild. It performs debugger detection (BeingDebugged, NtQueryInformationProcess checks), virtual machine detection (VirtualBox, VMware, QEMU, Hyper-V via CPUID and device enumeration), anti-dumping, timing attacks, and anti-disassembly tricks—all compiled into a single x86/x64 binary you can run against your security tools to verify they're actually catching these behaviors. Monolithic Visual Studio solution (al-khaser.sln) with primary project at al-khaser/ containing modular folders: AntiDebug/ (12+ .cpp/.h pairs for IsDebuggerPresent, HardwareBreakpoints, NtGlobalFlag), AntiAnalysis/ (process detection), plus Tools/ subfolder with ATAIdentifyDump and StructDumpCodegen utilities for reverse-engineering malware artifacts. Entry point is Al-khaser.cpp with command-line argument parsing.

Security researchers, malware analysts, and anti-malware/EDR developers who need to validate that their detection systems catch real evasion techniques. Sandbox builders and security team leads validating whether their analysis infrastructure is properly hidden from adversarial detection.

Actively maintained at v0.81 with recent CI/CD pipelines (build.yml, release.yml for automated x86/x64 builds) and organized modular structure across AntiDebug/, AntiAnalysis/, etc. directories. The 432KB C++ codebase and password-protected release artifacts suggest production-quality releases, but no visible test suite or issue tracker details limit full production classification. Verdict: actively developed, production-ready for security testing but not battle-hardened library code.

Single maintainer (LordNoteworthy) creates succession risk if unmaintained. No visible dependency management files suggest minimal external dependencies, which is good. The codebase deliberately implements evasion techniques; running this against unvetted systems could trigger incident response. Real risk: Windows-only (C++ Win32 API heavy), x86/x64 only—limited cross-platform relevance.

v0.81 release cycle active with GitHub Actions workflows building x86/x64 binaries and automated releases. Recent additions include extended check types (TLS callbacks, code injections, Parallels detection). Command-line interface overhauled to support granular --check filters (DEBUG, VMWARE, HYPERV, etc.) and --sleep duration configuration.

git clone https://github.com/ayoubfaouzi/al-khaser.git
cd al-khaser
msbuild al-khaser.sln /p:Configuration=Release /p:Platform=x64
# Or use Visual Studio 2019+ to open al-khaser.sln
./Release/x64/al-khaser.exe --help

Daily commands:

# Run all checks with 30-second sleep
./al-khaser.exe --check DEBUG --check VMWARE --check QEMU --sleep 30

# Run only anti-debugging checks
./al-khaser.exe --check DEBUG

# Run only VM detection (verbose)
./al-khaser.exe --check VBOX --check VMWARE --check HYPERV

# Full suite (default 600s sleep)
./al-khaser.exe

• al-khaser/Al-khaser.cpp — Main entry point orchestrating all anti-analysis detection modules and command-line argument parsing
• al-khaser/AntiDebug/pch.h — Precompiled header for anti-debugging techniques; defines core detection APIs and utilities used across all debugger checks
• al-khaser/AntiVM/Generic.cpp — Core VM detection logic checking for hypervisor signatures, timing anomalies, and virtualization artifacts
• al-khaser/AntiAnalysis/process.cpp — Process enumeration and analysis detection; identifies sandboxes and analysis tools by process name/module patterns
• al-khaser/AntiDump/ErasePEHeaderFromMemory.cpp — Anti-dumping technique that prevents memory forensics by erasing PE headers at runtime
• al-khaser/AntiDisassm/AntiDisassm.cpp — Anti-disassembly evasion using polymorphic code and instruction obfuscation across x86/x64 architectures

Add a New Anti-Debugging Technique

1. Create header file in al-khaser/AntiDebug/ following naming convention (e.g., MyCheck.h) (al-khaser/AntiDebug/MyCheck.h)
2. Implement detection logic in matching .cpp file with bool detection() function (al-khaser/AntiDebug/MyCheck.cpp)
3. Include header and call check function from main Al-khaser.cpp orchestrator (al-khaser/Al-khaser.cpp)

Add a New VM Detection Method

1. Add detection logic to existing Generic.cpp or create new file in al-khaser/AntiVM/ (al-khaser/AntiVM/Generic.cpp)
2. Check for hypervisor presence via CPUID, WMI, registry, or timing analysis (al-khaser/AntiVM/Generic.cpp)
3. Register check in main orchestrator with appropriate flag handling (al-khaser/Al-khaser.cpp)

Add Sandbox Detection for New Tool

1. Identify process name or module of analysis tool (e.g., 'winafl.exe', 'frida-agent.dll') (al-khaser/AntiAnalysis/process.cpp)
2. Add process/module name string to detection list in process.cpp (al-khaser/AntiAnalysis/process.cpp)
3. Optionally add registry key or file path checks for tool presence (al-khaser/AntiAnalysis/process.cpp)

Add Assembly-Level Anti-Disassembly Sequence

1. Create polymorphic instruction sequence in AntiDisassm_x86.asm or AntiDisassm_x64.asm (al-khaser/AntiDisassm/AntiDisassm_x86.asm)
2. Use conditional jumps, ambiguous instructions, or data-as-code tricks (al-khaser/AntiDisassm/AntiDisassm_x86.asm)
3. Export function and wrap in C++ interface in AntiDisassm.cpp (al-khaser/AntiDisassm/AntiDisassm.cpp)

Windows-only: All code uses Win32 API—will not compile on Linux/macOS without Wine/Cygwin. Visual Studio dependency: Requires MSVC 2019+ or msbuild; GCC/Clang Windows support untested. Admin/elevated privileges: Many checks (NtQueryInformationProcess, registry reads) work best with elevated integrity; behavior differs in user-mode sandboxes. Sleep command: --sleep parameter is mandatory for timing-attack tests; short sleeps (e.g., 5s) may not trigger sandbox behavioral analysis. Signed vs. unsigned: Release binaries may be signed; running unsigned custom builds may bypass detection by design (intentional gap).

• CPUID instruction — Al-khaser uses CPUID (via inline assembly) to detect VM hypervisors by checking for signature strings ('QEMU', 'KVM', 'Xen', 'VirtualBox') in the CPU vendor field; essential for understanding CPU-level VM detection.
• PEB (Process Environment Block) — BeingDebugged.cpp and NtGlobalFlag.cpp read the PEB directly to detect debuggers via the IsDebugged flag and NtGlobalFlag field; understanding PEB layout is key to kernel-level evasion techniques.
• Hardware breakpoints (Dr* registers) — HardwareBreakpoints.cpp inspects x86 debug registers (DR0–DR7) to detect debugger hooks; this is CPU-level stealth detection invisible to user-mode APIs.
• NtQueryInformationProcess (Native API) — Al-khaser uses this undocumented kernel API (via direct syscall or ntdll.dll) to query process debug flags, debug port, and debug object—more reliable than high-level API calls for debugger detection.
• Timing attacks (rdtsc, Sleep evasion) — Timing_Attacks module uses RDTSC (Read Time Stamp Counter) and Sleep() delays to detect sandbox slowdown or redirection; sandboxes often skip sleep or execute code slower, revealing themselves.
• Code injection & code caves — AntiAnalysis/process.cpp detects code injection indicators (loaded DLLs from atypical paths, hook detours) and Module-level tampering; understanding how malware hides injected code is core to al-khaser's philosophy.
• VM device signatures (PCI, ATA) — ATAIdentifyDump tool and VM detection modules enumerate PCI devices and ATA controller data to identify hypervisor-provided devices (e.g., 'VBOX' in device names); physical signature enumeration bypasses CPUID spoofing.

• a0rtega/pafish — Similar malware evasion PoC in C for Windows; detects virtual machines and analysis tools with lighter footprint than al-khaser
• LordNoteworthy/al-khaser-linux — Linux counterpart attempting port of al-khaser techniques to Linux (if it exists; validates cross-OS evasion patterns)
• zodiacon/ProcessExplorer — Complement tool for analyzing running processes and their handles; useful for validating what al-khaser detects
• zodiacon/WinSyscalls — Win32/Native API reference and syscall hooking framework; essential for understanding NtQueryInformationProcess internals that al-khaser exploits
• hasherezade/hollows_hunter — Malware analysis & hunting tool that detects many of the injection/evasion techniques al-khaser performs; inverse relationship useful for validation

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 comprehensive unit tests for AntiDebug detection techniques

The repo contains 20+ AntiDebug techniques (BeingDebugged, HardwareBreakpoints, NtQueryInformationProcess variants, etc.) but no visible test suite. Adding unit tests would validate detection accuracy, prevent regressions, and help contributors understand expected behavior for each technique.

• [ ] Create al-khaser/Tests directory with a test project in the .sln
• [ ] Write tests for each AntiDebug/*.cpp file covering success/failure cases
• [ ] Test edge cases like when debugger is present vs. absent
• [ ] Add test execution to .github/workflows/build.yml to run on each PR
• [ ] Document test patterns in Tools/StructDumpCodegen/README.md or create Tests/README.md

Implement missing AntiVM detection techniques from the description

The README lists 'Anti-VM' as a feature, but the file structure shows no AntiVM directory (unlike the complete AntiDebug folder). This suggests core VM detection techniques are missing or incomplete, representing a major gap in the PoC malware toolkit.

• [ ] Create al-khaser/AntiVM directory structure
• [ ] Implement common VM detection: CPUID checks (VirtualBox, VMware, Hyper-V signatures)
• [ ] Add registry heuristics (HKLM checks for VM vendor strings)
• [ ] Add device driver checks (vmmouse, VBoxGuest) via WMI or file enumeration
• [ ] Create AntiVM/README.md documenting each technique with references
• [ ] Update Al-khaser.cpp main function to include AntiVM checks in --check options

Add structured logging/reporting system with JSON output support

Currently the tool appears to run checks but output format is unclear from the codebase. Adding a structured logging system with JSON export would make results machine-parseable, help security researchers correlate findings, and improve usability for batch analysis.

• [ ] Create al-khaser/Logging directory with Logger.h/Logger.cpp interfaces
• [ ] Implement JSON output formatter (e.g., output each detection as {check_name, result, timestamp})
• [ ] Refactor Al-khaser.cpp to use Logger instead of direct console output
• [ ] Add --output-format flag (console/json) to command-line argument parsing
• [ ] Add examples in README.md showing JSON output format and sample results

• Add unit tests for AntiDebug checks: Create a test harness in al-khaser/Tests/ that mocks NtQueryInformationProcess and validates BeingDebugged.cpp, IsDebuggerPresent.cpp return values under debugger vs. non-debugger conditions (currently zero test coverage visible).
• Document VirtualBox detection signatures: Add comments to the CPUID and device enumeration logic in the VM detection modules explaining which bits/device names map to VirtualBox 6.x vs. 7.x (knowledge gap for contributors).
• Implement Bochs/GirtualBox detection: Neither emulator has a dedicated check file (only VBOX, VMWARE, QEMU, etc.); add al-khaser/AntiAnalysis/BochsDetect.cpp using CPUID 0x40000000 'Bochs' signature and TSC timing checks.

al-khaser is a proof-of-concept malware application explicitly designed to evade security analysis and detection. While the authors claim good intentions for stress-testing security systems, the codebase implements functional anti-debugging, anti-VM, sandbox evasion, and anti-analysis techniques typically used by actual malware. The project lacks adequate security warnings, code signing, and usage restrictions. Security score reflects that this is intentionally malicious code with minimal safeguards. This project should ONLY be used by authorized security professionals in isolated, controlled environments. Unauthorized possession, distribution, or execution of this code may violate laws in many jurisdictions.

• High · Malware PoC Application - Intentional Malicious Code — al-khaser/ (entire project). al-khaser is explicitly designed as a proof-of-concept malware application that implements common malware evasion techniques including anti-debugging, anti-VM detection, sandbox evasion, and anti-analysis methods. While labeled as having 'good intentions' for testing security systems, the codebase contains functional malware implementations that could be repurposed for malicious use. Fix: This application should only be used in isolated, controlled security testing environments with proper authorization and oversight. Access should be restricted to authorized security researchers only. Consider adding runtime restrictions, code signing verification, and audit logging for any execution.
• High · Anti-Debugging Techniques - Evasion of Security Analysis — al-khaser/AntiDebug/. The AntiDebug directory contains implementations of multiple debugger detection techniques (IsDebuggerPresent, CheckRemoteDebuggerPresent, Hardware Breakpoints, NtQueryInformationProcess variants, etc.) that actively prevent legitimate security analysis and reverse engineering. This allows malicious code to evade detection and analysis. Fix: These techniques should be documented clearly for educational purposes only. In production environments, implement monitoring for processes attempting to detect debugging rather than allowing them to succeed undetected.
• High · Anti-VM and Sandbox Detection — al-khaser/AntiAnalysis/ (likely contains VM/sandbox detection). The codebase includes anti-virtualization and sandbox detection mechanisms that prevent execution in analysis environments. This allows potentially malicious behavior to execute only on real systems, bypassing automated security analysis. Fix: Use in isolated test environments only. Implement detection for anti-analysis techniques at the hypervisor/sandbox level rather than relying on signature-based approaches.
• Medium · Lack of Input Validation Documentation — al-khaser/Al-khaser.cpp. The command-line interface accepts --check <type> parameters with documented types like 'TLS' but the file structure does not clearly show input validation mechanisms for these parameters. Potential for unexpected behavior if invalid types are provided. Fix: Implement strict whitelist validation for the --check parameter. Document all valid options and provide clear error messages for invalid inputs.
• Medium · Missing Security Documentation — README.md. While the README exists, there is no explicit WARNING or DISCLAIMER about the malware nature of the code in prominent locations. Users cloning this repository may not immediately understand the security implications. Fix: Add a prominent security warning at the top of README.md stating this is a malware PoC and should only be used in authorized security testing. Include legal disclaimers and requirements for responsible use.
• Medium · No Code Signing or Integrity Verification — al-khaser/. The project appears to lack code signing or integrity verification mechanisms, making it difficult to ensure the downloaded code hasn't been tampered with and increasing supply chain risk. Fix: Implement code signing for releases. Provide checksums (SHA-256) for all compiled binaries and source distributions.
• Low · Potential for Misuse Without Authorization — al-khaser/ (entire project). The codebase could be used maliciously if obtained by unauthorized parties. No built-in safeguards exist to prevent misuse beyond legal restrictions. Fix: Consider implementing geofencing, hardware-based licensing, or environment checks that restrict execution in production environments. However, note that any such protection can be reversed.

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.