auditops 0.1.0__tar.gz

auditops-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AuditOps LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

auditops-0.1.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: auditops
+Version: 0.1.0
+Summary: Open-source evidence collection framework.
+Author: AJ Dehn
+License-Expression: MIT
+Project-URL: Repository, https://github.com/AuditOps/auditops-sdk
+Project-URL: Issues, https://github.com/AuditOps/auditops-sdk/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: boto3>=1.40
+Requires-Dist: reportlab>=4.0
+Requires-Dist: requests>=2.34
+Dynamic: license-file
+
+# Purpose
+Gather evidence, perform testing, and create audit reports in ~25 lines of code per tool.
+
+## Use cases:
+- Vendor Due Diligence: Evaluate your vendors actual security posture (transparent and timely reports allows you to truly evaluate risk).
+- Audits: Automatically collect and upload high quality evidence directly to your auditor (no screenshots required).
+
+## What this library does:
+1. Evidence Collection: Gathers evidence (JSON files) directly from your vendor's API or SDK.
+2. Testing: Logic based configuration tests (encryption, MFA, key rotation, etc) against your cloud environment.
+3. Report Building: Builds JSON & PDF reports that summarize findings from each test & tool.
+4. Upload: Share full audit packages (evidence & audit reports) with auditors, customers, and regulators.
+
+## Philosophy:
+1. Lightweight: You can setup this library in minutes, and it doesn't require intensive integrations with your cloud providers. This eliminates vendor lock-in and gives you control over how your data is processed.
+2. Repeatability: Clear instructions explain how evidence was gathered and describes the test procedures that were performed. Share your AuditOps report + supporting evidence, and kindly ask your auditor to re-perform the work that was already done.
+3. Anti-Checkbox: We all know that compliance has become a check-box exercise. We hope you'll use this library to fight against it and start holding everyone to higher standard.

auditops-0.1.0/README.md

@@ -0,0 +1,17 @@
+# Purpose
+Gather evidence, perform testing, and create audit reports in ~25 lines of code per tool.
+
+## Use cases:
+- Vendor Due Diligence: Evaluate your vendors actual security posture (transparent and timely reports allows you to truly evaluate risk).
+- Audits: Automatically collect and upload high quality evidence directly to your auditor (no screenshots required).
+
+## What this library does:
+1. Evidence Collection: Gathers evidence (JSON files) directly from your vendor's API or SDK.
+2. Testing: Logic based configuration tests (encryption, MFA, key rotation, etc) against your cloud environment.
+3. Report Building: Builds JSON & PDF reports that summarize findings from each test & tool.
+4. Upload: Share full audit packages (evidence & audit reports) with auditors, customers, and regulators.
+
+## Philosophy:
+1. Lightweight: You can setup this library in minutes, and it doesn't require intensive integrations with your cloud providers. This eliminates vendor lock-in and gives you control over how your data is processed.
+2. Repeatability: Clear instructions explain how evidence was gathered and describes the test procedures that were performed. Share your AuditOps report + supporting evidence, and kindly ask your auditor to re-perform the work that was already done.
+3. Anti-Checkbox: We all know that compliance has become a check-box exercise. We hope you'll use this library to fight against it and start holding everyone to higher standard.

auditops-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "auditops"
+version = "0.1.0"
+description = "Open-source evidence collection framework."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Information Technology",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+]
+
+dependencies = [
+    "boto3>=1.40",
+    "reportlab>=4.0",
+    "requests>=2.34"
+]
+
+authors = [
+    {name = "AJ Dehn"}
+]
+
+[project.urls]
+Repository = "https://github.com/AuditOps/auditops-sdk"
+Issues = "https://github.com/AuditOps/auditops-sdk/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+exclude = ["tests*", "docs*", "env*", "venv*"]
+
+[tool.setuptools.exclude-package-data]
+"*" = [".env", "*.pyc", "__pycache__", "config.json"]

auditops-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

auditops-0.1.0/src/auditops/core/__init__.py

@@ -0,0 +1,17 @@
+__version__ = "0.1.0"
+
+from .evidence.writer import EvidenceWriter
+from .evidence.reader import EvidenceReader
+from .models import Test, Audit
+from .uploader import Uploader
+from .reporting.pdf_report_builder import PDFReportBuilder
+from .exclusions import ExclusionManager
+
+__all__ = [
+    "EvidenceWriter",
+    "EvidenceReader",
+    "Uploader",
+    "PDFReportBuilder",
+    "Test",
+    "ExclusionManager"
+]

auditops-0.1.0/src/auditops/core/evidence/reader.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+import json
+
+
+class EvidenceReader:
+    def __init__(self, root_dir="tmp"):
+        self.root_dir = Path(root_dir)
+        self.evidence_dir = self.root_dir / "audit_evidence"
+
+    def _path(self, relative_path):
+        return self.evidence_dir / relative_path
+
+    def read_json(self, relative_path, optional=False):
+        """
+        Read a JSON evidence file.
+
+        Args:
+            relative_path: Path relative from the audit's evidence folder.
+            optional: Return None instead of raising if the file is missing.
+        """
+        path = self._path(relative_path)
+
+        if not path.exists():
+            if optional:
+                return None
+            
+            raise FileNotFoundError(f"Missing required evidence: {relative_path}")
+
+        with path.open() as f:
+            return json.load(f)

auditops-0.1.0/src/auditops/core/evidence/writer.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+import json
+import logging
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(levelname)s %(name)s: %(message)s"
+)
+
+class EvidenceWriter:
+    def __init__(self, root_dir="tmp"):
+        self.root_dir = Path(root_dir)
+        self.evidence_dir = self.root_dir / "audit_evidence"
+
+
+    def save_json(self, relative_path, data):
+        if data:
+            file_path = self.evidence_dir / relative_path
+
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+
+            with file_path.open("w") as f:
+                json.dump(data, f, indent=4, default=str)

auditops-0.1.0/src/auditops/core/exclusions.py

@@ -0,0 +1,109 @@
+import json
+from collections import defaultdict
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+import fnmatch
+
+@dataclass
+class Exclusion:
+    provider: str
+    test_id: str
+    rationale: str
+    sample_id: dict | None = None
+    expires: date | None = None
+
+    @property
+    def is_expired(self) -> bool:
+        return self.expires is not None and self.expires < date.today()
+
+    @property
+    def is_pattern(self) -> bool:
+        return self.sample_id is not None and any(
+            "*" in str(v) for v in self.sample_id.values()
+        )
+    
+    def matches_sample(self, sample_id: dict) -> bool:
+        """Only valid for pattern exclusions."""
+        for field, pattern in self.sample_id.items():
+            value = sample_id.get(field)
+            if value is None or not fnmatch.fnmatch(str(value), str(pattern)):
+                return False
+        return True
+
+
+class ExclusionManager:
+    def __init__(self, exclusions: list[Exclusion] | None = None):
+        self._test_exclusions: dict[tuple, Exclusion] = {}
+        self._sample_exclusions: dict[tuple, Exclusion] = {}
+        self._sample_patterns: dict[tuple, list[Exclusion]] = defaultdict(list)
+
+        for exclusion in exclusions or []:
+            if exclusion.is_expired:
+                continue
+
+            key_prefix = (exclusion.provider, exclusion.test_id)
+
+            if exclusion.sample_id is None:
+                self._test_exclusions[key_prefix] = exclusion
+            elif exclusion.is_pattern:
+                self._sample_patterns[key_prefix].append(exclusion)
+            else:
+                key = key_prefix + (frozenset(exclusion.sample_id.items()),)
+                self._sample_exclusions[key] = exclusion
+
+    @classmethod
+    def load_exclusions(cls, filename: str | Path):
+        filename = Path(filename)
+
+        if not filename.exists():
+            return cls()
+
+        with open(filename, "r") as f:
+            data = json.load(f)
+
+        exclusions = []
+        for item in data.get("exclusions", []):
+            expires = item.get("expires")
+            if expires:
+                expires = date.fromisoformat(expires)
+
+            exclusions.append(
+                Exclusion(
+                    provider=item["provider"].lower(),
+                    test_id=item["test_id"],
+                    sample_id=item.get("sample_id"),
+                    rationale=item["rationale"],
+                    expires=expires,
+                )
+            )
+
+        return cls(exclusions)
+
+    def get_test_exclusion(self, provider: str, test_id: str) -> Exclusion | None:
+        return self._test_exclusions.get(
+            (provider.lower(), test_id)
+        )
+
+    def get_sample_exclusion(self, provider: str, test_id: str, sample_id: dict) -> Exclusion | None:
+        provider = provider.lower()
+
+        # Exact match first (fast)
+        key = (provider.lower(), test_id, frozenset(sample_id.items()))
+
+        exclusion = self._sample_exclusions.get(key)
+        if exclusion:
+            return exclusion
+
+        # Pattern match — only checks patterns registered under this (provider, test_id)
+        for exclusion in self._sample_patterns.get((provider, test_id), []):
+            if exclusion.matches_sample(sample_id):
+                return exclusion
+
+        return None
+
+    def is_test_excluded(self, provider: str, test_id: str) -> bool:
+        return self.get_test_exclusion(provider, test_id) is not None
+
+    def is_sample_excluded(self, provider: str, test_id: str, sample_id: dict) -> bool:
+        return self.get_sample_exclusion(provider, test_id, sample_id) is not None

auditops-0.1.0/src/auditops/core/models.py

@@ -0,0 +1,238 @@
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any
+from datetime import date
+from datetime import datetime, timezone
+from pathlib import Path
+from .reporting.pdf_report_builder import PDFReportBuilder
+from .evidence.reader import EvidenceReader
+from .evidence.writer import EvidenceWriter
+from .exclusions import ExclusionManager
+
+
+@dataclass
+class AuditHelpers:
+    reader: EvidenceReader
+    writer: EvidenceWriter
+    exclusions: ExclusionManager
+    report_builder: PDFReportBuilder
+
+    @classmethod
+    def create(cls, exclusions_file: str | None = None):
+        return cls(
+            reader=EvidenceReader(),
+            writer=EvidenceWriter(),
+            exclusions=(
+                ExclusionManager.load_exclusions(exclusions_file)
+                if exclusions_file
+                else ExclusionManager()
+            ),
+            report_builder=PDFReportBuilder(),
+        )
+
+
+@dataclass(slots=True)
+class AuditContext:
+    provider: str
+    helpers: AuditHelpers
+
+    config: object | None = None
+    evidence_folder: str = ""
+    report_name: str = ""
+    auditor_name: str = "AJ Dehn"
+    delete_cached_evidence: bool = True
+    summary_mode: bool = False
+
+    @property
+    def reader(self):
+        return self.helpers.reader
+
+    @property
+    def writer(self):
+        return self.helpers.writer
+
+    @property
+    def exclusions(self):
+        return self.helpers.exclusions
+
+    @property
+    def report_builder(self):
+        return self.helpers.report_builder
+
+    @property
+    def report_dir(self) -> Path:
+        path = Path(self.reader.root_dir) / "reports"
+        if self.evidence_folder:
+            path /= self.evidence_folder
+        return path
+
+    @property
+    def json_report_path(self) -> Path:
+        return self.report_dir / f"{self.report_name}.json"
+
+    @property
+    def pdf_report_path(self) -> Path:
+        return self.report_dir / f"{self.report_name}.pdf"
+
+
+class Audit:
+    def __init__(self, title=None, auditor_name="AuditOps"):
+        self.test_results = None
+        self.title = title
+        self.auditor_name = auditor_name
+        self.scope = None
+
+    def update_scope(self, updated_scope):
+        self.scope = updated_scope
+
+    def get_scope(self):
+        return self.scope
+
+    def get_scope_formatted(self):
+        html = []
+
+        for item in self.scope:
+            if ":" in item:
+                label, value = item.split(":", 1)
+                html.append(f"<b>{label}:</b> {value}")
+            else:
+                html.append(item)
+
+        html_output = "<br/>".join(html)
+
+        return html_output
+
+    def to_dict(self):
+        return {
+            "metadata": {
+                "scope": self.scope,
+                "report_date": datetime.now(timezone.utc).strftime('%Y-%m-%d')
+            },
+            "test_results": [t.to_dict() for t in self.test_results]
+        }
+
+
+# NOTE: Samples default to "is_passing: False" until logic determines sample passes the testing criteria.
+@dataclass
+class Sample:
+    sample_id: Dict[str, Any]
+    is_excluded: bool = False
+    is_passing: bool = False
+    comments: str = ""
+
+    def __str__(self):
+        return (
+            f"sample_id: {self.sample_id}\n"
+            f"is_excluded: {self.is_excluded}\n"
+            f"is_passing: {self.is_passing}\n"
+            f"comments: {self.comments}\n"
+        )
+
+    def to_dict(self):
+        return {
+            "sample_id": self.sample_id,
+            "is_excluded": self.is_excluded,
+            "is_passing": self.is_passing,
+            "comments": self.comments,
+        }
+
+
+# NOTE: Tests default to "is_passing: True" until there is a failing sample or other logic determines the test has failed.
+@dataclass
+class Test:
+    test_id: str
+    test_description: str
+    test_procedures: List[str]
+    test_attributes: List[str]
+    # Rating Matrix: 0 - Informational, 1 - Low, 2 - Medium, 3 - High.
+    risk_rating: int
+    table_headers: Optional[List[str]] = None
+    samples: List["Sample"] = field(default_factory=list)
+    is_passing: bool = True
+    is_excluded: bool = False
+    comments: str = ""
+    num_findings: int = 0
+    num_exclusions: int = 0
+    num_passing: int = 0
+    total_population: int = 0
+
+    def __str__(self):
+        return (
+            f"test_id: {self.test_id}\n"
+            f"test_description: {self.test_description}\n"
+            f"risk_rating: {self.risk_rating}\n"
+            f"is_passing: {self.is_passing}\n"
+            f"comments: {self.comments}\n"         
+        )
+
+
+    def to_dict(self):
+        result = {
+            "test_id": self.test_id,
+            "is_excluded": self.is_excluded,
+            "test_description": self.test_description,
+            "risk_rating": self.risk_rating,
+            "is_passing": self.is_passing,
+            "comments": self.comments,
+            "test_procedures": self.test_procedures,
+            "test_attributes": self.test_attributes,
+        }
+        # Include samples, if present.
+        if self.samples:  
+            result["samples"] = [s.to_dict() for s in self.samples]
+
+        return result
+
+
+    def get_risk_rating_str(self):
+        if self.risk_rating == 0: return "Informational"
+        elif self.risk_rating == 1: return "Low"
+        elif self.risk_rating == 2: return "Medium"
+        elif self.risk_rating == 3: return "High"
+        else:
+            raise ValueError(f"Invalid risk rating: {self.risk_rating}. Accepted values are 0 - 3.")
+
+
+    def add_sample(self, sample):
+        self.samples.append(sample)
+
+
+    def evaluate_samples(self, exclusions=None, provider=None, test_id = None, failure_message: str = None):
+        self.total_population = len(self.samples)
+        self.num_exclusions = 0
+        self.num_findings = 0
+        self.num_passing = 0
+
+        for sample in self.samples:
+            if exclusions:
+                exclusion = exclusions.get_sample_exclusion(provider, self.test_id, sample.sample_id)
+                if exclusion:
+                    sample.is_excluded = True
+                    sample.comments = exclusion.rationale
+
+            if sample.is_excluded:
+                self.num_exclusions += 1
+                continue
+
+            if not sample.is_passing:
+                self.num_findings += 1
+
+        self.is_passing = self.num_findings == 0
+        
+        self.num_passing = self.total_population - self.num_findings - self.num_exclusions
+
+        if failure_message:
+            self.set_failure_summary(failure_message)
+
+
+    def set_failure_summary(self, message: str):
+        if self.is_passing:
+            return
+
+        # Make sure message ends with a period.
+        message = message.rstrip()
+        if not message.endswith("."):
+            message += "."
+        
+        self.comments = (
+            f"Exceptions Noted. {self.num_findings} of {self.total_population} {message}"
+        )