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

# Audit Module Integration Guide

## Overview

The audit module integrates with other prov-ecosystem crates to provide comprehensive security auditing across your infrastructure.

## Integration Architecture

```
┌─────────────────────────────────────────────────────┐
│                  Audit Module                        │
│  SBOM │ Scanners │ Policy Engine │ Reporting        │
└────────┬────────┬────────┬────────┬──────────────────┘
         │        │        │        │
    ┌────┴──┬─────┴─┐  ┌───┴──┬────┴──┬───────┐
    │       │       │  │      │       │       │
  valida  gitops  runtime encrypt  observ  backup
 (rules) (events) (SBOM)  (secrets) (metrics)
```

## 1. Valida Integration

### Converting Vulnerabilities to Validation Rules

The audit module automatically converts CVE findings to valida rules:

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

// Vulnerability from CVE scan
let vuln = Vulnerability {
    cve_id: "CVE-2024-12345".into(),
    package: "tokio".into(),
    installed_version: "1.0.0".into(),
    severity: VulnerabilitySeverity::Critical,
    // ...
};

// Convert to valida rule condition
let rule_condition = vulnerability_to_rule(&vuln)?;
// Result: package == "tokio" && version == "1.0.0" && cve_severity == "critical"
```

### Audit Rule Definition

Define audit rules in your KCL configuration:

```kcl
import valida

audit_rules = valida.RuleSet {
    name = "Security Audit Rules"
    rules = [
        valida.SecurityRule {
            id = "audit-critical-cve"
            name = "No Critical CVEs in Production"
            category = "security"
            severity = "error"
            contexts = ["deploy", "production"]
            mandatory_contexts = ["production"]
            condition = "cve_severity != 'critical'"
            message = "Critical CVEs must be remediated before production deployment"
        }
    ]
}
```

## 2. GitOps Integration

### Event-Driven Audits

Trigger audits from GitOps events:

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

// On git push
Event::GitPush {
    repo: "prov-ecosystem",
    branch: "main",
    // Trigger audit...
};

// Emit audit events
let audit_event = AuditEvent::AuditCompleted {
    status: "passed".into(),
};

// Emit vulnerability event
let vuln_event = AuditEvent::VulnerabilityDetected {
    cve_id: "CVE-2024-12345".into(),
};
```

### Automated Remediation

Create GitOps workflows for audit failures:

```yaml
# .gitops/audit-remediation.yaml
apiVersion: gitops.prov-ecosystem.io/v1
kind: Workflow
metadata:
  name: audit-remediation
spec:
  triggers:
    - type: audit
      event: vulnerability-detected
      severity: critical
  steps:
    - name: create-issue
      action: github.CreateIssue
      inputs:
        title: "Critical CVE Detected"
        body: "{{ .event.message }}"
    - name: notify-slack
      action: slack.Notify
      inputs:
        channel: "#security-alerts"
```

## 3. Observability Integration

### Audit Metrics

Register audit metrics with observability module:

```rust
#[cfg(feature = "observability-integration")]
{
    use observability::metrics;

    // Track vulnerabilities
    metrics::gauge!("audit_vulnerabilities_total").set(report.summary.total_vulnerabilities as f64);
    metrics::gauge!("audit_critical_count").set(report.summary.critical_count as f64);

    // Track scan duration
    metrics::histogram!("audit_scanner_duration_seconds").record(scan_result.duration_seconds);

    // Track policy violations
    metrics::gauge!("audit_policy_violations_total").set(report.summary.total_policy_violations as f64);
}
```

### Health Checks

Register audit health checks:

```rust
#[cfg(feature = "observability-integration")]
{
    use observability::health::checks::HealthCheckRegistry;

    let registry = HealthCheckRegistry::new();

    // Check if scanners are available
    registry.register("audit_scanners_available", || {
        if TrivyScanner::new().is_available().await.unwrap() {
            HealthStatus::Healthy
        } else {
            HealthStatus::Degraded
        }
    });

    // Check last audit result
    registry.register("audit_last_scan_status", || {
        if last_audit_passed {
            HealthStatus::Healthy
        } else {
            HealthStatus::Unhealthy
        }
    });
}
```

### Dashboard Integration

The observability module displays audit data in Grafana:

```json
{
  "dashboard": {
    "title": "Security Audit Dashboard",
    "panels": [
      {
        "title": "Vulnerabilities by Severity",
        "targets": [
          {"expr": "audit_vulnerabilities{severity='critical'}"},
          {"expr": "audit_vulnerabilities{severity='high'}"}
        ]
      },
      {
        "title": "Policy Violations Trend",
        "targets": [
          {"expr": "rate(audit_policy_violations_total[1h])"}
        ]
      }
    ]
  }
}
```

## 4. Runtime Integration

### SBOM Enforcement for Containers

Enforce SBOM generation when building containers:

```rust
#[cfg(feature = "runtime-integration")]
{
    use runtime::Container;

    let container = Container::build("my-app:latest")?;

    // Enforce SBOM requirement
    if container.is_production() && !container.has_sbom() {
        return Err(AuditError::sbom_required(
            "my-app:latest",
            "Production containers must include SBOM"
        ));
    }

    // Add SBOM to container metadata
    let sbom = runner.run_sbom().await?;
    container.attach_sbom(sbom)?;
}
```

### Container Scanning

Scan container images for vulnerabilities:

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

let scan_target = ScanTarget::Container("registry.example.com/my-app:latest".into());
let scan_result = runner.run_scan(&scan_target).await?;

if scan_result.critical_count() > 0 {
    println!("Container has critical vulnerabilities!");
}
```

## 5. Encrypt Integration

### Secret Detection Integration

Extend encrypt module's secret detection for audit:

```rust
#[cfg(feature = "encrypt-integration")]
{
    use encrypt::detect_secrets;

    // Detect secrets in codebase
    let secrets = detect_secrets(&source_code)?;

    // Check if secrets are encrypted
    for secret in secrets {
        if !secret.is_encrypted() {
            audit_violations.push(format!("Unencrypted {} found at {}",
                secret.secret_type, secret.location));
        }
    }
}
```

### Encryption Policy

Define encryption requirements in policies:

```rego
package audit.encryption

# All secrets must be encrypted
deny[msg] {
    secret := input.secrets[_]
    secret.encrypted == false
    msg = sprintf("Unencrypted secret %s in %s", [secret.type, secret.location])
}

# Require strong encryption algorithms
deny[msg] {
    secret := input.secrets[_]
    secret.algorithm in ["DES", "RC4", "MD5"]
    msg = sprintf("Weak encryption algorithm %s for secret %s", [secret.algorithm, secret.name])
}
```

## 6. Backup Module Integration

### Audit Backup Configuration

Ensure backup configurations are audited:

```toml
# audit.toml
[audit.policy.rules.backup-audit]
id = "backup-configuration-audit"
name = "Backup Configuration Security Check"
engine = "opa"
rules_path = "./policies/backup"

# policies/backup/retention.rego
package audit.backup

deny[msg] {
    backup := input.backups[_]
    backup.retention_days < 30
    msg = sprintf("Backup %s retention too short: %d days", [backup.name, backup.retention_days])
}
```

## 7. N8N Integration

### Workflow Audit

Audit n8n workflow configurations:

```rust
#[cfg(feature = "n8n-integration")]
{
    use n8n::Workflow;

    let workflow = Workflow::load("workflows/data-processing.json")?;

    // Audit workflow security
    // Check for hardcoded credentials
    let secrets_found = detect_workflow_secrets(&workflow)?;

    if !secrets_found.is_empty() {
        for secret in secrets_found {
            violations.push(format!("Hardcoded {} in workflow", secret.secret_type));
        }
    }
}
```

## Deployment Architecture

### Docker/Kubernetes

```dockerfile
# Dockerfile with audit
FROM rust:latest

WORKDIR /app
COPY . .

# Generate SBOM before building
RUN cargo install cargo-sbom
RUN cargo sbom --output sbom/app.xml

# Scan for vulnerabilities
RUN cargo install trivy
RUN trivy fs /app

RUN cargo build --release

# Attach SBOM to final image
COPY sbom/app.xml /app/sbom.xml
```

### Kubernetes Admission Controller

Use Kyverno to enforce audit policies:

```yaml
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-sbom
spec:
  validationFailureAction: audit
  rules:
  - name: check-sbom
    match:
      resources:
        kinds:
        - Pod
    validate:
      message: "SBOM annotation required"
      pattern:
        metadata:
          annotations:
            sbom: "?*"
```

## CI/CD Pipeline Integration

### GitHub Actions

```yaml
name: Security Audit

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 6 * * *'

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Generate SBOM
        run: |
          cargo install cargo-sbom
          cargo sbom --output sbom.xml

      - name: Scan for vulnerabilities
        run: |
          curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh
          ./trivy fs /github/workspace

      - name: Run audit policies
        run: cargo run --bin audit-cli -- --config audit.toml

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: audit-report.sarif
```

## Monitoring and Alerting

### Alert Rules

Define alerts based on audit metrics:

```yaml
# prometheus-alerts.yaml
groups:
  - name: audit-alerts
    interval: 30s
    rules:
      - alert: CriticalVulnerabilityDetected
        expr: audit_vulnerabilities{severity='critical'} > 0
        for: 5m
        annotations:
          summary: "Critical vulnerability detected"

      - alert: PolicyViolation
        expr: rate(audit_policy_violations_total[1h]) > 0
        for: 10m
        annotations:
          summary: "Policy violation detected"

      - alert: SBOMMissing
        expr: audit_sbom_missing_containers > 0
        for: 30m
        annotations:
          summary: "Production container missing SBOM"
```

## Performance Tuning

### Parallel Scanning

```rust
let scanners = vec![
    Box::new(TrivyScanner::new()),
    Box::new(CargoAuditScanner::new()),
];

// Run scans in parallel
let results: Vec<_> = futures::future::join_all(
    scanners.iter().map(|s| s.scan(&target))
).await;
```

### Caching

```toml
[audit.cache]
enabled = true
ttl_hours = 24
path = ".audit-cache"
```

## Security Best Practices

1. **Store audit reports securely**
   - Encrypt sensitive findings
   - Restrict access to reports
   - Maintain audit trail

2. **Regular policy updates**
   - Review and update policies monthly
   - Test policy changes in non-prod first
   - Document policy decisions

3. **Vulnerability response SLA**
   - Critical: 24 hours
   - High: 72 hours
   - Medium: 1 week
   - Low: 30 days

4. **SBOM management**
   - Version control SBOMs
   - Sign SBOMs with certificates
   - Maintain for 2+ years

## Troubleshooting

### Integration Issues

Check feature flags:
```toml
# Cargo.toml
audit = { path = "../audit", features = ["full-integration"] }
```

### Policy Not Applying

Verify policy path:
```bash
ls -la ./policies/
cat ./policies/*.rego
```

### Scanner Integration Issues

Test scanner directly:
```bash
trivy fs .
cargo audit
```

## References

- [OPA/Rego Documentation](https://www.openpolicyagent.org/docs/latest/)
- [Kyverno Policies](https://kyverno.io/policies/)
- [SBOM Standards](https://cyclonedx.org/)
- [CVE Database](https://nvd.nist.gov/)