# pranlawate/avc-parser architecture

> Architecture diagram of the GitHub repository pranlawate/avc-parser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pranlawate/avc-parser
- Repository: https://github.com/pranlawate/avc-parser

## Overview

##### Project Type and Purpose
- This is an open-source, standalone CLI tool written in Python for post-incident forensic analysis of SELinux AVC denial logs.
- It implements a modular pipeline: input validation → parsing/anomaly detection → semantic enrichment → output formatting (rich terminal, reports, JSON).
- Key use cases: security analysis, compliance reporting, SIEM integration.

##### High-Level Components
- CLI Controller (parse_avc.py)
- Entry point: parses command-line arguments, dispatches workflow.
- Configuration Module (config/constants.py)
- Centralizes audit patterns, size limits, analysis settings.
- Validators (validators/file_validator.py)
- Validates file type, existence, permissions; auto-detects format.
- Parsers & Context Model (selinux/context.py)
- Builds AvcContext objects, interprets raw AVC log records.
- Detectors (detectors/anomaly_detector.py)
- Implements semantic rules: deduplication, dontaudit detection, correlation.
- Utility Libraries (utils/*.py)
- Shared helpers: file format detection, time parsing, pattern matching, sorting, SELinux command generation, legacy logic.
- Formatters
- json_formatter.py → outputs normalized JSON for machines/SIEM.
- report_formatter.py → renders rich terminal panels or text reports.
- Examples & Scripts
- examples/ → sample integration code using the core library.
- scripts/ → developer utilities (test data generation, profiling, log validation).
- Tests
- tests/ → unit and integration tests covering all modules.

##### External Dependencies & Integrations
- Python 3.6+
- Third-party: Rich library (terminal styling), audit/ausearch package (optional).
- External commands: sesearch for policy investigation commands.
- Input sources: raw audit.log, ausearch output, piped/pasted blocks.
- Outputs: console, JSON files, piped data to SIEM or other tools.

##### Details to Capture
- CLI invocation options and how they alter the workflow (flags → branching).
- The two-tier output system (rich panels vs. report vs. JSON).
- The auto-detection path in validators.
- Test coverage spanning all modules.
- Configuration constants driving analyzer behavior.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input Sources
    subgraph "Input Sources"
        InputFiles[/"Raw audit.log\nausearch output"/]:::io
        SESearch(("sesearch")):::external
    end

    %% Controller Layer
    subgraph "Controller" 
        CLI["CLI Controller\n(parse_avc.py)"]:::controller
        Config["Configuration\n(constants.py)"]:::controller
    end

    %% Validation Layer
    subgraph "Validation"
        Validator["File Validator\n(file_validator.py)"]:::core
    end

    %% Core Logic Layer
    subgraph "Core Logic"
        Parser["Parser & Context\n(context.py)"]:::core
        Detector["Anomaly Detector\n(anomaly_detector.py)"]:::core
    end

    %% Utilities Layer
    subgraph "Utilities"
        FileUtils["File Utils\n(file_utils.py)"]:::util
        Legacy["Legacy Support\n(legacy.py)"]:::util
        PatternUtils["Pattern Utils\n(pattern_utils.py)"]:::util
        SELinuxUtils["SELinux Utils\n(selinux_utils.py)"]:::util
        SortUtils["Sort Utils\n(sort_utils.py)"]:::util
        TimeUtils["Time Utils\n(time_utils.py)"]:::util
    end

    %% Formatters Layer
    subgraph "Formatters"
        JSONFmt["JSON Formatter\n(json_formatter.py)"]:::io
        ReportFmt["Report Formatter\n(report_formatter.py)"]:::io
    end

    %% Extensions Layer
    subgraph "Examples & Scripts"
        Examples["Examples\n(basic_analysis.py,\nbatch_processing.py,\njson_integration.py,\nperformance_test.py,\nsecurity_report.py)"]:::ext
        Scripts["Scripts\n(generate_test_data.py,\nprofile_performance.py,\nrun_tests.py,\nsyntax_check.py,\nvalidate_logs.py)"]:::ext
    end

    %% Tests Layer
    subgraph "Tests"
        Tests["Test Suite\n(test_core_functions.py,\n...,\ntest_validation_functions.py,\ntest_coverage_summary.md)"]:::ext
    end

    %% Outputs
    subgraph "Outputs"
        Console["Console Output"]:::io
        JSONOut[/"JSON Files"/]:::io
        ReportOut[/"Report Files"/]:::io
    end

    %% Flow Connections
    InputFiles -->|provides logs| CLI
    SESearch -->|policy lookup| Detector

    CLI -->|reads| Config
    CLI -->|validates| Validator
    CLI -->|parses| Parser
    Parser -->|builds AvcContext| Detector
    Detector -->|calls| FileUtils
    Detector -->|calls| Legacy
    Detector -->|calls| PatternUtils
    Detector -->|calls| SELinuxUtils
    Detector -->|calls| SortUtils
    Detector -->|calls| TimeUtils
    Detector -->|detects anomalies| FormatterChoices{"Format Flow"}:::io
    FormatterChoices -->|machine| JSONFmt
    FormatterChoices -->|rich/report| ReportFmt
    JSONFmt -->|outputs| JSONOut
    ReportFmt -->|outputs| Console
    ReportFmt -->|outputs| ReportOut

    CLI -->|invokes examples| Examples
    CLI -->|runs scripts| Scripts

    Tests -->|covers| CLI
    Tests -->|covers| Config
    Tests -->|covers| Validator
    Tests -->|covers| Parser
    Tests -->|covers| Detector
    Tests -->|covers| FileUtils
    Tests -->|covers| Legacy
    Tests -->|covers| PatternUtils
    Tests -->|covers| SELinuxUtils
    Tests -->|covers| SortUtils
    Tests -->|covers| TimeUtils
    Tests -->|covers| JSONFmt
    Tests -->|covers| ReportFmt

    %% Click Events
    click CLI "https://github.com/pranlawate/avc-parser/blob/main/parse_avc.py"
    click Config "https://github.com/pranlawate/avc-parser/blob/main/config/constants.py"
    click Validator "https://github.com/pranlawate/avc-parser/blob/main/validators/file_validator.py"
    click Parser "https://github.com/pranlawate/avc-parser/blob/main/selinux/context.py"
    click Detector "https://github.com/pranlawate/avc-parser/blob/main/detectors/anomaly_detector.py"
    click FileUtils "https://github.com/pranlawate/avc-parser/blob/main/utils/file_utils.py"
    click Legacy "https://github.com/pranlawate/avc-parser/blob/main/utils/legacy.py"
    click PatternUtils "https://github.com/pranlawate/avc-parser/blob/main/utils/pattern_utils.py"
    click SELinuxUtils "https://github.com/pranlawate/avc-parser/blob/main/utils/selinux_utils.py"
    click SortUtils "https://github.com/pranlawate/avc-parser/blob/main/utils/sort_utils.py"
    click TimeUtils "https://github.com/pranlawate/avc-parser/blob/main/utils/time_utils.py"
    click JSONFmt "https://github.com/pranlawate/avc-parser/blob/main/formatters/json_formatter.py"
    click ReportFmt "https://github.com/pranlawate/avc-parser/blob/main/formatters/report_formatter.py"
    click Examples "https://github.com/pranlawate/avc-parser/blob/main/examples/basic_analysis.py"
    click Examples "https://github.com/pranlawate/avc-parser/blob/main/examples/batch_processing.py"
    click Examples "https://github.com/pranlawate/avc-parser/blob/main/examples/json_integration.py"
    click Examples "https://github.com/pranlawate/avc-parser/blob/main/examples/performance_test.py"
    click Examples "https://github.com/pranlawate/avc-parser/blob/main/examples/security_report.py"
    click Scripts "https://github.com/pranlawate/avc-parser/blob/main/scripts/generate_test_data.py"
    click Scripts "https://github.com/pranlawate/avc-parser/blob/main/scripts/profile_performance.py"
    click Scripts "https://github.com/pranlawate/avc-parser/blob/main/scripts/run_tests.py"
    click Scripts "https://github.com/pranlawate/avc-parser/blob/main/scripts/syntax_check.py"
    click Scripts "https://github.com/pranlawate/avc-parser/blob/main/scripts/validate_logs.py"
    click Tests "https://github.com/pranlawate/avc-parser/blob/main/tests/test_core_functions.py"
    click Tests "https://github.com/pranlawate/avc-parser/blob/main/tests/test_core_parsing.py"
    click Tests "https://github.com/pranlawate/avc-parser/blob/main/tests/test_display_layer.py"
    click Tests "https://github.com/pranlawate/avc-parser/blob/main/tests/test_edge_cases.py"
    click Tests "https://github.com/pranlawate/avc-parser/blob/main/tests/test_integration.py"
    click Tests "https://github.com/pranlawate/avc-parser/blob/main/tests/test_malformed_logs.py"
    click Tests "https://github.com/pranlawate/avc-parser/blob/main/tests/test_regression.py"
    click Tests "https://github.com/pranlawate/avc-parser/blob/main/tests/test_runner.py"
    click Tests "https://github.com/pranlawate/avc-parser/blob/main/tests/test_timestamp_tracking.py"
    click Tests "https://github.com/pranlawate/avc-parser/blob/main/tests/test_validation_functions.py"
    click Tests "https://github.com/pranlawate/avc-parser/blob/main/tests/test_coverage_summary.md"

    %% Styles
    classDef controller fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef core fill:#d4edda,stroke:#333,stroke-width:1px
    classDef util fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef io fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef ext fill:#f5c6cb,stroke:#333,stroke-width:1px
    classDef external fill:#d1ecf1,stroke:#333,stroke-width:1px
```
