GitHub Actions Integration

The Pentest-Tools.com GitHub Action allows you to run automated security scans directly in your CI/CD pipeline.

Whether you're testing on every commit, protecting pull requests, or running scheduled security audits, this integration helps you catch vulnerabilities before they reach production.

What you can do:

• Run light scans (free, no API key required, but recommended in order to see the scans in the platform) for quick vulnerability checks
• Run deep scans (requires API key) for comprehensive security testing
• Automatically fail builds based on vulnerability severity
• Get results in JSON or text format for easy processing
• Configure flexible scanning on commits, pull requests, or schedules

How to Access the Configuration Tool

Head over to the Integrations section and click the GitHub Actions button.

As you fill in the details, the code snippet on the right side will automatically update to reflect your configuration.
This makes it easy to create your GitHub Action workflow without having to write any YAML code manually!

Configuration options:

1. Action name: Give your action a descriptive name (e.g., Security Scan)
2. Target: Enter the URL you want to scan (e.g., https://example.com)
3. Secret name: Specify the name of your GitHub secret containing the API key (e.g., PTT_API_KEY)
4. Output format: Choose between:
      - text: Human-readable format, ideal for logs
      - json: Structured format, perfect for parsing and automation
5. Fail condition: Select when the action should fail your build:
      - None: Never fail, always return success
      - Low: Fail if any vulnerability with low risk or higher is found
      - Medium: Fail if vulnerabilities with medium risk or higher are found
      - High: Fail if high-risk or critical vulnerabilities are found
      - Critical: Fail only if critical vulnerabilities are found
6. Scan type: Choose your scan depth:
      - Light: Quick scan (1-15 minutes)
      - Deep: Comprehensive scan (60-120 minutes)

Once you've configured all the options, the generated code on the right will be ready to use!

⚠️ Note: You will need to set up your GitHub Actions secret in your repository (see Step 3 below).

Step 2: Copy and create your workflow file

After configuring your settings in the integration page:

1. Copy the generated code from the right panel
2. In your GitHub repository, create a new file at .github/workflows/security-scan.yml 
3. Paste the generated code into this file
4. Optionally, add trigger conditions (see examples below for on: configuration)
5. Commit the file to your repository

Example with trigger conditions:

yaml
name: Security Scan

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  # Paste your generated job configuration here
  test_deep_scan:
    runs-on: ubuntu-latest
    steps:
      - name: Actual test
        uses: pentesttoolscom/pentesttools-github-action@master
        id: ptt
        with:
          target: https://pentest-ground.com
          format: json
          fail: high
          type: deep
          key: $
      - name: Check the output
        run: echo "The report $"

Once you commit this file, the action will run automatically based on your trigger configuration!

Step 3: Set up your API key in GitHub Secrets

If you're using deep scans, you'll need to add your Pentest-Tools.com API key to GitHub:

1. Get your API key:
   1. Click on Generate REST API key button
   2. Define a profile name
   3. Set the profile expiration time
   4. Save the API key provided
2. Add it to GitHub Secrets:
   1. In your GitHub repository, go to Settings → Secrets and variables → Actions
   2. Click New repository secret
   3. Name it PTT_API_KEY (or whatever you specified in the configuration tool)
   4. Paste your API key as the value
   5. Click Add secret

That's it! Your GitHub Action is now configured and ready to run.