From 3b5b0c7c2ab2555dd013300201ed3e014b5de6b6 Mon Sep 17 00:00:00 2001 From: nogueiraguh Date: Fri, 27 Feb 2026 19:47:16 -0300 Subject: [PATCH] docs: add comprehensive README for v1.1 --- README.md | 535 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 377 insertions(+), 158 deletions(-) diff --git a/README.md b/README.md index 37eb6f1..a2f7d4d 100644 --- a/README.md +++ b/README.md @@ -1,218 +1,437 @@ # 🛡️ OCI CIS AI Agent -**AI Agent - Infrastructure & Security Engineer** +**Oracle Cloud Infrastructure — CIS Foundations Benchmark 3.0 — AI-Powered Compliance Platform** -Plataforma web Dockerizada para auditoria de segurança OCI baseada no **CIS Foundations Benchmark 3.0**, com interface de chat AI Agent, geração de relatórios HTML/JSON, gerenciamento de configurações OCI, integração com bancos vetoriais e controle de acesso RBAC com MFA. +![Version](https://img.shields.io/badge/version-1.1-C74634?style=flat-square) +![Python](https://img.shields.io/badge/python-3.12-3776AB?style=flat-square) +![FastAPI](https://img.shields.io/badge/FastAPI-0.115-009688?style=flat-square) +![OCI](https://img.shields.io/badge/OCI-GenAI-C74634?style=flat-square) +![Docker](https://img.shields.io/badge/docker-compose-2496ED?style=flat-square) +![License](https://img.shields.io/badge/license-MIT-green?style=flat-square) --- -## 📋 Funcionalidades +## Overview -### Interface Web (4 abas principais + 3 admin) -| Aba | Descrição | -|-----|-----------| -| **💬 Chat Agent** | Interface de chat com AI Agent para consultas sobre CIS, status do sistema e comandos | -| **📊 Report** | Visualização de relatórios HTML de compliance com iframe integrado | -| **📁 Downloads** | Lista de relatórios com filtro, download em JSON/HTML | -| **☁️ Config OCI** | Gerenciamento de credenciais OCI (tenancy, OCID, chaves PEM, região) | -| **🔗 Vector DB** | Configuração de conexão com bancos vetoriais (ChromaDB, Pinecone, Weaviate, PGVector, Qdrant, Milvus, Oracle 23ai) | -| **👥 Usuários** | *(admin)* Gerenciamento de usuários, criação, roles, ativação/desativação | -| **🔐 MFA** | Configuração de autenticação TOTP (Google Authenticator / Authy) | -| **📋 Audit Log** | *(admin)* Log de auditoria de todas as ações do sistema | +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. -### Segurança -- **Autenticação JWT** com expiração configurável -- **MFA/TOTP** compatível com Google Authenticator e Authy -- **3 roles**: `admin`, `user`, `viewer` -- **Audit log** completo de todas as ações -- **Senhas com PBKDF2-SHA256** (100k iterações + salt) - -### Roles e Permissões -| Role | Permissões | -|------|-----------| -| `admin` | Acesso total: usuários, configs, relatórios, MFA, audit, instalar OCI CLI | -| `user` | Criar configs OCI/VectorDB, executar relatórios, usar chat | -| `viewer` | Visualizar relatórios, downloads, usar chat (somente leitura) | +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. --- -## 🚀 Quick Start +## Features -### Pré-requisitos -- Docker e Docker Compose instalados +### 🤖 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 -### 1. Clone e configure +### 🔍 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 -```bash -git clone -cd oci-agent +### 📊 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 -# Crie o arquivo de ambiente -cp .env.example .env -# Edite o .env e defina um APP_SECRET forte +### 🔌 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 │ +└─────────────────────────────────────────────────────────────┘ ``` -### 2. Suba os containers +--- + +## 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. Acesse +### 3. Access -Abra o navegador em **http://localhost:8080** +Open `http://localhost:8080` -**Credenciais padrão:** -- Usuário: `admin` -- Senha: `admin123` +Default credentials: +- **Username:** `admin` +- **Password:** `admin123` -> ⚠️ **Altere a senha padrão imediatamente após o primeiro login!** +> ⚠️ Change the default password immediately after first login. --- -## 📐 Arquitetura +## Configuration Guide -``` -┌──────────────┐ ┌──────────────┐ ┌──────────────┐ -│ Browser │────▶│ Nginx │────▶│ FastAPI │ -│ (Frontend) │ :80 │ (Frontend) │ │ (Backend) │ -│ SPA HTML │ │ Reverse │ │ Auth/API │ -└──────────────┘ │ Proxy /api │ │ SQLite DB │ - └──────────────┘ └──────┬───────┘ - │ - ┌───────▼───────┐ - │ /data vol │ - │ ├─ agent.db │ - │ ├─ oci_configs│ - │ ├─ reports │ - └───────────────┘ -``` +### Step 1 — OCI Credentials -### Containers -| Container | Imagem | Porta | Função | -|-----------|--------|-------|--------| -| `oci-agent-frontend` | `nginx:alpine` | 8080→80 | Serve o SPA + reverse proxy para API | -| `oci-agent-backend` | `python:3.12-slim` | 8000 | FastAPI com auth, RBAC, lógica de negócio | +Navigate to **OCI Credentials** tab and add: -### Volume persistente -- `agent-data` → `/data` no backend (SQLite, configs OCI, relatórios) +| 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. -## 🔌 Integração com MCP Server +### Step 2 — GenAI Model -O sistema foi projetado para ser conectado ao **MCP Server FastMCP** criado anteriormente. Para integrar: +Navigate to **GenAI Config** tab: -### 1. Monte o MCP server no container +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` -No `docker-compose.yml`, adicione ao serviço `backend`: +For **dedicated endpoints**, switch Serving Type to `DEDICATED` and provide the endpoint ID. -```yaml -volumes: - - agent-data:/data - - ./mcp_server/server.py:/app/mcp_server.py:ro # MCP server -``` - -### 2. Substitua o runner stub - -Edite `backend/cis_runner.py` para importar e usar as tools do MCP server: +The GenAI connection follows Oracle's official SDK pattern: ```python -from mcp_server import connect, collect_all_data, run_cis_checks, export_report_json +# 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 ``` -### 3. Ou conecte via SSE/stdio +### Step 3 — MCP Servers (Optional) -O MCP server pode ser exposto como serviço separado e o backend se conecta via protocolo MCP padrão. +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 --- -## 🗄️ Integração Vector DB +## OCI IAM Policies -A aba **Vector DB** permite configurar conexão com: +The following policies are required in your tenancy: -| Banco | Porta Padrão | Uso | -|-------|-------------|-----| -| ChromaDB | 8000 | Embeddings locais | -| Pinecone | 443 | SaaS vetorial | -| Weaviate | 8080 | Vetorial + busca híbrida | -| PGVector | 5432 | PostgreSQL com extensão vetorial | -| Qdrant | 6333 | Vetorial open-source | -| Milvus | 19530 | Vetorial distribuído | -| Oracle 23ai | 1521 | Oracle Database com AI Vector Search | - -Use para armazenar e consultar findings de compliance, embeddings de documentação CIS, e contexto para o AI Agent. - ---- - -## 📊 Relatórios CIS - -O sistema gera relatórios compatíveis com o **CIS OCI Foundations Benchmark 3.0** contendo: - -- **54 controles** em 8 domínios -- Relatório HTML estilizado (similar ao Oracle Cloud Security Assessment) -- Relatório JSON para integração programática -- Resumo por domínio com contagem de PASS/FAIL -- Detalhamento de cada controle - ---- - -## 🔧 Configuração Avançada - -### Variáveis de Ambiente - -| Variável | Padrão | Descrição | -|----------|--------|-----------| -| `APP_SECRET` | (gerado) | Chave secreta para JWT | -| `JWT_EXPIRY_HOURS` | 12 | Expiração do token JWT | -| `PORT` | 8080 | Porta do frontend | -| `DATA_DIR` | /data | Diretório de dados persistentes | - -### Instalar OCI CLI no container - -Na interface como admin, vá em **Config OCI** → **Instalar OCI CLI no Container**. - -Ou manualmente: -```bash -docker exec -it oci-agent-backend pip install oci-cli +``` +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 ``` -### Backup dos dados +--- + +## 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 +├── .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 -docker cp oci-agent-backend:/data ./backup-data +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 ``` --- -## 📝 API Endpoints +## Troubleshooting -| Método | Endpoint | Auth | Descrição | -|--------|----------|------|-----------| -| POST | `/api/auth/login` | - | Login (retorna JWT) | -| POST | `/api/auth/logout` | ✅ | Logout | -| POST | `/api/auth/register` | admin | Criar usuário | -| POST | `/api/auth/change-password` | ✅ | Alterar senha | -| POST | `/api/mfa/setup` | ✅ | Gerar secret MFA | -| POST | `/api/mfa/verify` | ✅ | Ativar MFA | -| GET | `/api/users` | admin | Listar usuários | -| GET | `/api/users/me` | ✅ | Dados do usuário atual | -| PUT | `/api/users/{id}` | admin | Atualizar usuário | -| POST | `/api/oci/config` | user+ | Salvar config OCI (multipart) | -| GET | `/api/oci/configs` | ✅ | Listar configs | -| POST | `/api/oci/test/{id}` | user+ | Testar conexão OCI | -| POST | `/api/reports/run` | user+ | Executar relatório CIS | -| GET | `/api/reports` | ✅ | Listar relatórios | -| GET | `/api/reports/{id}/html` | ✅ | Relatório HTML | -| GET | `/api/reports/{id}/download` | ✅ | Download relatório | -| POST | `/api/vectordb/config` | user+ | Salvar config Vector DB | -| GET | `/api/vectordb/configs` | ✅ | Listar configs VDB | -| POST | `/api/chat` | ✅ | Chat com AI Agent | -| GET | `/api/audit-log` | admin | Log de auditoria | -| GET | `/api/health` | - | Health check | +**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 +``` --- -## 📄 Licença +## License -Projeto interno. Todos os direitos reservados. +MIT + +--- + +

+ Built with ❤️ for Oracle Cloud Infrastructure security compliance +

\ No newline at end of file