GitHub Security Lab Taskflows

This repository contains example taskflows to use with the SecLab Taskflow Agent, as well as the custom MCP servers that are needed to run the taskflows.

Quick start

• Go to https://github.com/GitHubSecurityLab/seclab-taskflows and start a codespace.
• Wait a few minutes for the codespace to start. It's ready when you see (.venv) before the prompt in the terminal.
• Run the demo:

python -m seclab_taskflow_agent -t seclab_taskflows.taskflows.audit.ghsa_variant_analysis_demo -g repo=github/cmark-gfm -g ghsa=GHSA-c944-cv5f-hpvr

Now try running our auditing taskflows on one of your projects. Here, we're using the OWASP Juice Shop as an example:

./scripts/audit/run_audit.sh juice-shop/juice-shop

⚠️ Note: the auditing taskflows can take several hours to run, especially on larger projects, and make a lot of AI requests, which can cost a non-trivial amount of money. By default, the taskflows use the Copilot API. You can find out more information about Copilot Billing here. Alternatively, you could use a different AI API by setting the AI_API_ENDPOINT environment variable, as explained here.

The results of the audit are written to an SQLite database, which is opened automatically in an SQLite viewer at the end of the run. The results are in the table named "audit_result". The table has a column named "has_vulnerability", with checkmarks in the rows that are most likely to be genuine vulnerabilities.

Running with docker script

We recommend running taskflows in a sandboxed environment. GitHub Codespaces are convenient, or if you prefer you can use the script run_seclab_agent.sh to run a docker container of the seclab-taskflow-agent as outlined here. Note that this script needs to be run from the main directory of the repo, and the .env file with the environment variables for the custom MCP servers to store data needs to be in the same directory.

First, create a .env file in the main directory of the repo. For run_seclab_agent.sh you can use:

MEMCACHE_STATE_DIR=/app/data
CODEQL_DBS_BASE_PATH=/app/data
DATA_DIR=/app/data
LOG_DIR=/app/logs

The MEMCACHE_STATE_DIR is needed to persist some intermediate data in the memcache, DATA_DIR is needed for various mcp servers to store intermediate results, and LOG_DIR is used to store log files generated by the servers. These can be set in a .env file in the main directory. If no environment variables are set for the custom MCP servers, relevant folders will be created automatically. The location depends on the platform, and is set by platformdirs.

In addition, AI API endpoints and secrets also need to be configured via environment variables or Codespace secrets. In particular, the environment variables AI_API_TOKEN and AI_API_ENDPOINT need to be set to the appropriate AI API endpoints and credentials. If not set, the default AI_API_ENDPOINT is GitHub Copilot:

AI_API_ENDPOINT="https://api.githubcopilot.com"

In addition, the GH_TOKEN environment variable also needs to be set to allow interaction with the GitHub API, such as fetching content, creating issues etc.

Individual taskflows may need additional setup, please refer to the README.md in the relevant subdirectories for further requirements.

After setting the relevant env vars, run an example taskflow with:

./scripts/run_seclab_agent.sh -t seclab_taskflows.taskflows.audit.ghsa_variant_analysis_demo -g repo=github/cmark-gfm -g ghsa=GHSA-c944-cv5f-hpvr

Background

SecLab Taskflows is a companion repository to the SecLab Taskflow Agent repository. SecLab Taskflow Agent is an experimental agentic framework maintained by GitHub Security Lab. This repository provides example taskflows and supporting resources for use with the SecLab Taskflow Agent. We are using the agent and these taskflows to experiment with using AI Agents for security purposes, such as auditing code for vulnerabilities or triaging issues.

We'd love to hear your feedback. Please create an issue to send us a feature request or bug report. We also welcome pull requests (see our contribution guidelines for more information if you wish to contribute).

Requirements

Python >= 3.10 or Docker

License

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

Maintainers

CODEOWNERS

Support

SUPPORT