How kanguros/policy_inspector works
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.