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

```bash
# 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

```bash
# 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](https://github.com/FriendsOfPHP/security-advisories).

### Output Formats

**Table Format (Human-Readable):**
```bash
composer security:audit
# or
make security-check
```

**JSON Format (Machine-Readable):**
```bash
composer security:audit-json
# or
make security-audit-json
```

Example JSON structure:
```json
{
  "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):

```bash
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

```bash
# 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

```yaml
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:
```json
{
  "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`:
```bash
#!/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:
```bash
chmod +x .git/hooks/pre-commit
```

### 2. Scheduled Local Scans

Add to crontab for daily scans:
```cron
0 9 * * * cd /path/to/project && make security-check
```

### 3. Pull Request Template

Include security checklist in `.github/pull_request_template.md`:
```markdown
## 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:**
```bash
# 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:
```bash
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](https://github.com/FriendsOfPHP/security-advisories)
- [Composer Audit Documentation](https://getcomposer.org/doc/03-cli.md#audit)
- [Roave Security Advisories](https://github.com/Roave/SecurityAdvisories)
- [OWASP Dependency Check](https://owasp.org/www-project-dependency-check/)
- [GitHub Security Advisories](https://github.com/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