provisioning-platform/prov-ecosystem/crates/audit/README.md

# Audit Module

Automated security audit framework for comprehensive vulnerability scanning, SBOM generation, policy enforcement, and compliance checking.

## Features

- **SBOM Generation**: CycloneDX and SPDX format support
- **Multi-Backend CVE Scanning**: Trivy, cargo-audit, Grype, OSV-scanner
- **Policy Enforcement**: OPA/Rego and Kyverno integration
- **SBOM Requirements**: Enforce SBOM for containers (production-ready)
- **Compliance Checking**: PCI-DSS, HIPAA aware rules
- **Chaos Engineering**: Fault injection testing (optional)
- **Comprehensive Reporting**: JSON, SARIF, HTML, Markdown formats
- **Integrated Metrics**: Prometheus integration with observability module
- **Event-Driven**: GitOps integration for automated workflows

## Quick Start

### Basic Audit

```rust
use audit::{AuditCoordinator, AuditRunner};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create coordinator with default config
    let coordinator = AuditCoordinator::new(audit::AuditConfig::default())?;

    // Create runner
    let runner = AuditRunner::new(coordinator);

    // Run full audit
    let report = runner.run().await?;
    println!("Audit report: {:?}", report.summary);

    Ok(())
}
```

### From Configuration File

```rust
// Load from TOML
let coordinator = AuditCoordinator::from_toml("audit.toml")?;
let runner = AuditRunner::new(coordinator);
let report = runner.run().await?;
```

## Configuration

### Minimal Configuration

```toml
[audit]
name = "my-app-audit"
enabled = true

[audit.sbom]
format = "cyclonedx"
required_for_containers = true

[audit.scanners]
enabled = ["trivy"]
fail_on_severity = "high"

[audit.policy]
enabled = true
engine = "opa"
rules_path = "./policies"
```

### Complete Configuration

```toml
[audit]
name = "comprehensive-audit"
enabled = true

[audit.sbom]
format = "cyclonedx"
cyclonedx_version = "1.6"
required_for_containers = true
output_dir = "./sbom"
retention_days = 90

[audit.scanners]
enabled = ["trivy", "cargo-audit"]
fail_on_severity = "high"
ignore_cves = ["CVE-2024-XXXX"]
ignore_unfixed = false

[audit.scanners.trivy]
endpoint = "http://localhost:8080"
timeout_secs = 30

[audit.policy]
enabled = true
engine = "opa"
rules_path = "./policies"
fail_on_violation = true

[audit.schedule]
enabled = true
cron = "0 6 * * *"  # Daily at 6 AM

[audit.report]
formats = ["json", "sarif", "html"]
output_dir = "./audit-reports"
detailed = true
retention_days = 90
```

## Features and Cargo

```toml
# Default features
audit = { version = "0.1", features = ["default"] }

# With all scanners
audit = { version = "0.1", features = ["scanner-full"] }

# With policy engine
audit = { version = "0.1", features = ["policy-opa"] }

# With chaos engineering
audit = { version = "0.1", features = ["chaos"] }

# Full integration
audit = { version = "0.1", features = ["full"] }
```

## SBOM Generation

### CycloneDX Format

```rust
let sbom = runner.run_sbom().await?;
// Generated SBOM with:
// - Component inventory
// - Licenses
// - Hashes (SHA-256)
// - Metadata
// - Tool information
```

### SBOM Requirements for Containers

Production containers automatically require SBOM:

```rego
# In sbom_required.rego
deny[msg] {
    input.container_type == "production"
    not input.sbom_present
    msg = "Production container requires SBOM"
}
```

## Vulnerability Scanning

### Supported Scanners

1. **Trivy** (recommended, default)
   - Container and package scanning
   - Large vulnerability database

2. **cargo-audit**
   - RustSec advisory database
   - Fast, Rust-specific

3. **Grype**
   - Multi-language support
   - Container and dependency scanning

4. **OSV-scanner**
   - Google's OSV database
   - No code execution required

### Running Scans

```rust
use audit::{ScanTarget, VulnerabilityScanner};

// Scan workspace
let target = ScanTarget::Workspace(Path::new("/path/to/project"));
let result = runner.run_scan(&target).await?;
println!("Found {} vulnerabilities", result.vulnerability_count());
```

## Policy Enforcement with OPA

### Policy Rules Location

```
crates/audit/policies/
├── sbom_required.rego          # SBOM mandatory for containers
├── cve_severity.rego           # CVE severity thresholds
└── secret_exposure.rego        # Detect exposed secrets
```

### Custom Policies

Create custom Rego rules in `./policies/`:

```rego
package audit.custom

# Example: Deny specific packages in production
deny[msg] {
    input.environment == "production"
    pkg := input.dependencies[_]
    pkg.name == "unsafe-package"
    msg = sprintf("Package %s not allowed in production", [pkg.name])
}
```

### Policy Evaluation

```rust
let evaluation = policy_engine.evaluate(input).await?;
if !evaluation.is_passed() {
    println!("Policy violations: {}", evaluation.violations.len());
}
```

## Integration with Other Crates

### Valida Integration

Convert vulnerabilities to validation rules:

```rust
#[cfg(feature = "valida-integration")]
use audit::integration::valida::vulnerability_to_rule;

let rule_condition = vulnerability_to_rule(&vuln)?;
// Creates: package == "tokio" && version == "1.0.0" && cve_severity == "critical"
```

### Observability Integration

Register audit metrics and health checks:

```rust
#[cfg(feature = "observability-integration")]
use audit::integration::observability::{
    register_audit_metrics,
    register_audit_health_checks,
};

register_audit_metrics();
register_audit_health_checks();
```

Metrics exported:
- `audit_vulnerabilities_total`
- `audit_sbom_generation_duration_seconds`
- `audit_policy_violations_total`
- `audit_scanner_duration_seconds`

### GitOps Integration

Trigger audits from GitOps events:

```rust
#[cfg(feature = "gitops-integration")]
use audit::integration::gitops::AuditEvent;

// Event-driven audit execution
// Triggers when code is pushed, alerts firing, or on schedule
```

## Reporting

### Report Formats

1. **JSON**: Machine-readable, detailed
2. **SARIF**: Static Analysis Results Format (GitHub Security tab)
3. **HTML**: Interactive dashboard
4. **Markdown**: Human-readable, shareable

### Generating Reports

```rust
let mut report = AuditReport::new("Security Audit");
report.add_scan_result(scan_result);
report.add_policy_evaluation(policy_eval);

// Save in multiple formats
report.write_to_file("report.json", ReportFormat::Json).await?;
report.write_to_file("report.sarif", ReportFormat::Sarif).await?;
report.write_to_file("report.html", ReportFormat::Html).await?;
```

### Grafana Dashboard

Pre-built dashboard available at `dashboards/audit_overview.json`:
- Vulnerability counts by severity
- Policy violation trends
- SBOM generation status
- Scan duration metrics
- Top affected packages

## Chaos Engineering (Optional)

Test application resilience to vulnerabilities and failures:

```toml
[audit.chaos]
enabled = true
platform = "chaos-mesh"
scenarios = ["network-latency", "resource-stress", "pod-failure"]
max_duration_minutes = 30
```

## Security Best Practices

1. **SBOM Management**
   - Store SBOMs in version control
   - Sign SBOM files
   - Retain for minimum 2 years

2. **Vulnerability Handling**
   - Act on critical/high within 24h
   - Document accepted risks
   - Track remediation progress

3. **Policy Enforcement**
   - Start in audit mode
   - Enforce in CI/CD pipeline
   - Regular policy reviews

4. **Secret Detection**
   - Scan for hardcoded credentials
   - Use encryption for secrets at rest
   - Rotate secrets regularly

## Troubleshooting

### Scanner Not Available

```
Error: Scanner not available: trivy. Install from...
```

Install the scanner:
```bash
# Trivy
curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh

# cargo-audit
cargo install cargo-audit

# Grype
curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh
```

### Policy Violations

Check policy rules at configured `rules_path`:
```bash
ls -la ./policies/
```

### SBOM Generation Issues

Ensure write permissions to `sbom.output_dir`:
```bash
chmod 755 ./sbom
```

## Performance

- SBOM generation: < 5 seconds for typical projects
- CVE scanning: 10-60 seconds depending on scanner
- Policy evaluation: < 1 second for typical rule sets
- Report generation: < 2 seconds

## Architecture

```
Audit Workflow:
┌─────────────────┐
│  AuditRunner    │
└────────┬────────┘
         │
    ┌────┴────┬─────────┬──────────┐
    ▼         ▼         ▼          ▼
  SBOM    Scanner    Policy    Report
  Gen     Engine     Engine    Generator
```

## License

MIT