diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..cf0494c --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,33 @@ +# Copilot Instructions — seclab-taskflows + +## Project + +- **Name**: seclab-taskflows +- **Organization**: AiFeatures (fork from GitHubSecurityLab) +- **Enterprise**: iAiFy +- **Description**: Security lab task flows and automation templates + +## Conventions + +- Use kebab-case for file and directory names +- Use conventional commits (feat:, fix:, chore:, docs:, refactor:, test:) +- All PRs require review before merge +- Branch from main, merge back to main + +## Shared Infrastructure + +- Reusable workflows: Ai-road-4-You/enterprise-ci-cd@v1 +- Composite actions: Ai-road-4-You/github-actions@v1 +- Governance standards: Ai-road-4-You/governance + +## Quality Standards + +- Run lint and tests before submitting PRs +- Keep dependencies updated via Dependabot +- No hardcoded secrets — use GitHub Secrets or environment variables +- Follow OWASP Top 10 security practices + +## AgentHub Integration +- Skills: `.agents/skills/` in this repo links to shared AgentHub skills +- 14 shared agents available +- MCP: 12 servers (GitHub, Supabase, Playwright, MongoDB, Notion, HuggingFace, etc.) diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..cbd920f --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,10 @@ +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 419de51..e427ca6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,39 +2,14 @@ name: Python CI on: push: - branches: [ main ] + branches: [main] pull_request: - branches: [ main ] + branches: [main] permissions: contents: read jobs: - test: - name: Run Tests ${{ matrix.python-version }} on ${{ matrix.os }} - runs-on: ${{ matrix.os }} - strategy: - matrix: - os: [ubuntu-latest, windows-latest, macos-latest] - python-version: ['3.11', '3.13'] # the one we have in the Codespace + the latest supported one by PyO3. - fail-fast: false # Continue testing other version(s) if one fails - - steps: - - name: Checkout repository - uses: actions/checkout@v5 - - - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v6 - with: - python-version: ${{ matrix.python-version }} - cache: 'pip' - - - - name: Install Hatch - run: pip install --upgrade hatch - - - name: Run static analysis - run: hatch fmt --linter --check - - - name: Run tests - run: hatch test --python ${{ matrix.python-version }} --cover --randomize --parallel --retries 2 --retry-delay 1 + ci: + uses: Ai-road-4-You/enterprise-ci-cd/.github/workflows/ci-python.yml@v1 + secrets: inherit diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml new file mode 100644 index 0000000..48de185 --- /dev/null +++ b/.github/workflows/docker.yml @@ -0,0 +1,18 @@ +name: Docker + +on: + push: + branches: [main] + pull_request: + branches: [main] + +permissions: + contents: read + packages: write + +jobs: + docker: + uses: Ai-road-4-You/enterprise-ci-cd/.github/workflows/ci-docker.yml@v1 + with: + tags-override: latest + secrets: inherit diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..009532d --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,14 @@ +name: Release + +on: + push: + tags: + - "v*" + +permissions: + contents: write + +jobs: + release: + uses: Ai-road-4-You/enterprise-ci-cd/.github/workflows/release.yml@v1 + secrets: inherit diff --git a/.github/workflows/security-scan.yml b/.github/workflows/security-scan.yml new file mode 100644 index 0000000..89c03b6 --- /dev/null +++ b/.github/workflows/security-scan.yml @@ -0,0 +1,18 @@ +name: Security Scan + +on: + push: + branches: [main] + pull_request: + branches: [main] + schedule: + - cron: "0 6 * * 1" + +permissions: + contents: read + security-events: write + +jobs: + security: + uses: Ai-road-4-You/enterprise-ci-cd/.github/workflows/security-scan.yml@v1 + secrets: inherit diff --git a/.gitignore b/.gitignore index 3d413d4..4a4ebe4 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,47 @@ -*.log +# ============================================================================= +# Cross-language / cross-platform ignore rules +# ============================================================================= + +# OS junk +.DS_Store +Thumbs.db + +# Editor / IDE temp files +*.bak +*.swp +*.swo +.idea/ +.vscode/ +*.sublime-workspace +*.sublime-project + +# Node / JS / TS +node_modules/ +.next/ +.nuxt/ + +# Terraform +.terraform/ +*.tfstate +*.tfstate.* + +# Generic build / coverage artifacts +coverage/ + +# Environment files (broad glob) +.env* +!.env.example + +# Direnv .direnv .envrc +# ============================================================================= +# Python-specific (from github/gitignore) +# ============================================================================= + +*.log + # https://github.com/github/gitignore/blob/main/Python.gitignore # Byte-compiled / optimized / DLL files __pycache__/ @@ -133,9 +173,8 @@ celerybeat.pid # SageMath parsed files *.sage.py -# Environments -.env -.venv +# Environments (`.env*` covered by cross-language section above) +.venv/ env/ venv/ ENV/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..56c0932 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,47 @@ +# AI Agent Instructions + +## Repository: seclab-taskflows + +- **Organization**: AiFeatures (fork from GitHubSecurityLab) +- **Enterprise**: iAiFy + +## Shared Infrastructure + +| Resource | Reference | +|---|---| +| Reusable workflows | `Ai-road-4-You/enterprise-ci-cd@v1` | +| Composite actions | `Ai-road-4-You/github-actions@v1` | +| Governance docs | `Ai-road-4-You/governance` | +| Repo templates | `Ai-road-4-You/repo-templates` | + +## Conventions + +1. Use **conventional commits** (`feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`) +2. Create **feature branches** for all changes +3. Never push directly to `main` +4. Run tests before submitting PR +5. Keep dependencies updated via Dependabot +6. All file names in **kebab-case** + +## Quality Gates + +Before merging any PR: + +- [ ] Lint passes +- [ ] Tests pass (if test suite exists) +- [ ] No new security vulnerabilities +- [ ] PR has a meaningful description +- [ ] Conventional commit messages used + +## Branch Strategy + +- `main` — Production-ready, protected +- `feature/*` — New features +- `fix/*` — Bug fixes +- `chore/*` — Maintenance + +## Code Review + +- CODEOWNERS auto-assigns reviewers +- Self-merge allowed for single-developer workflow +- All changes must go through PR (org ruleset enforced) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..59eb503 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,22 @@ +# seclab-taskflows + +## Overview + +Security lab task flows and automation templates. + +## Project Structure + +- GitHub Security Lab workflows and task definitions + +## Conventions + +- Use kebab-case for file and directory names +- Use conventional commits +- Follow security best practices + +## AgentHub +- Central hub: `~/AgentHub/` +- Skills: `.agents/skills/` (symlinked to AgentHub shared skills) +- MCP: 12 servers synced across all agents +- Agents: 14 shared agents available +- Hooks: Safety, notification, and logging hooks diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..d6f0173 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,28 @@ +FROM python:3.12-slim AS builder + +WORKDIR /build + +COPY pyproject.toml README.md ./ +COPY src/ ./src/ + +RUN pip install --no-cache-dir --prefix=/install . + +# ----------------------------------------------------------- +FROM python:3.12-slim + +LABEL org.opencontainers.image.source="https://github.com/AiFeatures/seclab-taskflows" \ + org.opencontainers.image.description="Security lab task flows and automation templates" \ + org.opencontainers.image.licenses="MIT" + +COPY --from=builder /install /usr/local + +WORKDIR /app +COPY src/ ./src/ + +RUN groupadd --system appgroup && useradd --system --gid appgroup appuser +USER appuser + +HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \ + CMD ["python", "-c", "import seclab_taskflows; print('ok')"] + +ENTRYPOINT ["python", "-m", "seclab_taskflows"] diff --git a/README.md b/README.md index f226c13..0f84483 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,45 @@ -# GitHub Security Lab Taskflows +# seclab-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. +Example taskflows and custom MCP servers for the [SecLab Taskflow Agent](https://github.com/GitHubSecurityLab/seclab-taskflow-agent) framework. + +## Why this exists + +[GitHub Security Lab](https://securitylab.github.com/) maintains an experimental agentic framework for AI-driven security work — vulnerability auditing, alert triage, and variant analysis. This repository provides the concrete taskflow definitions, MCP server integrations, and helper scripts that turn the framework into runnable security workflows. It is a fork maintained by [AiFeatures](https://github.com/AiFeatures) as part of the iAiFy enterprise. + +## Status + +| Field | Value | +|-------|-------| +| Version | `0.0.4` (pre-release) | +| Python | `>= 3.9` | +| Build system | [Hatch](https://hatch.pypa.io/) | +| License | [MIT](./LICENSE) | ## 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: +### Option A — Codespace (recommended) + +1. Open this repo in a [GitHub Codespace](https://github.com/features/codespaces). +2. Wait for the devcontainer to finish (look for `(.venv)` in the prompt). +3. 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 +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: +### Option B — Local install ```bash -./scripts/audit/run_audit.sh juice-shop/juice-shop +pip install hatch +hatch env create ``` -> ⚠️ Note: the auditing taskflows can take several hours to run, especially on larger projects, and make a _lot_ of AI requests. -> You will almost certainly need a [Copilot Pro](https://github.com/github-copilot/pro) account to run them. - -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. +### Option C — Docker -## 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: +Create a `.env` file in the repo root: ``` MEMCACHE_STATE_DIR=/app/data @@ -39,44 +48,84 @@ DATA_DIR=/app/data LOG_DIR=/app/logs ``` +Then run: -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/). +```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 +``` -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 models: +### Environment variables +| Variable | Purpose | Default | +|----------|---------|---------| +| `AI_API_TOKEN` | AI API credentials | _(required)_ | +| `AI_API_ENDPOINT` | AI model endpoint | `https://models.github.ai/inference` | +| `GH_TOKEN` | GitHub API access | _(required)_ | + +> **Note:** Auditing taskflows can take several hours on large projects and require a [Copilot Pro](https://github.com/github-copilot/pro) account. + +### Running an audit + +```bash +./scripts/audit/run_audit.sh juice-shop/juice-shop ``` -AI_API_ENDPOINT="https://models.github.ai/inference" -``` -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. +Results are written to an SQLite database. The `audit_result` table has a `has_vulnerability` column marking likely genuine findings. + +## Package overview + +``` +src/seclab_taskflows/ +├── taskflows/ # Taskflow definitions (audit, triage, container shell) +├── mcp_servers/ # Custom MCP servers (GHSA, CodeQL, GitHub APIs, etc.) +├── configs/ # Agent and taskflow configuration +├── containers/ # Container image definitions +├── personalities/ # Agent persona prompts +├── prompts/ # Prompt templates +└── toolboxes/ # Tool definitions for taskflows +``` -Individual taskflows may need additional setup, please refer to the `README.md` in the relevant subdirectories for further requirements. +## Development -After setting the relevant env vars, run an example taskflow with: +Requires Python >= 3.9 and [Hatch](https://hatch.pypa.io/). ```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 -``` +# Install Hatch +pip install --upgrade hatch -## Background +# Lint (check only) +hatch fmt --linter --check -[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. +# Format +hatch fmt -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). +# Run tests with coverage +hatch test --cover --randomize --parallel --retries 2 --retry-delay 1 -## Requirements +# Type check +hatch run types:check +``` -Python >= 3.9 or Docker +## Deployment -## License +CI runs on every push and PR to `main` via `.github/workflows/ci.yml`. The pipeline: +- Lints with `hatch fmt --linter --check` +- Tests across Python 3.11 and 3.13 on Ubuntu, Windows, and macOS +- Publishing to PyPI/TestPyPI is handled by dedicated workflows -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. +Enterprise deployments use [Ai-road-4-You/enterprise-ci-cd@v1](https://github.com/Ai-road-4-You/enterprise-ci-cd) reusable workflows. -## Maintainers +## Security -[CODEOWNERS](./CODEOWNERS) +This project follows OWASP Top 10 practices. See [SECURITY.md](./SECURITY.md) for the vulnerability disclosure policy. No secrets should be hardcoded — use environment variables or GitHub Secrets. -## Support +## Contributing + +See [CONTRIBUTING.md](./CONTRIBUTING.md) and [Ai-road-4-You/governance](https://github.com/Ai-road-4-You/governance) for guidelines. + +## License -[SUPPORT](./SUPPORT.md) +[MIT](./LICENSE) — Copyright GitHub, Inc.