Metadata-Version: 2.4
Name: seclab-taskflows
Version: 0.1.0
Summary: Example taskflows to use with the the GitHub Security Lab Taskflow Agent Framework (https://github.com/GitHubSecurityLab/seclab-taskflow-agent)
Project-URL: Source, https://github.com/GitHubSecurityLab/seclab-taskflows
Project-URL: Issues, https://github.com/GitHubSecurityLab/seclab-taskflows/issues
Author-email: GitHub Security Lab <securitylab@github.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: seclab-taskflow-agent==0.4.0
Description-Content-Type: text/markdown

# GitHub Security Lab Taskflows

This repository contains example taskflows to use with the [SecLab Taskflow Agent](https://github.com/GitHubSecurityLab/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:

```bash
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](https://github.com/juice-shop/juice-shop) as an example:

```bash
./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](https://docs.github.com/en/copilot/concepts/billing).
> Alternatively, you could use a different AI API by setting the `AI_API_ENDPOINT` environment variable, as explained [here](https://github.com/GitHubSecurityLab/seclab-taskflow-agent#configuration).

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](https://github.com/features/codespaces) are convenient, or if you prefer you can use the script [`run_seclab_agent.sh`](scripts/run_seclab_agent.sh) to run a docker container of the `seclab-taskflow-agent` as outlined [here](https://github.com/GitHubSecurityLab/seclab-taskflow-agent/tree/main?tab=readme-ov-file#deploying-from-docker). 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`](scripts/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`](https://pypi.org/project/platformdirs/).

In addition, AI API endpoints and secrets also need to be configured via [environment variables or Codespace secrets](https://github.com/GitHubSecurityLab/seclab-taskflow-agent?tab=readme-ov-file#configuration). 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:

```bash
./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](https://github.com/GitHubSecurityLab/seclab-taskflows) is a companion repository to the [SecLab Taskflow Agent](https://github.com/GitHubSecurityLab/seclab-taskflow-agent) repository.
SecLab Taskflow Agent is an experimental agentic framework maintained by [GitHub Security Lab](https://securitylab.github.com/). 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](https://github.com/GitHubSecurityLab/seclab-taskflows/issues/new/choose) to send us a feature request or bug report. We also welcome pull requests (see our [contribution guidelines](./CONTRIBUTING.md) 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](https://spdx.org/licenses/MIT.html) license. Please refer to the [LICENSE](./LICENSE) file for the full terms.

## Maintainers

[CODEOWNERS](./CODEOWNERS)

## Support

[SUPPORT](./SUPPORT.md)
