ekfsm

# License Compliance Guide

This document explains how to use the license scanning features in this project to ensure OSS compliance.

## Quick Start

Run the enhanced audit scan that includes license analysis:
```bash
audit-scan
```

This will generate several reports:
- `license-report.json` - Detailed license information for all dependencies
- `license-report.csv` - License information in CSV format
- `license-report.txt` - Human-readable license report
- `license-compliance-report.json` - Compliance analysis based on project policy

## License Policy Configuration

The project uses [.license-policy.yaml](.license-policy.yaml) to define:

- **Permitted licenses**: Automatically approved (e.g., MIT, Apache-2.0)
- **Review required**: Need legal review (e.g., GPL, LGPL)
- **Prohibited licenses**: Not allowed in the project
- **Package exceptions**: Override license detection for specific packages

## Available Commands

### Full Audit Scan
```bash
audit-scan
```
Comprehensive security and license audit with compliance checking.

### License Quick Check
```bash
license-check
```
Display license information for current dependencies.

### License Summary
```bash
license-summary
```
Show aggregated license statistics.

## Understanding the Reports

### License Report (license-report.json)
Contains detailed information for each package:
```json
{
  "Name": "package-name",
  "Version": "1.0.0",
  "License": "MIT",
  "LicenseFile": "path/to/license/file",
  "Author": "Package Author"
}
```

### Compliance Report (license-compliance-report.json)
Provides compliance analysis:
```json
{
  "compliance_summary": {
    "permitted_licenses": 15,
    "review_required_licenses": 2,
    "prohibited_licenses": 0,
    "unknown_licenses": 1,
    "risk_level": "MEDIUM",
    "policy_compliant": true
  },
  "policy_violations": [],
  "potential_issues": [...]
}
```

## Risk Levels

- **LOW**: All licenses are permitted
- **MEDIUM**: Some licenses require review or are unknown
- **HIGH**: Prohibited licenses found or policy violations

## Handling Compliance Issues

### Unknown Licenses
1. Research the actual license for the package
2. Add to `package_exceptions` in `.license-policy.yaml` if permitted
3. Contact package maintainer to clarify licensing

### Review Required Licenses
1. Consult with legal team about copyleft implications
2. Document approval/rejection decision
3. Add to permitted or prohibited list as appropriate

### Policy Violations
1. Find alternative packages with compatible licenses
2. Get legal approval for exceptions
3. Remove the dependency if no alternatives exist

## CI/CD Integration

The audit-scan can be integrated into CI/CD:
- Exit code 0: All compliant
- Exit code 1: Policy violations found (fails build)

Configure behavior in `.license-policy.yaml`:
```yaml
compliance_settings:
  fail_on_prohibited: true      # Fail build on prohibited licenses
  warn_on_review_required: true # Warn on copyleft licenses
  fail_on_unknown: false       # Don't fail on unknown licenses
```

## Production vs Development Scanning

By default, the scan includes development dependencies. For production-only scanning:

```bash
EKFSM_FULL_LICENSE_SCAN=true audit-scan
```

This creates a clean environment with only production dependencies for more accurate compliance reporting.

## Best Practices

1. **Regular Scanning**: Run `audit-scan` before releases
2. **Dependency Updates**: Check licenses when adding new dependencies
3. **Policy Maintenance**: Review and update license policy regularly
4. **Documentation**: Document license decisions and approvals
5. **Legal Consultation**: Involve legal team for complex licensing questions

## Troubleshooting

### Missing License Information
Some packages may not include proper license metadata. Solutions:
- Check package repository for license files
- Look up license on PyPI package page
- Contact package maintainer
- Add manual override to `package_exceptions`

### False Positives
Sometimes license detection may be incorrect:
- Verify actual license in package source
- Use `package_exceptions` to override detection
- Report issues to `pip-licenses` project

### Policy Conflicts
When business requirements conflict with technical dependencies:
- Document the business case for exceptions
- Get legal approval for specific use cases
- Consider technical alternatives
- Regularly review exception list