audit-packs

An evidence-first Compliance Intelligence Engine that transforms security scanner findings into standardized, evidence-backed compliance artifacts (inline PR comments, OSCAL assessment results, SARIF, and control coverage reports).

🔍 The Problem

Modern security scanners (such as Checkov, Semgrep, Trivy, tfsec, and gitleaks) are highly effective at identifying infrastructure-as-code (IaC) misconfigurations and software vulnerabilities. However, they are scanner-centric and do not directly answer the critical questions that governance, risk, and compliance (GRC) teams or auditors ask:

• Which compliance controls (e.g., NIST 800-53, SOC 2, HIPAA, GDPR) are affected by this finding?
• Where is the exact code/configuration evidence to prove compliance or violation?
• How do we avoid false-positive alerts bloating our engineering workflows?

💡 The Solution

audit-packs bridges the gap by providing a scanner-agnostic mapping, enrichment, and consensus layer. Rather than replacing existing detection tools, it takes their output (typically via SARIF), normalizes it, enriches it with codebase/git evidence context, maps the findings to GRC control requirements, and optionally filters noise using an AI consensus ensemble.

📦 Installation

To run audit-packs locally as a CLI tool:

# Install audit-packs CLI via pip
pip install audit-packs

# Or install in an isolated environment via pipx (recommended)
pipx install audit-packs

Note: Detection is delegated to best-in-class open-source engines. For the scanners to run, ensure they are installed on your system path, or inject them into the pipx environment:

pipx inject audit-packs checkov semgrep

🚀 Quick Start

1. Initialize Configuration

Bootstrap your repository with a default configuration and download local compliance packs:

audit-packs --init

2. Run a Compliance Scan

Scan your workspace and map findings to NIST 800-53 and SOC 2 frameworks:

audit-packs --frameworks nist-800-53,soc2

📋 CLI Command Matrix & Flags

🌐 GitHub Action Integration

audit-packs is designed to run seamlessly in GitHub Action pipelines to block compliance regressions on pull requests.

# .github/workflows/compliance-audit.yml
name: Compliance Audit

on:
  pull_request:

jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write # Required to post inline review comments

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Required for diff-only scanning

      - name: Run Audit Packs compliance check
        uses: prakharsingh/audit-packs@v1
        with:
          frameworks: nist-800-53,soc2
          fail-on: high

📊 Supported Compliance Frameworks

Compliance frameworks are defined as declarative YAML packs. The following packs are supported:

📤 Output Artifacts

• Inline PR Comments: Posts targeted comments containing control mappings and cryptographic/configuration evidence on changed lines of a PR.
• OSCAL Assessment Results: Machine-readable oscal.json compliant with NIST SP 800-53 GRC tooling workflows.
• Coverage Reports: Beautiful coverage.md and coverage.html containing an audit-ready compliance matrix.
• Aggregated SARIF: A combined audit-packs.sarif file containing all scanner findings mapped to controls.

📦 Ecosystem Architecture

audit-packs is built as a modular ecosystem consisting of five Python packages:

Package	PyPI Link	Role	Standalone?
audit-packs		Main CLI & Action entrypoint	Yes
audit-packs-core		Primitives, diff parsing, normalization	No
audit-packs-mapping		Compliance pack loader & OSCAL exporter	No
audit-packs-evidence		Evidence collectors & heuristic agents	No
audit-packs-ai		LLM consensus & confidence scoring	No

🤝 Contributing & Backtrack Links

• GitHub Repository: https://github.com/prakharsingh/audit-packs
• Issue Tracker: https://github.com/prakharsingh/audit-packs/issues
• Contributing Guidelines: Refer to the repository CONTRIBUTING.md.

📄 License

This project is licensed under the Apache-2.0 License. See the LICENSE file in the main repository for details.