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/cobbr/Covenant 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 — Stale — last commit 2y ago

• 5 active contributors
• GPL-3.0 licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 96% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected
• ⚠ 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 cobbr/Covenant repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/cobbr/Covenant.

What it runs against: a local clone of cobbr/Covenant — 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 cobbr/Covenant | 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 master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 690 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "cobbr/Covenant(\\.git)?\\b" \\
  && ok "origin remote is cobbr/Covenant" \\
  || miss "origin remote is not cobbr/Covenant (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Covenant/API/CovenantAPI.cs" \\
  && ok "Covenant/API/CovenantAPI.cs" \\
  || miss "missing critical file: Covenant/API/CovenantAPI.cs"
test -f "Covenant/API/ICovenantAPI.cs" \\
  && ok "Covenant/API/ICovenantAPI.cs" \\
  || miss "missing critical file: Covenant/API/ICovenantAPI.cs"
test -f "Covenant/API/Models/Grunt.cs" \\
  && ok "Covenant/API/Models/Grunt.cs" \\
  || miss "missing critical file: Covenant/API/Models/Grunt.cs"
test -f "Covenant/API/Models/Listener.cs" \\
  && ok "Covenant/API/Models/Listener.cs" \\
  || miss "missing critical file: Covenant/API/Models/Listener.cs"
test -f "Covenant/API/Models/GruntTask.cs" \\
  && ok "Covenant/API/Models/GruntTask.cs" \\
  || miss "missing critical file: Covenant/API/Models/GruntTask.cs"

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

Covenant is a .NET-based command and control (C2) framework written in ASP.NET Core that provides red teamers with a collaborative, multi-user web interface for managing implants (called Grunts) across target systems. It highlights .NET attack surface through dynamic Roslyn-based compilation, encrypted key exchange, and listener profiles that control implant-to-server communication signatures. The framework runs cross-platform (Linux, macOS, Windows) and in Docker, making it accessible for distributed red team operations. Monolithic ASP.NET Core application under /Covenant with two primary layers: (1) API layer in /Covenant/API containing CovenantAPI.cs (main service), ICovenantAPI.cs (interface), and CovenantAPIExtensions.cs for dependency injection; (2) Data models in /Covenant/API/Models (Grunt.cs for implants, GruntTask.cs for tasking, HTTPListener.cs/BridgeListener.cs for communication channels, CapturedCredential.cs hierarchy for credential storage). Frontend is HTML/JavaScript/CSS in separate directories consuming the API via Swagger-documented endpoints.

Red teamers and penetration testers who need a modern C2 framework for collaborative .NET-based offensive operations, particularly those running infrastructure assessments where multi-user coordination, implant task management, and credential harvesting are required. Developers contributing to Covenant add features like new launchers (BinaryLauncher, CscriptLauncher, InstallUtilLauncher), GruntTasks, and listener types.

Covenant is production-ready and actively maintained. The project has significant community adoption (visible through the badge showing contributors and commit activity), a comprehensive Wiki with installation and feature documentation, and a well-organized codebase with 2.7M lines of C# across API models, listeners, and implant logic. The presence of CHANGELOG.md, Docker support, and multi-version .NET targeting indicates mature release management.

Risk is moderate: Covenant is intentionally offensive security tooling, so it carries inherent legal/compliance risk in jurisdictions restricting C2 frameworks. The codebase is actively maintained (visible commit activity), but dependency surface area grows with ASP.NET Core ecosystem. Single-maintainer risk (cobbr) is partially mitigated by community contribution. Breaking changes to implant protocols (GruntCommand, GruntTasking models) could affect existing engagements, so changelog review before upgrading is critical.

Based on file structure maturity, active work includes: implant task framework (GruntTask, GruntCommand, GruntTasking models), multi-launcher support (BinaryLauncher, CscriptLauncher, InstallUtilLauncher visible in models), credential harvesting systems (CapturedPasswordCredential, CapturedHashCredential, CapturedTicketCredential), and HTTP profile customization (HttpProfile, HttpProfileHeader). The presence of recent model files and CHANGELOG suggests ongoing feature refinement rather than maintenance mode.

Clone and build: git clone https://github.com/cobbr/Covenant.git && cd Covenant && dotnet build Covenant.sln. For Docker: docker build -t covenant -f Covenant/Dockerfile .. For local development: cd Covenant && dotnet run. See /github/ISSUE_TEMPLATE/issue-template.md for issue reporting conventions and refer to the Wiki (linked in README) for Installation-and-Startup guide.

Daily commands: Dev server: cd Covenant && dotnet run (launches ASP.NET Core on default port, check Program.cs for configuration). Docker: docker build -t covenant -f Covenant/Dockerfile . && docker run -p 7443:7443 covenant. Check logs for listener bind port and default credentials. Covenant uses in-memory or persistent database (configure in appsettings.json) — default likely SQLite for dev, configurable for production.

• Covenant/API/CovenantAPI.cs — Main API orchestrator that routes all C2 commands, listener management, and grunt communication—every feature flows through here.
• Covenant/API/ICovenantAPI.cs — Core API interface defining the contract for all C2 operations; changes here ripple across the entire framework.
• Covenant/API/Models/Grunt.cs — Central agent model representing an implant; fundamental to understanding beaconing, tasking, and output handling.
• Covenant/API/Models/Listener.cs — Base listener abstraction for all C2 communication channels (HTTP, Bridge, etc.); essential for multi-protocol support.
• Covenant/API/Models/GruntTask.cs — Task definition model that drives command execution, capability loading, and output parsing across all grunts.
• Covenant.sln — Solution file anchoring the entire .NET build; required to understand project structure and dependency relationships.
• Covenant/API/CovenantAPIExtensions.cs — Extension methods and dependency injection setup for the API layer; critical for understanding service initialization.

Add a New Grunt Task (Command Module)

1. Create a new GruntTask model in Covenant/API/Models/ inheriting task metadata (name, description, options, output parsing rules) (Covenant/API/Models/GruntTask.cs)
2. Register the task in CovenantAPI via a registration method that adds it to the available task catalog (Covenant/API/CovenantAPI.cs)
3. Define task options as GruntTaskOption objects specifying argument types, defaults, and validation (Covenant/API/Models/GruntTaskOption.cs)
4. Add the compiled task assembly/source to the embedded resources or reference library for implant inclusion (Covenant/API/Models/EmbeddedResource.cs)
5. Create a Razor component in Covenant/Components/GruntTaskings/ for task configuration UI (Covenant/Components/GruntTaskings/EditGruntTasking.razor)

Add a New Launcher Type

1. Create a new launcher class inheriting from Covenant/API/Models/Launcher.cs (e.g., WinRMLauncher.cs) (Covenant/API/Models/Launcher.cs)
2. Implement launcher-specific generation logic (stager code, encoding, obfuscation parameters) (Covenant/API/CovenantAPI.cs)
3. Register the launcher type in LauncherType enum if needed (Covenant/API/Models/LauncherType.cs)
4. Add a Razor UI component for launcher configuration in Covenant/Components/ (Covenant/Components/App.razor)

Add a New Listener Protocol

1. Create a new listener class inheriting from Covenant/API/Models/Listener.cs (e.g., SMBListener.cs) (Covenant/API/Models/Listener.cs)
2. Implement protocol-specific communication handling (send, receive, serialization, encryption) (Covenant/API/CovenantAPI.cs)
3. Register listener type in ListenerType enum and add to listener factory in CovenantAPI (Covenant/API/Models/ListenerType.cs)
4. Add corresponding Grunt communication code to handle the new protocol on the implant side (Covenant/API/Models/Grunt.cs)

Add Credential Capture & Storage

1. Create a new credential subclass (e.g., SSOTokenCredential) inheriting CapturedCredential in Covenant/API/Models/ (Covenant/API/Models/CapturedCredential.cs)
2. Register credential type in CredentialType enum (Covenant/API/Models/CredentialType.cs)
3. Add task command output parsing to extract and populate credential fields automatically (Covenant/API/Models/GruntTask.cs)
4. Create a Razor table component for displaying the new credential type in Covenant/Components/Credentials/ (Covenant/Components/Credentials/CredentialTables.razor)

• ASP.NET Core + Blazor — Cross-platform C# framework enabling web-based multi-user UI with real-time SignalR updates; leverages .NET ecosystem for seamless implant compilation.
• .NET Runtime & C# Compilation — Covenant targets .NET frameworks on victim machines; in-framework compilation and reflection enables dynamic task/implant generation without external toolchains.
• Entity Framework Core / SQL Database — Persistent storage for users, grunts, tasks, taskings, credentials, indicators; enables audit logging and collaborative session state.
• HTTP/HTTPS Listeners — Primary command channel mimicking legitimate C2 traffic; HTTP profiles allow customization of headers, URIs, and beaconing signatures for evasion.
• Bridge Listener & Protocol Abstraction — Decouples listener transport from implant logic; allows SMB, named pipes, and future custom protocols without modifying core agent.

• Multi-user collaborative UI vs. single-operator simplicity
  • Why: Red teams require
  • Consequence: undefined

Database initialization: Covenant likely uses Entity Framework migrations on first run — ensure database is writable and migration applied before starting (check appsettings.json for connection string). Port conflicts: Default listeners bind to 7443 (HTTPS web UI) and may bind to configurable ports for C2 listeners; ensure no firewall blocking. Implant staging: Grunts are dynamically compiled with Roslyn, requiring .NET SDK or runtime on server with sufficient resources; large-scale implant generation can be memory-intensive. SSL certificate: For HTTPS listener, Covenant needs valid certificate or uses self-signed; check for certificate path in configuration. Multi-user session state: No indication of distributed caching in file list — deployments with multiple Covenant instances may need session affinity or Redis backing (not visible in repo).

• Command and Control (C2) Framework — Covenant's core purpose is implementing a C2 system; understanding the attacker-implant command loop (Grunt receives GruntTask, executes, returns CommandOutput) is essential to navigating the codebase.
• Listener Profile / Network Signature Evasion — Covenant's HttpProfile system allows operators to customize HTTP headers, URI patterns, and User-Agent strings to evade detection; this is a key differentiation and requires understanding how profiles bind to listeners.
• Roslyn Dynamic Compilation — Covenant uses Roslyn (Microsoft's .NET compiler API) to dynamically generate and compile implant payloads with custom options; understanding this is critical for extending implant functionality without pre-compiling binaries.
• Encrypted Key Exchange (Forward Secrecy) — Covenant implements Empire-inspired encrypted session establishment between Grunts and listeners; studying this prevents implant-listener communication from being replayed or decrypted if a single session key leaks.
• Credential Type Hierarchy (Password, Hash, Ticket) — Covenant's CapturedCredential model and subclasses (CapturedPasswordCredential, CapturedHashCredential, CapturedTicketCredential) represent different Windows credential formats; understanding this enables proper credential parsing and reuse workflows.
• Multi-User Collaboration & API-Driven Architecture — Covenant is designed for teams; the REST API (CovenantAPI.cs) with Swagger documentation and multi-user session management (CovenantUser models) allows parallel operator workflows — this is non-trivial and critical for distributed red team operations.
• Tasking Queue & Implant Staging — GruntTasking models queue commands for Grunts and track execution status; understanding this queueing pattern is essential for adding new task types or debugging implant communication delays.

• BC-SECURITY/Empire — Predecessor C2 framework that inspired Covenant's encrypted key exchange; Empire is Python-based while Covenant targets .NET, but shares tasking/listener architecture philosophy.
• ghostsec/sliver — Modern Go-based C2 framework with similar multi-user, listener profile, and multi-platform capabilities; represents alternative approach to Covenant's .NET focus.
• MythicC2/Mythic — Collaborative C2 framework with web UI and modular payload architecture; shares Covenant's emphasis on multi-user coordination and customizable task modules.
• BloodHoundAD/BloodHound — AD enumeration and visualization tool frequently used alongside Covenant for target reconnaissance and credential path planning in Windows environments.
• rasta-mouse/Covenant-Profiles — Community-maintained HTTP listener profiles for Covenant; directly extends HttpProfile.cs functionality with real-world evasion signatures.

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 API/Models serialization and validation

The API/Models directory contains 50+ model classes (Grunt.cs, GruntTask.cs, HTTPListener.cs, Launcher.cs, etc.) with no apparent unit tests in the repository structure. These models are critical for C2 communication and serialization. Adding tests would prevent regressions in model binding, JSON serialization, and field validation—especially important for a security tool where data integrity is crucial.

• [ ] Create Covenant.Tests project (if not exists) alongside Covenant.sln
• [ ] Add unit tests for core models: Grunt.cs, GruntTask.cs, GruntTasking.cs with serialization/deserialization scenarios
• [ ] Add validation tests for Launcher models (PowerShellLauncher.cs, MSBuildLauncher.cs, etc.) to ensure required fields are enforced
• [ ] Add tests for CapturedCredential.cs subtypes to verify credential data integrity
• [ ] Create GitHub Actions workflow to run tests on PR and commits to main

Add integration tests for Listener implementations (HTTPListener.cs, BridgeListener.cs)

HTTPListener.cs and BridgeListener.cs are critical components for C2 communication, but no integration tests are visible. These listeners handle incoming Grunt connections and must be robust. Integration tests would validate listener startup, connection handling, message routing, and error scenarios across different profile configurations.

• [ ] Create Covenant.Tests.Integration project with test infrastructure for spinning up listeners
• [ ] Add integration tests for HTTPListener: test listener startup, client connection, message receive/send with different HttpProfile configurations
• [ ] Add integration tests for BridgeListener: test inter-listener communication and message bridging scenarios
• [ ] Test listener error handling (invalid requests, malformed protocols, timeout scenarios)
• [ ] Add test fixtures that validate listener behavior matches ICovenantAPI contract

Add API endpoint documentation and OpenAPI/Swagger specification generation

With 50+ model classes and a CovenantAPI.cs containing numerous endpoints, there's likely no auto-generated API documentation. For a collaborative C2 framework, clear API documentation is essential for operators and contributors building custom integrations. Adding Swagger/OpenAPI would enable better discoverability and reduce onboarding friction.

• [ ] Install Swashbuckle.AspNetCore NuGet package to Covenant.csproj
• [ ] Configure Swagger generation in Covenant/Startup.cs or Program.cs with XML documentation comments
• [ ] Add XML documentation comments to all public methods in CovenantAPI.cs and ICovenantAPI.cs
• [ ] Add data annotations to API/Models classes for better schema generation
• [ ] Add Swagger UI endpoint documentation in README.md pointing to /swagger

• Add unit tests for Covenant/API/Models/CapturedCredential.cs and its subclasses (CapturedPasswordCredential, CapturedHashCredential, CapturedTicketCredential); currently no test files visible in top 60, indicating potential gap in credential model coverage.
• Document the GruntTasking lifecycle in /API/Models/GruntTasking.cs with inline code comments and a wiki entry covering status transitions (queued → running → complete) and result handling for new contributors.
• Implement missing launcher type: Add a PowerShellLauncher.cs model (pattern exists for BinaryLauncher, CscriptLauncher, InstallUtilLauncher) with support for encoded script delivery, addressing gap in common Windows execution vectors.

• High · Potential Credential Exposure in API Models — Covenant/API/Models/Captured*Credential.cs files. The codebase contains multiple credential-related models (CapturedCredential.cs, CapturedHashCredential.cs, CapturedPasswordCredential.cs, CapturedTicketCredential.cs) that handle sensitive authentication data. Without visible encryption or secure storage mechanisms in the file structure, there is risk of credential exposure in memory, logs, or database storage. Fix: Implement field-level encryption for sensitive credential data, use secure memory handling to prevent credential dumps, implement secure logging that excludes sensitive fields, and consider using a dedicated secrets management system.
• High · Potential Insecure Deserialization — Covenant/API/Models/Grunt.cs, GruntCommand.cs, HttpProfile.cs, HTTPListener.cs. The Covenant framework processes serialized data from Grunts (implants) and HTTP profiles. Without visible input validation in the file structure, deserialization of untrusted data could lead to Remote Code Execution (RCE) vulnerabilities, particularly with .NET binary formatting. Fix: Use type-safe serialization formats (JSON with strong typing), implement strict input validation and allowlisting of expected types, avoid using BinaryFormatter or NetDataContractSerializer, and implement deserialization security controls.
• High · Command Injection Risk in Launcher Components — Covenant/API/Models/*Launcher.cs files. Multiple launcher types (PowerShellLauncher, CscriptLauncher, MshtaLauncher, WmicLauncher, InstallUtilLauncher, Regsvr32Launcher, MSBuildLauncher) generate and execute system commands. Insufficient input sanitization could allow command injection attacks if user-controlled parameters are not properly escaped. Fix: Implement strict input validation and sanitization for all launcher parameters, use parameterized command execution where possible, avoid shell interpretation, implement allowlisting for valid parameter values, and perform security testing of launcher parameter handling.
• High · Missing Authentication/Authorization on API Endpoints — Covenant/API/CovenantAPI.cs, CovenantAPIExtensions.cs. The CovenantAPI.cs and CovenantAPIExtensions.cs files suggest REST API endpoints, but the visibility of authentication mechanisms is unclear. Sensitive operations like listener management, grunt tasking, and credential handling require proper authentication and authorization. Fix: Implement mandatory authentication on all API endpoints (JWT tokens, API keys, or OAuth2), enforce role-based access control (RBAC) for sensitive operations, implement rate limiting to prevent brute force attacks, and add comprehensive audit logging for all API access.
• Medium · Potential XSS Vulnerabilities in Razor Components — Covenant/Components/ (all .razor files, particularly CommandOutput, CredentialTables, EventModel components). Razor components (*.razor files) that display user-controlled data such as command output, events, and credentials may be vulnerable to Cross-Site Scripting (XSS) if data is not properly encoded before rendering. Fix: Ensure all dynamic content is HTML-encoded by default in Razor templates, use @Html.Encode() for user-controlled content, avoid using @Html.Raw() unless absolutely necessary with pre-validated content, implement Content Security Policy (CSP) headers, and perform XSS testing on all user-facing UI components.
• Medium · Insecure Direct Object References (IDOR) — Covenant/API/CovenantAPI.cs and all model controllers. The framework manages multiple objects with IDs (Grunts, Listeners, Tasks, Users) through API endpoints. Without proper authorization checks, users may be able to access or modify objects belonging to other users or teams. Fix: Implement object-level authorization checks, verify user ownership/access rights before returning data, use opaque identifiers instead of sequential IDs where possible, and implement comprehensive audit logging for object access attempts.
• Medium · Potential SQL Injection via ORM Configuration — Covenant/API/CovenantAPI.cs (database access logic not visible but likely present). While the codebase uses Entity Framework (implied by .razor components and API models), improper LINQ query construction or raw SQL usage could lead to SQL injection vulnerabilities. Fix: Ensure all database queries use parameterized queries/LINQ, avoid string concatenation

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.