GHARF: GitHub Actions RedTeam Framework

GHARF: GitHub Actions RedTeam Framework

Speakers: Yuuki Matsumoto (Junior Offensive Security Researcher, NTT Docomo Business), Yusuke Kubo (Offensive Security Researcher, NTT DOCOMO BUSINESS)

Conference: CODE BLUE

YouTube: https://www.youtube.com/watch?v=xckfqVji5Z8

Overview

In a compelling presentation at CODE BLUE, Yuuki Matsumoto and Yusuke Kubo from NTT Docomo Business unveiled GHARF, the GitHub Actions RedTeam Framework. This innovative framework represents a paradigm shift in red team operations, addressing the inherent challenges of high operational costs and complexity by applying the principles of Continuous Integration/Continuous Delivery (CI/CD) to offensive security. GHARF introduces the concept of Continuous Attack Integration/Continuous Attack Delivery (CAI/CAD), a novel approach designed to automate and streamline the entire lifecycle of red team engagements.

The core innovation of GHARF lies in its strategic utilization of GitHub Actions self-hosted runners as stealthy and resource-less Command and Control (C2) agents. By co-opting legitimate GitHub infrastructure, the framework enables red team operators to manage and execute complex attack scenarios with unprecedented efficiency and reproducibility. This not only significantly reduces the manual effort typically associated with developing, deploying, and managing attack tools and infrastructure but also allows red teams to focus their expertise on sophisticated scenario development and strategic thinking.

GHARF is more than just a tool; it's a comprehensive methodology encapsulated in an open-source framework, transforming red team operations into a code-driven, automated process. This approach minimizes the need for custom C2 development and infrastructure setup, leveraging existing, trusted platforms. The talk provided a detailed technical deep dive into its architecture, capabilities, and a live demonstration, alongside a crucial discussion on ethical considerations and defensive implications, underscoring its potential to revolutionize how red team exercises are conducted while maintaining responsible disclosure practices.

Background

▶ Watch: Red Team operational challenges and manual effort (2:50)

Red teaming is a critical discipline in cybersecurity, involving the simulation of real-world cyberattacks to rigorously evaluate an organization's security posture, defensive capabilities, and incident response readiness. These exercises are often conducted against a Blue Team, whose objective is to detect, respond to, and mitigate the simulated threats. While invaluable, traditional red team operations are notoriously resource-intensive. The speakers highlighted several key challenges: the significant human effort required for developing sophisticated attack scenarios, preparing and weaponizing custom tools, establishing and maintaining execution and verification environments, executing complex attack operations, and managing the entire engagement lifecycle. This entire process demands substantial time, specialized skills, and continuous manual oversight, often leading to high operational costs and slower iteration cycles.

To address these challenges, the presenters drew inspiration from the software development paradigm of CI/CD (Continuous Integration/Continuous Delivery). CI/CD automates various stages of the software development lifecycle, including coding, building, testing, delivery, and deployment, thereby reducing human error, accelerating development cycles, and improving overall software quality. The core idea behind GHARF is to transpose these efficiency-driven principles onto red team operations, giving rise to the new concept of CAI/CAD (Continuous Attack Integration/Continuous Attack Delivery). CAI/CAD aims to automate the development, preparation, and execution phases of simulated attacks, enabling red teams to iterate faster, manage operations more efficiently, and deliver higher-quality assessments.

At the heart of GHARF's implementation is GitHub Actions, GitHub's integrated CI/CD platform. GitHub Actions allows developers to automate workflows triggered by various repository events, such as code pushes, pull requests, or even manual triggers. These workflows are defined using YAML files and executed on virtual machines. A crucial component of GitHub Actions for GHARF's design is the self-hosted runner. Unlike GitHub-hosted runners, which are managed by GitHub, self-hosted runners are machines provided and managed by the user. These runners can be customized with specific hardware specifications or unique software environments, making them ideal for specialized tasks. GHARF leverages these self-hosted runners not for their intended CI/CD purpose, but as a stealthy and flexible C2 (Command and Control) mechanism. In cybersecurity, C2 refers to the communication channel established between an attacker's infrastructure and a compromised target, enabling remote command execution, data exfiltration, and further malicious activities. By using GitHub Actions as the entire C2 infrastructure, GHARF transforms a legitimate, widely used development platform into a potent red team tool.

Key Findings

▶ Watch: Using GitHub Self-Hosted Runners as C2 infrastructure (6:30)

The development and public release of GHARF represent several significant findings and contributions to the field of offensive security:

• Introduction of CAI/CAD: The most foundational finding is the proposal and demonstration of Continuous Attack Integration/Continuous Attack Delivery (CAI/CAD). This novel conceptual framework successfully adapts the efficiency and automation principles of CI/CD to the traditionally manual and resource-intensive domain of red teaming. CAI/CAD promises to significantly reduce operational overhead and accelerate attack cycles.
• GHARF as a Realization of CAI/CAD: GHARF itself is a testament to the feasibility and effectiveness of the CAI/CAD concept. By leveraging existing GitHub Actions infrastructure, the framework provides a practical, open-source solution that drastically cuts down on the operational costs, improves efficiency, and enhances the overall quality of red team exercises. Its open-source nature promotes community contribution and further development.
• GitHub Actions Self-Hosted Runners as a Stealthy C2: A critical technical finding is the successful repurposing of legitimate GitHub Actions self-hosted runners as a robust and stealthy C2 mechanism. This technique allows red team operators to establish command and control over target environments without deploying custom, potentially detectable, C2 agents or servers. The use of legitimate GitHub communication channels can make detection more challenging for traditional security tools.
• Red Team Operations as Code (RTOaC): GHARF inherently promotes "Red Team Operations as Code." By defining attack workflows and scenarios in YAML, the framework enables version control, reproducibility, and easier customization. This code-based approach ensures that red team operations are consistent, auditable, and easily shared or adapted across different engagements or environments, enhancing the overall reusability of attack methodologies.
• Resource-less Architecture: The framework eliminates the need for red teams to build and maintain dedicated C2 infrastructure. The GitHub repository serves as the C2 server, and self-hosted runners act as agents, reducing the financial and technical overhead associated with setting up and managing offensive infrastructure. Additionally, it can leverage GitHub-hosted runners for resource-intensive tasks like tool compilation, obfuscation, or password cracking, further offloading computational requirements.
• Simplified and Rapid Setup: Compared to many traditional C2 frameworks that require complex setups, GHARF offers a remarkably simple and rapid deployment process. The core setup involves just creating a GitHub account, cloning the GHARF repository, and deploying a self-hosted runner agent on the target environment. This ease of deployment lowers the barrier to entry for effective red teaming.
• Responsible Disclosure and Ethical Considerations: A significant non-technical finding is the commitment to ethical security research. The developers engaged in responsible disclosure with GitHub regarding the use of self-hosted runners as C2 agents, obtaining permission before public release. Furthermore, GHARF incorporates critical ethical safeguards, such as a user consent/approval mechanism for command execution and the embedding of Indicators of Compromise (IOCs) in generated artifacts, alongside YARA rules for their detection, to prevent misuse and aid blue teams.

Technical Deep Dive

▶ Watch: Live demo: Runner setup and command execution (21:00)

GHARF's architecture is meticulously designed to leverage GitHub's robust CI/CD capabilities for offensive operations, creating a seamless and automated red team experience. The framework's core strength lies in its ability to transform complex, multi-stage attack scenarios into repeatable, version-controlled workflows.

GHARF's Core Features

1. Full Automation of the Attack Lifecycle: GHARF automates the entire flow from attack development and tool preparation to execution. This automation minimizes the manual overhead associated with red teaming, allowing operators to concentrate on strategic scenario design. The framework connects various processes as a pipeline within GitHub, enabling seamless data transfer between phases. For instance, an operation might involve building a malicious binary, delivering it to a target environment, executing it, and then passing the collected output (e.g., hashes) to another tool for analysis (e.g., Hashcat for cracking), all within an automated workflow.
2. Red Team Operations as Code (RTOaC): All red team operations within GHARF are defined as YAML workflows for GitHub Actions. This "as code" approach offers several critical advantages:

• Structured Definition: Operations are clearly and structurally defined, improving clarity and maintainability.
• Reproducibility: Workflows can be executed repeatedly with consistent results, crucial for verifying findings and training.
• Version Control: Storing operations in a Git repository allows for versioning, tracking changes, reverting to previous states, and collaborative development.
• Environment Agnosticism: While environments differ, the framework aims to absorb some of these differences, allowing similar operations to run across varied target systems with minimal modification.
• Customizability: Workflows can be easily adapted and extended to suit specific engagement requirements.

1. Resource-less Architecture: This is a defining characteristic of GHARF.

• C2 Agent: The GitHub Actions self-hosted runner agent itself serves as the C2 agent. This eliminates the need for red teams to develop, compile, and deploy custom C2 binaries, which are often prone to detection. The self-hosted runner is a legitimate application, making its initial setup less suspicious.
• C2 Server: The GitHub repository where GHARF is set up effectively acts as the C2 server. All command and control communications are channeled through GitHub's legitimate API, potentially blending with normal enterprise network traffic. This removes the burden of deploying and securing a dedicated C2 server.
• Leveraging GitHub-Hosted Resources: GHARF can utilize GitHub-hosted runners (the default cloud-based runners) for resource-intensive tasks that shouldn't occur on the target. Examples include building attack tools, performing binary obfuscation or packing, pre-testing attack tools, or cracking hashes (e.g., NTLM hashes obtained from a target). This offloads computational burden and keeps sensitive operations off the compromised host.

1. Simple and Rapid Setup: The framework is designed for quick deployment. The minimal setup involves three steps: obtaining a GitHub account, cloning the GHARF repository (which is provided as an open-source template), and setting up the self-hosted runner application on the target environment. The runner setup follows standard GitHub documentation, involving simple command execution via PowerShell or shell scripts.

Architectural Components

GHARF's architecture comprises three main components:

• Red Team Operator Environment: The operator interacts with GHARF via a CLI client or directly through the GitHub Web UI. The CLI client provides command-line control, while the Web UI allows for browser-based interaction, making the framework accessible even with minimal tools.
• Attack Development Repository (on GitHub): This central repository hosts all the necessary resources:
• C2 Server Workflows: YAML files defining the logic for command execution and data handling on the target.
• Manual Execution Workflows: Workflows specifically designed to be triggered manually via the GitHub Web UI.
• Attack Resources: This includes source code for attack tools, custom TTPs (Tactics, Techniques, and Procedures) implemented as GitHub Actions or workflows, and files intended for transfer to or from the target.
• Target Environment: This environment hosts the self-hosted runner agent, which acts as the C2 agent. Once installed and configured, this agent continuously polls the GitHub repository for new jobs (commands) to execute.

Supported C2 Operations

GHARF supports a range of C2 capabilities:

• Shell Command Execution: The most fundamental C2 operation, allowing operators to execute arbitrary shell commands on the target.
• JavaScript Code Execution: Leverages the JavaScript runtime often present in runner environments, enabling the execution of JavaScript code directly.
• File Upload/Download: Facilitates the transfer of files to and from the target. This process is two-staged: files are first uploaded from the client to the GitHub repository (as an artifact) and then downloaded from the repository to the target (or vice-versa for downloads from the target).
• Custom Workflow Execution: A powerful feature allowing users to define their own TTPs as GitHub Actions workflows. These custom workflows can be modular and reusable. The talk highlighted two sample workflows included with GHARF:
• A workflow to perform Kerberoasting (often used in Active Directory environments) to obtain NTLM hashes, followed by cracking these hashes using Hashcat.
• A simpler workflow to execute SharpHound (a BloodHound data collector) and retrieve the generated zip file.

C2 Host Identification

To direct commands to specific compromised hosts, GHARF utilizes GitHub Actions' runner labels feature. When setting up a self-hosted runner, it can be assigned a unique label. The red team operator can then specify this label when triggering a workflow, ensuring the command is executed only on the intended target.

CLI Client and Web UI

• CLI Client: GHARF provides a command-line interface tool for operators to interact with the framework. It supports calling various workflow commands, retrieving job logs, and managing file transfers. An "interactive version" is also under development, aiming to provide a more intuitive, shell-like experience for continuous operations.
• Web UI for Manual Execution: Leveraging the workflow_dispatch event in GitHub Actions, GHARF allows operators to trigger workflows directly from the GitHub repository's web interface. This provides a user-friendly, browser-based option for command execution, useful when a CLI client might not be convenient.

Demo / Proof of Concept

▶ Watch: Ethical considerations and user consent implementation (33:00)

The presentation included a comprehensive demonstration of GHARF's capabilities, primarily showcasing its setup and various C2 functions via the CLI client and GitHub Web UI.

1. Runner Setup: The demo began with the setup of a self-hosted runner on a Windows machine. The process followed GitHub's official instructions: downloading a ZIP archive, extracting its contents, running config.cmd to register the runner with a specific name and label, and finally executing run.cmd to start the runner. The GitHub Actions interface subsequently showed the newly registered runner in an "idle" state, awaiting commands.

1. CLI Client - Shell Command Execution:

• The presenter used the GHARF CLI client to execute a simple whoami command on the Windows target.
• The command was sent to GitHub, which queued a job for the self-hosted runner.
• A critical feature demonstrated was the approval process: before execution, the job required explicit user approval, highlighting GHARF's built-in ethical safeguards.
• Upon approval, the whoami command executed on the Windows machine. The output was then retrieved and displayed both in the GitHub Actions job logs and via the GHARF CLI client, confirming successful execution.

1. CLI Client - JavaScript Execution: A simple JavaScript snippet, designed to print a number to the console, was executed via the CLI client. The output was successfully captured and displayed in the logs, showcasing the framework's ability to leverage the JavaScript runtime within the runner environment.

1. CLI Client - File Upload:

• A file named test.txt was uploaded from the operator's machine to the target.
• The demo clarified the two-stage upload process: first, the file is uploaded from the CLI client to the GitHub repository as an artifact; then, a separate command triggers the runner to download this artifact from the repository to a specified directory (upload directory) on the target Windows machine.
• Verification on the Windows machine confirmed the successful transfer and content of test.txt.

1. CLI Client - Custom Workflow Execution:

• The presenter demonstrated executing a custom workflow designed to run SharpHound on the target.
• The CLI client listed available custom workflows, and the SharpHound workflow was selected.
• The job progressed, and upon completion, a .zip file (the output of SharpHound) was found on the target Windows machine, illustrating the execution of complex, multi-step TTPs.

1. CLI Client - File Download:

• To retrieve the SharpHound zip file from the target, a download operation was initiated.
• Similar to uploads, downloads are a two-stage process: the target runner first uploads the file to the GitHub repository, and then the CLI client downloads it from the repository.
• The download list command was used to show available files from completed jobs. The specific job ID corresponding to the SharpHound output was then used to download the zip file to the operator's local download_files directory. The integrity of the downloaded zip was verified.

1. Interactive CLI Client: A brief look at the interactive CLI client, which is still under development, showed a shell-like interface for continuous command execution. While it displayed logs, the automatic fetching of command results was noted as a future enhancement.

1. Web UI Execution: Finally, the whoami command was executed directly from the GitHub Actions Web UI, leveraging the workflow_dispatch event. This demonstrated that full operational control can be achieved entirely within the browser, without needing the CLI client, providing flexibility for red team operators. The results were confirmed in the GitHub UI, mirroring the CLI execution.

The demo conclusively proved GHARF's functionality, ease of use, and its capability to perform common C2 operations and execute complex custom TTPs through the GitHub Actions ecosystem.

Defensive Implications

▶ Watch: Q&A: Future work on detection evasion for GHARF (37:20)

GHARF presents a sophisticated new approach to red teaming, and understanding its defensive implications is crucial for blue teams. While designed for ethical red team engagements, the underlying techniques could be adopted by malicious actors, making detection strategies paramount.

1. Detection Challenges with Legitimate Infrastructure: The primary defensive challenge stems from GHARF's use of legitimate GitHub Actions self-hosted runners. These runners are genuine applications, and their network traffic communicates with legitimate GitHub API endpoints over HTTPS. This makes it difficult for traditional Antivirus (AV) software to flag the runner agent itself as malicious, and Network Intrusion Detection Systems (NIDS) may struggle to differentiate C2 traffic from normal GitHub CI/CD activity.
2. Behavioral Detection by EDR: As confirmed by the speaker during the Q&A, Endpoint Detection and Response (EDR) solutions are the most effective line of defense. While the runner agent itself might not be flagged, EDRs excel at detecting malicious behavior. Tools like Windows Defender were explicitly mentioned as being capable of detecting the execution of common offensive tools such as SharpHound or Kerberoasting tools when run by the GHARF agent. Defenders should focus on:

• Process Monitoring: Detecting suspicious processes launched by the runner agent (e.g., cmd.exe, powershell.exe, or specific attack tools like SharpHound.exe).
• File System Monitoring: Identifying the creation of suspicious files (e.g., .zip files from SharpHound, binaries dropped by the runner) or modifications to system files.
• Network Behavior Analysis: While GitHub traffic is legitimate, EDRs can monitor the destinations and protocols of connections initiated by processes spawned by the runner. Unusual connections or data exfiltration patterns should raise alerts.

1. GitHub Auditing and Monitoring: Organizations that utilize GitHub Actions should implement robust auditing and monitoring strategies:

• Self-Hosted Runner Registration: Monitor for the registration of new self-hosted runners, especially on critical assets or in unexpected network segments. Unauthorized runner registrations could indicate compromise.
• Workflow Execution Logs: Scrutinize GitHub Actions workflow execution logs for unusual activity, such as workflows being triggered at odd hours, by unusual users, or executing commands outside of typical CI/CD operations.
• Repository Access: Ensure strict access controls on GitHub repositories, as compromise of a repository could enable an attacker to deploy GHARF.

1. Leveraging IOCs and YARA Rules: GHARF's developers have proactively incorporated defensive mechanisms. The framework includes a mechanism to embed Indicators of Compromise (IOCs) into binaries generated by workflows and provides YARA rules for detecting these artifacts. Blue teams should integrate these YARA rules into their detection engines to identify GHARF-generated malicious payloads. This responsible disclosure and defensive aid are crucial for the community.
2. Importance of the Approval Process: The built-in user approval process for command execution is a critical security control. Organizations deploying self-hosted runners should ensure such explicit approval mechanisms are enabled and strictly enforced. This acts as a "human in the loop" to prevent unauthorized or unintended command execution, even if the runner is compromised.
3. Supply Chain Security: The reliance on GitHub infrastructure highlights the importance of supply chain security. If an attacker gains control over a developer's GitHub account or an organization's GitHub repository, they could potentially deploy malicious GHARF workflows or runners, impacting downstream systems.
4. Future Evasion Techniques: The speaker acknowledged that future work might include detection evasion techniques such as packers or encryption for the runner application wrappers. Defenders must anticipate the evolution of these methods and continuously update their detection strategies, focusing on behavioral analysis and threat intelligence.

In summary, while GHARF offers significant advantages for red teaming, blue teams must shift their focus from signature-based detection of C2 agents to advanced behavioral analysis, comprehensive logging, and robust monitoring of both endpoint activities and GitHub Actions infrastructure.

Key Takeaways

• CAI/CAD Revolutionizes Red Teaming: The proposed Continuous Attack Integration/Continuous Attack Delivery (CAI/CAD) approach significantly streamlines and automates red team operations, addressing the high costs and complexity of traditional engagements by applying CI/CD principles.
• GHARF Leverages Legitimate Infrastructure for C2: The framework effectively repurposes GitHub Actions self-hosted runners as stealthy and resource-less C2 agents, with the GitHub repository itself acting as the C2 server, minimizing the need for custom offensive infrastructure.
• Red Team Operations as Code (RTOaC) Enhances Efficiency: Defining attack scenarios and TTPs as YAML workflows enables version control, reproducibility, and easy customization, making red team exercises more efficient, consistent, and reusable across engagements.
• Simplified Setup and Broad Capabilities: GHARF offers a remarkably simple setup process compared to traditional C2 frameworks, while still supporting a wide range of C2 operations including shell command execution, JavaScript execution, file transfer, and the execution of custom, complex TTPs.
• Behavioral Detection is Key for Defenders: While the GHARF runner uses legitimate channels, EDR solutions can effectively detect the malicious behaviors of tools executed by the runner (e.g., SharpHound, Kerberoasting), making behavioral analytics a critical defensive strategy.
• Ethical Security Research and Defensive Aids: The project emphasizes responsible disclosure (to GitHub), incorporates an explicit user approval process for command execution, and embeds IOCs with accompanying YARA rules in generated artifacts to prevent misuse and assist blue teams in detection.

About the Speaker(s)

Yuuki Matsumoto is a Junior Offensive Security Researcher at NTT Docomo Business. He joined the company (formerly NTT Communications) in 2024 and has since been involved in security-related work. His responsibilities include contributing to the "Wide Angle Red Team Service," enhancing internal security from an offensive perspective, and conducting research and development in offensive security. The GHARF framework, presented at CODE BLUE, is a direct outcome of his research and development efforts.

Yusuke Kubo is an Offensive Security Researcher at NTT DOCOMO BUSINESS. While the transcript primarily features Yuuki Matsumoto's presentation, Yusuke Kubo's role as a co-speaker indicates his significant contribution and expertise in the field of offensive security research, aligning with the advanced technical nature of the GHARF project.