Compliance & Audit Reporting

Relevant source files

The following files were used as context for generating this wiki page:

• QUICK_START.md
• README.md
• SECURITY_REVIEW.md
• configs/default.json
• CHANGELOG.md
• src/index.ts

Introduction

Compliance & Audit Reporting in the Unified Security Scanner is a specialized workflow designed to generate high-fidelity, machine-readable, and human-verifiable documentation of a project's security posture. This system aggregates findings from multiple scanning phases—including traditional SAST, AI-enhanced validation, and targeted deep dives—to produce audit trails suitable for SOC 2 preparation, quarterly assessments, and enterprise security reviews.

The reporting architecture focuses on reducing "security bankruptcy" by providing structured data that distinguishes between critical vulnerabilities (like hardcoded secrets or command injection) and contextual risks. It supports industry-standard formats such as SARIF for CI/CD integration and JSON/HTML for internal auditing purposes.

Sources: QUICK_START.md:124-130, README.md:16-25, CHANGELOG.md:18-24

Reporting Architecture & Data Flow

The reporting system operates as the final stage of the 3-Phase Scanning Strategy. After findings are orchestrated across multiple tools and validated via AI, the SARIFProcessor and various reporters format the raw data into compliant audit logs.

The 3-Phase Audit Workflow

1. Phase 1: Traditional SAST: Initial filtering using Semgrep and CodeQL to identify potential CWE violations.
2. Phase 2: AI Validation: Three iterations of AI analysis to verify true positives and reduce noise.
3. Phase 3: Deep Dive: Targeted analysis of business logic and multi-file vulnerability flows.

The diagram above illustrates the transition from multi-phase scanning to the generation of various audit-compliant output formats.

Sources: README.md:46-55, src/index.ts:11-12, CHANGELOG.md:11-17

Compliance Formats & Use Cases

The scanner provides a "Decision Matrix" for output formats to ensure that reporting meets specific compliance and developer workflow needs.

Format	Use Case	Audit Value
SARIF	CI/CD Integration	Native GitHub Security tab support and PR annotations.
JSON	Automation & APIs	Machine-readable data for custom compliance dashboards.
HTML	Executive Reviews	Human-readable visualization of security posture.
Terminal	Local Validation	Immediate feedback for developers before code commits.

Sources: QUICK_START.md:168-176, README.md:119-125, CHANGELOG.md:18-24

Audit Configuration & Severity Management

Compliance reporting is governed by the .securityrc.json configuration, which defines "fail-on" conditions and exclusion rules to maintain an audit trail while filtering known false positives.

Severity Thresholds for Audits

The system categorizes findings into four primary levels to help auditors prioritize remediation efforts:

• 🔴 CRITICAL: Immediate blocks (e.g., Exposed Secrets, Shell Injection).
• 🟠 HIGH: Fix before production merge (e.g., SQL Injection, XSS).
• 🟡 MEDIUM: Address in current sprint (e.g., Outdated packages).
• ⚪ LOW: Minor optimizations or code quality issues.

Fail-On Strategy for Compliance Gates

This sequence shows how compliance gates are enforced during the automated audit process based on configured severity levels.

Sources: QUICK_START.md:88-115, QUICK_START.md:178-189, configs/default.json:34-37

Verification and Quality Assurance

To ensure the integrity of audit reports, the scanner implements specific mechanisms to handle non-determinism and test reliability.

False Positive Reduction

The system targets a <5% False Positive Rate using:

• Context-Aware Filtering: Detecting framework security controls.
• Intent Analysis: Comparing developer comments against implementation.
• ML-Enhanced Classification: Learning from historical patterns.

Flaky Test Management

For audit environments where stability is critical, the FlakyTestManager isolates unstable security tests to prevent false negatives in compliance reports.

// Configuration for audit reliability
const flakyManager = new FlakyTestManager({
  detection: {
    enabled: true,
    monitoringWindow: 7 // Track for 7 days
  },
  quarantine: {
    enabled: true,
    autoQuarantine: true
  }
});

Sources: README.md:213-228, README.md:27-30, src/index.ts:13

Summary of Findings (Audit Sample)

Audit reports include structured metadata for every finding to assist in remediation and verification.

Field	Description	Source Example
Type	CWE classification	CWE-78 (OS Command Injection)
File/Line	Precise location	src/auth/login.ts:45
Risk	Potential impact	Remote code execution
Remediation	Specific fix steps	Use shell: false in spawn

Sources: SECURITY_REVIEW.md:27-45, README.md:73-81

Conclusion

Compliance & Audit Reporting in this project serves as a bridge between automated vulnerability detection and formal security verification. By utilizing a multi-phase approach validated by AI and providing high-fidelity SARIF/JSON outputs, the system ensures that security audits are both comprehensive and actionable, maintaining a low false-positive rate essential for enterprise-grade security standards.

Sources: README.md:1-10, CHANGELOG.md:11-20