provisioning-platform/prov-ecosystem/crates/audit

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

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

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

Configuration

Minimal Configuration

[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

[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

# 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

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:

# 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

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/:

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

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:

#[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:

#[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:

#[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

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:

[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:

# 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:

ls -la ./policies/

SBOM Generation Issues

Ensure write permissions to sbom.output_dir:

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