michaelschiemer/docs/dependency-scanning.md

Automated Dependency Scanning

Comprehensive guide for automated security vulnerability scanning in the Custom PHP Framework project.

Overview

This project implements a multi-layered security scanning strategy to protect against vulnerable dependencies:

1. Composer Audit - Active vulnerability scanning
2. Makefile Targets - Developer workflow integration
3. GitHub Actions - Automated CI/CD scanning
4. Roave Security Advisories - Passive prevention (deferred for PHP 8.5 compatibility)

Quick Start

Local Development

# Run security audit
make security-check

# Get JSON output for detailed analysis
make security-audit-json

# Check only production dependencies
make security-check-prod

Composer Scripts

# Direct composer commands
docker exec php composer security:audit
docker exec php composer security:audit-json
docker exec php composer security:check

Composer Audit

What is Composer Audit?

Built-in security vulnerability scanning tool (available since Composer 2.4+) that checks installed packages against the PHP Security Advisories Database.

Output Formats

Table Format (Human-Readable):

composer security:audit
# or
make security-check

JSON Format (Machine-Readable):

composer security:audit-json
# or
make security-audit-json

Example JSON structure:

{
  "advisories": {
    "vendor/package": [
      {
        "title": "Security vulnerability title",
        "cve": "CVE-2024-12345",
        "severity": "high",
        "link": "https://github.com/advisories/GHSA-xxxx",
        "affectedVersions": ">=1.0.0,<1.5.3"
      }
    ]
  },
  "abandoned": {
    "old/package": "new/replacement-package"
  }
}

Production-Only Scanning

To scan only production dependencies (excluding dev packages):

composer security:check
# or
make security-check-prod

This is useful for production deployment pipelines where dev dependencies are not installed.

Makefile Integration

Available Targets

Target	Description	Output Format
make security-check	Run composer security audit	Table (human-readable)
make security-audit-json	Run security audit with JSON output	JSON (machine-readable)
make security-check-prod	Check only production dependencies	Table (human-readable)

Usage in Development Workflow

# Before committing changes
make security-check

# Before creating a pull request
make security-check-prod

# Automated in pre-commit hook (recommended)
#!/bin/bash
make security-check || exit 1

Gitea Actions CI/CD

Workflow Configuration

File: .gitea/workflows/security-scan.yml

Triggers:

• Push to main or develop branches
• Pull requests to main or develop
• Scheduled daily at 2 AM UTC
• Manual workflow dispatch

Features

1. Automated Scanning: Runs on every push and PR
2. Daily Scheduled Scans: Catches newly disclosed vulnerabilities
3. Artifact Upload: Stores audit results for 30 days
4. Gitea Issue Creation: Automatically creates security issues on scheduled scans (requires GITEA_TOKEN)
5. Job Summary: Provides clear summary in Gitea Actions UI

Workflow Steps

1. Checkout code
2. Setup PHP 8.4
3. Validate composer.json
4. Cache Composer packages
5. Install dependencies (production only)
6. Run security audit
7. Parse results
8. Upload artifacts
9. Create GitHub issue (if vulnerabilities found in scheduled run)
10. Generate job summary

Viewing Results

Gitea Actions UI:

• Navigate to repository → Actions → Security Vulnerability Scan
• Click on latest workflow run
• View "Summary" tab for quick overview
• Download security-audit-results-{run_number} artifact for detailed JSON

Automated Gitea Issues:

• Created automatically when scheduled scan detects vulnerabilities
• Labels: security, dependencies, automated
• Contains detailed vulnerability information and remediation links
• Note: Requires GITEA_TOKEN secret configured in repository settings

Setting up GITEA_TOKEN

1. Generate a Gitea access token:

   • Navigate to Settings → Applications → Generate New Token
   • Permissions needed: write:issue
   • Copy the generated token

2. Add as repository secret:

   • Repository → Settings → Secrets
   • Add new secret: GITEA_TOKEN
   • Paste the access token

3. Verify configuration:

   • Push a commit to trigger the workflow
   • Check workflow logs for "GITEA_TOKEN not configured" warnings

Roave Security Advisories (Future Integration)

What is Roave Security Advisories?

A Composer package that prevents installation of packages with known security vulnerabilities by declaring conflicts in composer.json.

Status: Deferred due to PHP 8.5 RC2 compatibility issues.

How It Works

When added as a dev dependency:

{
  "require-dev": {
    "roave/security-advisories": "dev-latest"
  }
}

Roave automatically blocks composer install or composer update if any installed package has known vulnerabilities.

Why Deferred?

Current project uses PHP 8.5 RC3 (bleeding edge), which causes dependency resolution conflicts:

brianium/paratest v7.8.4 requires php ~8.2.0 || ~8.3.0 || ~8.4.0
your php version (8.5.0RC4) does not satisfy that requirement

Planned Integration: When PHP 8.5 stable is released and all testing dependencies support it.

ℹ️ PHP Runtime Strategy:

• Runtime container builds accept --build-arg PHP_VERSION (default 8.5.0RC4) to keep PHP aligned with upstream RC tags.
• .gitea/workflows/production-deploy.yml sets the same version for CI rebuilds (--pull ensures fresh layers).
• We'll move to 8.5.0RC4 as soon as upstream publishes the image and switch to the latest stable PHP release at the end of November.

Roave vs Composer Audit

Feature	Roave Security Advisories	Composer Audit
Type	Passive prevention	Active scanning
Blocks installation	✅ Yes	❌ No
Manual intervention	Required	Optional
CI/CD friendly	⚠️ Can break builds	✅ Doesn't break workflow
Production use	Best for development	Best for CI/CD

Recommendation: Use both for comprehensive security:

• Roave prevents accidental installation of vulnerable packages
• Composer Audit provides actionable scanning and reporting

Security Workflow Best Practices

1. Pre-Commit Hook

Create .git/hooks/pre-commit:

#!/bin/bash

echo "Running security audit..."
make security-check

if [ $? -ne 0 ]; then
    echo "❌ Security vulnerabilities detected. Commit aborted."
    echo "Run 'make security-check' to see details."
    exit 1
fi

echo "✅ No security vulnerabilities found."

Make executable:

chmod +x .git/hooks/pre-commit

2. Scheduled Local Scans

Add to crontab for daily scans:

0 9 * * * cd /path/to/project && make security-check

3. Pull Request Template

Include security checklist in .github/pull_request_template.md:

## Security Checklist

- [ ] Ran `make security-check` - No vulnerabilities found
- [ ] No new direct dependencies added
- [ ] Updated dependencies reviewed for security advisories

4. Dependency Update Strategy

Monthly Dependency Updates:

# 1. Check current security status
make security-check

# 2. Update dependencies
docker exec php composer update

# 3. Run security audit again
make security-check

# 4. Run tests
make test

# 5. Commit if all checks pass
git add composer.lock
git commit -m "chore: update dependencies - security audit passed"

Interpreting Audit Results

No Vulnerabilities Found

No security vulnerability advisories found.

Action: ✅ No action required. Dependencies are secure.

Vulnerabilities Detected

Found 2 security vulnerability advisories affecting 1 package:

vendor/package (1.2.3)
  - CVE-2024-12345: SQL Injection vulnerability
    Severity: high
    Link: https://github.com/advisories/GHSA-xxxx

Actions:

1. Review Severity: Critical/High = immediate action, Medium/Low = plan upgrade
2. Check Affected Versions: Determine if current version is vulnerable
3. Update Package: composer update vendor/package
4. Test Thoroughly: Run full test suite after update
5. Document Changes: Note security fix in commit message

Abandoned Packages

Found 1 abandoned package:

old/package is abandoned. Use new/replacement instead.

Actions:

1. Plan Migration: Schedule replacement in next sprint
2. Research Replacement: Verify new/replacement is suitable
3. Create Migration Task: Track in project management tool
4. Update Dependencies: Gradually migrate to replacement

Troubleshooting

Issue: Composer audit not working

Symptoms:

[RuntimeException]
Could not fetch security advisories

Solution:

1. Check internet connection
2. Verify Composer version: composer --version (requires >= 2.4)
3. Update Composer: composer self-update
4. Clear Composer cache: composer clear-cache

Issue: GitHub Actions workflow fails

Symptoms: Workflow runs but doesn't detect vulnerabilities

Solution:

1. Check workflow logs in GitHub Actions UI
2. Verify composer.lock is committed to repository
3. Ensure PHP version in workflow matches project requirements
4. Check if jq is available for JSON parsing

Issue: False positives

Symptoms: Audit reports vulnerabilities in dev dependencies for production

Solution: Use production-only scan:

make security-check-prod

This excludes dev dependencies from the audit.

Security Contacts

Security Issues: Report to security@example.com Vulnerability Disclosure: Follow responsible disclosure policy Bug Bounty: Check project documentation for bug bounty program

Additional Resources

• PHP Security Advisories Database
• Composer Audit Documentation
• Roave Security Advisories
• OWASP Dependency Check
• GitHub Security Advisories

Changelog

2024-10-19

• ✅ Implemented Composer audit scripts
• ✅ Added Makefile integration
• ✅ Created GitHub Actions workflow
• ⏳ Roave Security Advisories deferred for PHP 8.5 compatibility

Future Enhancements

• Integrate Roave Security Advisories when PHP 8.5 stable available
• Add Snyk or similar commercial scanning tool
• Implement automated pull requests for security updates (Dependabot)
• Create security dashboard for historical vulnerability tracking