# Audit Scripts Documentation

This project provides separate scripts for security vulnerability scanning and license compliance auditing, allowing for independent execution and CI/CD integration.

## Available Scripts

### 🔐 Security Audit: `security-audit`

Performs security vulnerability scanning of production dependencies.

**What it does:**
- Scans `prod-requirements.txt` for known security vulnerabilities
- Generates SBOM (Software Bill of Materials) in CycloneDX format
- Creates GitLab-compatible dependency scanning reports

**Generated Files:**
- `gl-sbom.json` - Security SBOM in CycloneDX format
- `gl-dependency-scanning-report.json` - GitLab security vulnerability report

**Usage:**
```bash
security-audit
```

### 📄 License Audit: `license-audit`

Performs license compliance scanning and policy enforcement.

**What it does:**
- Scans all dependencies for license information
- Analyzes against defined license policy (`.license-policy.yaml`)
- Generates detailed compliance reports with risk assessment

**Generated Files:**
- `license-report.json` - Detailed license information (JSON format)
- `license-report.csv` - License information (CSV format)
- `license-report.txt` - Human-readable license report
- `license-compliance-report.json` - Policy compliance analysis with risk assessment

**Environment Variables:**
- `EKFSM_FULL_LICENSE_SCAN=true` - Scan production dependencies only (isolated environment)
- `EKFSM_FULL_LICENSE_SCAN=false` (default) - Include development dependencies

**Usage:**
```bash
# Development scan (includes dev dependencies)
license-audit

# Production scan (production dependencies only)
EKFSM_FULL_LICENSE_SCAN=true license-audit
```

### 🔍 Combined Audit: `audit-scan`

Runs both security and license audits sequentially.

**Usage:**
```bash
audit-scan
```

## CI/CD Integration

### Separate CI Jobs

The project provides separate GitLab CI job configurations:

**Security Job** (`.gitlab/ci/security.yml`)
- Focuses on vulnerability scanning
- Generates security artifacts for GitLab Security Dashboard
- Allow failure: `true` (warnings only)

**License Job** (`.gitlab/ci/license.yml`)
- Focuses on license compliance
- Enforces license policy compliance
- Allow failure: `false` (fails pipeline on policy violations)
- Uses production-only scanning (`EKFSM_FULL_LICENSE_SCAN=true`)

### Benefits of Separation

1. **Independent Execution** - Run security or license audits separately
2. **Faster Feedback** - Parallel execution in CI pipelines
3. **Different Failure Policies** - Security warnings vs license policy enforcement
4. **Specialized Artifacts** - Targeted reports for different compliance needs
5. **Easier Debugging** - Isolated logs for troubleshooting specific audit types

### Migration

Existing workflows using `audit-scan` continue to work unchanged. The combined script now internally calls the separate scripts, maintaining backward compatibility while enabling the new separation benefits.

## Quick Reference

| Command | Purpose | Production Only | Fail on Issues |
|---------|---------|-----------------|----------------|
| `security-audit` | Vulnerability scanning | ✅ | ❌ (warnings) |
| `license-audit` | License compliance | ⚙️ (configurable) | ⚙️ (configurable) |
| `audit-scan` | Both audits | ⚙️ (configurable) | ⚙️ (configurable) |

## License Policy Configuration

License compliance is controlled by `.license-policy.yaml`. See `LICENSE-COMPLIANCE.md` for detailed policy configuration options.
