16 KiB
16 KiB
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, infrastructure exploration, and vector-based knowledge storage into a single, containerized solution with Oracle Cloud's official light theme.
Features
🤖 AI Chat Agent
- OCI Generative AI integration via official SDK (
oci.generative_ai_inference) - 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
.pyscripts 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-oracledbThin mode (no Oracle Client needed)- Wallet ZIP upload and automatic extraction
- Connection testing
- Configurable embeddings table name (default:
CIS_EMBEDDINGS)
🔐 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 │ │
│ │ └─────────────┘ │ │
│ │ │ │
│ │ SQLite (agent.db) │ │
│ └──────────────────────────────┘ │
│ │ │
│ agent-data volume │
└─────────────────────────────────────────────────────────────┘
Quick Start
Prerequisites
- Docker and Docker Compose
- OCI API Key pair (private
.pemkey + 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:
- Select the OCI Credential created in Step 1
- Choose a model from the catalog
- Select the GenAI region (must have Generative AI service available)
- Set the Compartment OCID (where GenAI policies are configured)
- Adjust parameters (temperature, max_tokens, etc.)
- 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 (Optional)
For persistent vector storage of CIS findings and embeddings:
- Add DSN (TNS name from tnsnames.ora, e.g.,
myatp_high) - Set credentials (username/password)
- Upload Wallet ZIP (for mTLS)
- Test the connection
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 (933 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 (419 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 |
| GET | /api/adb/configs |
List ADB connections |
| POST | /api/adb/{id}/upload-wallet |
Upload wallet ZIP |
| POST | /api/adb/test/{id} |
Test ADB connection |
| DELETE | /api/adb/configs/{id} |
Delete ADB config |
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 |
| Gemini 2.5 Pro | GENERIC | |
| Gemini 2.5 Flash | GENERIC | |
| xAI | Grok 4 | GENERIC |
| xAI | Grok 3 | GENERIC |
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.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