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

• 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
• 12 models across 4 providers: Cohere (Command A/R/R+), Meta (Llama 4/3.3/3.2/3.1), Google (Gemini 2.5), xAI (Grok 3/4)
• 16 OCI regions supported with auto-generated endpoints
• Full parameter control: temperature, max_tokens, top_p, top_k, frequency/presence penalty
• 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

• Automated CIS OCI Foundations Benchmark 3.0 execution
• 54 security controls across 8 domains (IAM, Networking, Compute, Logging, Storage, etc.)
• HTML and JSON report output
• Optional MCP server selection per report execution
• Region filtering

🔌 MCP Server Registry

• Register multiple MCP servers (stdio, SSE, Python module)
• 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
• Configurable embeddings table name (default: CIS_EMBEDDINGS)
• Link to GenAI config for embedding generation via OCI GenAI

🧬 Embeddings Management

• Dedicated tab for managing vector embeddings
• Embed CIS Reports: automatically chunk reports by section (IAM, Networking, Compute, etc.) and generate embeddings
• Upload text files: upload .txt files, automatically chunked by paragraphs
• OCI GenAI Embeddings: uses Cohere Embed models (v3.0, multilingual, light) via OCI GenAI embed_text API
• Browse, inspect and delete individual embeddings from the ADB vector store
• 4 embedding models supported: Cohere Embed English/Multilingual v3.0 (1024d), Light variants (384d)

🔐 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      │    │
│                          │  ├─────────────┤              │    │
│                          │  │ MCP Servers  │──▶ Tools    │    │
│                          │  ├─────────────┤              │    │
│                          │  │ 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

git clone https://github.com/nogueiragustavo/oci-cis-agent.git
cd oci-cis-agent
cp .env.example .env

Edit .env:

APP_SECRET=your-very-long-random-secret-string-here-at-least-64-chars
JWT_EXPIRY_HOURS=12
PORT=8080

2. Build & Run

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

Click Testar to validate the connection.

Step 2 — GenAI Model

Navigate to GenAI Config tab:

1. Select the OCI Credential created in Step 1
2. Choose a model from the catalog
3. Select the GenAI region (must have Generative AI service available)
4. Set the Compartment OCID (where GenAI policies are configured)
5. Adjust parameters (temperature, max_tokens, etc.)
6. 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:

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.

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 v3.0 recommended)
5. Upload Wallet ZIP (for mTLS)
6. Test the connection
7. Click Create Table to initialize the embeddings table in ADB

Step 5 — Embeddings (Optional)

Navigate to the Embeddings tab to populate the vector store:

1. From CIS Reports: Select a completed report and generate embeddings (1 per section)
2. From text files: Upload .txt files for automatic chunking and embedding
3. Browse and manage existing embeddings

Once embeddings exist, the chat automatically uses RAG — it queries the ADB vector store 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 (~1100 lines)
│   ├── cis_runner.py        # CIS Benchmark check executor
│   ├── Dockerfile           # Python 3.12 + OCI CLI
│   └── requirements.txt     # Dependencies
├── frontend/
│   └── index.html           # SPA with Oracle Cloud theme (~620 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
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
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}/toggle	Activate/deactivate
POST	/api/mcp/servers/{id}/upload	Upload script file
PUT	/api/mcp/servers/{id}/link-adb	Link to ADB Vector
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
POST	/api/adb/{id}/upload-wallet	Upload wallet ZIP
POST	/api/adb/test/{id}	Test ADB connection
POST	/api/adb/{id}/ensure-table	Create embeddings table in ADB
DELETE	/api/adb/configs/{id}	Delete ADB config

Embeddings

Method	Endpoint	Description
POST	/api/embeddings/report/{rid}	Generate embeddings from CIS report (chunked by section)
POST	/api/embeddings/upload	Upload .txt file and generate embeddings (chunked by paragraphs)
GET	/api/embeddings/{vid}/list	List embeddings in ADB (paginated)
DELETE	/api/embeddings/{vid}/{doc_id}	Delete individual embedding

Chat & Reports

Method	Endpoint	Description
POST	/api/chat	Send message (with optional GenAI model)
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

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

Provider	Model	API Format
Cohere	Command A (03-2025)	COHERE
Cohere	Command R+ (08-2024)	COHERE
Cohere	Command R (08-2024)	COHERE
Meta	Llama 4 Maverick	GENERIC
Meta	Llama 4 Scout	GENERIC
Meta	Llama 3.3 70B Instruct	GENERIC
Meta	Llama 3.2 90B Vision	GENERIC
Meta	Llama 3.1 405B Instruct	GENERIC
Google	Gemini 2.5 Pro	GENERIC
Google	Gemini 2.5 Flash	GENERIC
xAI	Grok 4	GENERIC
xAI	Grok 3	GENERIC

Embedding Models

Provider	Model	Dimensions
Cohere	Embed English v3.0	1024
Cohere	Embed Multilingual v3.0	1024
Cohere	Embed English Light v3.0	384
Cohere	Embed Multilingual Light 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 (stdio/SSE/module)

---

Versioning

Version	Date	Changes
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

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

Rebuild After Changes

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.

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:

docker compose logs backend

---

License

MIT

---

_{Built with ❤️ for Oracle Cloud Infrastructure security compliance}