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/HavocFramework/Havoc 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 — Slowing — last commit 5mo ago

• Last commit 5mo ago
• 8 active contributors
• Distributed ownership (top contributor 38% of recent commits)
• GPL-3.0 licensed
• Tests present
• ⚠ Slowing — last commit 5mo ago
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows 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 HavocFramework/Havoc repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/HavocFramework/Havoc.

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

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

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

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

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

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "client/CMakeLists.txt" \\
  && ok "client/CMakeLists.txt" \\
  || miss "missing critical file: client/CMakeLists.txt"
test -f "client/data/Havoc.ui" \\
  && ok "client/data/Havoc.ui" \\
  || miss "missing critical file: client/data/Havoc.ui"
test -f ".gitmodules" \\
  && ok ".gitmodules" \\
  || miss "missing critical file: .gitmodules"
test -f "CONTRIBUTING.MD" \\
  && ok "CONTRIBUTING.MD" \\
  || miss "missing critical file: CONTRIBUTING.MD"

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

Havoc is a post-exploitation command and control (C2) framework written in Go (teamserver), C/ASM (Demon agent), and C++/Qt (client UI). It enables operators to generate payloads, manage multiple agents across HTTP/HTTPS/SMB listeners, and execute post-exploitation commands with advanced evasion techniques like sleep obfuscation (Ekko/Ziliean/FOLIAGE), indirect syscalls, and hardware breakpoint-based AMSI/ETW patching. Monorepo with three core components: client/ (C++ Qt UI, CMakeLists.txt build, data/UIs/ has .ui files for windows like AgentBuilder, Chat, Connect), teamserver/ (Go backend with CLI via Cobra, WebSocket communication), and agent/ (Demon agent in C/ASM with payload templates). CI/CD lives in .github/, assets and docs in root with external Python API (havoc-py) and Modules repos for extensibility.

Red teamers, penetration testers, and security researchers who need a malleable, modular C2 framework they can extend with custom agents (like Talon) and modules, supporting multiplayer collaborative operations through a central teamserver. Not for detection evasion out-of-the-box—designed for customization.

Active and production-grade: Go 1.21+ is required, the framework includes comprehensive post-exploitation capabilities (token vault, shellcode injection, lateral movement), has organized GitHub issue templates for bugs/features, and maintains separate documentation (WIKI.MD, Installation docs at havocframework.com). Clear maintenance signals through RELEASE.md and CONTRIBUTING.MD, though commit recency would need to be verified in git log.

Moderate production risk: The codebase mixes Go, C, C++, and Assembly requiring different toolchains (CMake, Qt 5+, Python 3.10+), and the README explicitly warns against opening detection-related issues, suggesting this is a research/red-team tool not hardened for offensive production use. Build fragility is acknowledged (README recommends latest Debian/Ubuntu/Kali versions). Depends on gorilla/websocket, Gin framework, and mattn/go-sqlite3, typical for Go projects but increases attack surface if used for sensitive ops.

Actively maintained: RELEASE.md and WIKI.MD suggest regular updates; .github/ISSUE_TEMPLATE/ contains specific templates for Demon, Documentation, and Teamserver-Client bugs plus Feature_Suggestion, indicating triaged issue management. The Discord community link and explicit CONTRIBUTING.MD signal active development. Recent emphasis on extensibility (External C2 support, Python API, custom agent framework) suggests evolution toward modularity.

Clone the repo: git clone --recursive https://github.com/HavocFramework/Havoc.git (note .gitmodules suggests submodules). Install dependencies per README (Qt modern version, Python 3.10+, CMake, Go 1.21+, C/C++ compiler for Demon). Build client: cd client && cmake . && make. Build teamserver: Go binary in respective folder. See client/README.md and client/config.toml for initial config.

Daily commands: Teamserver: ./teamserver -config config file (executable in main Go folder after build). Client: Launch compiled Qt binary or ./Havoc from client build directory. Listener setup via UI (HTTP/HTTPS/SMB listeners defined in Teamserver config). Agent: Generate Demon payloads via Client UI (AgentBuilder.ui), execution depends on listener type.

• README.md — Entry point documenting Havoc's purpose as a modern post-exploitation C&C framework and required dependencies (Qt, Python 3.10+)
• client/CMakeLists.txt — Build configuration for the Qt-based cross-platform client; essential for understanding compilation targets and dependencies
• client/data/Havoc.ui — Root UI definition for the main client application; defines the overall layout and core widgets loaded by the client
• .gitmodules — Declares submodule dependencies (likely Demon payload and teamserver modules) critical to the full framework architecture
• CONTRIBUTING.MD — Outlines contribution guidelines, coding standards, and submission process for maintaining framework consistency
• WIKI.MD — Links to comprehensive documentation on installation, usage, and architecture; essential reference for understanding design decisions
• LICENSE — Defines the legal terms under which the framework can be used and modified; necessary for compliance and fork/contribution clarity

Add a New Listener Type

1. Create a new .ui file in client/data/UIs/listenersBox/ (e.g., DemonSMB.ui) defining the configuration dialog (client/data/UIs/listenersBox/DemonHTTP.ui)
2. Update HavocListener.ui to register the new listener category in the main listeners tab (client/data/UIs/HavocListener.ui)
3. Reference the new UI in the client's C++ code structure (typically in client source, not shown in file list) (client/CMakeLists.txt)

Add a New Post-Exploitation Feature

1. Design the UI widget in client/data/UIs/ (e.g., ScreenCapture.ui for screenshot capability) (client/data/UIs/LootWidget.ui)
2. Integrate with the Demon agent payload by defining new command handlers (requires submodule access) (.gitmodules)
3. Connect the new UI to DemonInteracted.ui or create a new tab in Controler.ui for operator control (client/data/UIs/Controler.ui)

Add a New Operator Tool (Scripting/Automation)

1. Create a new .ui widget in client/data/UIs/ (e.g., PythonConsole.ui or ScriptDebugger.ui) (client/data/UIs/LuaScriptWidget.ui)
2. Register the new tool in the ScriptManager.ui or a new management interface (client/data/UIs/ScriptManager.ui)
3. Update client/config.toml to add configuration options for the new tool (e.g., script paths, timeouts) (client/config.toml)

Extend Multi-Operator Collaboration

1. Enhance Operators.ui and Operator.ui to add new permission roles or metadata fields (client/data/UIs/Operators.ui)
2. Update the teamserver backend (via submodule) to enforce new permission checks (.gitmodules)
3. Add corresponding UI updates to Chat.ui for operator-specific notifications or messages (client/data/UIs/Chat.ui)

• Qt (C++) for Client UI — Cross-platform desktop UI with native performance, rich widgets, and strong threading model for responsive long-running operations (file transfers, log streaming)
• Go for Teamserver Backend — Efficient concurrent agent handling via goroutines, fast compilation, strong standard library (crypto, net, database/sql), ideal for I/O-heavy C&C scenarios
• SQLite for Persistence — Lightweight embeddable database for agent metadata, credentials, logs, and multi-operator state without external dependencies
• WebSocket (gorilla/websocket) — Real-time bidirectional communication between client and teamserver for live agent updates, event streaming, and

1. Qt version constraint: README warns 'modern version of Qt' required; older distros may have incompatible versions—use Debian 10/11, Ubuntu 20.04/22.04+, or Kali (latest). 2) Python 3.10.x specifically: Not just any Python 3; build fails on 3.9 or 3.11 per README. 3) Recursive clone required: .gitmodules present suggests submodules; git clone --recursive necessary or agent/module deps will be missing. 4) Go 1.21.0+ mandatory: go.mod specifies exact version; older Go toolchains will fail. 5) Cross-compilation complexity: Demon (C/ASM) targets Windows; Linux build host needs cross-compile toolchain (mingw64 or similar). 6) Config.toml before run: client/config.toml must be edited with teamserver address; binary won't find default config otherwise. 7) Detection liability: README explicitly states 'do not open issues regarding detection'—framework is not opsec-hardened out-of-the-box; expect to add custom obfuscation.

• Indirect Syscalls — Demon agent uses indirect syscalls for Nt* API invocations to bypass user-mode API hooks (e.g., those placed by EDR); essential for understanding evasion in agent code
• Sleep Obfuscation (Ekko/Ziliean) — Havoc agents can obfuscate sleep calls to evade memory scanning or anomaly detection; the Demon agent integrates multiple sleep obfuscation backends, a core evasion capability
• WebSocket-based C2 Communication — The teamserver uses gorilla/websocket for duplex agent-client communication; understanding the WebSocket protocol is essential for analyzing network traffic, building custom listeners, or implementing External C2
• Hardware Breakpoint-based AMSI/ETW Patching — Demon uses CPU debug registers to set hardware breakpoints that intercept and patch AMSI (antimalware scanning interface) and ETW (event tracing for windows) at runtime; a sophisticated evasion technique leveraging undocumented kernel behavior
• Token Vault — Demon maintains a vault of stolen Windows access tokens for lateral movement and privilege escalation; understanding token management is key to leveraging post-exploitation capabilities
• Payload Generation (EXE/Shellcode/DLL) — Havoc teamserver generates multiple payload types from a single agent template; understanding the payload generation pipeline (profile-driven, modular encoding/obfuscation) is essential for adding new payload types or customizing delivery
• C2 Profiles (Customizable Protocol Definitions) — Havoc uses profiles to define beacon protocol behavior (beacon interval, jitter, HTTP headers, URI paths, encryption); profiles allow operators to adapt the C2 to match target environment or avoid detection signatures

• HavocFramework/Talon — Official custom agent example built for Havoc framework; demonstrates how to extend Havoc with new agent types beyond Demon
• HavocFramework/havoc-py — Official Python API client for Havoc; allows programmatic operator control and automation of teamserver and agents via Python scripts
• HavocFramework/Modules — Official module repository for Havoc; community-contributed post-exploitation and utility modules that extend agent capabilities
• Cracked5pider/Ekko — Referenced sleep obfuscation technique used in Demon agent to defeat beacon detection via sleep anomalies
• SecIdiot/FOLIAGE — Alternative sleep obfuscation library integrated into Demon for evading sleep-based detection patterns

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 GitHub Actions CI/CD pipeline for Go teamserver builds and tests

The repo has Go dependencies and a teamserver component but no visible CI workflow file in .github/workflows/. This is critical for a C2 framework where code quality directly impacts operator safety. A workflow should build the teamserver against Go 1.21.0, run go test, and verify dependencies don't have known vulnerabilities.

• [ ] Create .github/workflows/teamserver-build.yml with Go 1.21.0 matrix builds for Linux/Windows
• [ ] Add 'go test ./...' step to validate all packages in the teamserver
• [ ] Add 'go mod verify' and optional nancy/govulncheck for dependency scanning
• [ ] Reference Go module requirements from go.mod (golang.org/x/crypto, mattn/go-sqlite3, gin-gonic/gin, etc.)
• [ ] Ensure workflow triggers on PR and push to main branches

Add Qt UI compilation verification workflow for client builds

The client directory contains numerous .ui files (20+ Qt Designer UI files in client/data/UIs/) but no CI verification that these compile or that CMake builds succeed. This creates silent failure risk where UI changes break the build. Missing: CI workflow for Qt/CMake client builds.

• [ ] Create .github/workflows/client-build.yml targeting Ubuntu 20.04/22.04 as documented in README
• [ ] Install Qt dependencies and cmake as per client/CMakeLists.txt requirements
• [ ] Run 'cmake .' and 'make' in client/ directory to verify all .ui files and C++ code compile
• [ ] Add matrix for both Debian/Ubuntu variants mentioned in README to catch distro-specific issues
• [ ] Include validation that Havoc.qrc and Havoc.rc resources are properly referenced

Create TESTING.md with specific test execution instructions for teamserver and Demon payload builds

The repo has issue templates for Bug_Report-Demon, Bug_Report-Teamserver-Client, and Feature_Suggestion but no TESTING.md file explaining how to write/run tests. With Go modules present and a complex agent/listener architecture (shown in issue templates), new contributors cannot easily validate changes. CONTRIBUTING.MD exists but lacks test-specific guidance.

• [ ] Create TESTING.md documenting: (1) how to run teamserver tests, (2) how to test listener types (HTTP/SMB/External per screenshots), (3) Demon payload build validation
• [ ] Reference go.mod test dependencies and example test patterns for listeners, credentials, and agent command handling
• [ ] Include instructions for testing multi-user scenarios (shown in Screenshots/MultiUser.png and MultiUserAgentControl.png)
• [ ] Document manual testing checklist for generated shellcode and staged/stageless payload builds (per issue template naming)
• [ ] Cross-reference with existing CONTRIBUTING.MD and add link to TESTING.md there

• Add unit tests for teamserver listener creation logic (likely missing in Go code), starting with HTTP listener setup in main teamserver package, to improve CI reliability and catch regressions in listener binding.: Security-critical code path (listener management) with no visible test files in the structure; good high-impact starter task.
• Document the External C2 protocol spec (WIKI.MD mentions 'External C2' but file structure shows no formal spec file), create a markdown file in docs/ or update WIKI.MD with wire format, authentication flow, and example payloads for custom agent authors.: Extensibility is a core feature but protocol documentation appears absent; blocking new agent integrations like Talon.
• Add missing build instrumentation: create a Makefile or shell script wrapper in the root directory that automates Qt dependency check, CMake configure, and Go build for all three components (client, teamserver, agent) in one command, with error messages explaining version requirements.: README warns of frequent build issues on incompatible systems; a verified build script reduces onboarding friction and provides a single source of truth for the build matrix (Qt version, Go 1.21+, Python 3.10+).

• High · Outdated Go Crypto Library — go.mod - golang.org/x/crypto v0.27.0. The dependency golang.org/x/crypto v0.27.0 is relatively recent but should be monitored. While this version is not severely outdated, cryptographic libraries should always use the latest available version to ensure all security patches are applied. Fix: Regularly update golang.org/x/crypto to the latest version. Implement a dependency management strategy that includes periodic security audits of cryptographic libraries.
• Medium · Unencrypted WebSocket Communication — go.mod - github.com/gorilla/websocket v1.5.3. The codebase uses gorilla/websocket v1.5.3 for WebSocket communication. WebSocket connections may be vulnerable to man-in-the-middle attacks if not properly configured with TLS/SSL encryption, which is critical for a command and control framework handling sensitive operations. Fix: Ensure all WebSocket connections are configured to use WSS (WebSocket Secure) with proper TLS/SSL certificates. Validate that the client and teamserver enforce encrypted connections.
• Medium · SQLite Database Without Encryption — go.mod - github.com/mattn/go-sqlite3 v1.14.23. The framework uses mattn/go-sqlite3 v1.14.23 for database operations. SQLite databases are stored as plaintext files on disk and are not encrypted by default, which could expose sensitive data if the server is compromised. Fix: Implement database-level encryption using SQLCipher or similar solutions. Alternatively, encrypt sensitive data at the application level before storing in the database. Ensure proper file permissions on database files (0600).
• Medium · Gin Web Framework Security Configuration — go.mod - github.com/gin-gonic/gin v1.10.0. The framework uses gin-gonic/gin v1.10.0 for HTTP routing. Gin requires explicit security configuration for features like CORS, secure headers, and CSRF protection. Default configurations may be permissive. Fix: Implement secure middleware in Gin including: Content-Security-Policy headers, X-Frame-Options, X-Content-Type-Options, HSTS headers, CORS restrictions, and CSRF token validation.
• High · Potential Hardcoded Configuration Files — client/config.toml and similar configuration files. The repository contains configuration files (client/config.toml) that may contain sensitive information such as default credentials, API keys, or server addresses. These could be committed to version control. Fix: Ensure all configuration files with sensitive data are excluded from version control using .gitignore. Use environment variables or secure configuration management for sensitive settings. Never commit default credentials or API keys.
• Medium · No Evidence of Input Validation Framework — Codebase architecture (not visible in file listing). While go-playground/validator/v10 is included as a transitive dependency, there's no clear indication of comprehensive input validation across the codebase, particularly for the HTTP handlers and command processing. Fix: Implement strict input validation on all HTTP endpoints and command processing logic. Use the validator package consistently and validate: data types, lengths, format, and allowed values. Implement rate limiting.
• Medium · Missing Security Headers Configuration — client/ and teamserver components. The Gin web framework is used but there's no visible evidence of security header middleware implementation in the provided file structure, which is critical for a C2 framework. Fix: Implement comprehensive security headers: Strict-Transport-Security, X-Content-Type-Options: nosniff, X-Frame-Options: DENY, X-XSS-Protection, Content-Security-Policy, Referrer-Policy.
• Low · Go Version Compatibility — go.mod - go 1.21.0. The project targets Go 1.21.0, which is now outdated. While not a direct security vulnerability, older Go versions may contain security fixes that are not applied. Fix: Update to the latest stable Go version (1.22.x or later). Test thoroughly after updating to ensure compatibility with all dependencies.
• Medium · Unclear Authentication Mechanism — undefined. undefined Fix: undefined

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.