pyCaOptics is a Python-based script designed to analyze Conditional Access policies in Azure Active Directory. It offers functionality similar to the original caOptics tool but is implemented in Python for ease of use and integration in various environments. This script enables users to authenticate via an Azure App Registration or interactively, retrieve Conditional Access policies, and perform an analysis to identify potential gaps or issues within the policies.

• Overview
• Features
• Prerequisites
• Setup
• Usage
  • Using the Script with App Registration
  • Using the Script with Interactive Authentication
• Output
• Error Handling
• References
• Acknowledgements

pyCaOptics is a tool to assist security teams in reviewing and auditing Conditional Access policies in Azure Active Directory (AAD). By automating the retrieval and analysis of these policies, the script helps identify gaps, such as users or applications that might not be covered by the policies or conflicts between policies.

The project was inspired by the original caOptics tool and re-implemented in Python to allow broader usage across different environments without needing to rely on Node.js.

• Authentication: Supports both interactive user authentication and client ID-based authentication via Azure App Registration.
• Conditional Access Policy Retrieval: Retrieves Conditional Access policies from Microsoft Graph API.
• Detailed Analysis: Identifies potential issues such as uncovered users, applications, and policy conflicts.
• Logging and Error Handling: Includes robust logging and error handling to assist in troubleshooting and policy review.

Before using pyCaOptics, ensure you have the following:

• Python 3.8 or higher installed on your system.
• Azure App Registration with appropriate Microsoft Graph API permissions (referenced below under Step 3).
• Azure AD Admin Consent granted for the app registration.

1. Clone the Repository:

   git clone https://github.com/riparino/pyCaOptics.git
   cd pyCaOptics

2. Install Dependencies: Install the required Python packages using pip:

   pip install -r requirements.txt

3. Configure Azure App Registration:
   • Go to Azure Portal > Azure Active Directory > App registrations.
   • Register a new application or use an existing one.
   • Assign necessary API permissions:
     • ConditionalAccessPolicy.Read.All
     • Policy.Read.All
     • Application.Read.All
     • Users.Read.All
     • Groups.Read.All
     • Policy.Read.All
   • Add https://localhost:8400 as a redirect URI under "Mobile and desktop applications".
   • Enable Access tokens for Implicit grant and hybrid flows.

To run the script using an Azure App Registration, use the following command:

python pyCaOptics_app.py <tenant_id> <client_id>

• <tenant_id>: The Azure Active Directory tenant ID.
• <client_id>: The client ID of your Azure App Registration.

To run the script using interactive browser-based authentication:

python pyCaOptics_usermode.py <tenant_id>

This mode will open a browser window for you to sign in with your Azure AD account.

Bear in mind that you will likely require at least Security Reader for this to work as your user.

The script will perform the following actions:

• Retrieve Policies: Fetches Conditional Access policies from Microsoft Graph API.
• Analyze Policies: Identifies gaps such as uncovered users, applications, or conflicting policies.
• Save Results: The analysis results are saved to a CSV file in the current directory. The file name will be of the format analysis_results_<timestamp>.csv.

The script includes detailed error handling to assist in troubleshooting:

• 403 Forbidden: Ensure your App Registration has the necessary permissions.
• Key Errors: The script will log and skip any policies missing expected fields.
• General Exceptions: Any unexpected issues are logged with a descriptive message to aid in debugging.

If you prefer to install the project using setup.py, follow these steps:

1. Ensure you are in the root directory where setup.py is located:

   cd pyCaOptics

2. Install the package using pip:

   pip install .

   This command will install the pyCaOptics package and its dependencies. After installation, you can run the scripts directly if they are defined as console scripts in the setup.py.
3. Run the Scripts:

   pyCaOptics-app <tenant_id> <client_id>
   pyCaOptics-usermode <tenant_id>

   Otherwise, you can continue to run the scripts as described in the Usage section.