# jsa2/caoptics architecture

> Architecture diagram of the GitHub repository jsa2/caoptics, 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/jsa2/caoptics
- Repository: https://github.com/jsa2/caoptics

## Overview

##### Project Type and Purpose
- This project is a specialized security analysis tool written in Node.js. Its primary purpose is to analyze Azure AD Conditional Access Policy configurations and detect “gaps” by generating and evaluating permutations of policy conditions.
- The README confirms that it is designed as a command-line tool that interacts with Azure Graph API and optionally the Azure CLI for authentication and token caching.

##### File Structure for Architectural Insights
- The root holds several utility scripts (e.g. creatUids.js, createCSVreport.js, createReport.js), configuration files (package.json, .gitignore, LICENSE), and documentation folders.
- The “ca” directory is the heart of the project. It contains:
– Condition definitions in the “ca/conditions” folder, with files for Applications.js, Locations.js, Platforms.js, clientAppTypes.js, and user conditions (both live and ‘eval’ subfolders). This indicates a modular approach to handling each condition category.
– The main entry point “ca/main.js” initiates the evaluation.
– “ca/mainPlugins” contains various helper modules (e.g. tokenHandler, customPolicyFilter, extraFiltering, graphHelpers, etc). These plugins are responsible for processing policy data, caching, mapping users/groups, and performing various logic tasks.
– “plugins” directory (and its contents) suggests additional extension points or alternate evaluation strategies.
- The “tokenHandler” folder (and its nested files) manages authentication by interfacing with Azure AD endpoints (login.microsoftonline.com and graph.microsoft.com).
- The “demodata” folder contains JSON files used for testing and demonstration.
- The documentation files (README.md, docs/example.md, logic.md) and reports generation scripts (createReport.js, createCSVreport.js) further confirm a clear separation between core processing and auxiliary utilities.

##### Main Components and Their Relationships
- Command-Line Interface (CLI) / Entry Point:
– ca/main.js is the entry point, receiving command-line flags (like --mapping, --clearPolicyCache, etc).
– It orchestrates the overall scanning and gap analysis.
- Condition Modules:
– The “ca/conditions” folder (and its “eval” subfolder) contains modules that encapsulate policy conditions for Applications, Locations, Platforms, users, and clientAppTypes.
– These are responsible for defining the criteria and performing lookups of policy conditions.
- Plugins System:
– Within “ca/mainPlugins”, many plugins handle discrete tasks: fetching policy data (graphHelpers), managing tokens and caching (tokenHandler.js, clearPolicyCache.js), filtering (customPolicyFilter.js, extraFiltering.js), data transformation (uniqueness check, grouping, in-memory list management), and permutation generation (findEmptySub.js, getPol.js/ getPol2.js).
– These modules work in a layered manner—they receive data from the condition evaluation modules, process it (for example mapping users to groups or checking roles), and pass it along.
- Permutation and Gap Analysis Engine:
– Files such as “permutationsPerPolicy.js” and “getPol2.js” handle the core logic for generating unique combinations (“permutations”) of policy conditions.
– This engine uses recursive search and then filters out the relevant gaps in the configuration.
- Token and Authentication Management:
– The “tokenHandler” directory and its files (axioshelpers.js, getCode.js, refresh.js) manage authentication flows and token caching.
– This module is crucial for accessing Microsoft Graph API to retrieve policy and directory data.
- Reporting and Output Generators:
– Files like “createCSVreport.js” and “createReport.js” generate output files (CSV, markdown, JSON) that document the analyzed “gaps” and permutations.
– This reporting component takes processed data from the gap analysis engine.
- External Dependencies:
– The system utilizes open-source packages like axios for HTTP requests, yargs for CLI parsing, chalk for command-line aesthetics, and js‑beautify for output formatting among others.

##### Architectural Patterns and Design Principles
- Modular Design and Separation of Concerns:
– The separation into condition modules, plugins, authentication/token management, and reporting clearly shows modular boundaries.
– The system applies a plug-in pattern by isolating functionality into “mainPlugins” and “plugins” directories.
- Dependency Injection:
– While not explicitly highlighted, the design suggests injection of dependencies (e.g., token configuration, filtering logic) via command-line parameters.
- External Integration:
- Data Flow Oriented:
– Data flows from the input (CLI parameters), through condition evaluation, transformation via plugins (including mapping logic), to permutation generation and ultimately reporting.

- Entry Point: ca/main.js gathers parameters and triggers the analysis.
- Condition Processing: ‘ca/conditions’ defines and evaluates policy conditions.
- Plugin Services: “mainPlugins” and “plugins” provide support modules (filtering, mapping, caching).
- Permutation Engine: Generates condition permutations (ca/permutationsPerPolicy.js and getPol2.js).
- Token Management: “tokenHandler” handles Azure authentication.
- Reporting: Scripts responsible for output generation (CSV, JSON, Markdown).
- External Dependencies: Include nodes for Microsoft Graph API and Azure CLI authentication flows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Layers
    entryPoint["CLI / Entry Point (ca/main.js)"]:::cli
    conditions["Condition Modules (ca/conditions: Applications.js, Locations.js, Platforms.js, clientAppTypes.js, users.js, eval)"]:::conditions
    plugins["Plugins System (ca/mainPlugins: axiosh.js, clearPolicyCache.js, customPolicyFilter.js, extraFiltering.js, findEmptySub.js, getPol.js, getPol2.js, graphHelpers.js, grouper.js, inMemList.js, tokenHandler.js, uniqNonterm.js, userMap.js, userMappers)"]:::plugins

    %% Permutation Engine Subgraph
    subgraph "Permutation Engine"
        direction TB
        P1["permutationsPerPolicy.js"]:::permutation
        P2["getPol2.js"]:::permutation
    end

    %% Token & Authentication Flow - split into two parts then merge
    TokenA["Token Directory (tokenHandler: axioshelpers.js, getCode.js, refresh.js)"]:::token
    TokenB["Token Plugin (ca/mainPlugins/tokenHandler.js)"]:::token
    tokenManager["Token & Auth Manager"]:::token

    %% Reporting Modules Subgraph
    subgraph "Reporting Modules"
        direction TB
        R1["createCSVreport.js"]:::reporting
        R2["createReport.js"]:::reporting
        R3["createReportLegacy.js"]:::reporting
    end
    reportingOut["Reporting Output"]:::reporting
    output["Output Files (CSV, Markdown, JSON)"]:::reporting

    external["External Services (Microsoft Graph API, Azure Login API)"]:::external

    %% Data Flow Connections
    entryPoint -- "CLI_flags" --> conditions
    conditions -- "evaluate_conditions" --> plugins
    plugins -- "transform_data" --> P1
    plugins -- "transform_data" --> P2
    P1 -- "generate_permutations" --> reportingOut
    P2 -- "generate_permutations" --> reportingOut
    reportingOut -- "create_reports" --> output

    %% Token & Auth Flow Connections
    entryPoint -- "token_auth" --> TokenA
    entryPoint -- "token_auth" --> TokenB
    TokenA --> tokenManager
    TokenB --> tokenManager
    tokenManager -- "api_calls" --> external

    %% Styling Definitions
    classDef cli fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef conditions fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef plugins fill:#abebc6,stroke:#333,stroke-width:2px;
    classDef permutation fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef token fill:#d7bde2,stroke:#333,stroke-width:2px;
    classDef reporting fill:#f9c7c7,stroke:#333,stroke-width:2px;
    classDef external fill:#fad7a0,stroke:#333,stroke-width:2px;

    %% Click Events
    click entryPoint "https://github.com/jsa2/caoptics/blob/main/ca/main.js"
    click conditions "https://github.com/jsa2/caoptics/tree/main/ca/conditions"
    click plugins "https://github.com/jsa2/caoptics/tree/main/ca/mainPlugins"
    click P1 "https://github.com/jsa2/caoptics/blob/main/ca/permutationsPerPolicy.js"
    click P2 "https://github.com/jsa2/caoptics/blob/main/ca/mainPlugins/getPol2.js"
    click TokenA "https://github.com/jsa2/caoptics/blob/main/tokenHandler/axioshelpers.js"
    click TokenB "https://github.com/jsa2/caoptics/blob/main/ca/mainPlugins/tokenHandler.js"
    click R1 "https://github.com/jsa2/caoptics/blob/main/createCSVreport.js"
    click R2 "https://github.com/jsa2/caoptics/blob/main/createReport.js"
    click R3 "https://github.com/jsa2/caoptics/blob/main/createReportLegacy.js"
```
