User Guide

This guide is the starting point for using OCI Policy Analysis after the application is installed. The root README is intentionally a short launch guide; this page and the linked references contain the detail.

Choose an application mode

• New desktop app: the default desktop experience starting in 7.0.

• Legacy desktop app: the maintained Tkinter interface for the 7.0 release line.

• Web application: browser workflow for local or server-hosted use.

• CLI: scripted loading, filtering, and export.

• MCP: policy and identity queries for MCP clients.

For a capability comparison and the relationship between the modes, see the overview.

First run

1. Complete the general setup.

2. Follow the Desktop or Web launch guide.

3. Choose the dataset you will analyze:

   • Live tenancy data: configure an OCI user/API-key profile, session token, instance principal, or resource principal. An OCI administrator must also grant the required IAM permissions to the principal that runs the tool.

   • CIS Compliance output: use a directory produced by the CIS Compliance script, then import it with Load Compliance Data. This path does not require OCI credentials in OCI Policy Analysis.

   • Combined cache: open a cache previously saved by the application when you need repeatable or offline analysis.

4. Load the chosen data source from Overview & Settings in the new desktop app, Settings in the legacy app, or the web home page. Start with the new UI usage guide or the legacy UI guide.

Clean, build, and run from a source checkout

The root scripts are short adapters to the maintained scripts in run/: local-build calls run/build, local-run calls run/local, and local-clean calls run/clean. Use the same UI names across setup, source running, and cleanup:

Task	macOS / Linux	Windows PowerShell
Prepare the environment	./local-build.sh --mode ui	./local-build.ps1 --mode ui
Run the new desktop app	./local-run.sh --mode ui	./local-run.ps1 --mode ui
Run the Tkinter app	./local-run.sh --mode legacy-ui	./local-run.ps1 --mode legacy-ui
Clean one UI’s executable files	./local-clean.sh --mode ui	./local-clean.ps1 --mode ui

Use legacy-ui in place of ui to prepare or clean Tkinter files. Both desktop modes include MCP dependencies for the embedded server or assistant. Build dependencies for the other interfaces with --mode web, cli, or mcp; --mode all prepares Qt, web, and MCP dependencies and is the default for local-build.

local-clean with no mode performs a full reset, including the shared virtual environment. The UI-specific clean modes remove only that UI’s executable artifacts and keep the environment. Choose the mode carefully before a full clean.

To package a native desktop executable, use the executable builder directly:

./run/build-executable.sh ui          # New Qt-based desktop app
./run/build-executable.sh ui --mode onefile # Single-file executable .exe (Windows) or .app (Mac bundle)
./run/build-executable.sh legacy-ui   # Tkinter desktop app

On Windows, use ./run/build-executable.ps1 with the same ui or legacy-ui selector. The Qt builder accepts additional Nuitka options such as --mode onefile; Tkinter uses PyInstaller. The old local-build-with-pyinstaller.sh and .ps1 names remain as compatibility adapters, but the run/build-executable commands are the clear entry point for both apps. See the run operations guide for executable options, configuration, container builds, and deployment.

Core workflows

Policy and identity analysis

The UI supports policy browsing, principal analysis, policy history, workload principals, permissions reports, and cross-tenancy analysis. The UI usage guide describes the new desktop pages; the legacy UI guide covers Tkinter.

Advanced policy analysis

• Simulation evaluates policy statements against OCI API operations.

• Recommendations explains risk, overlap, cleanup, and consolidation analysis.

• Tag-based policy search covers parsed tag conditions and policy metadata.

• OKE workload identity covers namespace and service-account queries.

• Limited Compliance Loading explains policy-and-compartments-only CIS imports.

• Limited Web User documents restricted web access profiles.

Troubleshooting and deployment

Use logging and troubleshooting for runtime diagnostics. For server deployments, see web setup, containerized MCP, and MCP OAuth.

Reference map

The architecture page explains the runtime layers and data flow. The API reference documents the maintained Python surface. The MCP examples provide concrete query patterns.