# kanguros/policy_inspector architecture

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

- Interactive diagram: https://gitdiagram.com/kanguros/policy_inspector
- Repository: https://github.com/kanguros/policy_inspector

## Overview

##### Project Context and Type
- Policy Inspector is a command-line tool built to analyze firewall security policies specifically from Palo Alto Firewalls. Its primary purpose is to detect scenarios where firewall rules are “shadowed” (i.e., never triggered) and allow users to write custom checks for additional policy issues.
- The tool evolved from a simple rule shadowing detector to a small framework for evaluating different “scenarios” (sets of checks) against security policies.

##### Analyzing the File Structure
- Key Directories/Files:
⁃ The main package is in the "policy_inspector" directory, which houses the core modules. Key files include:
▸ __main__.py & cli.py → These serve as the entrypoints for the command-line interface.
▸ loader.py → Responsible for loading and parsing the input policy files (in XML/JSON).
▸ filters.py → Contains logic to filter and possibly pre-process security rules.
▸ resolve.py → Likely deals with resolution of address objects and groups.
▸ models.py → Defines the core data structures representing policy rules and related components.
▸ scenario/ folder → Implements the “scenarios” (e.g., shadowing, complex_shadowing) that actually run the checks against the policies.
▸ utils.py → Utility functions that support the core operations.
⁃ The "tests" directory includes unit tests ensuring each module’s functionality.
⁃ The "scripts" directory contains additional utility scripts (e.g., fake_rule_generator.py for generating test or fake rules).

##### Components to Highlight
a. Entry Points and CLI:
- Modules: __main__.py, cli.py.
- Function: Process CLI commands, argument parsing, and initiating analysis (e.g., “pi run shadowing policies.xml”).

b. Data Ingestion and Parsing:
- Module: loader.py.
- Function: Reads policy files in XML or JSON formats, converting them into structured data models defined in models.py.
- Interaction: Input from CLI flows into the loader.

c. Filtering and Pre-Processing:
- Module: filters.py.
- Function: Applies initial filtering rules to the loaded policy data. This helps in selecting only the necessary rules that require further checks.

d. Rule Resolution & Normalization:
- Module: resolve.py.
- Function: Resolves address objects and groups to their concrete representations (IP addresses, subnets, etc.) ensuring accurate evaluation especially in the “Shadowing by Value” scenario.

e. Scenario Engine:
- Packages/Modules: scenario/ (which contains base.py, shadowing.py, complex_shadowing.py).
- Function: Implements various scenarios that encapsulate the domain-specific checks.
- Interaction: After filtering and resolution, the appropriate scenario is executed on the data.

f. Utility and Support:
- Module: utils.py.
- Function: Provides helper functionalities that might be used across other components.

g. Testing and Auxiliary Scripts:
- Directories: tests, scripts.
- They are essential in ensuring the overall system integrity but can be represented as supporting components around the core flow.

##### Relationships and Data Flow
- Start at the CLI Component (cli.py & __main__.py), which accepts user commands.
- The CLI then calls on the loader (loader.py) to import and parse firewall policy files into structured models (models.py).
- Next, the filters (filters.py) pre-process this data, followed by resolution (resolve.py) which ensures every element (e.g., address objects) is properly normalized.
- The processed data then flows into the Scenario Engine (scenario/ modules) where the core checks (e.g., shadowing detection) are executed.
- Finally, once processing is complete, analysis results are reported (typically through the CLI output).

##### Architectural Patterns & Design Principles
- Modular Design: Each function (parsing, filtering, resolution, analysis) is separated into distinct modules for better maintainability and extensibility.
- Pipeline Flow: There is a clear sequence from input ingestion, pre-processing, analysis (scenario engine), and result reporting.
- Extensibility: The “scenario” directory design shows that the system is built to easily add new checks. This separation of concerns is a key design point.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLI["CLI Entry"]:::cli
    Loader["Policy Loader"]:::core
    DataModels["Data Models"]:::core
    Filters["Filters"]:::core
    Resolver["Resolver"]:::core
    Report["Analysis Report"]:::scenario
    Utilities["Utilities"]:::auxiliary
    Tests["Tests"]:::auxiliary
    Aux["Auxiliary Scripts"]:::auxiliary

    subgraph "Scenario Engine"
        S1["Base Scenario"]:::scenario
        S2["Shadowing Scenario"]:::scenario
        S3["Complex Shadowing Scenario"]:::scenario
    end

    %% Core Processing Flow
    CLI -->|"invokes"| Loader
    Loader -->|"loads"| Filters
    Filters -->|"pre-processes"| Resolver
    Resolver --> S1
    Resolver --> S2
    Resolver --> S3
    S1 -->|"evaluates"| Report
    S2 -->|"evaluates"| Report
    S3 -->|"evaluates"| Report
    Report -->|"reports to"| CLI

    %% Loader uses Data Models
    Loader -.->|"parses with"| DataModels

    %% Support via Utilities
    Loader -.-> Utilities
    Filters -.-> Utilities
    Resolver -.-> Utilities

    %% Ancillary components
    CLI -.-> Tests
    CLI -.-> Aux

    %% Click Events
    click CLI "https://github.com/kanguros/policy_inspector/blob/main/policy_inspector/__main__.py"
    click Loader "https://github.com/kanguros/policy_inspector/blob/main/policy_inspector/loader.py"
    click DataModels "https://github.com/kanguros/policy_inspector/blob/main/policy_inspector/models.py"
    click Filters "https://github.com/kanguros/policy_inspector/blob/main/policy_inspector/filters.py"
    click Resolver "https://github.com/kanguros/policy_inspector/blob/main/policy_inspector/resolve.py"
    click S1 "https://github.com/kanguros/policy_inspector/blob/main/policy_inspector/scenario/base.py"
    click S2 "https://github.com/kanguros/policy_inspector/blob/main/policy_inspector/scenario/shadowing.py"
    click S3 "https://github.com/kanguros/policy_inspector/blob/main/policy_inspector/scenario/complex_shadowing.py"
    click Utilities "https://github.com/kanguros/policy_inspector/blob/main/policy_inspector/utils.py"
    click Tests "https://github.com/kanguros/policy_inspector/tree/main/tests/"
    click Aux "https://github.com/kanguros/policy_inspector/blob/main/scripts/fake_rule_generator.py"

    %% Styles
    classDef cli fill:#CCFFCC,stroke:#2E8B57,stroke-width:2px
    classDef core fill:#ADD8E6,stroke:#00008B,stroke-width:2px
    classDef scenario fill:#FFDAB9,stroke:#FF8C00,stroke-width:2px
    classDef auxiliary fill:#D3D3D3,stroke:#696969,stroke-width:2px,stroke-dasharray: 5,5
```
