446 lines
16 KiB
Markdown
446 lines
16 KiB
Markdown
<p align="center">
|
|
<img src="logo.svg" alt="OCI CIS AI Agent" width="96" height="96">
|
|
</p>
|
|
|
|
<h1 align="center">OCI CIS AI Agent</h1>
|
|
|
|
<p align="center">
|
|
<strong>Oracle Cloud Infrastructure — CIS Foundations Benchmark 3.0 — AI-Powered Compliance Platform</strong>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<img src="https://img.shields.io/badge/version-1.1-C74634?style=flat-square" alt="Version">
|
|
<img src="https://img.shields.io/badge/python-3.12-3776AB?style=flat-square" alt="Python">
|
|
<img src="https://img.shields.io/badge/FastAPI-0.115-009688?style=flat-square" alt="FastAPI">
|
|
<img src="https://img.shields.io/badge/OCI-GenAI-C74634?style=flat-square" alt="OCI">
|
|
<img src="https://img.shields.io/badge/docker-compose-2496ED?style=flat-square" alt="Docker">
|
|
<img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License">
|
|
</p>
|
|
|
|
---
|
|
|
|
## 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 `.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`)
|
|
|
|
### 🔐 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 `.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 (Optional)
|
|
|
|
For persistent vector storage of CIS findings and embeddings:
|
|
|
|
1. Add DSN (TNS name from tnsnames.ora, e.g., `myatp_high`)
|
|
2. Set credentials (username/password)
|
|
3. Upload Wallet ZIP (for mTLS)
|
|
4. 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 |
|
|
| Google | Gemini 2.5 Pro | GENERIC |
|
|
| Google | 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
|
|
|
|
```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
|
|
|
|
---
|
|
|
|
<p align="center">
|
|
<sub>Built with ❤️ for Oracle Cloud Infrastructure security compliance</sub>
|
|
</p> |