OCI CIS AI Agent

OCI CIS AI Agent

Oracle Cloud Infrastructure β€” CIS Foundations Benchmark 3.0 β€” AI-Powered Compliance Platform

Version Python FastAPI OCI Docker License

--- ## 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 ```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 | 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: ```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: | 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 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 (~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 ```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. **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