Onboarding: beefproject/beef

Generated by RepoPilot · 2026-05-07 · Source

Agent protocol

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/beefproject/beef 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.

Verdict

WAIT — Missing license — unclear to depend on

• Last commit today
• 4 active contributors
• Distributed ownership (top contributor 34% of recent commits)
• CI configured
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ No license — legally unclear to depend on
• ⚠ No test directory detected

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

Verify before trusting

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

What it runs against: a local clone of beefproject/beef — 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 beefproject/beef | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>beefproject/beef</code></summary>

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

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

# 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 "core/core.rb" \\
  && ok "core/core.rb" \\
  || miss "missing critical file: core/core.rb"
test -f "core/api/main/server.rb" \\
  && ok "core/api/main/server.rb" \\
  || miss "missing critical file: core/api/main/server.rb"
test -f "core/main/client/beef.js" \\
  && ok "core/main/client/beef.js" \\
  || miss "missing critical file: core/main/client/beef.js"
test -f "core/bootstrap.rb" \\
  && ok "core/bootstrap.rb" \\
  || miss "missing critical file: core/bootstrap.rb"
test -f "core/loader.rb" \\
  && ok "core/loader.rb" \\
  || miss "missing critical file: core/loader.rb"

# 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/beefproject/beef"
  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).

</details>

TL;DR

BeEF (Browser Exploitation Framework) is a penetration testing tool written in Ruby that hooks web browsers and uses them as attack platforms to assess client-side security posture. It allows security professionals to launch directed command modules and exploits against systems from within the browser context, focusing on web-borne attack vectors that bypass network perimeters. Monolithic Ruby on Rails structure with core/ directory containing the framework engine: core/api.rb and core/api/ subdirectories manage extensions and modules, core/api/main/ contains the server (hook.rb), network stack, and configuration. Frontend is JavaScript-heavy (2.6M LOC) for browser-side exploitation logic. Modules live in core/modules. Configuration driven by conf.json and config.yaml.

Who it's for

Professional penetration testers and security auditors who need to assess real-world browser-based vulnerabilities in target environments during authorized security assessments. Developers building browser security tools will also find the codebase instructive.

Maturity & risk

Actively maintained and production-ready. The project has been actively developed since 2006 (20-year history), uses CI/CD pipelines (CodeQL, dependabot automation in .github/workflows/), has comprehensive test coverage, and maintains a large codebase (2.6M lines of JavaScript, 1.2M lines of Ruby). Recent GitHub Actions workflows and active dependabot integration indicate ongoing maintenance.

Moderate risk. The codebase is large and complex with heavy JavaScript/Ruby dependencies listed in Gemfile and Gemfile.lock, creating a broad attack surface. Windows is explicitly unsupported (macOS/Linux only), limiting deployment flexibility. The project handles sensitive security operations (browser exploitation), so any unpatched vulnerability could have serious implications; reliance on accurate version pinning in Gemfile.lock is critical.

Active areas of work

Active development visible through GitHub Actions workflows (CodeQL security scanning, dependabot auto-merge, stale issue management). The .github/workflows/ directory shows CI/CD pipeline maturity. Recent attention to dependencies and security scanning suggests the team is focused on keeping the codebase current and secure.

Get running

git clone https://github.com/beefproject/beef.git
cd beef
./install
./beef

The install script (referenced in README) handles OS package and Ruby gem dependencies. BeEF requires Ruby 3.0+, SQLite 3.x, and Node.js 10+.

Daily commands:

./beef

Follows standard Sinatra startup convention. Configuration is read from conf.json and config.yaml. The beef script (no extension) in repo root is the entrypoint. Gem dependencies are managed by Bundler (Gemfile/Gemfile.lock).

Map of the codebase

• core/core.rb — Main entry point and orchestrator for the BeEF framework; initializes all core components and extensions.
• core/api/main/server.rb — HTTP server configuration and request handling; core of the command-and-control interface.
• core/main/client/beef.js — Client-side JavaScript bootstrap that initializes the hooked browser and establishes communication with BeEF server.
• core/bootstrap.rb — Framework initialization and dependency loading; must understand startup sequence before contributing.
• core/loader.rb — Dynamic module and extension loader; critical for understanding how BeEF discovers and registers attack modules.
• core/api/modules.rb — Module registry and lifecycle management; defines how command modules are loaded and executed.
• Gemfile — Ruby dependency manifest; required for setting up development environment and understanding external libraries.

Components & responsibilities

• BeEF Core (core/core — undefined

How to make changes

Add a New Attack Module

1. Create a new module file in modules/ directory inheriting from BeEF::Core::Models::CommandModule (core/api/module.rb)
2. Define module metadata (name, description, targets) and register command handler (core/api/modules.rb)
3. Implement execute() method with your attack payload logic (core/api/module.rb)
4. Optionally add client-side JavaScript execution in core/main/client/ subdirectories (core/main/client/beef.js)

Add a New Extension

1. Create new extension directory with models, views, and controllers (core/extension.rb)
2. Register extension in core/extensions.rb with load path and dependencies (core/extensions.rb)
3. Add routes and API endpoints to your extension controller (core/api/main/server.rb)
4. Create ActiveRecord migrations in core/main/ar-migrations/ if persistence needed (core/main/ar-migrations/002_create_hooked_browsers.rb)

Add a New Client-Side Capability

1. Create new JavaScript module in core/main/client/ following existing patterns (browser.js, dom.js) (core/main/client/beef.js)
2. Register capability in beef.js initialization to expose to modules (core/main/client/init.js)
3. Add network communication layer in core/main/client/net/ if server sync needed (core/main/client/net/connection.js)

Add Request/Response Filtering

1. Create new filter class in core/filters/ inheriting from base.rb (core/filters/base.rb)
2. Implement before/after hooks for request/response processing (core/filters/browser.rb)
3. Register filter in core/filters.rb filter chain (core/filters.rb)

Why these technologies

• Ruby on Rails / Sinatra — Provides rapid development of the C2 server, HTTP routing, and ORM layer; mature security tooling; good for penetration testing tools.
• JavaScript (Client-side) — Executes in victim browser context with full DOM access; only language that can run natively in all modern browsers.
• ActiveRecord + SQLite/MySQL — Persistent storage of hooked browsers, command history, and results; allows historical analysis and audit trails.
• WebSocket + Long-polling HTTP — Low-latency C2 communication; WebSocket for real-time command dispatch, fallback to polling for restricted networks.

Trade-offs already made

• Modular, dynamic module loading via file convention

  • Why: Allows security researchers to add custom attack modules without recompiling framework; lowers barrier to contribution.
  • Consequence: Requires robust error handling and module validation; easier to introduce malicious/broken modules.

• Client-side polling vs. server push

  • Why: Polling avoids NAT/firewall traversal complexity; works in restricted corporate networks.
  • Consequence: Higher latency (5–60s depending on poll interval); more server load; less interactive user experience.

• In-process HTTP server (Thin/WEBrick) vs. separate app container

  • Why: Simplifies single-machine deployments; no additional infrastructure required.
  • Consequence: Limited horizontal scaling; single point of failure; harder to separate concerns for large penetration tests.

• Monolithic client-side beef.js payload

  • Why: Single injection point; all capabilities loaded together; simpler browser hooking.
  • Consequence: Large payload (~50KB+ minified); can be detected by size/signature; harder to customize per-target.

Non-goals (don't propose these)

• Real-time bidirectional server push without client polling
• Automatic payload obfuscation or evasion of security controls
• Multi-browser coordination (Scenario: attacker controls 10k browsers simultaneously)
• Encrypted C2 channel by default (relies on HTTPS at deployment layer)
• Mobile browser exploitation (focus is desktop browsers)
• Mitigation against browser Content Security Policy (CSP) hardening

Traps & gotchas

Critical: BeEF requires HTTPS by default for browser communication (beef_cert.pem and beef_key.pem must exist; see CONTRIBUTING.md for security guidance). Version pinning: Ruby 3.0+ is hard requirement; older Ruby will silently fail. Platform: Explicitly unsupported on Windows (macOS/Linux only); cross-platform issues are low priority. Selenium dependency (noted in README) is for testing only, not core functionality. Database migrations exist (core/api/main/migration.rb) and must run on schema changes. Configuration persistence: changes to conf.json require server restart.

Architecture

Concepts to learn

• Browser hooking — Core BeEF capability: injecting JavaScript into target browsers to establish persistent command channels; essential to understand how core/api/main/network_stack/assethandler.rb and browser-side JS communicate
• Client-side attack vectors — BeEF's entire premise is exploiting vulnerabilities in the browser client (XSS, CSRF, drive-by downloads) rather than network/server sides; understanding attack surface is critical before writing modules
• Sinatra/Ruby web routing — The API server (core/api/main/server.rb) uses Sinatra conventions for RESTful routing; knowing Sinatra DSL is essential for modifying API endpoints or adding new server routes
• Module plugin architecture — BeEF uses a modular loader system (core/extensions.rb, core/modules.rb) where commands are dynamically loaded; understanding how modules register and execute is critical for adding new exploitation features
• Content Security Policy (CSP) evasion — Modern browser protections like CSP can block injected hooks; BeEF modules must account for CSP policies, making this a recurring challenge in module development
• SQLite persistence layer — BeEF stores hooked browser state, command results, and session data in SQLite; understanding migrations (core/api/main/migration.rb) is necessary for schema changes
• Filter pipeline (aspect-oriented security) — The core/filters/ directory implements before/after hooks for browser commands, HTTP requests, and execution—understanding this pattern is essential for adding security controls or logging middleware

Related repos

• metasploit-framework/metasploit-framework — Industry-standard penetration testing framework; BeEF complements it by focusing specifically on browser-based vectors while Metasploit covers broader network exploitation
• projectdiscovery/nuclei — Modern vulnerability scanning engine; users of BeEF for browser testing often pair it with Nuclei for template-based exploit validation
• beefproject/beef-modules — Official separate repository for community-contributed BeEF command modules; extends core framework with additional exploits and payloads
• mitmproxy/mitmproxy — HTTP proxy used alongside BeEF for intercepting and analyzing browser traffic during penetration tests
• owasp/owasp-zap — OWASP security scanner often used in conjunction with BeEF for comprehensive web application security testing

PR ideas

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 RSpec unit tests for core/api/main/configuration.rb and core/api/main/migration.rb

The repo has a .rspec configuration file and Rakefile present, indicating a Ruby/RSpec testing setup, but there are no visible test files in the file structure for critical core configuration and migration logic. These modules handle server configuration and database migrations, which are critical paths. Adding comprehensive unit tests would catch regressions early and improve maintainability for new contributors.

• [ ] Create spec/core/api/main/configuration_spec.rb with tests for configuration loading, validation, and edge cases
• [ ] Create spec/core/api/main/migration_spec.rb with tests for database migration execution and rollback scenarios
• [ ] Add test fixtures for sample config.yaml and conf.json files in spec/fixtures/
• [ ] Run tests locally with bundle exec rspec and ensure 80%+ coverage for these modules
• [ ] Update .github/workflows/github_actions.yml to include RSpec test execution in CI/CD pipeline if not already present

Add integration tests for core/api/main/network_stack/assethandler.rb and server.rb

The network stack and asset handler are critical for BeEF's core functionality (hooking browsers and serving payloads), but there's no visible test coverage in the file structure. Adding integration tests would verify that the HTTP server correctly handles asset serving, routing, and browser hooking requests without breaking across Ruby versions or dependency updates.

• [ ] Create spec/core/api/main/network_stack/assethandler_spec.rb with tests for asset serving, MIME types, and path traversal prevention
• [ ] Create spec/core/api/main/server_spec.rb with integration tests for server startup, port binding, and basic HTTP request/response handling
• [ ] Add test fixtures in spec/fixtures/assets/ with sample files to test serving various content types
• [ ] Test against the Dockerfile Ruby version to ensure compatibility
• [ ] Document test setup in .github/CONTRIBUTING.md for new contributors

Add migration validation and rollback tests for core/main/ar-migrations/

The migrations directory contains 15 ActiveRecord migrations (001-015) that set up the database schema, but there are no visible tests validating migration integrity, sequencing, or rollback safety. This is critical because broken migrations block new deployments. Adding migration tests would ensure migrations are idempotent and can be safely applied/reverted.

• [ ] Create spec/core/main/ar_migrations_spec.rb with tests that run each migration in sequence and verify schema state
• [ ] Add rollback tests for each migration to ensure data safety and reversibility
• [ ] Create a test database fixture/seed to verify migrations work against realistic data
• [ ] Test migration up/down in GitHub Actions for each push to catch breaking changes early
• [ ] Document migration guidelines in .github/CONTRIBUTING.md for contributors adding new migrations

Good first issues

• Add missing unit tests for core/filters/ subdirectories (browser.rb, command.rb, http.rb); these filtering modules handle sensitive operations but test coverage is unclear from file listing
• Improve inline documentation for core/api/extensions.rb and core/api/modules.rb—the extension loading system is complex and lacks clear docstrings explaining the plugin architecture
• Create a migration guide or example in the wiki for upgrading from Ruby 2.7 to 3.0+, since the codebase now requires Ruby 3.0 minimum but no upgrade docs exist in the visible file structure

Top contributors

• @github-actions[bot] — 34 commits
• @dependabot[bot] — 34 commits
• @zinduolis — 27 commits
• @jake-the-dev — 5 commits

Recent commits

• c27f459 — Merge pull request #3561 from beefproject/dependabot/bundler/sqlite3-2.9.4 (github-actions[bot])
• 930427e — Build(deps): bump sqlite3 from 2.9.3 to 2.9.4 (dependabot[bot])
• 2fe2762 — Merge pull request #3559 from beefproject/dependabot/bundler/rubyzip-3.3.0 (github-actions[bot])
• 8d57c78 — Build(deps): bump rubyzip from 3.2.2 to 3.3.0 (dependabot[bot])
• 2c4c572 — Merge pull request #3556 from beefproject/dependabot/bundler/curb-1.3.2 (github-actions[bot])
• 17882ca — Build(deps-dev): bump curb from 1.3.1 to 1.3.2 (dependabot[bot])
• 10d88ec — Merge pull request #3555 from beefproject/dependabot/bundler/irb-1.18.0 (github-actions[bot])
• 4178ab6 — Build(deps-dev): bump irb from 1.17.0 to 1.18.0 (dependabot[bot])
• 4d4fd9a — Merge pull request #3554 from beefproject/dependabot/bundler/json-2.19.4 (github-actions[bot])
• f3f747f — Build(deps): bump json from 2.19.2 to 2.19.4 (dependabot[bot])

Security observations

• Critical · Default Credentials in Docker Configuration — Dockerfile, config.yaml. The Dockerfile explicitly warns that BeEF does NOT allow authentication with default credentials (beef:beef), but the presence of config.yaml and the warning itself indicates default credentials may be present in the repository or documentation. This is a critical security issue as the default credentials could be used to compromise the entire BeEF instance. Fix: Ensure no default credentials are shipped with the codebase. Generate strong, unique credentials during deployment. Implement credential rotation policies and never commit credentials to version control.
• Critical · Hardcoded SSL/TLS Certificates — beef_cert.pem, beef_key.pem. The presence of beef_cert.pem and beef_key.pem files in the root directory indicates hardcoded SSL/TLS certificates are included in the repository. These certificates are exposed to anyone with repository access and should never be committed to version control. Fix: Remove hardcoded certificates from the repository immediately. Generate certificates dynamically during deployment. Use certificate management tools like Let's Encrypt or internal PKI. Add *.pem to .gitignore.
• High · Client-Side Code Injection Risks — core/main/client/*.js files. The presence of multiple JavaScript files in core/main/client/ (beef.js, browser.js, cookie.js, popup.js, dom.js, geolocation.js, base64.js, json.js) without visible sanitization patterns suggests potential XSS vulnerabilities. BeEF's nature as an exploitation framework means client-side code may be particularly vulnerable to injection attacks. Fix: Implement strict Content Security Policy (CSP) headers. Sanitize all user inputs and DOM operations. Use frameworks with built-in XSS protection. Conduct thorough security audits of all JavaScript code.
• High · Database Migration Files Without Input Validation — core/main/ar-migrations/*.rb. Multiple ActiveRecord migration files are present (001-025 in core/main/ar-migrations/) but without visible code inspection, there's high risk of SQL injection vulnerabilities in migration code and ORM usage throughout the application. Fix: Use parameterized queries and ORM features exclusively. Never concatenate user input into SQL queries. Implement input validation and sanitization for all database operations. Use prepared statements.
• High · API Endpoint Security — core/api/*, core/api/main/server.rb. Multiple API-related files (core/api.rb, core/api/extensions.rb, core/api/module.rb, core/api/main/configuration.rb) suggest an API layer without visible authentication/authorization controls in the file structure. This could expose sensitive functionality. Fix: Implement robust authentication (OAuth2, JWT) and authorization (RBAC) for all API endpoints. Apply rate limiting. Validate all inputs. Use API versioning. Document security requirements.
• High · No Visible Security Headers Configuration — core/api/main/server.rb, core/api/main/network_stack/assethandler.rb. The main server configuration (core/api/main/server.rb) and network stack components do not show explicit security header implementation (HSTS, X-Frame-Options, X-Content-Type-Options, etc.). Fix: Implement comprehensive security headers in HTTP responses. Add HSTS, X-Frame-Options, X-Content-Type-Options, X-XSS-Protection, Referrer-Policy, and CSP headers.
• High · Insecure Deserialization Risk — core/main/client/encode/json.js, core/*.rb files. The use of JSON encoding/decoding (core/main/client/encode/json.js) without visible deserialization controls could lead to insecure deserialization vulnerabilities, particularly in Ruby's YAML and JSON parsing. Fix: Never deserialize untrusted data. Use safe deserialization methods. Avoid YAML.load() in favor of YAML.safe_load(). Validate deserialized objects against strict schemas.
• Medium · Logging of Sensitive Information — core/logger.rb, core. The presence of core/logger.rb suggests logging functionality that may inadvertently log sensitive information such as authentication tokens, credentials, or personal data. Fix: undefined

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

Where to read next

• 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.