AI Agent — Infrastructure & Security Engineer

Oracle Cloud Infrastructure — CIS Foundations Benchmark 3.0 — AI-Powered Compliance Platform

---

Overview

AI Agent — Infrastructure & Security Engineer 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 a React 19 SPA (TypeScript, Vite), Oracle Dark Premium theme (light/dark modes), KPI dashboard with compliance gauge, i18n (pt/en/es), and Recharts visualizations.

---

Features

AI Chat Agent with RAG + MCP Tool Use

• OCI Generative AI integration via official SDK (oci.generative_ai_inference)
• RAG (Retrieval-Augmented Generation): queries ADB vector store for relevant context before generating responses — single ADB connection per search, smart table skip, CIS recommendation text filter for exact matching, follow-up context enrichment
• Source hierarchy: findings tables > cisrecom (official remediation) > engineerknowledgebase (complementary) — temporal awareness with extract dates, tenancy isolation via JSON_VALUE filter
• MCP Tool Use (Function Calling): GenAI models call tools from registered MCP servers during chat — supports Cohere and Generic (OpenAI-style) function calling with automatic tool execution loop (max 5 iterations)
• Chat Memory Compaction: automatic summarization of older messages when conversation exceeds ~6000 tokens — keeps 20 recent messages intact
• Chat Sidebar: collapsible panel with model parameters (temperature, max_tokens, top_p, top_k, penalties)
• Multimodal Chat: upload images (PNG/JPG/GIF/WebP), PDFs, and text files for AI analysis — 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 (10 threads), frontend polls for results
• 16 chat models + 3 embedding models across 5 providers: Meta (Llama 4), Google (Gemini 2.5), OpenAI (GPT-5.2/5.1/5 Mini/4.1/4o, o3/o4-mini), xAI (Grok 4/3)
• OCID-based model resolution: catalog maps model IDs to OCI resource IDs per region
• 16 OCI regions supported with auto-generated endpoints
• Provider parameter matrix: automatic parameter segmentation per model — reasoning models (o3/o4-mini) only get max_completion_tokens + reasoning_effort, OpenAI GPT-4.x gets freq/pres penalties, Google/Meta get top_k
• Full parameter control: temperature, max_tokens, top_p, top_k, frequency/presence penalty (when supported)
• Toggle MCP tools on/off per chat session
• Conversation history with session management
• On-Demand and Dedicated serving modes

Terraform Agent (IaC)

• AI-powered Terraform code generation for OCI infrastructure provisioning
• Dedicated chat interface with OCI Terraform provider context
• Workspace management: create, plan, apply, destroy Terraform workspaces
• Compartment-aware: browse and select target compartment, with existing OCI resources injected as context
• Plan/Apply/Destroy lifecycle: full Terraform workflow with real-time output tracking
• File management: view generated .tf files, copy, download individually or as bundle
• Inline file editor: click any .tf file to edit in-place with monospace editor, Tab support, and save
• Split-panel terminal: real-time Plan/Apply/Destroy output in a dark terminal panel alongside files/plan/resources
• Multi-file generation: AI generates separate .tf files via // filename: markers (main.tf, variables.tf, outputs.tf, etc.)
• Smart file correction: when fixing errors, model generates only changed files — frontend merges with existing workspace, preserving untouched files
• 14-point validation checklist: system prompt enforces cross-references, CIDRs, security lists, route tables, DRG attachments, RPC peering, HCL syntax, resource type validation, and variable declarations
• Auto-split pipeline (3 layers): frontend + backend auto-split of monolithic HCL files into categorized files + backend deduplication
• HCL syntax fix: automatic expansion of single-line blocks into valid multi-line HCL format
• Resource type validation: SQLite-based validation of ~937 OCI resource types with difflib.get_close_matches suggestions
• Chat history: ChatGPT-style session history with rename/delete, shared between Chat Agent and Terraform Agent
• Resizable split view: chat on top (50%), files/plan/resources + terminal on bottom (50%) with drag-to-resize
• Terraform CLI installed in container (v1.14.7)
• Terraform Resource Reference: auto-generated OCI provider resource catalog (~937 resources) injected into system prompt — built from terraform providers schema -json, stored in SQLite, refreshable via UI
• Official Resource Docs Injection: on-demand fetch of Example Usage + Argument Reference from the official OCI Terraform provider docs — cached in SQLite
• Smart variable resolution: auto-generates terraform.tfvars by scanning declared variables and mapping them to OCI config values
• Multi-region provider management: auto-detects provider aliases and region variables, generates provider.tf with correct region references
• Region safety guard: plan is blocked if the model does not declare variable "region" — prevents accidental provisioning in the wrong region
• Rollback button: when terraform apply fails, a Rollback button appears for terraform destroy with confirmation
• Prompt Generator: dedicated sub-menu for AI-powered prompt generation — curated models, same knowledge pipeline as Terraform Agent, official docs injection, copy & send to Terraform Agent
• Prompt Editor: inline system prompt editor with auto-save (800ms debounce)
• Compact system prompt optimized for OCI Terraform provider best practices (100K max_tokens)

OCI Services

• Service Status tab: auto-detect 6 security services (VSS, Data Safe, Cloud Guard, Bastion, Security Zones, Vault) per tenancy via OCI API with user overrides
• OCI Health tab: real-time Oracle service health from ocistatus.oraclecloud.com — 49 regions, search, geographic filters

OCI Resource Actions

• Start/Stop Compute Instances directly from OCI Account Explorer with one click
• Start/Stop Autonomous Databases from Explorer with confirmation prompt
• Start/Stop DB Systems, MySQL, Container Instances — 5 resource types with operational control
• Update Network Access: add your IP to ADB ACL (whitelisted_ips) directly from Explorer
• ACL display: view current whitelisted IPs for Autonomous Databases in Explorer cards
• Auto-refresh: resource state updates automatically after Start/Stop actions (polling)
• Lifecycle state badges (RUNNING/STOPPED/AVAILABLE) with color indicators
• Actions audited in the audit log

OCI Account Explorer

• KPI stats bar: real-time resource counts per category with tooltip breakdown, cached in SQLite
• Tree-view navigation with resizable side panel (280px default) and drag handle
• 36 resource types across 9 categories:
  • Compute: Instances, Boot Volumes, Instance Pools
  • Networking: VCNs, Subnets, Security Lists, NSGs, Route Tables, NAT/Internet/Service Gateways, Public IPs, Load Balancers
  • Storage: Buckets, Block Volumes, File Systems, Mount Targets
  • Database: Autonomous Databases, DB Systems, MySQL DB Systems
  • Containers: Container Instances, OKE Clusters
  • Serverless: Functions, API Gateways
  • Observability: Alarms, Log Groups, Notification Topics, Events Rules
  • Security: Vaults, DNS Zones, Network Firewalls, Firewall Policies
  • IAM: Users, Groups, Policies, Dynamic Groups
• Enhanced views: expandable cards for VCNs (CIDRs, DNS), Subnets (AD, route table), Load Balancers (listeners, backends), Buckets (size, object count, visibility)
• Multi-region support: select and filter by multiple OCI regions with checkbox selection
• Compartment tree: hierarchical compartment browser with full OCID visibility
• Dead state filtering: automatically hides TERMINATED/DELETED/DELETING resources
• Background count refresh: counts cached in SQLite, refreshed on compartment access without blocking UI
• Security list detail: view ingress/egress rules directly in the explorer
• 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
• 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
• Delete reports: remove completed reports and their associated files
• File browser: files grouped by section within the Reports page, with per-section embedding
• Embed individual files: embed any report file (CSV, TXT, JSON, PDF) into the ADB vector store for RAG enrichment
• Region filtering with multi-select
• Real-time progress tracking with phase-based progress bar
• CIS Engine auto-update: check for new versions from Oracle's GitHub and update with one click (admin only)

LAD A-Team CIS Compliance Report

• Professional compliance report following Oracle Cloud Security Assessment format (cover page, purpose statement, disclaimer, copyright)
• Table of Contents with links to each section and recommendation
• Security Overview: 7 Oracle security pillars (Customer Isolation, Data Encryption, Data Management, etc.)
• OCI Services section: summary table of 6 security services per tenancy + detailed descriptions + Cloud Guard recommendations table
• CIS Assessment Summary: table with Domains / Total Controls / Failed / Passed per section
• CIS Benchmark Recommendation Summary: full table with Item / Description / Status (OK/FAILED)
• Detailed findings: per-recommendation cards with compliance percentage bar, result description, and remediation steps
• RAG-powered remediation: enriched remediation steps from ADB vector store (CISRECOM table) using cosine similarity — filters by exact recommendation number
• Affected resources CSV links: non-compliant findings show a clickable link to download the CSV with affected resource details (JWT auth)
• Back page: Connect with us + copyright
• Download PDF: window.print() with CSS @page A4 formatting
• Download DOCX: standalone DOCX export with Pillow camouflage strip, green header tables, result boxes, code blocks, A4 format
• compliance_data.json: shared data source between HTML and DOCX (identical content)
• Progress bar during generation: shows RAG progress (X/35), percentage, and current recommendation
• ADB connection pre-check: fail fast with 503 if ADB is unreachable before starting generation
• Caching: generated HTML cached to disk; "Regenerar" button clears cache and re-generates
• Collapsible sections: HTML report and compliance report start minimized, expandable on demand

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
• Region-specific scanning: all scan tools accept optional regions parameter to target specific OCI regions
• Session caching: collected data cached per config+regions scope (2-hour TTL)
• Compartment filtering: scan results can be filtered by specific compartment
• Parallelized data collection: base and regional collectors run in parallel (up to 8 workers), 30-minute timeout with 1 automatic retry

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
• Upload .py scripts directly to servers
• Link MCP servers to ADB Vector databases as tools
• Activate/deactivate servers

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 with case-insensitive table validation against ADB user_tables
• Multiple vector tables per ADB: register, edit, toggle active/inactive
• Multi-table RAG search: queries all active tables across all ADB configs, merges results by cosine distance
• Auto-resolve embedding config: automatically uses existing OCI credentials for GenAI embeddings
• Case-insensitive table matching: supports both uppercase and lowercase table names with quoted identifiers

Embeddings & Knowledge Base

• Auto-embed CIS Reports: one-click embedding of all report CSVs — each CSV automatically mapped to its ADB table
• Per-section embedding: embed individual sections with dedicated button per section
• CIS Recommendation tagging: each embedded document includes CIS recommendation number, section, and status
• Auto-detect embedding dimension: detects table dimension (1536/3072) from DDL (even on empty tables) and selects correct model automatically (1536 = small, 3072 = large)
• Purge before re-embed: automatically deletes old data for same tenancy/date before inserting
• Real-time progress: progress bar with current section, global progress, queue of upcoming sections
• Background persistence: embedding continues when navigating away, progress resumes on return
• Text chunking: large CSV rows split into 8000-char chunks with context header (Tenancy, Resource, CIS Recommendation) repeated
• CIS PDF Chunker: segments CIS PDF by recommendation number (X.X Ensure...), target 7000 chars with 500-char overlap, filters TOC/appendix/page headers — 54/54 recommendations with complete Description + Rationale + Remediation
• RAG timeout 60s + retry: increased from 30s with no retry for improved reliability
• Direct SQL fetch: retrieves chunks by metadata recommendationNumber for overlap resolution
• Knowledge Base: upload documents (.txt, .pdf, .csv, .json, .md) or import URLs to populate engineerknowledgebase
• Consult Embeddings: chat-like interface with tenancy selector — queries vector store with CIS number detection for exact matching, smart table skip, source citations
• OCI GenAI Embeddings: uses OpenAI Text Embedding 3 Large/Small via OCI GenAI
• 11 ADB vector tables supported (9 CIS report + 2 knowledge base)

Configuration & Chat Logs

• Persistent activity log per configuration tab (OCI, GenAI, ADB, MCP)
• Chat audit logs: all chat interactions logged with session/message ID, severity, and source
• 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

Export / Import Configuration

• Full config export as JSON: OCI credentials (with private keys), GenAI configs, MCP servers, system prompts, app settings, ADB vector configs
• Import from exported JSON with merge-by-ID (skips existing, prevents duplicates)
• Private keys exported as base64 and restored to disk on import
• Enables full environment migration between machines

Theme System & UI

• Light/Dark mode toggle in the sidebar footer
• Oracle Dark Premium design: deep dark backgrounds (#0D0F12), dark cards (#1A1D24), Oracle Red accent (#C74634)
• Oracle-branded light mode: warm light backgrounds (original theme)
• Theme preference persisted in localStorage across sessions
• All CSS driven by CSS custom properties — zero hardcoded colors
• SVG icon system: 45+ Lucide-based inline SVG icons for cross-platform consistency
• KPI Dashboard: compliance score gauge (SVG semicircular arc with gradient), pass/fail/total KPI cards, donut chart, horizontal bar chart — powered by Recharts
• Animated UI: staggered fade-in, smooth theme transitions, hover effects, shimmer loading states, pulse alerts

OCI CLI Terminal

• Linux-style web terminal for OCI CLI interaction directly from the browser
• Config selector: choose the OCI Config to run commands against
• Tab autocomplete: auto-completes OCI CLI commands and subcommands
• OCID auto-lookup: paste any OCID (60+ resource types) → auto-detects type and runs oci <service> <resource> get
• find by name/IP: search OCI resources by display name or IP address via OCI Search API
• Command history: per-user, navigable with arrow keys
• Help panel: collapsible help with all commands and keyboard shortcuts
• State persistence: terminal output, config selection, and history survive page navigation (Zustand store)
• User isolation: commands execute with user's own OCI config only, history is per-user

User Management

• Sub-menu: Users, My Settings, Oracle IAM
• My Settings: per-user timezone, language preference (pt/en/es), password change (local users only), MFA toggle
• Oracle IAM page: OIDC configuration UI (issuer, client ID/secret, redirect URI, group-to-role mapping, test connection)
• Users list: admin view with role, status, MFA, auth provider badge (OIDC/Local)

Security

• JWT authentication with configurable expiry
• TOTP MFA (Google Authenticator / Authy compatible)
• Oracle IAM OIDC: SSO via Oracle Identity Domains — authorization code flow with PKCE, JWKS signature validation, JIT user provisioning, group-to-role mapping
• Dual auth modes: local only, OIDC only, or both simultaneously
• RBAC with 3 roles: Admin, User, Viewer
• Fernet encryption (AES-128-CBC + HMAC-SHA256) for credentials and sensitive settings
• User isolation: ownership checks on ~70 endpoints, is_global flag for shared resources, private reports, per-user embeddings
• Export sanitization: config export strips private keys, passwords, and OCIDs
• Sensitive settings protection: oidc_*, secret_* keys blocked for non-admin users
• Audit logging for all operations (auth, OIDC, JIT provisioning, resource actions)
• Rate limiting on login and OIDC endpoints (10 attempts / 5 min)
• Per-user timezone and language settings
• Non-root container execution (runuser)

---

Architecture

+--------------------------------------------------------------+
|                       Docker Compose                         |
|                                                              |
|  +-----------------+     +--------------------------------+  |
|  |                 |     |                                |  |
|  |  Nginx          |     |  FastAPI Backend               |  |
|  |  (React SPA)    |---->|  (Python 3.12)                 |  |
|  |  :8080          |     |  8 workers x 10 threads        |  |
|  |                 |     |                                |  |
|  +-----------------+     |  Agents:                       |  |
|                          |   - Chat (RAG + MCP Tools)     |  |
|                          |   - Terraform (Plan/Apply)     |  |
|                          |   - CIS Scanner (12 tools)     |  |
|                          |   - Embedding Pipeline         |  |
|                          |                                |  |
|                          |  Services:                     |  |
|                          |   - OCI SDK --> OCI APIs       |  |
|                          |   - GenAI --> LLM (16 models)  |  |
|                          |   - oracledb --> ADB Vector    |  |
|                          |   - Chromium --> PDF gen       |  |
|                          |   - Pillow --> DOCX gen        |  |
|                          |   - Terraform CLI 1.14.7       |  |
|                          |   - SQLite (agent.db)          |  |
|                          |                                |  |
|                          +--------------------------------+  |
|                                          |                   |
|                              +-----------v------------+      |
|                              |   agent-data volume    |      |
|                              |   /data (SQLite,       |      |
|                              |    reports, configs,   |      |
|                              |    terraform, wallets) |      |
|                              +------------------------+      |
+--------------------------------------------------------------+
                                |
                   +------------v-------------+
                   |   Oracle ADB (external)  |
                   |   11 vector tables       |
                   |   RAG + embeddings       |
                   +--------------------------+

---

Quick Start

Option A — Automated Setup (from OCIR image)

bash distribution/setup.sh

One command: authenticates to OCIR, pulls the image, starts the container. Access http://localhost:8080 — default credentials admin / admin123 (forced password change on first login).

Option B — Development (Docker Compose)

cp .env.example .env
# Edit .env: set APP_SECRET (openssl rand -hex 64)
docker compose up -d --build

Access http://localhost:8080.

Prerequisites

• Docker and Docker Compose
• OCI API Key pair (private .pem key + fingerprint)
• OCI Tenancy OCID, User OCID, Compartment OCID

---

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:

# 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 an Embedding Model (Cohere Embed v4.0 recommended)
4. Upload Wallet ZIP (for mTLS)
5. Test the connection
6. Register vector tables: add the names of existing tables in your ADB. Table names are case-insensitive and validated against ADB. Toggle tables active/inactive to control which are queried during RAG.

GenAI Config is optional — the app auto-resolves embedding credentials from your existing OCI config.

Required ADB Vector Tables

Important

: These tables must be created in your Autonomous Database before using the embedding and RAG features. Without them, the auto-embedding and historical data consultation will not work.

All tables must use the following schema:

CREATE TABLE <table_name> (
    ID        RAW(16),
    TEXT      CLOB,
    METADATA  JSON,
    EMBEDDING VECTOR
);

Run the SQL below to create all 11 required tables:

-- CIS Report tables (auto-populated via "Embed Report")
CREATE TABLE summaryreportcsvvector (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
CREATE TABLE identityandaccess     (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
CREATE TABLE networking            (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
CREATE TABLE computeinstances      (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
CREATE TABLE loggingandmonitoring  (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
CREATE TABLE objectstorage         (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
CREATE TABLE storageblockvolume    (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
CREATE TABLE filestorageservice    (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
CREATE TABLE assetmanagement       (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);

-- Knowledge base tables (populated manually via Embeddings tab)
CREATE TABLE cisrecom              (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
CREATE TABLE engineerknowledgebase (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);

CIS Report Tables — auto-populated when you click "Embed Report":

Table Name	Purpose	Source CSVs
summaryreportcsvvector	CIS report summary — compliance scores per section, total controls passed/failed	cis_summary_report.csv
identityandaccess	IAM findings — users, policies, MFA status, API keys, password policies	cis_Identity_and_Access_Management_*.csv
networking	Network findings — security lists, NSGs, VCNs, open ports, ICMP rules	cis_Networking_*.csv
computeinstances	Compute findings — instances, metadata service, secure boot, encryption	cis_Compute_*.csv
loggingandmonitoring	Logging findings — alarms, events, notifications, flow logs, Cloud Guard	cis_Logging_and_Monitoring_*.csv
objectstorage	Object Storage findings — bucket visibility, encryption, versioning	cis_Storage_Object_Storage_*.csv
storageblockvolume	Block Volume findings — encryption with CMK	cis_Storage_Block_Volumes_*.csv
filestorageservice	File Storage findings — encryption with CMK	cis_Storage_File_Storage_Service_*.csv
assetmanagement	Asset Management findings — compartment usage, resource tagging	cis_Asset_Management_*.csv

Knowledge Base Tables — populated manually via Embeddings tab:

Table Name	Purpose	How to populate
cisrecom	CIS Benchmark official recommendations — remediation steps, rationale, audit procedures per control	Upload CIS PDF in Embeddings tab (auto-chunked by recommendation)
engineerknowledgebase	General knowledge base — blogs, documentation, PDFs, URLs for complementary context	Upload files or import URLs in Embeddings tab

How embedding works: When you click "Embed Report" on a completed CIS report, the system automatically:

1. Maps each CSV file to its corresponding table based on the filename
2. Adds CIS recommendation number, section name, tenancy, and extract date to each document
3. Purges old data for the same tenancy/date before inserting (prevents duplicates)
4. Shows real-time progress with current section and queue

Each embedded document contains structured metadata (tenancy, extract_date, cis_recommendation) enabling precise filtered searches by the Chat Agent and Consult Embeddings.

Step 5 — Embeddings (Optional)

Navigate to the Embeddings tab to populate the vector store:

1. CIS Recommendations: Upload the CIS PDF to populate the cisrecom table with Oracle Cloud security recommendations
2. Knowledge Base: Upload documents (.txt, .pdf, .csv, .json, .md) or paste a URL to import web pages — all content goes to the engineerknowledgebase table
3. From CIS Reports (Reports tab): Click "Embed Report" to auto-embed all findings CSVs into their mapped tables
4. Browse and inspect 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 <group-name> to use generative-ai-family in compartment <compartment-name>
Allow group <group-name> to read all-resources in tenancy
Allow group <group-name> to inspect compartments in tenancy
Allow group <group-name> to inspect autonomous-databases in compartment <compartment-name>
Allow group <group-name> to read virtual-network-family in compartment <compartment-name>
Allow group <group-name> to read instance-family in compartment <compartment-name>
Allow group <group-name> to read objectstorage-namespaces in tenancy
Allow group <group-name> to read buckets in compartment <compartment-name>

---

Project Structure

oci-cis-agent/
├── backend/
│   ├── app.py               # FastAPI application (~10500 lines)
│   ├── cis_reports.py        # Oracle CIS Benchmark checker (6660 lines)
│   ├── mcp_cis_server.py     # MCP server with 12 granular CIS tools
│   ├── gen_tf_reference.py   # OCI Terraform provider resource catalog generator
│   ├── Dockerfile            # Backend image (Python 3.12 + OCI CLI + Terraform + Chromium)
│   ├── requirements.txt
│   └── tests/                # 86 baseline tests (pytest)
├── frontend/
│   ├── src/                  # React 19 SPA (TypeScript, 46 files, ~19500 lines)
│   │   ├── pages/            # 20 page components
│   │   ├── api/              # API client + endpoint modules
│   │   ├── stores/           # Zustand stores (app, auth, terminal)
│   │   ├── hooks/            # Custom hooks (theme, polling)
│   │   └── i18n/             # Internationalization (pt/en/es, 850+ keys)
│   └── dist/                 # Built SPA
├── infra/
│   ├── docker/
│   │   ├── Dockerfile.single # Single container (nginx + backend + supervisord)
│   │   └── Dockerfile.frontend
│   ├── terraform-vm/         # OCI VM deployment (ARM Free Tier, LB+WAF+SSL)
│   ├── scripts/
│   │   ├── push-images.sh    # Build + push to OCIR
│   │   └── ocir-login.py     # Encrypted OCIR credentials helper
│   └── ...
├── distribution/             # Public release package (setup.sh + README + terraform)
├── nginx/
│   └── default.conf
├── docker-compose.yml
├── .env.example
└── 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
GET	/api/auth/oidc/config	Public auth mode (local/oidc/both)
GET	/api/auth/oidc/login	Redirect to Oracle Identity Domains
GET	/api/auth/oidc/callback	OIDC callback (code exchange + JIT provisioning)
POST	/api/auth/oidc/logout	OIDC logout + IdP logout URL
POST	/api/settings/oidc/test	Test OIDC discovery (admin)

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}/compartment-tree	Hierarchical compartment tree
GET	/api/oci/explore/{id}/regions	List subscribed regions
GET	/api/oci/explore/{id}/vcns	List VCNs
GET	/api/oci/explore/{id}/subnets	List Subnets
GET	/api/oci/explore/{id}/security_lists	List Security Lists (with rules)
GET	/api/oci/explore/{id}/nsgs	List Network Security Groups
GET	/api/oci/explore/{id}/route_tables	List Route Tables (with rules)
GET	/api/oci/explore/{id}/nat_gateways	List NAT Gateways
GET	/api/oci/explore/{id}/internet_gateways	List Internet Gateways
GET	/api/oci/explore/{id}/service_gateways	List Service Gateways
GET	/api/oci/explore/{id}/network_firewalls	List Network Firewalls
GET	/api/oci/explore/{id}/network_firewall_policies	List Firewall Policies
GET	/api/oci/explore/{id}/public_ips	List Public IPs
GET	/api/oci/explore/{id}/instances	List Compute Instances
GET	/api/oci/explore/{id}/instance_pools	List Instance Pools
GET	/api/oci/explore/{id}/container_instances	List Container Instances
GET	/api/oci/explore/{id}/databases	List Autonomous Databases
GET	/api/oci/explore/{id}/db_systems	List DB Systems
GET	/api/oci/explore/{id}/mysql_db_systems	List MySQL DB Systems
GET	/api/oci/explore/{id}/buckets	List Object Storage Buckets
GET	/api/oci/explore/{id}/block_volumes	List Block Volumes
GET	/api/oci/explore/{id}/boot_volumes	List Boot Volumes
GET	/api/oci/explore/{id}/file_systems	List File Systems
GET	/api/oci/explore/{id}/mount_targets	List Mount Targets
GET	/api/oci/explore/{id}/oke_clusters	List OKE Clusters
GET	/api/oci/explore/{id}/load_balancers	List Load Balancers
GET	/api/oci/explore/{id}/functions	List Functions
GET	/api/oci/explore/{id}/iam_users	List IAM Users
GET	/api/oci/explore/{id}/iam_groups	List IAM Groups
GET	/api/oci/explore/{id}/iam_policies	List IAM Policies
GET	/api/oci/explore/{id}/iam_dynamic_groups	List Dynamic Groups
GET	/api/oci/explore/{id}/vaults	List Vaults
GET	/api/oci/explore/{id}/dns_zones	List DNS Zones
GET	/api/oci/explore/{id}/api_gateways	List API Gateways
GET	/api/oci/explore/{id}/alarms	List Alarms
GET	/api/oci/explore/{id}/log_groups	List Log Groups
GET	/api/oci/explore/{id}/notification_topics	List Notification Topics
GET	/api/oci/explore/{id}/events_rules	List Events Rules
GET	/api/oci/explore/{id}/counts	Get cached resource counts (instant from SQLite)
POST	/api/oci/explore/{id}/counts/refresh	Refresh all resource counts in background

OCI Services

Method	Endpoint	Description
GET	/api/oci-services/{config_id}	Get service status per tenancy
PUT	/api/oci-services/{config_id}	Update service overrides
GET	/api/oci-health	Oracle Cloud status proxy (49 regions)

OCI Resource Actions

Method	Endpoint	Description
POST	/api/oci/instances/{id}/action	Start/Stop compute instance
POST	/api/oci/autonomous-databases/{id}/action	Start/Stop Autonomous Database
POST	/api/oci/db-systems/{id}/action	Start/Stop DB System
POST	/api/oci/mysql-db-systems/{id}/action	Start/Stop MySQL DB System
POST	/api/oci/container-instances/{id}/action	Start/Stop Container Instance

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)
POST	/api/adb/{id}/tables/check	Validate registered tables against ADB (case-insensitive)
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, report_date)
POST	/api/embeddings/report/{rid}/file/{fid}	Embed individual report file (CSV/TXT/JSON/PDF) into vector store
POST	/api/embeddings/upload	Upload file (.txt/.pdf/.csv/.json/.md) and generate embeddings
POST	/api/embeddings/upload-url	Import URL (web page or PDF), extract text, and generate embeddings
POST	/api/embeddings/consult	Query embeddings via vector search + GenAI (natural language Q&A)
POST	/api/embeddings/{vid}/purge	Purge old embeddings by table + tenancy before re-embedding
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)

Terraform Agent

Method	Endpoint	Description
POST	/api/terraform/chat	Send message to Terraform Agent
GET	/api/terraform/resources	List OCI resources in compartment (for context)
POST	/api/terraform/workspaces	Create Terraform workspace
GET	/api/terraform/workspaces	List user's workspaces
GET	/api/terraform/workspaces/{wid}	Get workspace details
PUT	/api/terraform/workspaces/{wid}/code	Update workspace Terraform code
POST	/api/terraform/workspaces/{wid}/plan	Run terraform plan
POST	/api/terraform/workspaces/{wid}/apply	Run terraform apply
POST	/api/terraform/workspaces/{wid}/destroy	Run terraform destroy
GET	/api/terraform/workspaces/{wid}/status	Poll workspace execution status
GET	/api/terraform/workspaces/{wid}/download	Download workspace .tf files
POST	/api/terraform/workspaces/{wid}/cancel	Cancel running Terraform operation
DELETE	/api/terraform/workspaces/{wid}	Delete workspace
POST	/api/terraform/refresh-reference	Regenerate OCI Terraform resource reference (UI button)
POST	/api/terraform/generate-prompt	Generate structured Terraform prompt via AI (Prompt Generator)

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)
GET	/api/chat/sessions	List chat sessions (history) with agent type filter
GET	/api/chat/sessions/{sid}/messages	Get messages for a session
PUT	/api/chat/sessions/{sid}/title	Rename a chat session
DELETE	/api/chat/{sid}	Delete chat session and messages
POST	/api/reports/run	Execute CIS report
GET	/api/reports	List reports
DELETE	/api/reports/{rid}	Delete report and associated files
GET	/api/reports/{id}/html	View HTML report
GET	/api/reports/{id}/download	Download report
GET	/api/reports/{rid}/summary	Report KPI summary (score, pass/fail, sections)
GET	/api/reports/{rid}/files	List report files by category
GET	/api/reports/{rid}/files/{fid}/download	Download individual report file
GET	/api/reports/{rid}/compliance-report	Serve cached LAD A-Team compliance report HTML
POST	/api/reports/{rid}/compliance-report/generate	Generate compliance report (background, with RAG)
GET	/api/reports/{rid}/compliance-report/status	Check compliance report status (returns progress: current, total, step, rec)
GET	/api/reports/{rid}/compliance-report/docx	Download compliance report as DOCX

User Settings

Method	Endpoint	Description
GET	/api/users/me	Get current user profile (includes auth_provider)
GET	/api/users/me/timezone	Get user timezone
PUT	/api/users/me/timezone	Set user timezone
GET	/api/users/me/language	Get user language preference
PUT	/api/users/me/language	Set user language preference (pt/en/es)
GET	/api/settings/timezone/options	List available timezone options

OCI CLI Terminal

Method	Endpoint	Description
POST	/api/terminal/execute	Execute OCI CLI command
GET	/api/terminal/autocomplete	Tab autocomplete suggestions
POST	/api/terminal/ocid-lookup	OCID auto-lookup (60+ types)
POST	/api/terminal/find	Search resources by name/IP
GET	/api/terminal/history	Get command history (per-user)

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 (16 Chat + 3 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
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
Google	Gemini 2.5 Pro	google.gemini-2.5-pro	GENERIC
Google	Gemini 2.5 Flash	google.gemini-2.5-flash	GENERIC
OpenAI	GPT-5.2	openai.gpt-5.2	GENERIC
OpenAI	GPT-5.1	openai.gpt-5.1	GENERIC
OpenAI	GPT-5 Mini	openai.gpt-5-mini	GENERIC
OpenAI	GPT-4.1 (Default)	openai.gpt-4.1	GENERIC
OpenAI	GPT-4.1 Mini	openai.gpt-4.1-mini	GENERIC
OpenAI	GPT-4o	openai.gpt-4o	GENERIC
OpenAI	o4-mini	openai.o4-mini	GENERIC
OpenAI	o3	openai.o3	GENERIC
xAI	Grok 4	xai.grok-4	GENERIC
xAI	Grok 3	xai.grok-3	GENERIC
xAI	Grok 3 Mini Fast	xai.grok-3-mini-fast	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

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	React 19 SPA (Vite + TypeScript), Oracle Dark Premium theme, Recharts, Zustand, i18n (pt/en/es), rehype-highlight
Auth	JWT + TOTP MFA + RBAC + Oracle IAM OIDC
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
Image Processing	Pillow (DOCX report generation)
Container	Docker Compose, Nginx reverse proxy
MCP	Model Context Protocol SDK (stdio/SSE) with tool discovery + execution
Terraform	Terraform CLI 1.14.7, OCI Provider
CIS Scanner	Oracle CIS Foundations Benchmark 3.0 checker (cis_reports.py)

---

Versioning

Version	Date	Changes
v3.1	2026-04	Oracle IAM OIDC: SSO via Oracle Identity Domains — authorization code flow, JWKS ID token validation (RS256), CSRF protection (state+nonce), JIT user provisioning from OIDC claims, group-to-role mapping (admin/user/viewer), dual auth modes (local/oidc/both), oidc_client_secret encrypted with Fernet, rate-limited OIDC endpoints, IdP logout support. OCI CLI Terminal: Linux-style web terminal with Tab autocomplete, OCID auto-lookup (60+ resource types), find by name/IP via OCI Search API, per-user command history, help panel. User Management: sub-menu (Users, My Settings, Oracle IAM), per-user timezone/language/MFA/password change, auth_provider badge (OIDC/Local) in user list. Spanish i18n: 3 languages (pt/en/es), 850+ i18n keys. Security hardening: Fernet encryption (AES) for credentials (replacing base64), export sanitization (strips private keys/passwords/OCIDs), sensitive settings protection (oidc_*/secret_* blocked for non-admin). User isolation: ownership checks on ~70 endpoints, is_global flag for shared ADB/MCP configs, private reports, per-user embeddings with user_id metadata. State persistence: Terminal and Explorer state survives page navigation via Zustand stores (compartment tree, selected regions, counts, terminal output, history). 175+ API endpoints, 20 pages, ~36,500 lines of code.
v3.0	2026-03	OCI Services page: new menu item with Service Status tab (auto-detect 6 security services — VSS, Data Safe, Cloud Guard, Bastion, Security Zones, Vault — per tenancy via OCI API + user overrides) and OCI Health tab (real-time Oracle service health from ocistatus.oraclecloud.com, 49 regions, search, geo filters). Compliance Report v3.0: OCI Services section with summary table + detailed descriptions + Cloud Guard recommendations, back page (Connect with us + copyright), DOCX download (Pillow camouflage strip, green header tables, result boxes, code blocks, A4 format), compliance_data.json shared between HTML and DOCX, progress bar during RAG generation (X/35, percentage), ADB connection pre-check (fail fast 503). CIS PDF Chunker: segments CIS PDF by recommendation number (X.X Ensure...), target 7000 chars with 500-char overlap, filters TOC/appendix/page headers — 54/54 recommendations with complete Description + Rationale + Remediation. Embedding improvements: auto-detect dimension from DDL (even on empty tables), auto-detect model per dimension (1536=small, 3072=large), RAG timeout 60s + retry (was 30s), direct SQL fetch by metadata recommendationNumber for overlap chunks. Per-user timezone (not global). New API endpoints: OCI Health proxy, OCI Services status/overrides, user timezone CRUD, DOCX download, compliance progress details, timezone options.
v2.8	2026-03	Legacy frontend removed: React SPA now served at root / (no more /app/ prefix), legacy vanilla JS SPA removed. Compliance Report ZIP download: Chromium headless PDF generation (identical to browser print) + CSV findings bundled in ZIP. Compliance generation state persisted server-side: .compliance_generating marker file ensures generation status survives page navigation — spinner auto-resumes on return. RAG remediation enriched: extracts Description, Rationale, Audit, and Remediation sections from CIS vector chunks, combines up to 3 matched chunks. Chat markdown styling: full markdown rendering with syntax highlighting (Catppuccin Mocha theme via rehype-highlight), styled headings, lists, tables, blockquotes, inline/block code. Default model auto-select: Chat Agent auto-selects first GenAI config on page load. Explorer silent polling: no more flickering during start/stop resource actions.
v2.7	2026-03	LAD A-Team CIS Compliance Report: professional Oracle-format compliance report with cover page, TOC, Security Overview (7 pillars), CIS Assessment Summary, detailed findings with compliance % bars, RAG-powered remediation from ADB vector store (CISRECOM table with strict recommendation number filtering), affected resources CSV download links per non-compliant finding (JWT auth via query param). React SPA: 15-page React 19 frontend (TypeScript, Vite, Zustand, 38 source files). i18n: full internationalization with 625 keys (pt/en), language switcher persisted in localStorage. Report management: delete reports endpoint, embed individual report files (CSV/TXT/JSON/PDF) into vector store. Terraform ZIP download: replaced individual file downloads with client-side ZIP generation (pure JS, no external lib). Explorer UX: silent polling during start/stop actions eliminates flickering (resources update in-place without clearing the list). Report sections collapsed by default: HTML report and compliance report iframes start minimized.
v2.6	2026-03	Rename: app renamed to "AI Agent — Infrastructure & Security Engineer". Session Token Auth: OCI session token authentication support (type selector API Key/Session Token, conditional form fields, collapsible credential form, type tags in credentials table, SecurityTokenSigner backend). Terraform Workspaces submenu: sidebar sub-tab listing all workspaces grouped by date with accordion UI, filtered by existing chat sessions (INNER JOIN), actions (plan/apply/destroy/delete/open). Retry on failure: "Reenviar" button on failed messages across Chat Agent, Terraform Agent, and Prompt Generator. Terraform fixes: f2 undefined variable in dedup logic, oci_core_services false positive validation (data sources excluded), S.tfCode reconstruction from S.tfFiles for Re-plan, auto-fix button visible without pre-selected model, DRG attachment rules in system prompt. Resilience: stuck workspace recovery on container restart (planning/applying/destroying reset + lock file cleanup).
v2.5	2026-03	Explorer Expansion: KPI stats bar with per-category resource counts (cached in SQLite explorer_counts_cache, background refresh on compartment access), enhanced views for VCNs/Subnets/Load Balancers/Buckets with expandable cards, start/stop for DB Systems + MySQL + Container Instances (5 resource types total), dead state filtering (TERMINATED/DELETED/DELETING hidden across all 36 endpoints), wider compartment tree (280px), IAM excluded from compartment totals. Prompt Generator Intelligence: same knowledge pipeline as Terraform Agent — auto-detects resource types from user message, fetches official docs (Example Usage + Arguments) from GitHub cached in SQLite, uses compact categorized resource reference. Network Firewall fix: NetworkFirewallPolicySummaryCollection not iterable — added .items accessor for collection objects.
v2.4	2026-03	Terraform Safety & UX: region safety guard (plan blocked if model omits variable "region" — prevents wrong-region provisioning), rollback button on apply failure (manual terraform destroy with "ROLLBACK" confirmation), SSH public key field in OCI configs (auto-injected into terraform.tfvars for compute instances), reasoning_effort uppercase fix for OCI SDK, split-panel layout (terminal right 40%, files/plan/resources below chat 60%), plan button persists after destroy. Terraform tfvars: expanded oci_var_map with ssh_public_key/ssh_authorized_keys auto-mapping from OCI config
v2.3	2026-03	Consult Embeddings: dedicated sub-menu with chat-like interface for natural language Q&A against vector store — queries all active tables via cosine similarity, returns contextual answers with source citations (works with or without GenAI config). Knowledge Base & RAG Enhancements: Knowledge Base (Base de Conhecimento) with file upload + URL import to engineerknowledgebase vector table, CIS Recommendations upload to cisrecom table, URL content extraction (HTML tag/script stripping, remote PDF parsing), auto-resolve embedding config from OCI credentials (no separate GenAI config required), report_date metadata tracking for embedding freshness, purge & re-embed flow for updated reports. ADB Vector Improvements: case-insensitive table matching with quoted identifiers for Oracle ADB, table validation endpoint against user_tables, tables section moved inside edit connection card, case-preserving table registration (removed forced uppercase). Vector search fix: FLOAT32 compatibility for VECTOR_DISTANCE queries, base64-decoded compartment_id for auto-resolved OCI configs. Embeddings tab cleanup: removed delete buttons, simplified to read-only view, updated descriptions. Dependencies: added PyPDF2 for PDF text extraction
v2.2	2026-03	UI Modernization (Phases 1B-5): Oracle Dark Premium theme, 45+ Lucide SVG icons replacing all emojis, KPI dashboard with compliance gauge + Recharts donut/bar charts, report summary API endpoint, Phase 5 animations (staggered fade-in, smooth theme transitions, hover effects) — animations scoped to tab switch only (no flickering on re-render). Terraform Intelligence: official resource docs injection from registry.terraform.io (Example Usage + Argument Reference, on-demand fetch + SQLite cache), smart tfvars auto-generation from declared variables, multi-region provider management with var.region support, RPC anti-cycle rule, system prompt auto-sync to DB, 60-min polling timeout for long-running applies. ADB fix: wallet_password always passed for thin mode mTLS (fixes DPY-6005). CIS_EMBEDDINGS default removed from ADB config
v2.1	2026-03	Terraform Agent (AI-powered IaC generation with plan/apply/destroy lifecycle, workspace management, Terraform CLI in container, inline file editor, split-panel terminal, multi-file generation via // filename: markers, smart file correction with merge-based updates, 14-point validation checklist, 100K max_tokens), 3-layer auto-split pipeline (frontend + backend monolithic HCL splitting into categorized files + backend deduplication), HCL syntax auto-fix (single-line blocks expanded to multi-line), SQLite-based resource type validation (~937 types with difflib suggestions for invalid types), Terraform Resource Reference (auto-generated OCI provider catalog from terraform providers schema -json, generated at startup to survive volume mounts, stored in SQLite, refreshable via menu button), compact system prompt for Terraform agent, ChatGPT-style chat history for both Chat Agent and Terraform Agent (rename/delete sessions), OCI Resource Actions (start/stop instances and Autonomous DBs from OCI Account Explorer), OCI Explorer expanded to 40+ resource types across 8 categories with tree-view navigation and resizable panels, compartment filtering for MCP CIS scans, chat sidebar with model parameters, chat audit logs, collection error tracking in MCP server, tool timeout increased to 30min with auto-retry, memory compaction tuned (6K threshold, 20 recent messages), model catalog trimmed from 69 to 15 curated models, improved GenAI response extraction with fallback for empty responses, fixed layout overflow (no page scroll), provider alias detection with brace-matching parser, multi-region Terraform support
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

cd backend
pip install -r requirements.txt
DATA_DIR=./data uvicorn app:app --reload --port 8000

Run with Docker Compose

docker compose up -d --build
docker compose logs -f backend

Run Tests

cd backend
pip install pytest httpx pytest-asyncio
python -m pytest tests/ -v

86 baseline tests covering auth, CRUD, settings, chat, terraform, reports, terminal, and user isolation.

Build & Push OCIR Image

OCIR_REGION=us-ashburn-1 OCIR_NAMESPACE=idi1o0a010nx ./infra/scripts/push-images.sh

Rebuild After Changes

docker compose up -d --build backend && docker compose restart frontend

---

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 (DPY-6005: cannot connect): Ensure the wallet ZIP contains tnsnames.ora and ewallet.pem. The DSN must match a service name in tnsnames.ora (e.g., myatp_high). If using an auto-login wallet without a custom password, leave the wallet password field empty — the app automatically passes an empty string for wallet_password which is required by python-oracledb thin mode even for auto-login wallets.

Container won't start:

docker compose logs backend

---

License

MIT

---

_{Built for Oracle Cloud Infrastructure security compliance}