12 KiB
12 KiB
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:
#[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:
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:
#[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:
# .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:
#[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:
#[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:
{
"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:
#[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:
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:
#[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:
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:
# 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:
#[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 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:
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
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:
# 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
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
[audit.cache]
enabled = true
ttl_hours = 24
path = ".audit-cache"
Security Best Practices
-
Store audit reports securely
- Encrypt sensitive findings
- Restrict access to reports
- Maintain audit trail
-
Regular policy updates
- Review and update policies monthly
- Test policy changes in non-prod first
- Document policy decisions
-
Vulnerability response SLA
- Critical: 24 hours
- High: 72 hours
- Medium: 1 week
- Low: 30 days
-
SBOM management
- Version control SBOMs
- Sign SBOMs with certificates
- Maintain for 2+ years
Troubleshooting
Integration Issues
Check feature flags:
# Cargo.toml
audit = { path = "../audit", features = ["full-integration"] }
Policy Not Applying
Verify policy path:
ls -la ./policies/
cat ./policies/*.rego
Scanner Integration Issues
Test scanner directly:
trivy fs .
cargo audit