Skip to content

Configuration

Configure and customize the security audit recipe to match your project's specific needs and requirements.

Prerequisites

Before configuring the workflow, make sure you've completed the initial setup.

Need to install first? Follow the Getting Started Guide for the one-command setup or manual installation.

Workflow Configuration

Customize Basic Settings

Modify these core settings in .github/workflows/security-audit.yml to match your project setup.

Workflow configuration options
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# Change default branch if needed
push:
  branches: [main]  # Change to: master, develop, etc.

# Adjust Python version
env:
  PYTHON_VERSION: "3.11"  # Change to: 3.8, 3.9, 3.10, etc.

# Modify schedule (optional)
schedule:
  - cron: "0 8 * * 1"  # Monday 8 AM UTC
  # Examples:
  # - cron: "0 0 * * 0"  # Sunday midnight UTC
  # - cron: "0 12 * * 5" # Friday noon UTC

Repository Permissions Required

Ensure your repository has the correct permissions for the workflow to create and manage issues.

Setup Steps:

  1. Go to Settings > Actions > General
  2. Scroll down to Workflow permissions
  3. Select "Read and write permissions"
  4. Check "Allow GitHub Actions to create and approve pull requests"
Required repository permissions
permissions:
  contents: read
  issues: write
  security-events: write

Advanced Configuration

Custom pip-audit Options

Enhance your security scans with additional pip-audit features and caching for better performance.

Custom pip-audit options
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
- name: Run pip-audit (JSON output)
  run: |
    # Basic scan
    pip-audit -r requirements.txt --format json --output audit-results.json

    # Scan with specific options
    pip-audit -r requirements.txt \
      --format json \
      --output audit-results.json \
      --desc \
      --cache-dir /tmp/pip-audit-cache
Multiple Requirements Files

Configure scanning for projects with separate development, testing, and production dependencies.

Multi-file scanning
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
- name: Run pip-audit on multiple files
  run: |
    mkdir -p audit-outputs

    # Scan main requirements
    pip-audit -r requirements.txt --format json --output audit-outputs/main.json || true

    # Scan dev requirements
    pip-audit -r requirements-dev.txt --format json --output audit-outputs/dev.json || true

    # Scan test requirements
    pip-audit -r requirements-test.txt --format json --output audit-outputs/test.json || true
Custom Issue Labels

Personalize issue creation with custom labels to match your team's workflow and prioritization system.

Custom issue creation with labels
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
- name: Create or update issue (vulnerabilities found)
  uses: actions/github-script@v7
  with:
    script: |
      const issueTitle = `🚨 Security: ${process.env.VULN_COUNT} vulnerabilities`;

      await github.rest.issues.create({
        title: issueTitle,
        body: issueBody,
        labels: [
          'security',
          'pip-audit',
          'vulnerability',
          'dependencies',
          'high-priority'  // Add custom labels
        ]
      });

Exclude Specific Packages

Ignore known false positives or vulnerabilities that don't apply to your use case.

- name: Run pip-audit with exclusions
  run: |
    pip-audit -r requirements.txt \
      --ignore-vuln GHSA-xxxx-xxxx-xxxx \
      --ignore-vuln CVE-2023-1234 \
      --format json \
      --output audit-results.json

Environment Variables

Available Workflow Variables

These environment variables are automatically set during the workflow execution and can be used for custom scripts or issue formatting.

# Audit results
$AUDIT_STATUS          # clean | vulnerabilities_found | error
$VULN_COUNT           # Number of vulnerabilities found
$AFFECTED_PACKAGES    # Number of packages with vulnerabilities

# GitHub context
${{ github.repository }}     # Repository name
${{ github.ref_name }}      # Branch name
${{ github.sha }}           # Commit SHA
${{ github.run_id }}        # Workflow run ID

pip-audit Command Reference

Complete pip-audit Command Guide

Comprehensive reference for all pip-audit commands and options you might need for security auditing.

# Basic usage
pip-audit -r requirements.txt

# Output formats
pip-audit -r requirements.txt --format json
pip-audit -r requirements.txt --format markdown
pip-audit -r requirements.txt --format columns
pip-audit -r requirements.txt --format cyclonedx-json
pip-audit -r requirements.txt --format cyclonedx-xml

# Fix vulnerabilities automatically
pip-audit -r requirements.txt --fix

# Ignore specific vulnerabilities
pip-audit -r requirements.txt --ignore-vuln CVE-2023-1234

# Scan local directory
pip-audit .

# Scan specific package
pip-audit package-name==1.0.0

Next: Explore Real-World Examples

📚 Documentation Progress Checklist

Track your progress through the Python Security Audit Recipe documentation:

  • 🏠 Home - Understanding the security challenge
  • 📖 Getting Started - Quick overview and concepts
  • ⚙️ Installation - Set up your environment
  • 🔄 Workflow Details - Understand GitHub Actions mechanics
  • 📋 Issue Templates - Master security notification management
  • 🔧 Configuration - Customize for your project needs
  • 📚 Examples - Real-world implementations

Next Up: Examples

Ready to see it in action? Continue to Examples to explore real-world implementations including Django, FastAPI, and monorepo setups!

Almost done! Check out examples to see complete implementations in various project types.