Seclab Taskflow Agent

The Security Lab Taskflow Agent is an MCP enabled multi-Agent framework.

The Taskflow Agent is built on top of the OpenAI Agents SDK.

While the Taskflow Agent does not integrate into the GitHub Doctom Copilot UX, it does operate using the Copilot API (CAPI) as its backend, similar to Copilot IDE extensions.

Core Concepts

The Taskflow Agent leverages a GitHub Workflow-esque YAML based grammar to perform a series of tasks using a set of Agents.

Its primary value proposition is as a CLI tool that allows users to quickly define and script Agentic workflows without having to write any code.

Agents are defined through personalities, that receive a task to complete given a set of tools.

Agents can cooperate to complete sequences of tasks through so-called taskflows.

You can find a detailed overview of the taskflow grammar here and example taskflows here.

Use Cases and Examples

The Seclab Taskflow Agent framework was primarily designed to fit the iterative feedback loop driven work involved in Agentic security research workflows and vulnerability triage tasks.

Its design philosophy is centered around the belief that a prompt level focus of capturing vulnerability patterns will greatly improve and scale security research results as frontier model capabilities evolve over time.

While the maintainer himself primarily uses this framework as a code auditing tool it also serves as a more generic swiss army knife for exploring Agentic workflows. For example, the GitHub Security Lab also uses this framework for automated code scanning alert triage.

The framework includes a CodeQL MCP server that can be used for Agentic code review, see the CVE-2023-2283 for an example of how to have an Agent review C code using a CodeQL database (demo video).

Instead of generating CodeQL queries itself, the CodeQL MCP Server is used to provide CodeQL-query based MCP tools that allow an Agent to navigate and explore code. It leverages templated CodeQL queries to provide targeted context for model driven code analysis.

Requirements

Python >= 3.9 or Docker

Configuration

Provide a GitHub token for an account that is entitled to use GitHub Copilot via the COPILOT_TOKEN environment variable. Further configuration is use case dependent, i.e. pending which MCP servers you'd like to use in your taskflows.

You can set persisting environment variables via an .env file in the project root.

Example:

# Tokens
COPILOT_TOKEN=<your_github_token>
# MCP configs
GITHUB_PERSONAL_ACCESS_TOKEN=<your_github_token>
CODEQL_DBS_BASE_PATH="/app/my_data/"

Deploying from Source

First install the required dependencies:

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Then run python main.py.

Example: deploying a prompt to an Agent Personality:

python main.py -p assistant 'explain modems to me please'

Example: deploying a Taskflow:

python main.py -t example

Deploying from Docker

You can deploy the Taskflow Agent via its Docker image using docker/run.sh.

WARNING: the Agent Docker image is NOT intended as a security boundary but strictly a deployment convenience.

The image entrypoint is main.py and thus it operates the same as invoking the Agent from source directly.

You can find the Docker image for the Seclab Taskflow Agent here and how it is built here.

Note that this image is based on a public release of the Taskflow Agent, and you will have to mount any custom taskflows, personalities, or prompts into the image for them to be available to the Agent.

Optional image mount points to supply custom data are configured via the environment:

• Custom data via MY_DATA, mounts to /app/my_data
• Custom personalities via MY_PERSONALITIES, mounts to /app/personalities/my_personalities
• Custom taskflows via MY_TASKFLOWS, mounts to /app/taskflows/my_taskflows
• Custom prompts via MY_PROMPTS, mounts to /app/prompts/my_prompts
• Custom toolboxes via MY_TOOLBOXES, mounts to /app/toolboxes/my_toolboxes

See docker/run.sh for further details.

Example: deploying a Taskflow (example.yaml):

docker/run.sh -t example

Example: deploying a custom taskflow (custom_taskflow.yaml):

MY_TASKFLOWS=~/my_taskflows docker/run.sh -t custom_taskflow

Example: deploying a custom taskflow (custom_taskflow.yaml) and making local CodeQL databases available to the CodeQL MCP server:

MY_TASKFLOWS=~/my_taskflows MY_DATA=~/codeql_databases CODEQL_DBS_BASE_PATH=/app/my_data docker/run.sh -t custom_taskflow

For more advanced scenarios like e.g. making custom MCP server code available, you can alter the run script to mount your custom code into the image and configure your toolboxes to use said code accordingly.

export MY_MCP_SERVERS="$PWD"/mcp_servers
export MY_TOOLBOXES="$PWD"/toolboxes
export MY_PERSONALITIES="$PWD"/personalities
export MY_TASKFLOWS="$PWD"/taskflows
export MY_PROMPTS="$PWD"/prompts
export MY_DATA="$PWD"/data

if [ ! -f ".env" ]; then
    touch ".env"
fi

docker run \
       --volume "$PWD"/logs:/app/logs \
       --mount type=bind,src="$PWD"/.env,dst=/app/.env,ro \
       ${MY_DATA:+--mount type=bind,src=$MY_DATA,dst=/app/my_data} \
       ${MY_MCP_SERVERS:+--mount type=bind,src=$MY_MCP_SERVERS,dst=/app/my_mcp_servers,ro} \
       ${MY_TASKFLOWS:+--mount type=bind,src=$MY_TASKFLOWS,dst=/app/taskflows/my_taskflows,ro} \
       ${MY_TOOLBOXES:+--mount type=bind,src=$MY_TOOLBOXES,dst=/app/toolboxes/my_toolboxes,ro} \
       ${MY_PROMPTS:+--mount type=bind,src=$MY_PROMPTS,dst=/app/prompts/my_prompts,ro} \
       ${MY_PERSONALITIES:+--mount type=bind,src=$MY_PERSONALITIES,dst=/app/personalities/my_personalities,ro} \
       "ghcr.io/githubsecuritylab/seclab-taskflow-agent" "$@"

Personalities

Core characteristics for a single Agent. Configured through YAML files in personalities/.

These are system prompt level instructions.

Example:

# personalities define the system prompt level directives for this Agent
personality: |
  You are a simple echo bot. You use echo tools to echo things.

task: |
  Echo user inputs using the echo tools.

# personality toolboxes map to mcp servers made available to this Agent
toolboxes:
  - echo

Toolboxes

MCP servers that provide tools. Configured through YAML files in toolboxes/.

Example stdio config:

# stdio mcp server configuration
server_params:
  kind: stdio
  command: python
  args:
    - toolboxes/echo/echo.py
  env:
    SOME: value

Taskflows

A sequence of interdependent tasks performed by a set of Agents. Configured through a YAML based grammar in taskflows/.

Example:

taskflow:
  - task:
      # taskflows can optionally choose any of the support CAPI models for a task
      model: gpt-4.1
      # taskflows can optionally limit the max allowed number of Agent task loop
      # iterations to complete a task, this defaults to 50 when not provided
      max_steps: 20
      must_complete: true
      # taskflows can set a primary (first entry) and handoff (additional entries) agent
      agents:
        - c_auditer
        - fruit_expert
      user_prompt: |
        Store an example vulnerable C program that uses `strcpy` in the
        `vulnerable_c_example` memory key and explain why `strcpy`
        is insecure in the C programming language. Do this before handing off
        to any other agent.

        Then provide a summary of a high impact CVE ID that involved a `strcpy`
        based buffer overflow based on your GHSA knowledge as an additional
        example.

        Finally, why are apples and oranges healthy to eat?

      # taskflows can set temporary environment variables, these support the general
      # "{{ env FROM_EXISTING_ENVIRONMENT }" pattern we use elsewhere as well
      # these environment variables can then be made available to any stdio mcp server
      # through its respective yaml configuration, see memcache.yaml for an example
      # you can use these to override top-level environment variables on a per-task basis
      env:
        MEMCACHE_STATE_DIR: "example_taskflow/"
        MEMCACHE_BACKEND: "dictionary_file"
      # taskflows can optionally override personality toolboxes, in this example
      # kevin normally only has the memcache toolbox, but we extend it here with
      # the GHSA toolbox
      toolboxes:
        - ghsa
        - memcache
  - task:
      must_complete: true
      model: gpt-4.1
      agents:
        - c_auditer
      user_prompt: |
        Retrieve C code for security review from the `vulnerable_c_example`
        memory key and perform a review.

        Clear the memory cache when you're done.
      env:
        MEMCACHE_STATE_DIR: "example_taskflow/"
        MEMCACHE_BACKEND: "dictionary_file"
      toolboxes:
        - memcache

Taskflows support Agent handoffs. Handoffs are useful for implementing triage patterns where the primary Agent can decide to handoff a task to any subsequent Agents in the Agents list.

See the taskflow examples for other useful Taskflow patterns such as repeatable and asynchronous templated prompts.

License

This project is licensed under the terms of the MIT open source license. Please refer to the LICENSE file for the full terms.

Maintainers

CODEOWNERS

Support

SUPPORT

Acknowledgements

Security Lab team members Man Yue Mo and Peter Stockli for contributing heavily to the testing and development of this framework, as well as the rest of the Security Lab team for helpful discussions and feedback.