audit-packs

An evidence-first Compliance Intelligence Engine that transforms security scanner findings into standardized, evidence-backed compliance artifacts (an evidence-backed PR summary comment, 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 local config files — an interactive wizard writes an audit-models.yaml model-router file and records your framework selection. It downloads nothing; the compliance packs ship bundled with the CLI:

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 Flags

These flags belong to the audit-packs command-line scanner (argparse). Run audit-packs --help for the authoritative list.

Notes:

• --trivy/--tfsec/--gitleaks default from their env vars (TRIVY_ENABLED, TFSEC_ENABLED, GITLEAKS_ENABLED); when those are unset on the CLI the scanner is off. The GitHub Action enables them by default via the corresponding inputs.
• Output emission is controlled by environment variables, not CLI flags: EMIT_OSCAL, EMIT_COVERAGE, EMIT_SARIF (all default true). These map to the emit-oscal/emit-coverage/emit-sarif Action inputs.

🧰 pack Subcommands

Manage custom framework packs via the audit-packs pack command space. See the pack management guide for details.

🌐 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 the PR summary comment

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

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

Action Inputs

Generated from action.yml. Input names use hyphens (GitHub Action convention) and may differ from the CLI flag names above.

Action Outputs

Exposed as GitHub Action step outputs (from action.yml).

📊 Supported Compliance Frameworks

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

📤 Output Artifacts

• PR Summary Comment: Posts one updatable summary comment containing control mappings and evidence for all diff-filtered findings in the 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.