Run Pentest Swarm AI in GitHub Actions CI Workflows

The official Pentest Swarm AI GitHub Action installs the pentestswarm binary, runs a scan against a configured target, and emits both a Markdown report and a SARIF file. SARIF output flows directly into GitHub Code Scanning — findings appear in the repository’s Security tab, are annotated on pull requests, and can be tracked over time. Job exit codes are controlled by a configurable severity threshold so pipelines fail automatically when high-severity issues are found.

Set up the workflow

Add your API key as a GitHub Actions secret

In your repository go to Settings → Secrets and variables → Actions → New repository secret and create:

Secret nameValueANTHROPIC_API_KEYYour Claude API key (sk-ant-...)

The action reads ANTHROPIC_API_KEY from the environment automatically if api-key input is not set explicitly.

Add repository variables for the target and scope

Create Actions variables (not secrets) for the scan target and scope:

Variable nameExample valuePENTEST_TARGETexample.comPENTEST_SCOPEexample.com,api.example.com

Add the workflow file

Create .github/workflows/pentest.yml in your repository. The full working example from the action repository:

# Example workflow that consumes the Pentest Swarm AI action.
# Copy this into your repo at .github/workflows/pentest.yml.

name: Pentest Swarm

on:
  schedule:
    - cron: "0 2 * * 1"   # weekly, Mondays 02:00 UTC
  workflow_dispatch:

permissions:
  contents: read
  security-events: write    # required for SARIF upload to Code Scanning

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Pentest Swarm
        id: swarm
        uses: Armur-Ai/Pentest-Swarm-AI@v0
        with:
          target: ${{ vars.PENTEST_TARGET }}
          scope: ${{ vars.PENTEST_SCOPE }}
          mode: bugbounty
          swarm: "true"
          fail-on: high
          api-key: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: pentest-report
          path: ./pentest-report

      - name: Upload SARIF to Code Scanning
        if: always() && steps.swarm.outputs.sarif-path != ''
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: ${{ steps.swarm.outputs.sarif-path }}

The permissions: security-events: write grant is required for the SARIF upload step to write findings to Code Scanning.

Upload SARIF to GitHub Code Scanning

The github/codeql-action/upload-sarif@v3 step reads the sarif-path output from the scan step and uploads it. Once uploaded, findings appear in Security → Code scanning alerts and are annotated on any open pull requests that touch affected code.

- name: Upload SARIF to Code Scanning
  if: always() && steps.swarm.outputs.sarif-path != ''
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: ${{ steps.swarm.outputs.sarif-path }}

Use if: always() so the upload runs even when the scan step exits with a non-zero code (i.e., when fail-on is triggered).

Configure the fail-on threshold

Set fail-on to the lowest severity that should fail the CI job. The action checks the report for matching severity rows and exits 1 if any are found:

- name: Run Pentest Swarm
  uses: Armur-Ai/Pentest-Swarm-AI@v0
  with:
    target: ${{ vars.PENTEST_TARGET }}
    scope: ${{ vars.PENTEST_SCOPE }}
    fail-on: high   # fail on Critical or High

Action inputs reference

Input	Required	Default	Description
`target`	✅	—	The target to scan: domain, URL, or CIDR
`scope`	✅	—	Comma-separated domain / CIDR list for scope enforcement
`mode`	❌	`manual`	Scan mode: `manual`, `bugbounty`, `asm`, or `ctf`
`objective`	❌	`find all vulnerabilities`	Natural-language goal for the swarm
`swarm`	❌	`false`	Set to `true` to use the stigmergic swarm scheduler
`dry-run`	❌	`false`	Set to `true` to plan without executing exploitation commands
`api-key`	❌	reads `ANTHROPIC_API_KEY`	Claude API key; falls back to the environment variable
`version`	❌	`latest`	Pentest Swarm AI release to pin (e.g. `v0.2.0`)
`fail-on`	❌	`high`	Lowest severity that fails the job (see table below)

Action outputs

Output	Description
`report-path`	Path to the generated Markdown report (`./pentest-report/*.md`)
`sarif-path`	Path to the SARIF file, uploadable to GitHub Code Scanning
`findings-count`	Total number of findings recorded in the report

Reference outputs from subsequent steps:

- name: Print findings count
  run: echo "Found ${{ steps.swarm.outputs.findings-count }} findings"

Severity thresholds

The fail-on input controls when the job exits with a non-zero code. The action scans the Markdown report for severity rows matching the threshold pattern:

`fail-on` value	Job fails when report contains	Pattern matched
`critical`	Any Critical finding	`\| Critical \|`
`high`	Any Critical or High finding	`\| (Critical\|High) \|`
`medium`	Any Critical, High, or Medium finding	`\| (Critical\|High\|Medium) \|`
`low`	Any finding of any severity	`\| (Critical\|High\|Medium\|Low) \|`
`none`	Never — always passes	(threshold check skipped)

Set fail-on: none if you want findings reported without ever blocking the build (useful for initial rollouts while you establish a baseline).

How the action installs pentestswarm

The action’s composite runs section:

Detects the runner architecture (x86_64 → amd64, aarch64 / arm64 → arm64)
Resolves the pinned version or fetches the latest release tag from the GitHub API
Downloads the pre-built binary from the release URL and installs it to /usr/local/bin/pentestswarm
Runs the scan with all provided inputs assembled into the CLI argument array
Writes report-path, sarif-path, and findings-count to $GITHUB_OUTPUT

No Docker container, no language runtime, no setup step — just the Go binary.

Full working example

Below is the complete example-workflow.yml from the action repository, suitable for copy-paste:

name: Pentest Swarm

on:
  schedule:
    - cron: "0 2 * * 1"   # weekly, Mondays 02:00 UTC
  workflow_dispatch:

permissions:
  contents: read
  security-events: write

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Pentest Swarm
        id: swarm
        uses: Armur-Ai/Pentest-Swarm-AI@v0
        with:
          target: ${{ vars.PENTEST_TARGET }}
          scope: ${{ vars.PENTEST_SCOPE }}
          mode: bugbounty
          swarm: "true"
          fail-on: high
          api-key: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: pentest-report
          path: ./pentest-report

      - name: Upload SARIF to Code Scanning
        if: always() && steps.swarm.outputs.sarif-path != ''
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: ${{ steps.swarm.outputs.sarif-path }}

Use --dry-run on pull request checks to validate the scan configuration and enumerate targets without executing exploitation commands — this keeps PR checks fast and safe. Reserve full --swarm scans for the scheduled weekly run or a manual workflow_dispatch trigger on merge to main.

- name: Run Pentest Swarm (PR dry-run)
  if: github.event_name == 'pull_request'
  uses: Armur-Ai/Pentest-Swarm-AI@v0
  with:
    target: ${{ vars.PENTEST_TARGET }}
    scope: ${{ vars.PENTEST_SCOPE }}
    dry-run: "true"
    fail-on: none
    api-key: ${{ secrets.ANTHROPIC_API_KEY }}

CI/CD Security Playbook

Run the ci-cd-security playbook for secret scanning, SAST, and dependency audits inside the repo.

Bug Bounty

Switch to bugbounty mode and scope imports for external target scanning.

ASM

Schedule continuous attack surface monitoring with weekly scans.

MCP Integration

Drive ad-hoc scans interactively from Claude Desktop without a full workflow.

Get Started

Core Concepts

CLI Reference

Guides

Security & Operations

Run Pentest Swarm AI in GitHub Actions CI Workflows

Set up the workflow

Action inputs reference

Action outputs

Severity thresholds

How the action installs pentestswarm

Full working example

CI/CD Security Playbook

Bug Bounty

ASM

MCP Integration

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Reference

Guides

Security & Operations

Documentation Index

​Set up the workflow

​Action inputs reference

​Action outputs

​Severity thresholds

​How the action installs pentestswarm

​Full working example

CI/CD Security Playbook

Bug Bounty

ASM

MCP Integration

Build docs developers (and LLMs) love

Set up the workflow

Action inputs reference

Action outputs

Severity thresholds

How the action installs pentestswarm

Full working example