auditops 0.1.0__py3-none-any.whl

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/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/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/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/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}"
+        )

auditops/core/reporting/pdf_report_builder.py

@@ -0,0 +1,263 @@
+from datetime import datetime, timezone
+from pathlib import Path
+from reportlab.lib.pagesizes import LETTER
+from reportlab.platypus import (
+    SimpleDocTemplate, Table, Paragraph, Spacer, PageBreak, KeepTogether, Image)
+from reportlab.lib.styles import getSampleStyleSheet
+from .styles import (LABEL_STYLE, VALUE_STYLE, LIST_STYLE, CENTER_STYLE, PASS_COLOR,
+    FAIL_COLOR, TABLE_STYLE_HIGHLIGHT_ROW, TABLE_STYLE_HIGHLIGHT_COLUMN)
+
+
+class PDFReportBuilder:
+    def __init__(self):
+        self.styles = getSampleStyleSheet()
+        self.page_width, _ = LETTER
+
+    def _format_pct(self, match_count, test_count):
+        # Formats percentage with one decimal point (ex. 99.9%)
+        if test_count == 0:
+            return f"0%"
+        pct = (match_count / test_count) * 100
+        return f"{pct:.1f}%"
+
+    def _label(self, text, style=LABEL_STYLE):
+        return Paragraph(text, style)
+
+    def _value(self, text, style=VALUE_STYLE):
+        return Paragraph(str(text), style)
+
+    def _logo(self, logo_path, width=300):
+        logo = Image(logo_path)
+        aspect = logo.imageHeight / logo.imageWidth
+        logo.drawWidth = width
+        logo.drawHeight = width * aspect
+
+        return logo
+
+    def _table(self, data, col_widths=None, style=None,
+        h_align="LEFT", v_align="TOP"):
+        table = Table(data, colWidths=col_widths, hAlign=h_align, vAlign=v_align)
+
+        if style:
+            table.setStyle(style)
+
+        return table
+
+    def _status_paragraph(self, passed, style=VALUE_STYLE):
+        color = PASS_COLOR if passed else FAIL_COLOR
+        text = "Pass" if passed else "Fail"
+        return self._value(f"<font color='{color}'>{text}</font>", style=style)
+
+
+    def build(self, audit, filename, summary_mode=False):
+        """Generate a PDF audit report."""
+
+        # Sort test results based on risk-rating.
+        tests = sorted(audit.test_results, key=lambda t: (t.is_passing, -t.risk_rating))
+
+        doc = SimpleDocTemplate(
+            filename,
+            pagesize= LETTER,
+            title= audit.title,
+            author= "AuditOps",
+            subject= f"Audit report findings and testing instruction for reperformance.",
+        )
+
+        elements = []
+
+        # Add logo
+        logo_path = str(Path(__file__).resolve().parent / "assets" / "logo.png")
+        elements.append(self._logo(logo_path))
+        elements.append(Spacer(1, 18))
+
+        # Add title
+        elements.append(self._value(f"{audit.title}", style=self.styles["Title"]))
+        elements.append(Spacer(1, 18))
+
+        # Add cover page table
+        elements.append(self._render_cover_page_table(audit))
+        elements.append(Spacer(1, 18))
+
+        # Add test results summary (includes all tests in the audit)
+        header_text = '<a name="test_summary_header"/>Test Summary'
+        elements.append(Paragraph(header_text, self.styles['Heading1']))
+
+        #elements.append(Paragraph("Test Summary", self.styles["Heading1"]))
+        elements.append(Spacer(1, 12))
+        elements.append(self._render_test_summary_table(tests))
+        elements.append(PageBreak())
+
+        for test in tests:
+            # Internal link definition using href="#anchor_name"
+            # Anchor for this test
+            anchor = test.test_id.replace(" ", "_")
+            link_text = (
+                f'<a name="{anchor}"/>'
+                f'<a href="#test_summary_header" color="blue">'
+                f'<b>BACK TO TEST SUMMARY</b></a>'
+            )
+            #link_text = f'<a href="#test_summary_header" name="{anchor}" color="blue"><b>BACK TO TEST SUMMARY</b></a>'
+            elements.append(Paragraph(link_text, self.styles['Normal']))
+
+            if not test.is_excluded:
+                # Build individual test summary
+                elements.append(Spacer(1, 18))
+                elements.append(KeepTogether(self._render_test_details_table(test)))
+                elements.append(Spacer(1, 12))
+                if test.table_headers:
+                    # Build sample table
+                    elements.append(self._render_test_sample_table(test, summary_mode=summary_mode))
+                    elements.append(PageBreak())
+
+        doc.build(elements)
+
+    def _render_cover_page_table(self, audit):
+        test_count = len(audit.test_results)
+        failed = sum(not t.is_passing for t in audit.test_results)
+        passed = test_count - failed
+        rows = [
+            ("Prepared By", audit.auditor_name),
+            ("Report Date", datetime.now(timezone.utc).strftime("%Y-%m-%d")),
+            ("Tests", test_count),
+            ("Passed", f"{passed} ({self._format_pct(passed, test_count)})"),
+            ("Failed", f"{failed} ({self._format_pct(failed, test_count)})"),
+            ("Scope", audit.get_scope_formatted()),
+        ]
+        metadata = [
+            [self._label(k), self._value(v)]
+            for k, v in rows
+        ]
+        return self._table(metadata, col_widths=[150, 200], style=TABLE_STYLE_HIGHLIGHT_COLUMN, h_align="CENTER")
+
+    def _render_test_summary_table(self, tests):
+        # Creates a table summarizing the results of all tests performed in the audit.
+        rows = [[
+            self._label("Test"),
+            self._label("Result"),
+            self._label("Risk"),
+            self._label("Comments"),
+        ]]
+
+        for test in tests:
+            # Creates a link to each test summary.
+            anchor = test.test_id.replace(" ", "_")
+            test_desc_str = (
+                f'<a href="#{anchor}" color="blue"><b>{test.test_id}</b></a>: '
+                f'{test.test_description}'
+            )
+
+            """
+            TODO: Consider removing full summary (population, passing, failing, excluded from passing tests.)
+            if test.num_exclusions > 0:
+                # Add transparency for the number of exclusions.
+                if not test.comments:
+                    # No comments have been populated. Add note for transparency.
+                    if test.num_exclusions > 1:
+                        test.comments = f"<b>NOTE:</b> {test.num_exclusions} samples were excluded by management."
+                    else:
+                        test.comments = f"<b>NOTE:</b> {test.num_exclusions} sample was excluded by management."
+                else:
+                    if test.num_exclusions > 1:
+                        test.comments = test.comments + f"<br/><br/><b>NOTE:</b> {test.num_exclusions} samples were excluded by management."
+                    else:
+                        test.comments = test.comments + f"<br/><br/><b>NOTE:</b> {test.num_exclusions} sample was excluded by management."
+            """
+            new_row = [
+                self._value(test_desc_str),
+                self._value("Excluded") if test.is_excluded else self._status_paragraph(test.is_passing),
+                self._value(test.get_risk_rating_str()),
+                # self._value(test.comments)
+                self._value(self._create_test_summary_formatted(test))
+            ]
+            rows.append(new_row)
+        
+        return self._table(rows, col_widths=[220, 60, 70, 140], style=TABLE_STYLE_HIGHLIGHT_ROW)
+
+    def _render_test_details_table(self, test):
+        test_procedures = [
+            self._value(f"{i+1}. {item}", LIST_STYLE)
+            for i, item in enumerate(test.test_procedures)
+        ]
+        
+        # Build summary table
+        table_data = [
+            [self._label("Test ID"), self._value(test.test_id)],
+            [self._label("Test Description"), self._value(test.test_description)],
+            [self._label("Risk Rating"), self._value(test.get_risk_rating_str())],
+            [self._label("Test Procedures"), test_procedures],
+            [self._label("Conclusion"), self._status_paragraph(test.is_passing)],
+        ]
+
+        if test.test_attributes:
+            test_attributes = [
+                self._value(f"• {item}", LIST_STYLE)
+                for item in test.test_attributes
+            ]
+            # Add test attributes only when populated.
+            table_data.insert(4, [self._label("Test Attributes"), test_attributes])
+
+        # Add row to summary table if test failed and comments is populated.
+        if not test.is_passing and test.comments:
+            table_data.append([self._label("Comments"), self._value(test.comments)])
+
+        table_width = self.page_width - 2 * 72
+        return self._table(table_data, col_widths=[table_width * 0.25, table_width * 0.75],
+         style=TABLE_STYLE_HIGHLIGHT_COLUMN)
+
+    def _render_test_sample_table(self, test, summary_mode=False):
+        # Sort failing samples to top of the table.
+        samples = sorted(test.samples, key=lambda s: (s.is_passing, s.is_excluded))
+        #samples = sorted(test.samples, key=lambda s: (s.is_passing))
+
+        table_data = []
+        # Build header row (Ex. ["Bucket Name", "Results", "Comments]")
+        table_data.append([self._label(h) for h in test.table_headers])
+        for i, sample in enumerate(samples, 1):
+            row = []
+            for val in sample.sample_id.values():
+                if summary_mode:
+                    row.append(self._value(f"Sample: {i}"))
+                else:
+                    row.append(self._value(val))
+
+            # Document Result
+            if sample.is_excluded:
+                row.append(self._value("Excluded", style=CENTER_STYLE))
+                row.append(self._value(str(sample.comments)))
+            else:
+                row.append(self._status_paragraph(sample.is_passing, CENTER_STYLE))
+                if not sample.is_passing:
+                    # Add comments if sample failed.
+                    row.append(self._value(str(sample.comments)))
+
+            table_data.append(row)
+
+        table_width = self.page_width - 2 * 72
+        col_width = table_width / len(table_data[0]) # divide evenly across columns
+        col_widths = [col_width] * len(table_data[0])
+        return self._table(table_data, col_widths=col_widths, style=TABLE_STYLE_HIGHLIGHT_ROW)
+
+
+    
+    def _create_test_summary_formatted(self, test):
+        test_summary = ""
+
+        """
+        if test.is_passing:
+            test_summary = "No Exceptions Noted."
+        else:
+            test_summary = "Exceptions Noted."
+        """
+
+        if test.total_population > 0:
+            test_summary += f"- Population: {test.total_population}"
+            passing_pct = self._format_pct(test.num_passing, test.total_population)
+            test_summary += f"<br/>- Passing: {test.num_passing} ({passing_pct})"
+            if test.num_findings > 0:
+                failing_pct = self._format_pct(test.num_findings, test.total_population)
+                test_summary += f"<br/>- Failing: {test.num_findings} ({failing_pct})"
+            if test.num_exclusions > 0:
+                exclusion_pct = self._format_pct(test.num_exclusions, test.total_population)
+                test_summary += f"<br/>- Excluded: {test.num_exclusions} ({exclusion_pct})"
+        
+        return test_summary