OCI CIS AI Agent
Oracle Cloud Infrastructure β CIS Foundations Benchmark 3.0 β AI-Powered Compliance Platform
---
## Overview
OCI CIS AI Agent is a self-hosted web application that automates **CIS Oracle Cloud Infrastructure Foundations Benchmark 3.0** compliance checks, powered by **OCI Generative AI** for intelligent analysis and an **MCP (Model Context Protocol)** server architecture for extensible task execution.
The platform combines security compliance scanning, AI-powered chat with **RAG (Retrieval-Augmented Generation)**, infrastructure exploration, and vector-based knowledge storage into a single, containerized solution with Oracle Cloud's official light theme.
---
## Features
### π€ AI Chat Agent with RAG + MCP Tool Use
- **OCI Generative AI** integration via official SDK (`oci.generative_ai_inference`)
- **RAG (Retrieval-Augmented Generation)**: automatically queries ADB vector store for relevant context before generating responses
- **MCP Tool Use (Function Calling)**: GenAI models can call tools from registered MCP servers during chat β supports both Cohere and Generic (OpenAI-style) function calling formats with automatic tool execution loop (max 5 iterations)
- **Chat Memory Compaction**: automatic summarization of older messages when conversation exceeds ~8000 tokens β keeps 6 recent messages intact and generates an LLM-based summary of older context, similar to Claude Code's context compression
- **Multimodal Chat**: upload images (PNG/JPG/GIF/WebP), PDFs, and text files directly in the chat for AI analysis β supports up to 5 files per message via OCI GenAI `ImageContent` and `DocumentContent`
- **Async Background Processing**: chat requests return immediately, GenAI + MCP tools process in background via dedicated thread pool (16 threads), frontend polls for results β eliminates 504 timeouts on long-running scans
- **Thinking Indicator**: button disables and shows spinner + "Pensando..." while waiting for GenAI response, with message timestamps
- 69 chat models + 11 embedding models across 6 providers: **Cohere**, **Meta**, **Google**, **OpenAI** (GPT-5.3/5.2/5.1/5/4.1/4o, Codex, Image, Audio, o1/o3/o4-mini, GPT-oss), **xAI** (Grok 4.1/4/3), **ProtectAI**
- OCID-based model resolution: catalog maps model IDs to OCI resource IDs per region for reliable API calls
- 16 OCI regions supported with auto-generated endpoints
- Full parameter control: temperature, max_tokens, top_p, top_k, frequency/presence penalty
- Toggle MCP tools on/off per chat session
- Conversation history with session management
- On-Demand and Dedicated serving modes
### π OCI Account Explorer
- Browse tenancy resources directly from the UI
- Explore: Compartments, Regions, VCNs, Compute Instances, Autonomous Databases, Object Storage Buckets
- Select which OCI connection to explore
- Real-time API calls via OCI Python SDK
### π CIS Compliance Reports (Oracle Official Engine)
- Powered by Oracle's official `cis_reports.py` (6660 lines, 48 CIS + 11 OBP checks)
- **Granular execution parameters**: CIS Level (1/2), OCI Best Practices, Raw Data, OCID Redaction
- **Level 1**: Essential security controls that can be implemented with minimal impact on operations. Recommended as baseline for all organizations.
- **Level 2**: Advanced security controls that may restrict functionality or require more effort to implement. Recommended for high-security environments.
- **Multiple output formats**: HTML summary, CSV per section/finding, JSON summary, optional XLSX
- **Report history**: full execution history with status, tenancy filter, and download actions (HTML/JSON) in the Reports tab
- **File browser**: dedicated Downloads tab with expandable cards per completed report, files grouped by category (Summary, CIS Findings, OBP, Raw Data, etc.)
- Region filtering with multi-select
- Real-time progress tracking with phase-based progress bar
- **CIS Engine auto-update**: check for new versions of `cis_reports.py` from Oracle's GitHub repository and update with one click (admin only). Custom patches are automatically reapplied after update
### π‘οΈ Built-in CIS MCP Server (Granular Per-Section)
- **Auto-registered** CIS Compliance Scanner MCP server β available out of the box
- **12 granular tools** instead of monolithic full-tenancy scan:
- `cis_scan_iam` β IAM checks (CIS 1.1β1.17): users, policies, groups, MFA, API keys
- `cis_scan_networking` β Network checks (CIS 2.1β2.8): security lists, NSGs, VCNs
- `cis_scan_compute` β Compute checks (CIS 3.1β3.3): instance metadata, monitoring
- `cis_scan_logging_monitoring` β Logging/Monitoring checks (CIS 4.1β4.17): audit, alarms, events
- `cis_scan_storage` β Storage checks (CIS 5.1β5.3): buckets, block volumes, file systems
- `cis_scan_asset_management` β Asset checks (CIS 6.1β6.2): compartments, tagging
- `cis_list_configs` / `cis_list_checks` β list available OCI configs and CIS checks
- `cis_get_check` / `cis_get_remediation` β detailed findings and remediation guidance
- `cis_get_scan_status` / `cis_invalidate_cache` β session status and cache management
- **Per-section data collection**: each scan tool collects only the OCI data needed for that section, avoiding unnecessary API calls
- **Region-specific scanning**: all scan tools accept optional `regions` parameter to target specific OCI regions (e.g., `["us-ashburn-1"]`) instead of scanning the entire tenancy
- **Session caching**: collected data is cached per config+regions scope (2-hour TTL), so subsequent scans on different sections reuse shared prerequisites (compartments, identity domains)
- **Parallelized data collection**: base collectors and regional collectors run in parallel thread pools (up to 8 workers), with 5-minute timeout per tool call
- Based on Oracle's official `cis_reports.py` (6660 lines, 48 CIS + 11 OBP checks)
### π MCP Server Registry + Tool Discovery
- Register multiple MCP servers (stdio, SSE, Python module)
- **Automatic tool discovery**: connect to MCP servers and discover available tools with names, descriptions, and input schemas
- **Manual tool definition**: add/edit tools with JSON Schema parameter definitions
- **Chat Agent integration**: discovered tools are automatically available as GenAI function calls during chat
- Upload `.py` scripts directly to servers
- **Link MCP servers to ADB Vector** databases as tools
- Activate/deactivate servers
- Select which MCP server to use per report execution
### ποΈ Autonomous Database Vector Storage
- Oracle Autonomous Database connection with **mTLS Wallet** authentication
- `python-oracledb` Thin mode (no Oracle Client needed)
- Wallet ZIP upload and automatic extraction
- Connection testing
- **Multiple vector tables per ADB**: register, edit, toggle active/inactive for each table
- **Multi-table RAG search**: queries all active tables across all ADB configs, merges results by cosine distance
- Link to GenAI config for embedding generation via OCI GenAI
### 𧬠Embeddings Management
- Dedicated tab for managing vector embeddings
- **Preview chunks before embedding**: review generated sections before creating embeddings
- **Embed CIS Reports**: automatically chunk reports by section with tenancy name, regions, and compartments enrichment
- **Upload text files**: upload `.txt` files, automatically chunked by paragraphs
- **Table selector**: choose which ADB vector table to store embeddings in
- **OCI GenAI Embeddings**: uses Cohere Embed models (v3.0/v4.0, multilingual, light) via OCI GenAI `embed_text` API
- Browse, inspect and delete individual embeddings from the ADB vector store
- 11 embedding models supported including Cohere Embed v4.0 and OpenAI Text Embedding 3
### π Configuration Logs
- **Persistent activity log** per configuration tab (OCI, GenAI, ADB, MCP)
- Logs all test, save, upload, report, and ingest operations with severity (success/error/info)
- **Inline log panel** at the bottom of each config tab with severity filter
- Auto-cleanup of logs older than 30 days
- Admin can view all logs; users see only their own
- API endpoints for listing and clearing logs
### π Security
- **JWT authentication** with configurable expiry
- **TOTP MFA** (Google Authenticator / Authy compatible)
- **RBAC** with 3 roles: Admin, User, Viewer
- Audit logging for all operations
- Encrypted credential storage
---
## Architecture
```
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Docker Compose β
β β
β ββββββββββββββββ ββββββββββββββββββββββββββββββββ β
β β Nginx β β FastAPI Backend β β
β β (Frontend) ββββββββΆβ (Python 3.12) β β
β β :8080 β β :8000 β β
β ββββββββββββββββ β β β
β β βββββββββββββββ β β
β β β OCI SDK ββββΆ OCI APIs β β
β β βββββββββββββββ€ β β
β β β GenAI Client ββββΆ LLM β β
β β βββββββββββββββ€ (tools) β β
β β β MCP Client ββββΆ MCP Svrs β β
β β βββββββββββββββ€ (discover β β
β β β β +execute) β β
β β βββββββββββββββ€ β β
β β β oracledb ββββΆ ADB β β
β β βββββββββββββββ€ β β
β β β RAG Pipeline ββββΆ Embed + β β
β β β β Search β β
β β βββββββββββββββ β β
β β β β
β β SQLite (agent.db) β β
β ββββββββββββββββββββββββββββββββ β
β β β
β agent-data volume β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
---
## Quick Start
### Prerequisites
- Docker and Docker Compose
- OCI API Key pair (private `.pem` key + fingerprint)
- OCI Tenancy OCID, User OCID, Compartment OCID
### 1. Clone & Configure
```bash
git clone https://github.com/nogueiragustavo/oci-cis-agent.git
cd oci-cis-agent
cp .env.example .env
```
Edit `.env`:
```env
APP_SECRET=your-very-long-random-secret-string-here-at-least-64-chars
JWT_EXPIRY_HOURS=12
PORT=8080
```
### 2. Build & Run
```bash
docker compose up -d --build
```
### 3. Access
Open `http://localhost:8080`
Default credentials:
- **Username:** `admin`
- **Password:** `admin123`
> β οΈ Change the default password immediately after first login.
---
## Configuration Guide
### Step 1 β OCI Credentials
Navigate to **OCI Credentials** tab and add:
| Field | Description |
|-------|-------------|
| Tenancy Name | Friendly name (e.g., `my-company`) |
| OCID Tenancy | `ocid1.tenancy.oc1..xxxxx` |
| OCID User | `ocid1.user.oc1..xxxxx` |
| Fingerprint | `aa:bb:cc:dd:ee:ff:...` |
| Region | `sa-saopaulo-1`, `us-ashburn-1`, etc. |
| Compartment OCID | `ocid1.compartment.oc1..xxxxx` |
| Private Key | `.pem` file |
| Key Passphrase | *(optional)* Only required if the private key is encrypted |
Click **Testar** to validate the connection.
### Step 2 β GenAI Model
Navigate to **GenAI Config** tab:
1. Select the **OCI Credential** created in Step 1 β **Region** and **Compartment OCID** are auto-filled from the selected credential
2. Choose a **model** from the catalog
3. Adjust the **GenAI region** if needed (auto-populated, must have Generative AI service available)
4. Adjust parameters (temperature, max_tokens, etc.)
5. The **endpoint** is auto-generated: `https://inference.generativeai.{region}.oci.oraclecloud.com`
For **dedicated endpoints**, switch Serving Type to `DEDICATED` and provide the endpoint ID.
The GenAI connection follows Oracle's official SDK pattern:
```python
# Auth via stored OCI config
config = oci.config.from_file(config_path, "DEFAULT")
# Client with endpoint, retry, and timeout
client = oci.generative_ai_inference.GenerativeAiInferenceClient(
config=config,
service_endpoint=endpoint,
retry_strategy=oci.retry.NoneRetryStrategy(),
timeout=(10, 240)
)
# Chat with TextContent + Message objects
chat_detail = oci.generative_ai_inference.models.ChatDetails()
chat_detail.serving_mode = OnDemandServingMode(model_id="...")
chat_detail.chat_request = GenericChatRequest(messages=[...])
chat_detail.compartment_id = compartment_id
```
### Step 3 β MCP Servers (Optional)
Register MCP servers for extended task execution and **Chat Agent tool use**:
| Type | Use Case |
|------|----------|
| `stdio` | Local Python scripts (e.g., CIS check runner) |
| `SSE` | Remote HTTP servers |
| `module` | Upload `.py` files directly |
MCP servers can be **linked to ADB Vector** databases, enabling them to use the vector store as a tool during report execution.
**Tool Discovery**: After registering a server, click **"Descobrir Tools"** to automatically discover available tools via MCP protocol. You can also add tools manually with name, description, and JSON Schema parameters. Discovered tools are automatically available as **function calls** in the Chat Agent.
### Step 4 β ADB Vector + RAG (Optional)
For persistent vector storage and RAG-powered chat:
1. Add DSN (TNS name from tnsnames.ora, e.g., `myatp_high`)
2. Set credentials (username/password)
3. Select a **GenAI Config** (for embedding generation via OCI GenAI)
4. Select an **Embedding Model** (Cohere Embed v4.0 recommended)
5. Upload Wallet ZIP (for mTLS)
6. Test the connection
7. **Register vector tables**: add the names of existing tables in your ADB that contain vectorized data (e.g., `CIS_REPORT`, `CIS_RECOMMENDATIONS`). Toggle tables active/inactive to control which are queried during RAG.
### Step 5 β Embeddings (Optional)
Navigate to the **Embeddings** tab to populate the vector store:
1. **From CIS Reports**: Select a completed report, **preview chunks** (with tenancy/regions/compartments context), then generate embeddings
2. **From text files**: Upload `.txt` files for automatic chunking and embedding
3. **Select target table**: choose which ADB vector table to store embeddings in
4. Browse and manage existing embeddings per table
Once embeddings exist, the **chat automatically uses RAG** β it queries all active vector tables across all ADB configs for relevant context before generating responses with the selected GenAI model.
---
## OCI IAM Policies
The following policies are required in your tenancy:
```
Allow group to use generative-ai-family in compartment
Allow group to read all-resources in tenancy
Allow group to inspect compartments in tenancy
Allow group to inspect autonomous-databases in compartment
Allow group to read virtual-network-family in compartment
Allow group to read instance-family in compartment
Allow group to read objectstorage-namespaces in tenancy
Allow group to read buckets in compartment
```
---
## Project Structure
```
oci-cis-agent/
βββ backend/
β βββ app.py # FastAPI application (~2600 lines)
β βββ cis_reports.py # Oracle CIS Benchmark checker (6660 lines, report engine)
β βββ mcp_cis_server.py # MCP server with 12 granular CIS tools
β βββ Dockerfile # Python 3.12 + OCI CLI
β βββ requirements.txt # Dependencies
βββ frontend/
β βββ index.html # SPA with Oracle Cloud theme (~900 lines)
βββ nginx/
β βββ default.conf # Reverse proxy config
βββ docker-compose.yml # Orchestration
βββ logo.svg # Project logo (Oracle AI Robot)
βββ .env.example # Environment template
βββ .gitignore
βββ README.md
```
---
## API Reference
### Authentication
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/auth/login` | Login (username + password + optional TOTP) |
| POST | `/api/auth/logout` | Logout and invalidate session |
| POST | `/api/auth/register` | Create user (admin only) |
| POST | `/api/auth/change-password` | Change password |
### OCI Management
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/oci/config` | Save OCI credentials (multipart) |
| GET | `/api/oci/configs` | List OCI credentials |
| PUT | `/api/oci/configs/{id}` | Update OCI credential (multipart) |
| POST | `/api/oci/test/{id}` | Test OCI connection |
| DELETE | `/api/oci/configs/{id}` | Delete OCI credential |
### OCI Account Explorer
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/oci/explore/{id}/compartments` | List compartments |
| GET | `/api/oci/explore/{id}/regions` | List subscribed regions |
| GET | `/api/oci/explore/{id}/vcns` | List VCNs |
| GET | `/api/oci/explore/{id}/instances` | List compute instances |
| GET | `/api/oci/explore/{id}/databases` | List Autonomous Databases |
| GET | `/api/oci/explore/{id}/buckets` | List Object Storage buckets |
### Generative AI
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/genai/models` | List available models and regions |
| POST | `/api/genai/config` | Save GenAI configuration |
| GET | `/api/genai/configs` | List GenAI configurations |
| PUT | `/api/genai/configs/{id}` | Update GenAI configuration |
| POST | `/api/genai/test/{id}` | Test GenAI connection |
| DELETE | `/api/genai/configs/{id}` | Delete GenAI config |
### MCP Servers
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/mcp/servers` | Register MCP server |
| GET | `/api/mcp/servers` | List MCP servers |
| PUT | `/api/mcp/servers/{id}` | Update MCP server |
| PUT | `/api/mcp/servers/{id}/toggle` | Activate/deactivate |
| POST | `/api/mcp/servers/{id}/upload` | Upload script file |
| PUT | `/api/mcp/servers/{id}/link-adb` | Link to ADB Vector |
| POST | `/api/mcp/servers/{id}/discover-tools` | Auto-discover tools from MCP server |
| PUT | `/api/mcp/servers/{id}/tools` | Manually update tool definitions |
| DELETE | `/api/mcp/servers/{id}` | Delete MCP server |
### ADB Vector
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/adb/config` | Save ADB connection (with GenAI config + embedding model) |
| GET | `/api/adb/configs` | List ADB connections (includes vector tables) |
| PUT | `/api/adb/configs/{id}` | Update ADB connection (multipart) |
| POST | `/api/adb/parse-wallet` | Parse wallet ZIP and extract DSN names |
| POST | `/api/adb/{id}/upload-wallet` | Upload wallet ZIP |
| POST | `/api/adb/test/{id}` | Test ADB connection |
| GET | `/api/adb/{id}/tables` | List vector tables for ADB config |
| POST | `/api/adb/{id}/tables` | Add vector table |
| PUT | `/api/adb/{id}/tables/{tid}` | Update vector table (name, description, active) |
| DELETE | `/api/adb/{id}/tables/{tid}` | Remove vector table |
| DELETE | `/api/adb/configs/{id}` | Delete ADB config |
### Embeddings
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/embeddings/preview/{rid}` | Preview report chunks before embedding (with tenancy/regions/compartments) |
| POST | `/api/embeddings/report/{rid}` | Generate embeddings from CIS report (chunked by section, accepts `table_name`) |
| POST | `/api/embeddings/upload` | Upload .txt file and generate embeddings (accepts `table_name`) |
| GET | `/api/embeddings/{vid}/list` | List embeddings in ADB (paginated, accepts `table_name` query param) |
| DELETE | `/api/embeddings/{vid}/{doc_id}` | Delete individual embedding (accepts `table_name` query param) |
### Chat & Reports
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/chat` | Send message (with RAG + MCP tool use, accepts `use_tools` flag) |
| POST | `/api/chat/upload` | Send message with file attachments (multipart, images/PDFs/text) |
| POST | `/api/reports/run` | Execute CIS report |
| GET | `/api/reports` | List reports |
| GET | `/api/reports/{id}/html` | View HTML report |
| GET | `/api/reports/{id}/download` | Download report |
| GET | `/api/reports/{rid}/files` | List report files by category |
| GET | `/api/reports/{rid}/files/{fid}/download` | Download individual report file |
### CIS Engine
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/cis-engine/version` | Current CIS engine version |
| GET | `/api/cis-engine/check-update` | Check GitHub for newer version (admin) |
| POST | `/api/cis-engine/update` | Download + apply update with patches (admin) |
### Config Logs
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/config-logs` | List config logs (filterable by `config_type`, `severity`, `config_id`) |
| DELETE | `/api/config-logs` | Clear config logs (admin, filterable by `config_type`, `config_id`) |
### Admin
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/users` | List users (admin) |
| PUT | `/api/users/{id}` | Update user role/status |
| POST | `/api/mfa/setup` | Generate MFA secret |
| POST | `/api/mfa/verify` | Activate MFA |
| GET | `/api/audit-log` | View audit log (admin) |
| GET | `/api/health` | Health check |
---
## Supported GenAI Models (69 Chat + 11 Embedding)
All models include OCID mapping for `us-ashburn-1`. For other regions, use the "Personalizado (usar OCID)" option.
### Chat Models
| Provider | Model | Model ID | API Format |
|----------|-------|----------|------------|
| Cohere | Command A Reasoning | `cohere.command-a-reasoning` | COHERE |
| Cohere | Command A Vision | `cohere.command-a-vision` | COHERE |
| Cohere | Command A | `cohere.command-a-03-2025` | COHERE |
| Cohere | Command R+ (08-2024) | `cohere.command-r-plus-08-2024` | COHERE |
| Cohere | Command R (08-2024) | `cohere.command-r-08-2024` | COHERE |
| Meta | Llama 4 Maverick | `meta.llama-4-maverick-17b-128e-instruct-fp8` | GENERIC |
| Meta | Llama 4 Scout | `meta.llama-4-scout-17b-16e-instruct` | GENERIC |
| Meta | Llama Guard 4 (12B) | `meta.llama-guard-4-12b` | GENERIC |
| Google | Gemini 2.5 Pro | `google.gemini-2.5-pro` | GENERIC |
| Google | Gemini 2.5 Flash | `google.gemini-2.5-flash` | GENERIC |
| Google | Gemini 2.5 Flash-Lite | `google.gemini-2.5-flash-lite` | GENERIC |
| OpenAI | GPT-5.3 Codex | `openai.gpt-5.3-codex` | GENERIC |
| OpenAI | GPT-5.2 Codex | `openai.gpt-5.2-codex` | GENERIC |
| OpenAI | GPT-5.2 Pro | `openai.gpt-5.2-pro` | GENERIC |
| OpenAI | GPT-5.2 Pro (2025-12-11) | `openai.gpt-5.2-pro-2025-12-11` | GENERIC |
| OpenAI | GPT-5.2 | `openai.gpt-5.2` | GENERIC |
| OpenAI | GPT-5.2 (2025-12-11) | `openai.gpt-5.2-2025-12-11` | GENERIC |
| OpenAI | GPT-5.2 Chat Latest | `openai.gpt-5.2-chat-latest` | GENERIC |
| OpenAI | GPT-5.1 Codex Max | `openai.gpt-5.1-codex-max` | GENERIC |
| OpenAI | GPT-5.1 Codex | `openai.gpt-5.1-codex` | GENERIC |
| OpenAI | GPT-5.1 Codex Mini | `openai.gpt-5.1-codex-mini` | GENERIC |
| OpenAI | GPT-5.1 | `openai.gpt-5.1` | GENERIC |
| OpenAI | GPT-5.1 (2025-11-13) | `openai.gpt-5.1-2025-11-13` | GENERIC |
| OpenAI | GPT-5.1 Chat Latest | `openai.gpt-5.1-chat-latest` | GENERIC |
| OpenAI | GPT-5 Codex | `openai.gpt-5-codex` | GENERIC |
| OpenAI | GPT-5 | `openai.gpt-5` | GENERIC |
| OpenAI | GPT-5 (2025-08-07) | `openai.gpt-5-2025-08-07` | GENERIC |
| OpenAI | GPT-5 Mini | `openai.gpt-5-mini` | GENERIC |
| OpenAI | GPT-5 Mini (2025-08-07) | `openai.gpt-5-mini-2025-08-07` | GENERIC |
| OpenAI | GPT-5 Nano | `openai.gpt-5-nano` | GENERIC |
| OpenAI | GPT-5 Nano (2025-08-07) | `openai.gpt-5-nano-2025-08-07` | GENERIC |
| OpenAI | GPT-4.1 | `openai.gpt-4.1` | GENERIC |
| OpenAI | GPT-4.1 (2025-04-14) | `openai.gpt-4.1-2025-04-14` | GENERIC |
| OpenAI | GPT-4.1 Mini | `openai.gpt-4.1-mini` | GENERIC |
| OpenAI | GPT-4.1 Mini (2025-04-14) | `openai.gpt-4.1-mini-2025-04-14` | GENERIC |
| OpenAI | GPT-4.1 Nano | `openai.gpt-4.1-nano` | GENERIC |
| OpenAI | GPT-4.1 Nano (2025-04-14) | `openai.gpt-4.1-nano-2025-04-14` | GENERIC |
| OpenAI | GPT-4o | `openai.gpt-4o` | GENERIC |
| OpenAI | GPT-4o (2024-08-06) | `openai.gpt-4o-2024-08-06` | GENERIC |
| OpenAI | GPT-4o (2024-11-20) | `openai.gpt-4o-2024-11-20` | GENERIC |
| OpenAI | GPT-4o Mini | `openai.gpt-4o-mini` | GENERIC |
| OpenAI | GPT-4o Mini Search Preview | `openai.gpt-4o-mini-search-preview` | GENERIC |
| OpenAI | GPT-4o Mini Search (2025-03-11) | `openai.gpt-4o-mini-search-preview-2025-03-11` | GENERIC |
| OpenAI | GPT-4o Search Preview | `openai.gpt-4o-search-preview` | GENERIC |
| OpenAI | GPT-4o Search (2025-03-11) | `openai.gpt-4o-search-preview-2025-03-11` | GENERIC |
| OpenAI | GPT Image 1.5 | `openai.gpt-image-1.5` | GENERIC |
| OpenAI | GPT Image 1 | `openai.gpt-image-1` | GENERIC |
| OpenAI | GPT Audio | `openai.gpt-audio` | GENERIC |
| OpenAI | o4-mini | `openai.o4-mini` | GENERIC |
| OpenAI | o4-mini (2025-04-16) | `openai.o4-mini-2025-04-16` | GENERIC |
| OpenAI | o3 | `openai.o3` | GENERIC |
| OpenAI | o3 (2025-04-16) | `openai.o3-2025-04-16` | GENERIC |
| OpenAI | o3-mini | `openai.o3-mini` | GENERIC |
| OpenAI | o3-mini (2025-01-31) | `openai.o3-mini-2025-01-31` | GENERIC |
| OpenAI | o1 | `openai.o1` | GENERIC |
| OpenAI | o1 (2024-12-17) | `openai.o1-2024-12-17` | GENERIC |
| OpenAI | GPT-oss (120B) | `openai.gpt-oss-120b` | GENERIC |
| OpenAI | GPT-oss (20B) | `openai.gpt-oss-20b` | GENERIC |
| xAI | Grok 4 | `xai.grok-4` | GENERIC |
| xAI | Grok 4.1 Fast Reasoning | `xai.grok-4-1-fast-reasoning` | GENERIC |
| xAI | Grok 4.1 Fast Non-Reasoning | `xai.grok-4-1-fast-non-reasoning` | GENERIC |
| xAI | Grok 4 Fast Reasoning | `xai.grok-4-fast-reasoning` | GENERIC |
| xAI | Grok 4 Fast Non-Reasoning | `xai.grok-4-fast-non-reasoning` | GENERIC |
| xAI | Grok 3 | `xai.grok-3` | GENERIC |
| xAI | Grok 3 Mini | `xai.grok-3-mini` | GENERIC |
| xAI | Grok 3 Fast | `xai.grok-3-fast` | GENERIC |
| xAI | Grok 3 Mini Fast | `xai.grok-3-mini-fast` | GENERIC |
| xAI | Grok Code Fast 1 | `xai.grok-code-fast-1` | GENERIC |
| ProtectAI | DeBERTa Prompt Injection v2 | `protectai.deberta-v3-base-prompt-injection-v2` | GENERIC |
> **Custom OCID**: You can also use any model available in your region by selecting "Personalizado (usar OCID)" and providing the full model OCID.
### Embedding Models
| Provider | Model | Model ID | Dimensions |
|----------|-------|----------|------------|
| Cohere | Embed v4.0 (Multimodal) | `cohere.embed-v4.0` | 1536 |
| OpenAI | Text Embedding 3 Large | `openai.text-embedding-3-large` | 3072 |
| OpenAI | Text Embedding 3 Small | `openai.text-embedding-3-small` | 1536 |
| Cohere | Embed English v3.0 | `cohere.embed-english-v3.0` | 1024 |
| Cohere | Embed Multilingual v3.0 | `cohere.embed-multilingual-v3.0` | 1024 |
| Cohere | Embed English Light v3.0 | `cohere.embed-english-light-v3.0` | 384 |
| Cohere | Embed Multilingual Light v3.0 | `cohere.embed-multilingual-light-v3.0` | 384 |
| Cohere | Embed English Image v3.0 | `cohere.embed-english-image-v3.0` | 1024 |
| Cohere | Embed Multilingual Image v3.0 | `cohere.embed-multilingual-image-v3.0` | 1024 |
| Cohere | Embed English Light Image v3.0 | `cohere.embed-english-light-image-v3.0` | 384 |
| Cohere | Embed Multilingual Light Image v3.0 | `cohere.embed-multilingual-light-image-v3.0` | 384 |
### GenAI Regions
`us-chicago-1` Β· `us-ashburn-1` Β· `us-phoenix-1` Β· `uk-london-1` Β· `eu-frankfurt-1` Β· `ap-tokyo-1` Β· `ap-osaka-1` Β· `sa-saopaulo-1` Β· `ca-toronto-1` Β· `ap-melbourne-1` Β· `ap-mumbai-1` Β· `eu-amsterdam-1` Β· `me-jeddah-1` Β· `ap-singapore-1` Β· `ap-seoul-1` Β· `sa-vinhedo-1`
---
## Tech Stack
| Component | Technology |
|-----------|-----------|
| Backend | Python 3.12, FastAPI 0.115, Uvicorn |
| Frontend | Vanilla JS SPA, Oracle Cloud UI theme |
| Auth | JWT + TOTP MFA + RBAC |
| Database | SQLite (WAL mode) |
| OCI SDK | `oci` 2.133.0, `oci-cli` |
| ADB | `python-oracledb` 2.4.1 (Thin mode) |
| GenAI | `oci.generative_ai_inference` |
| Container | Docker Compose, Nginx reverse proxy |
| MCP | Model Context Protocol SDK (stdio/SSE) with tool discovery + execution |
| CIS Scanner | Oracle CIS Foundations Benchmark 3.0 checker (`cis_reports.py`) |
---
## Versioning
| Version | Date | Changes |
|---------|------|---------|
| **v2.0** | 2026-03 | Async background chat processing (no more 504 timeouts), frontend polling with timestamps, 8 uvicorn workers + 16-thread chat executor for ~12 simultaneous chats, parallelized MCP data collection (5-thread base + 8-thread regional), 2-hour MCP session cache, 5-min tool timeout, full dead code cleanup across backend/frontend/MCP |
| **v1.9** | 2026-03 | Multimodal chat (image/PDF/text file upload with OCI GenAI ImageContent/DocumentContent), region-specific MCP scanning (`regions` param on all scan tools), orphaned report auto-detection on progress poll, nginx timeout increased to 15min, improved API error handling for non-JSON responses |
| **v1.8** | 2026-03 | CIS Engine auto-update from Oracle GitHub with automatic patch reapplication, version check UI card (admin), new `/api/cis-engine/*` endpoints, report file listing and individual download endpoints, reorganized Reports tab (execution history + status) and Downloads tab (file browser only with expandable cards per report), CIS Level description tooltip, persistent log expand during report generation |
| **v1.7** | 2026-03 | Oracle official CIS report engine (replaces lightweight checker), granular report parameters (Level, OBP, Raw Data, Redact), per-report file storage with category browser, tenancy filter in Downloads, individual file download |
| **v1.6** | 2026-03 | Granular CIS MCP server (12 per-section scan tools: IAM, Networking, Compute, Logging/Monitoring, Storage, Asset Management), chat memory compaction with LLM-based summarization, GenAI tool use loop fix (accumulated conversation), chat thinking indicator, auto-registered CIS MCP server |
| **v1.5** | 2026-03 | MCP Tool Use in Chat (GenAI function calling with auto tool discovery + execution via MCP SDK), multi-table ADB vector search, preview chunks before embedding, enriched embeddings with tenancy/regions/compartments, searchable dropdowns, editable vector tables, orphaned report cleanup on restart |
| **v1.4** | 2026-03 | In-place config editing, 69 chat + 11 embedding models with OCID resolution (OpenAI GPT-5.3/5.2/5.1/5/4.1/4o/Codex/Image/Audio, xAI, Google, Meta, ProtectAI), OpenAI Text Embedding 3, custom OCID support, wallet auto-parse with DSN extraction |
| **v1.3** | 2026-03 | Persistent config logs per tab, GenAI auto-fill from OCI credentials, inline UX feedback with loading spinners, MCP type-switch fix, encrypted key passphrase support, Docker stdin hang fix |
| **v1.2** | 2026-03 | RAG pipeline (OCI GenAI embeddings + ADB vector search), dedicated Embeddings tab, CIS report chunking, file upload embedding |
| **v1.1** | 2025-02 | OCI SDK GenAI (exact pattern), OCI Account Explorer, MCPβADB linking, full chat parameters |
| **v1.0** | 2025-02 | Initial release: OCI theme, GenAI integration, MCP servers, ADB vector, JWT+MFA+RBAC |
---
## Development
### Run Backend Locally
```bash
cd backend
pip install -r requirements.txt
DATA_DIR=./data uvicorn app:app --reload --port 8000
```
### Run with Docker
```bash
docker compose up -d --build
docker compose logs -f backend
```
### Rebuild After Changes
```bash
docker compose down
docker compose up -d --build
```
---
## Troubleshooting
**OCI CLI test fails with timeout:**
Check that your API key is correctly configured and the tenancy OCID is valid. Ensure outbound HTTPS (443) is allowed.
**GenAI returns 401/403:**
Verify the IAM policy `Allow group ... to use generative-ai-family in compartment ...` exists. Check that the compartment OCID in the GenAI config matches the policy.
**OCI CLI test hangs with passphrase prompt (Docker):**
If your private key is encrypted (`ENCRYPTED` in the PEM header), provide the passphrase in the **Key Passphrase** field when saving the credential. Unencrypted keys work without a passphrase. The app automatically detects encrypted keys and blocks upload if no passphrase is provided.
**ADB connection fails:**
Ensure the wallet ZIP contains `tnsnames.ora` and `ewallet.pem`. The DSN must match a service name in `tnsnames.ora` (e.g., `myatp_high`).
**Container won't start:**
```bash
docker compose logs backend
```
---
## License
MIT
---
Built with β€οΈ for Oracle Cloud Infrastructure security compliance