Blackdagger

<p align="center"> <img src="./assets/images/blackdaggerReadme.png" width="500" alt="blackdagger-logo"> </p> <p align="center"> <a href="https://goreportcard.com/report/github.com/ErdemOzgen/blackdagger"> <img src="https://goreportcard.com/badge/github.com/ErdemOzgen/blackdagger" /> </a> <a href="https://codecov.io/gh/ErdemOzgen/blackdagger"> <img src="https://codecov.io/gh/ErdemOzgen/blackdagger/branch/main/graph/badge.svg?token=CODZQP61J2" /> </a> <a href="https://github.com/erdemozgen/blackdagger/releases"> <img src="https://img.shields.io/github/release/erdemozgen/blackdagger.svg" /> </a> <a href="https://godoc.org/github.com/ErdemOzgen/blackdagger"> <img src="https://godoc.org/github.com/ErdemOzgen/blackdagger?status.svg" /> </a> <img src="https://github.com/ErdemOzgen/blackdagger/actions/workflows/test.yaml/badge.svg" /> <a href="https://hub.docker.com/r/erdemozgen/blackdagger"> <img src="https://img.shields.io/docker/v/erdemozgen/blackdagger?label=docker&logo=docker" /> </a> <a href="https://www.blackhat.com/us-24/arsenal/schedule/index.html#blackdagger-39274"> <img src="https://github.com/toolswatch/badges/blob/master/arsenal/usa/2024.svg" /> </a> <a href="https://www.blackhat.com/sector/2024/arsenal/schedule/index.html#blackdagger-40889"> <img src="https://github.com/toolswatch/badges/blob/master/arsenal/sector/2024.svg" /> </a> <a href="https://www.blackhat.com/eu-24/arsenal/schedule/index.html#blackdagger-41344"> <img src="https://github.com/ataseren/badges/blob/master/arsenal/europe/2024.svg" /> </a> <a href="https://www.blackhat.com/asia-25/arsenal/schedule/index.html#blackdagger-43296"> <img src="https://github.com/ataseren/badges/blob/master/arsenal/asia/2025.svg" /> </a> </p> <div align="center">

Installation | Quick Start Docs | Blackdagger YAML Creator GPT4

</div> <h1><b>Blackdagger: Cyber Workflow Automation Framework</b></h1>

Blackdagger is a powerful, user-friendly framework designed to orchestrate complex workflows in DevOps, DevSecOps, MLOps, MLSecOps, and Continuous Automated Red Teaming (CART) environments. By leveraging a declarative YAML format and a Directed Acyclic Graph (DAG) structure, Blackdagger simplifies the definition, management, and execution of automation pipelines, enabling seamless integration with containerized environments and versatile task execution.

What Sets Blackdagger Apart?

• Declarative YAML Format: Blackdagger uses a YAML-based DAG to define workflows, simplifying complex task dependencies without the need for scripting.
• Web UI for Visual Management: Intuitive browser interface for managing, monitoring, and rerunning pipelines with real-time status and logs.
• Native Docker Support: Seamlessly integrates Docker containers for efficient task orchestration in distributed environments.
• Versatile Task Execution: Supports HTTP requests, SSH commands, and custom code for flexible automation.

You can find everything about Blackdagger, including this README, in our documentation.

Table of Contents

• Key Features
• Evolution of Blackdagger to a Framework
• Installation
  • Via Bash script
  • Via Docker
  • Via GitHub Release Page
  • Get Example YAMLs For Various Purposes
• Quick Start Guide
  • 1. Launch the Web UI
  • 2. Create a New DAG
  • 3. Edit the DAG
  • 4. Execute the DAG
• CLI
• Web UI
  • Dashboard
  • DAG Details
  • DAGs List
  • Search DAGs
  • Execution History
  • DAG Execution Log
• Documentation
• Use cases
• Example Workflow
• Tutorial Videos
• Motivation
• Why Not Use an Existing Workflow Scheduler Like Airflow?
• How It Works
• Roadmap
  • Short-term Goals
  • Mid-term Initiatives
  • Long-term Vision
  • Executor Roadmap
  • TODOS for Roadmap
• License

Key Features

• Web UI & CLI for managing and executing DAGs
• YAML-based DAG definition, supporting:
  • Custom code execution
  • Parameters, command substitution, and conditional logic
  • Output redirection (stdout/stderr)
  • Lifecycle hooks and task repetition
  • Automatic retries
• Executors for:
  • Running Docker containers
  • Making HTTP requests
  • Sending emails
  • Running jq command
  • Executing remote commands via SSH
• Email notifications
• Scheduling with Cron expressions
• REST API
• Basic Authentication over HTTPS

Evolution of Blackdagger to a Framework

To improve usability and streamline complex workflows, the team introduced a structured framework around Blackdagger. This includes pre-configured YAML files for common use cases and deployable infrastructure for Continuous Automated Red Teaming (CART) and DevSecOps. These additions are consolidated under the Blackdagger: Cyber Workflow Automation Framework, providing a cohesive solution that enhances the tool's overall effectiveness.

The framework consists of 5 components:

• Blackdagger (this repository): Core of the framework for orchestrating the components and workflows
• Blackcart: A specialized Docker image optimized for Continuous Automated Red Teaming (CART) and DevSecOps pipeline tasks.
• Blackdagger YAMLs: Pre-tested example workflows, demonstrating real-world DevSecOps and CART use-cases, facilitating quick adoption and adaptation.
• Blackdagger Github Infra: A suite of advanced workflows utilizing GitHub Actions infrastructure for enhanced defense evasion techniques, scalability, and performance.
• Blackdagger Web Kit: A browser extension integrating core functionalities, allowing direct execution of Blackdagger workflows from the browser.

<p align="center"> <img src="https://github.com/ErdemOzgen/blackdagger/blob/main/assets/images/framework_diagram.png" width="500" alt="framework-diagram"> </p>

Each component within the framework is designed for interoperability, allowing seamless integration across various environments and use cases with maximum ease, speed, and efficiency. The framework is modular, supporting the addition, removal, or modification of components to introduce new features or adapt to evolving requirements.

With Blackdagger at its core, this repository offers a detailed overview of the framework's capabilities. For more information on specific components, please refer to their individual repositories.

Installation

Prerequisites

• A Linux, macOS, or Windows system with bash or Docker installed.
• For certain workflows, sudo permissions may be required (see Sudo Configuration).

Via Bash Script

# Step 1: Download the script
curl -L https://raw.githubusercontent.com/ErdemOzgen/blackdagger/main/scripts/blackdagger-installer.sh -o blackdagger-installer.sh

# Step 2: Make the script executable if needed
chmod +x blackdagger-installer.sh

# Step 3: Run the script with sudo
sudo bash blackdagger-installer.sh

Important Note: Within the Blackdagger server, to access the GoTTY web terminal, you must manually start the default-gotty-service DAG found in the DAGs section. Blackdagger utilizes GoTTY for web terminal functionality, which, for security reasons, does not automatically start upon system initialization.

Via Docker

# Clone the repository and run Docker Compose
git clone https://github.com/ErdemOzgen/blackdagger.git
cd blackdagger
docker compose up
# If docker compose does not work please try to docker compose build
#docker compose build

Access the Web UI at http://127.0.0.1:8080 and the GoTTY web terminal at http://127.0.0.1:8090 (username: blackdagger, password: blackdagger) (Do not forget to run default-gotty-service dag at http://[::]:8080/dags/default-gotty-service).

Via GitHub Releases Page

Download the latest binary from the Releases page and place it in your $PATH (e.g. /usr/bin).

Sudo Configurations

Some YAML configurations or processes executed through Blackdagger may require sudo permissions. To ensure smooth operation, users should configure the necessary sudo access beforehand. Without it, core functionalities such as running, maintaining, or stopping processes—as well as other Blackdagger features—may not function correctly or could result in errors. Below are several options for configuring sudo permissions:

1. First and suggested option is adding user account to the /etc/sudoers file with NOPASSWD permissions, enabling them to execute sudo commands without needing to enter a password. This modification simplifies operations that require elevated privileges by removing the requirement to provide a password for each sudo command.

In the terminal, type the f