Bug Killer (bug-killer / bk)

Autonomous Vulnerability Discovery & Self-Healing Engine for Deep and Ghosty Bugs

"Let Your AI Find The Deep and Ghosty Bugs, Vulnerabilities, Security Issues and Heal From It — Tested & Verified."

Bug Killer is an offline-first, polyglot defensive security system engineered to discover elusive runtime memory corruptions, verify reachability through static binary disassembly and kernel memory maps, execute atomic self-healing repairs, and guarantee bit-for-bit rollback.

Initial benchmark targets:

• PHP2Shell (CVE-2026-109618 & CVE-2026-109619): Zend Engine allocator longjmp OOM heap corruption and persistent worker Use-After-Free.
• Node2Shell (CVE-2026-111497): Bundled Google Brotli decoder out-of-bounds memory write in node:zlib.

Fast Installation

Choose the installation method suited to your environment:

Method 1: Universal 1-Line Installer (macOS & Linux)

curl -fsSL https://raw.githubusercontent.com/imMamdouhaboammar/bug-killer/master/scripts/install.sh | bash

Installs bk and bug-killer into ~/.local/bin, generates shell auto-completions for Bash/Zsh/Fish, and runs system health diagnostics.

Method 2: Global NPM / Bun Package

# Using Bun (recommended)
bun add -g bug-killer-cli

# Or using NPM / NPX
npm install -g bug-killer-cli

# Or execute instantly without permanent installation
npx bug-killer-cli init

Method 3: Cargo (Rust Toolchain)

# Install directly from GitHub
cargo install --git https://github.com/imMamdouhaboammar/bug-killer.git --bin bk --bin bug-killer

# Or from a local clone
cargo install --path .

Method 4: Makefile / System Install

make build
sudo make install

Both bk (concise daily CLI) and bug-killer (canonical binary) are available on your PATH.

Quickstart for Any Project

Run three commands in any repository (Python, Node/TS, Go, Rust, PHP, C/C++, Docker):

# 1. Onboard project (detects stack, sets baseline, installs pre-commit hook)
bk init

# 2. Run a fast security scan (<50ms, ideal for pre-commit & CI)
bk security scan . --profile quick

# 3. Configure Model Context Protocol (MCP) for Cursor, Claude Code, or Gemini CLI
bk mcp config --host cursor

To run a machine-readable scan report:

bk security scan . --profile quick --json

Initialization (bk init) writes project security configuration (.bugkiller/config.json), runs a baseline scan, protects identity keys in .gitignore, and installs a non-destructive Git pre-commit hook by default. Run a read-only scan first (bk security scan . --profile quick) if you only want to inspect the project without configuring it.

🤖 Copyable Agent Prompt (For Cursor, Claude Code, Gemini CLI, Copilot)

Copy and paste this directive directly into your AI coding assistant (Cursor chat, Claude Code, Gemini CLI, Windsurf, or Antigravity) to have it install, configure, and audit your project automatically:

You are paired with me on this repository. We are adopting **Bug Killer (`bk`)** as our defensive security analysis, vulnerability detection, and virtual healing framework.

Execute the following setup and audit sequence autonomously:

1. **Verify or Install Bug Killer:**
   Check if `bk` is installed (`command -v bk`). If not found, install via:
   ```bash
   curl -fsSL https://raw.githubusercontent.com/imMamdouhaboammar/bug-killer/master/scripts/install.sh | bash
   # Or via npm/bun: bun add -g bug-killer-cli
   ```

2. **Run System & Environment Diagnostics:**
   ```bash
   bk doctor .
   ```

3. **Initialize Repository Baseline & Pre-Commit Security Gate:**
   ```bash
   bk init .
   ```
   *This detects our tech stack, creates `.bugkiller/config.json`, computes a clean baseline snapshot, safeguards keys in `.gitignore`, and installs the staged Git pre-commit hook.*

4. **Audit for Vulnerabilities & Taint Exposures:**
   ```bash
   bk security scan . --profile project
   bk scan . --taint --osv
   ```

5. **Examine Findings & Plan Safe Remediation:**
   - If vulnerabilities or exposures are detected:
     - Run `bk evidence <finding-id> .` to inspect verified AST/taint traces and cryptographic receipts.
     - Run `bk plan <finding-id> .` to generate a deterministic, non-mutating virtual patch preview.
     - Present the evidence and plan to me before any state mutation.

One place to assess, investigate, and repair

A scanner finding is the start of a security decision. You still need to know which files and dependencies were checked, whether the issue affects the running software, and whether a proposed fix survives verification.

Bug Killer brings those steps together:

1. Inspect the target. Inventory source files, manifests, runtimes, and applicable security checks.
2. Collect evidence. Record findings, affectedness, uncertainty, and gaps in scan coverage.
3. Investigate. Use source analysis, optional advisory lookups, bounded agent investigations, or approved runtime checks.
4. Plan the repair. Review a proposed change before granting write access.
5. Verify the result. Recheck the affected property and retain rollback evidence when a change is approved.

What works in the current code

The source also contains an analyzer adapter registry, an execution protocol, and a benchmark harness. Connecting a mature external scanner does not automatically make it part of a released scan profile. Availability, license, output fidelity, and coverage must be tested per adapter.

Common workflows

Check a repository or CI job

bk security scan . --profile project --json
bk security scan . --profile ci --fail-on high
bk security scan . --profile quick --staged

--staged evaluates the staged Git snapshot for pre-commit use. CI can block on findings or incomplete mandatory coverage; a report with no findings is not proof that every check ran.

Investigate a dependency or runtime

bk doctor . --json
bk scan . --check-runtime --json
bk scan . --osv --taint --json
bk cve-info CVE-2026-109618

--osv makes external advisory requests. Use it when the workspace and network policy permit those requests. Live endpoint probing is separate and requires authorization for the exact target.

Get security guidance for a coding task

bk security guidance "Add a file upload endpoint" --language rust
bk security catalog --json
bk agent doctor --provider local --json

Guidance and model-generated hypotheses are inputs for review. They do not certify that code is safe or authorize a fix.

Preview a fix, then use operator approval

bk heal . --dry-run
bk evidence <finding-id> .
bk plan <finding-id> .

After provisioning a separate operator signing key and reviewing the plan, the authorized operator can use bk approve and bk apply. See Operator approval setup for the trust and receipt requirements.

bk heal --apply and bk heal --auto-apply are deprecated shortcuts that the CLI rejects. They cannot bypass independent approval. A successful patch command alone does not prove remediation.

Connect a coding agent through MCP

bk mcp config --host codex
bk mcp config --host claude
bk mcp serve --transport stdio .

The configuration command prints host-specific examples. The MCP server communicates over standard input and output; it does not expose a network listener by default. See the operator guide for scope and permission details, and the sibling tools specification for external engine broker coordination.

Microservices architecture

The Rust CLI is the main local entry point. Additional services cover inventory, binary inspection, and supervised host changes. They are separate build targets, so ordinary source scans do not require starting the full service stack.

flowchart TD
    A["Authorized project or host"] --> B["Rust CLI and security guard"]
    B --> C["Built-in analysis and optional advisory checks"]
    C --> D["Findings, coverage, and evidence"]
    D --> E["Review and operator approval"]
    E --> F["Scoped repair and independent verification"]
    G["Go inventory and Rust inspector services"] --> D
    F --> H["Rollback records"]

Polyglot specialization matrix

Build the full stack

The full build needs Rust, Go 1.26.5 or a compatible newer toolchain, Make, and platform-specific native dependencies. Inspector and orchestrator builds may require protobuf and libpcap development packages.

make build
make test
make lint

To install the resulting executables, choose an appropriate PREFIX and run make install with write permission to that directory. The Makefile's default is /usr/local/bin and shell completions are installed to /usr/local/share (SHARE_PREFIX).

Shell Auto-Completions

Bug Killer distributes pre-generated, drift-checked completion scripts under completions/ for Bash, Zsh, and Fish:

# Generate dynamically for any supported shell (bash, zsh, fish, powershell, elvish)
bug-killer completion bash > ~/.local/share/bash-completion/completions/bug-killer
bug-killer completion zsh > ~/.zsh/completion/_bug-killer
bug-killer completion fish > ~/.config/fish/completions/bug-killer.fish

# Or regenerate and install from repository assets
make completions
sudo make install

Docker Compose is available for controlled Linux-host deployments. Access to /var/run/docker.sock can grant broad host control, even when mounted read-only. Use the service stack only on hosts where that access is explicitly approved.

The agentic security room roadmap

The Ultimate Spec defines Bug Killer's next product direction: an agentic workspace that selects and coordinates mature security tools, keeps their evidence separate, and helps a human approve and verify repairs.

The goal is coordination over reinvention. Existing engines do the specialized analysis. Bug Killer selects them, enforces scope and budgets, records what actually ran, and presents evidence that a developer or security reviewer can act on.

The architecture is deliberately incremental. A registered tool, a catalog entry, or an agent's confident explanation is never enough to claim complete security coverage.

• Operations-room architecture and integration decisions
• Milestones and implementation gates
• Benchmarks and verification requirements
• Documentation Architecture & Canonical Hierarchy Map

Development and verification

cargo test --workspace
cargo clippy --all-targets -- -D warnings

# Run from each Go service directory
cd services/orchestrator && go test -v ./... && go vet ./...
cd ../healer && go test -v ./... && go vet ./...

The separate Rust inspector has its own tests under services/inspector. The repository's make test and make lint targets cover the configured Rust and Go projects.

Security reports need more than a passing build. Detection claims require reproducible fixtures and coverage receipts; repair claims require a fresh recheck of the changed target. See the contribution instructions and security policy.

License and responsible use

Bug Killer uses the Source-Available & Business Attribution License v1.0, copyright © 2026 Mamdouh Aboammar.

• You may inspect, fork, modify, and contribute while retaining the required attribution and license terms.
• Internal use by businesses, non-profits, educational organizations, and government teams is permitted without royalties.
• Selling Bug Killer or derivatives, or offering them as a paid hosted or managed security service, requires separate written commercial authorization.
• Public derivatives must retain the same license terms, copyright, and author attribution.

The LICENSE governs use and redistribution. Third-party analyzers and their rules may carry separate terms.

Only assess systems you own or have explicit permission to test. Bug Killer's defensive scope excludes weaponized exploits and unauthorized probing. Report issues in Bug Killer itself through SECURITY.md.