docs: add comprehensive README for v1.1

2026-02-27 19:47:16 -03:00
parent c759d0f06d
commit 3b5b0c7c2a
1 changed files with 377 additions and 158 deletions
--- 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 <seu-repo>
-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 <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>
 ```

-### 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
+
+---
+
+<p align="center">
+  <sub>Built with ❤️ for Oracle Cloud Infrastructure security compliance</sub>
+</p>