README

A powerful CLI tool for Composer security audits with blacklist functionality and JUnit XML reports for CI/CD integration.

✨ Features

• 🔍 Security Scanning: Runs composer audit and groups vulnerabilities by severity level
• 🚫 Blacklist Function: Ignore known packages and display them separately
• 📊 JUnit XML Reports: Perfect for Jenkins, GitLab CI, and other CI/CD systems
• ⚙️ Config File Support: Configuration via .auditguardrc.json file
• 🎨 Colored Output: Clear, color-coded terminal output
• 🔄 Flexible Options: Scan with or without dev dependencies

📦 Installation

Global

composer global require koeker/composer-audit-guard

Make sure your global composer bin directory is in your PATH.

Local (per project)

composer require --dev koeker/composer-audit-guard

🚀 Usage

Initialize Config File

Create a .auditguardrc.json config file in your project:

composer-audit-guard init

This creates a default config file that you can customize with your blacklist and settings.

Basic Scan

Standard scan without dev dependencies:

composer-audit-guard

or with composer exec:

composer exec composer-audit-guard

With Dev Dependencies

composer-audit-guard --dev

With Blacklist

Option 1: Using config file (recommended for multiple packages)

# Create config file once
composer-audit-guard init

# Edit .auditguardrc.json and add your packages to the blacklist array
# Then just run:
composer-audit-guard

Option 2: Command line (quick one-time use)

composer-audit-guard --blacklist="symfony/http-kernel,guzzlehttp/guzzle,monolog/monolog"

JUnit XML Report

# Standard output (./audit-results.xml)
composer-audit-guard --junit

# Custom output path
composer-audit-guard --junit --output="./test-results/security-audit.xml"

Important: The JUnit XML also includes blacklist warnings as failures!
If a package is on the blacklist but has no security issues, this will be reported as a failure in Jenkins/CI.
This helps keep your blacklist clean.

Combined

composer-audit-guard --dev --blacklist="old-package,legacy-dep" --junit --output="./reports/audit.xml"

📋 Example Output

Running security audit... [████████████████████] 100%

=== Security Audit Results ===

Critical:
  - symfony/http-kernel (>=2.0.0 <5.4.20)
  - guzzlehttp/guzzle (>=6.0.0 <6.5.8)

High:
  - monolog/monolog (>=1.0.0 <1.27.1)

Moderate:
  - symfony/mime (>=4.3.0 <4.4.48)

Ignored (Blacklisted):
  - old-package (high)
  - legacy-dep (moderate)

Warning: Blacklisted package "another-package" not found in audit results

=== Summary ===
Total vulnerabilities found: 4
Ignored (blacklisted): 2

✗ 4 vulnerabilities require attention!

⚙️ Configuration

Config File (.auditguardrc.json)

You can create a config file to persist your audit settings. The file is automatically loaded if it exists in your project directory.

Option 1: Using the init command (recommended)

composer-audit-guard init

This creates a .auditguardrc.json file with default settings that you can customize.

Option 2: Manual creation

Create a .auditguardrc.json file in your project root:

{
  "blacklist": [
    "package-name-1",
    "package-name-2",
    "old-legacy-package"
  ],
  "includeDev": false
}

How it works:

• ✅ The config file is automatically detected and loaded - no extra command needed
• ✅ Run composer-audit-guard and it will use your blacklist from the config file
• ⚠️ CLI parameters override config file settings (e.g., --blacklist on command line takes priority)

CLI Commands & Options

Commands:

Options:

🔄 CI/CD Integration

Jenkins

pipeline {
    agent any
    stages {
        stage('Security Audit') {
            steps {
                sh 'composer exec composer-audit-guard -- --junit --output="./test-results/audit.xml"'
            }
            post {
                always {
                    junit 'test-results/audit.xml'
                }
            }
        }
    }
}

GitLab CI

security_audit:
  script:
    - composer exec composer-audit-guard -- --junit --output="audit-results.xml"
  artifacts:
    when: always
    reports:
      junit: audit-results.xml

GitHub Actions

name: Security Audit

on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
      - run: composer install
      - run: composer exec composer-audit-guard -- --junit --output="audit-results.xml"
      - uses: actions/upload-artifact@v3
        if: always()
        with:
          name: audit-results
          path: audit-results.xml

📊 Exit Codes

📄 Requirements

• PHP >= 8.0
• Composer >= 2.0

🔗 Related Projects

• npm-audit-guard - The npm/Node.js version of this tool

📝 License

MIT License - see LICENSE file for details.