GustavoNogueira/A-Team-Security-Infra-Agent-Engineer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: complete README with all deployment options

Browse Source
This commit is contained in:
nogueiraguh
2026-04-02 16:53:13 -03:00
parent fa7df3ac75
commit 83602019a0
1 changed files with 251 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

355
README.md
View File

@@ -22,87 +22,180 @@
A-Team Security 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. A-Team Security 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 a **React 19 SPA** (TypeScript, Vite), **Oracle Dark Premium** theme (light/dark modes), **KPI dashboard** with compliance gauge, **i18n** (pt/en/es), and **Recharts** visualizations. The platform combines security compliance scanning, AI-powered chat with **RAG (Retrieval-Augmented Generation)**, infrastructure exploration, and vector-based knowledge storage into a single Docker image with a **React 19 SPA**, **Oracle Dark Premium** theme (light/dark modes), **KPI dashboard** with compliance gauge, **i18n** (pt/en/es), and **Recharts** visualizations.
Distributed as pre-built Docker containers via **Oracle Container Registry (OCIR)** — no source code required. ---
## Container Image
The platform is distributed as a single Docker image on **Oracle Container Registry (OCIR)**:
```
us-ashburn-1.ocir.io/idi1o0a010nx/oci-cis-agent:latest
```
- **Multi-architecture**: `linux/amd64` + `linux/arm64`
- **Single container**: nginx (frontend) + FastAPI (backend) + supervisord
- **Port**: `8080`
- **Volume**: `/data` (persistent storage — database, configs, reports, wallets)
--- ---
## Features ## Features
### AI Chat Agent with RAG + MCP Tool Use ### AI Chat Agent with RAG + MCP Tool Use
- **OCI Generative AI** integration via official SDK - **OCI Generative AI** integration via official SDK (`oci.generative_ai_inference`)
- **RAG (Retrieval-Augmented Generation)**: queries ADB vector store for relevant context before generating responses - **RAG (Retrieval-Augmented Generation)**: queries ADB vector store for relevant context before generating responses — single ADB connection per search, smart table skip, CIS recommendation text filter for exact matching, follow-up context enrichment
- **MCP Tool Use (Function Calling)**: GenAI models call tools from registered MCP servers during chat - **Source hierarchy**: findings tables > cisrecom (official remediation) > engineerknowledgebase (complementary) — temporal awareness with extract dates, tenancy isolation via JSON_VALUE filter
- **Chat Memory Compaction**: automatic summarization when conversation exceeds token limit - **MCP Tool Use (Function Calling)**: GenAI models call tools from registered MCP servers during chat — supports Cohere and Generic (OpenAI-style) function calling with automatic tool execution loop (max 5 iterations)
- **Multimodal Chat**: upload images, PDFs, and text files for AI analysis - **Chat Memory Compaction**: automatic summarization of older messages when conversation exceeds ~6000 tokens — keeps 20 recent messages intact
- 16 chat models + 3 embedding models across 5 providers: **Meta** (Llama 4), **Google** (Gemini 2.5), **OpenAI** (GPT-5.2/5.1/4.1/4o, o3/o4-mini), **xAI** (Grok 4/3) - **Chat Sidebar**: collapsible panel with model parameters (temperature, max_tokens, top_p, top_k, penalties)
- **Multimodal Chat**: upload images (PNG/JPG/GIF/WebP), PDFs, and text files for AI analysis — up to 5 files per message via OCI GenAI `ImageContent` and `DocumentContent`
- **Async Background Processing**: chat requests return immediately, GenAI + MCP tools process in background via dedicated thread pool (10 threads), frontend polls for results
- 16 chat models + 3 embedding models across 5 providers: **Meta** (Llama 4), **Google** (Gemini 2.5), **OpenAI** (GPT-5.2/5.1/5 Mini/4.1/4o, o3/o4-mini), **xAI** (Grok 4/3)
- Full parameter control: temperature, max_tokens, top_p, top_k, frequency/presence penalty (when supported)
- Toggle MCP tools on/off per chat session
- Conversation history with session management
- On-Demand and Dedicated serving modes
### Terraform Agent (IaC) ### Terraform Agent (IaC)
- **AI-powered Terraform code generation** for OCI infrastructure provisioning - **AI-powered Terraform code generation** for OCI infrastructure provisioning
- Dedicated chat interface with OCI Terraform provider context
- **Workspace management**: create, plan, apply, destroy Terraform workspaces - **Workspace management**: create, plan, apply, destroy Terraform workspaces
- **14-point validation checklist**: cross-references, CIDRs, security lists, HCL syntax - **Compartment-aware**: browse and select target compartment, with existing OCI resources injected as context
- **Resource type validation**: ~937 OCI resource types with close-match suggestions - **Plan/Apply/Destroy lifecycle**: full Terraform workflow with real-time output tracking
- **File management**: view generated `.tf` files, copy, download individually or as bundle
- **Inline file editor**: click any `.tf` file to edit in-place with monospace editor, Tab support, and save
- **Split-panel terminal**: real-time Plan/Apply/Destroy output in a dark terminal panel alongside files/plan/resources
- **Multi-file generation**: AI generates separate `.tf` files via `// filename:` markers (main.tf, variables.tf, outputs.tf, etc.)
- **Smart file correction**: when fixing errors, model generates only changed files — frontend merges with existing workspace, preserving untouched files
- **14-point validation checklist**: system prompt enforces cross-references, CIDRs, security lists, route tables, DRG attachments, RPC peering, HCL syntax, resource type validation, and variable declarations
- **Resource type validation**: SQLite-based validation of ~937 OCI resource types with `difflib.get_close_matches` suggestions
- **Terraform Resource Reference**: auto-generated OCI provider resource catalog (~937 resources) injected into system prompt
- **Official Resource Docs Injection**: on-demand fetch of Example Usage + Argument Reference from the official OCI Terraform provider docs — cached in SQLite
- **Prompt Generator**: dedicated sub-menu for AI-powered prompt generation - **Prompt Generator**: dedicated sub-menu for AI-powered prompt generation
- Terraform CLI installed in container (v1.14.7)
### OCI Account Explorer ### OCI Account Explorer
- **36 resource types** across 9 categories (Compute, Networking, Storage, Database, Containers, Serverless, Observability, Security, IAM) - **KPI stats bar**: real-time resource counts per category with tooltip breakdown
- **KPI stats bar**: real-time resource counts per category - **36 resource types** across 9 categories:
- **Compute**: Instances, Boot Volumes, Instance Pools
- **Networking**: VCNs, Subnets, Security Lists, NSGs, Route Tables, NAT/Internet/Service Gateways, Public IPs, Load Balancers
- **Storage**: Buckets, Block Volumes, File Systems, Mount Targets
- **Database**: Autonomous Databases, DB Systems, MySQL DB Systems
- **Containers**: Container Instances, OKE Clusters
- **Serverless**: Functions, API Gateways
- **Observability**: Alarms, Log Groups, Notification Topics, Events Rules
- **Security**: Vaults, DNS Zones, Network Firewalls, Firewall Policies
- **IAM**: Users, Groups, Policies, Dynamic Groups
- **Start/Stop** Compute Instances, Autonomous Databases, DB Systems, MySQL, Container Instances - **Start/Stop** Compute Instances, Autonomous Databases, DB Systems, MySQL, Container Instances
- **Tree-view navigation** with resizable compartment panel - **Tree-view navigation** with resizable compartment panel
- **Multi-region support** with checkbox selection - **Multi-region support** with checkbox selection
### OCI CLI Terminal ### OCI CLI Terminal
- **Linux-style web terminal** for OCI CLI interaction - **Linux-style web terminal** for OCI CLI interaction directly from the browser
- **Tab autocomplete**, **OCID auto-lookup** (60+ resource types), **find by name/IP** - **Tab autocomplete**: auto-completes OCI CLI commands and subcommands
- **OCID auto-lookup**: paste any OCID (60+ resource types) — auto-detects type and runs the appropriate `get` command
- **`find` by name/IP**: search OCI resources by display name or IP address via OCI Search API
- Per-user command history, state persists across navigation - Per-user command history, state persists across navigation
### OCI Services ### OCI Services
- **Service Status**: auto-detect 6 security services per tenancy via OCI API - **Service Status**: auto-detect 6 security services (VSS, Data Safe, Cloud Guard, Bastion, Security Zones, Vault) per tenancy via OCI API with user overrides
- **OCI Health**: real-time Oracle service health from 49 regions - **OCI Health**: real-time Oracle service health from ocistatus.oraclecloud.com — 49 regions, search, geographic filters
### CIS Compliance Reports ### CIS Compliance Reports (Oracle Official Engine)
- Oracle's official CIS engine (48 CIS + 11 OBP checks) - Powered by Oracle's official `cis_reports.py` (48 CIS + 11 OBP checks)
- **Multiple formats**: HTML, CSV, JSON, XLSX - **Granular execution parameters**: CIS Level (1/2), OCI Best Practices, Raw Data, OCID Redaction
- **Professional Compliance Report**: Oracle-format PDF/DOCX with RAG-powered remediation - **Multiple output formats**: HTML summary, CSV per section/finding, JSON summary, optional XLSX
- **Report history**: full execution history with status, tenancy filter, and download actions
- Region filtering with multi-select
- Real-time progress tracking with phase-based progress bar - Real-time progress tracking with phase-based progress bar
- **CIS Engine auto-update**: check for new versions from Oracle's GitHub and update with one click
### Built-in CIS MCP Server ### LAD A-Team CIS Compliance Report
- **12 granular tools** for per-section scanning (IAM, Networking, Compute, Logging, Storage, Assets) - **Professional compliance report** following Oracle Cloud Security Assessment format (cover page, purpose statement, disclaimer, copyright)
- **Parallelized data collection** with session caching - **Table of Contents** with links to each section and recommendation
- **Security Overview**: 7 Oracle security pillars
- **OCI Services section**: summary table of 6 security services per tenancy + detailed descriptions + Cloud Guard recommendations table
- **CIS Assessment Summary**: Domains / Total Controls / Failed / Passed per section
- **Detailed findings**: per-recommendation cards with compliance percentage bar, result description, and remediation steps
- **RAG-powered remediation**: enriched remediation steps from ADB vector store
- **Download PDF** and **Download DOCX** with professional formatting
- **Progress bar during generation**: shows RAG progress, percentage, and current recommendation
### Built-in CIS MCP Server (Granular Per-Section)
- **Auto-registered** CIS Compliance Scanner MCP server — available out of the box
- **12 granular tools** instead of monolithic full-tenancy scan
- **Per-section data collection**: each scan tool collects only the OCI data needed for that section
- **Region-specific scanning**: all scan tools accept optional `regions` parameter
- **Session caching**: collected data cached per config+regions scope (2-hour TTL)
- **Parallelized data collection**: base and regional collectors run in parallel (up to 8 workers)
### MCP Server Registry + Tool Discovery
- Register multiple MCP servers (stdio, SSE, Python module)
- **Automatic tool discovery**: connect to MCP servers and discover available tools
- **Chat Agent integration**: discovered tools are automatically available as GenAI function calls
- Upload `.py` scripts directly to servers
- **Link MCP servers to ADB Vector** databases as tools
### Autonomous Database Vector Storage
- Oracle Autonomous Database connection with **mTLS Wallet** authentication
- `python-oracledb` Thin mode (no Oracle Client needed)
- **Multiple vector tables per ADB**: register, edit, toggle active/inactive
- **Multi-table RAG search**: queries all active tables across all ADB configs
- **Auto-resolve embedding config**: automatically uses existing OCI credentials for GenAI embeddings
### Embeddings & Knowledge Base ### Embeddings & Knowledge Base
- **CIS PDF Chunker**: segments by recommendation, 7000-char chunks with overlap - **Auto-embed CIS Reports**: one-click embedding of all report CSVs
- **Auto-detect embedding dimension** and model selection - **CIS PDF Chunker**: segments CIS PDF by recommendation number, target 7000 chars with 500-char overlap
- **Knowledge Base**: upload documents or import URLs - **Auto-detect embedding dimension**: detects table dimension from DDL and selects correct model automatically
- **Consult Embeddings**: chat-like interface for vector Q&A - **Knowledge Base**: upload documents (`.txt`, `.pdf`, `.csv`, `.json`, `.md`) or **import URLs**
- **Consult Embeddings**: chat-like interface with tenancy selector — queries vector store with CIS number detection
- 11 ADB vector tables supported (9 CIS report + 2 knowledge base)
### User Management
- **Sub-menu**: Users, My Settings, Oracle IAM
- **My Settings**: per-user timezone, language preference (pt/en/es), password change (local users only), MFA toggle
- **Oracle IAM page**: OIDC configuration UI (issuer, client ID/secret, redirect URI, group-to-role mapping, test connection)
- **Users list**: admin view with role, status, MFA, auth provider badge (OIDC/Local)
### Security ### Security
- **JWT + TOTP MFA** (Google Authenticator / Authy compatible) - **JWT authentication** with configurable expiry
- **Oracle IAM OIDC**: SSO via Oracle Identity Domains with JIT provisioning - **TOTP MFA** (Google Authenticator / Authy compatible)
- **Oracle IAM OIDC**: SSO via Oracle Identity Domains — authorization code flow, JWKS signature validation, JIT user provisioning, group-to-role mapping
- **Dual auth modes**: local only, OIDC only, or both simultaneously
- **RBAC** with 3 roles: Admin, User, Viewer - **RBAC** with 3 roles: Admin, User, Viewer
- **Fernet encryption** (AES) for credentials and sensitive settings - **Fernet encryption** (AES-128-CBC + HMAC-SHA256) for credentials and sensitive settings
- **User isolation**: ownership checks, private reports, per-user embeddings - **User isolation**: ownership checks on ~70 endpoints, `is_global` flag for shared resources, private reports, per-user embeddings
- **Force password change** on first login - **Force password change** on first login (random password generated at startup)
- Rate limiting, audit logging, non-root container execution - Audit logging for all operations
- Rate limiting on login and OIDC endpoints (10 attempts / 5 min)
- Non-root container execution
### Theme & UI ### Theme & UI
- **Light/Dark mode** with Oracle Dark Premium design - **Light/Dark mode** with Oracle Dark Premium design
- **KPI Dashboard**: compliance gauge, pass/fail cards, donut chart, bar chart - **KPI Dashboard**: compliance score gauge, pass/fail cards, donut chart, bar chart — powered by Recharts
- **20 pages**, code splitting, Zustand state persistence across navigation
- **i18n**: Portuguese, English, Spanish (850+ keys) - **i18n**: Portuguese, English, Spanish (850+ keys)
- **20 pages**, code splitting, Zustand state persistence
--- ---
## Deployment Options ## Deployment
The platform is distributed as a single Docker image available on **Oracle Container Registry (OCIR)**: ### Prerequisites
``` - Docker installed
us-ashburn-1.ocir.io/idi1o0a010nx/oci-cis-agent:latest - Access to the OCI Container Registry (OCIR)
- OCI API Key pair (private `.pem` key + fingerprint) for application configuration
### OCIR Authentication
```bash
docker login us-ashburn-1.ocir.io
``` ```
Multi-architecture: `linux/amd64` + `linux/arm64` - **Username:** `<namespace>/oracleidentitycloudservice/<email>`
- **Password:** Auth Token (generate in OCI Console > Profile > Auth Tokens)
--- ---
@@ -111,10 +204,6 @@ Multi-architecture: `linux/amd64` + `linux/arm64`
Run on any machine with Docker installed (Linux, macOS, Windows). Run on any machine with Docker installed (Linux, macOS, Windows).
```bash ```bash
# 1. Login to OCIR
docker login us-ashburn-1.ocir.io
# 2. Run
docker run -d \ docker run -d \
--name oci-cis-agent \ --name oci-cis-agent \
-p 8080:8080 \ -p 8080:8080 \
@@ -123,73 +212,38 @@ docker run -d \
-e TZ=America/Sao_Paulo \ -e TZ=America/Sao_Paulo \
--restart unless-stopped \ --restart unless-stopped \
us-ashburn-1.ocir.io/idi1o0a010nx/oci-cis-agent:latest us-ashburn-1.ocir.io/idi1o0a010nx/oci-cis-agent:latest
# 3. Access: http://localhost:8080
docker logs oci-cis-agent | grep "password"
``` ```
Access: `http://localhost:8080`
--- ---
### Option 2 — OCI Compute Instance (Terraform) ### Option 2 — OCI Compute Instance (Terraform)
Production deployment on Oracle Cloud with Load Balancer, WAF, SSL, and persistent storage. Automated production deployment on Oracle Cloud with Load Balancer, WAF, and SSL.
**Architecture:**
```
+--------------------------------------------------------------+
| Oracle Cloud |
| |
| +-----------------+ +--------------------------------+ |
| | | | | |
| | WAF Policy | | Private Subnet | |
| | (OWASP rules) | | | |
| +-----------------+ | +---------------------------+ | |
| | | | Compute Instance | | |
| +-----------------+ | | (ARM, Free Tier eligible) | | |
| | | | | | | |
| | Load Balancer |---->| | oci-cis-agent container | | |
| | (HTTPS / 443) | | | Block Volume (/data) | | |
| | Public Subnet | | | | | |
| | | | +---------------------------+ | |
| +-----------------+ +--------------------------------+ |
| |
+--------------------------------------------------------------+
```
**Setup:**
```bash ```bash
cd terraform cd terraform
cp terraform.tfvars.example terraform.tfvars cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with OCI credentials # Edit terraform.tfvars with OCI credentials
```
**Deploy:**
```bash
terraform init terraform init
terraform plan terraform plan
terraform apply terraform apply
``` ```
**Resources Created:** **Resources provisioned:**
| Resource | Description | | Resource | Description |
|----------|-------------| |----------|-------------|
| VCN | 10.0.0.0/16 with public/private subnets, gateways, security lists | | VCN | 10.0.0.0/16 with public/private subnets, gateways, security lists |
| Compute | VM.Standard.A1.Flex — 2 OCPU, 16GB RAM (ARM, Free Tier eligible) | | Compute | VM.Standard.A1.Flex — 2 OCPU, 16GB RAM (ARM, Free Tier eligible) |
| Block Volume | 50GB persistent storage for application data | | Block Volume | 50GB persistent storage for application data |
| Load Balancer | Flexible 10-100 Mbps with SSL (self-signed or Let's Encrypt) | | Load Balancer | Flexible 10-100 Mbps with SSL |
| WAF | OWASP protection — XSS, SQL injection, path traversal + rate limiting | | WAF | OWASP protection — XSS, SQL injection, path traversal + rate limiting |
| DNS | OCI DNS Zone + A record (conditional — when domain is configured) | | DNS | OCI DNS Zone + A record (conditional — when domain is configured) |
**Outputs:** Access: `https://<load_balancer_ip>` (from `terraform output app_url`)
```bash
terraform output load_balancer_ip # Public IP address
terraform output app_url # Application URL
```
--- ---
@@ -213,7 +267,12 @@ oci container-instances container-instance create \
} }
}]' \ }]' \
--vnics '[{"subnetId": "<SUBNET_OCID>"}]' \ --vnics '[{"subnetId": "<SUBNET_OCID>"}]' \
--image-pull-secrets '[{"registryEndpoint": "us-ashburn-1.ocir.io", "secretType": "BASIC", "username": "<OCIR_USER>", "password": "<AUTH_TOKEN>"}]' --image-pull-secrets '[{
"registryEndpoint": "us-ashburn-1.ocir.io",
"secretType": "BASIC",
"username": "<OCIR_USER>",
"password": "<AUTH_TOKEN>"
}]'
``` ```
--- ---
@@ -223,7 +282,6 @@ oci container-instances container-instance create \
Deploy on Oracle Kubernetes Engine or any Kubernetes cluster. Deploy on Oracle Kubernetes Engine or any Kubernetes cluster.
```yaml ```yaml
# Minimal deployment
apiVersion: apps/v1 apiVersion: apps/v1
kind: Deployment kind: Deployment
metadata: metadata:
@@ -310,38 +368,95 @@ Navigate to **OCI Credentials** tab and add:
| Region | `sa-saopaulo-1`, `us-ashburn-1`, etc. | | Region | `sa-saopaulo-1`, `us-ashburn-1`, etc. |
| Compartment OCID | `ocid1.compartment.oc1..xxxxx` | | Compartment OCID | `ocid1.compartment.oc1..xxxxx` |
| Private Key | `.pem` file | | Private Key | `.pem` file |
| Key Passphrase | *(optional)* Only required if the private key is encrypted |
Click **Test** to validate the connection. Click **Test** to validate the connection.
### Step 2 — GenAI Model ### Step 2 — GenAI Model
Navigate to **GenAI Config** tab:
1. Select the **OCI Credential** created in Step 1 1. Select the **OCI Credential** created in Step 1
2. Choose a **model** from the catalog (16 models across 5 providers) 2. Choose a **model** from the catalog (16 models across 5 providers)
3. Adjust parameters (temperature, max_tokens, etc.) 3. Adjust the **GenAI region** if needed
4. Adjust parameters (temperature, max_tokens, etc.)
### Step 3 — ADB Vector + RAG (Optional) For **dedicated endpoints**, switch Serving Type to `DEDICATED` and provide the endpoint ID.
For persistent vector storage and RAG-powered chat: ### Step 3 — MCP Servers (Optional)
1. Add DSN (from tnsnames.ora) Register MCP servers for extended task execution and **Chat Agent tool use**:
2. Set credentials and upload Wallet ZIP
3. Select an **Embedding Model**
4. Register vector tables
### Step 4 — MCP Servers (Optional)
Register MCP servers for extended AI task execution:
| Type | Use Case | | Type | Use Case |
|------|----------| |------|----------|
| `stdio` | Local Python scripts | | `stdio` | Local Python scripts (e.g., CIS check runner) |
| `SSE` | Remote HTTP servers | | `SSE` | Remote HTTP servers |
| `module` | Upload `.py` files directly | | `module` | Upload `.py` files directly |
**Tool Discovery**: After registering a server, click **"Discover Tools"** to automatically discover available tools via MCP protocol. Discovered tools are automatically available as **function calls** in the Chat Agent.
### 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 an **Embedding Model** (Cohere Embed v4.0 recommended)
4. Upload Wallet ZIP (for mTLS)
5. Test the connection
6. **Register vector tables**: add the names of existing tables in your ADB
> GenAI Config is optional — the app auto-resolves embedding credentials from your existing OCI config.
#### Required ADB Vector Tables
All tables must use the following schema:
```sql
CREATE TABLE <table_name> (
ID RAW(16),
TEXT CLOB,
METADATA JSON,
EMBEDDING VECTOR
);
```
Run the SQL below to create all 11 required tables:
```sql
-- CIS Report tables (auto-populated via "Embed Report")
CREATE TABLE summaryreportcsvvector (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
CREATE TABLE identityandaccess (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
CREATE TABLE networking (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
CREATE TABLE computeinstances (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
CREATE TABLE loggingandmonitoring (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
CREATE TABLE objectstorage (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
CREATE TABLE storageblockvolume (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
CREATE TABLE filestorageservice (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
CREATE TABLE assetmanagement (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
-- Knowledge base tables (populated manually via Embeddings tab)
CREATE TABLE cisrecom (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
CREATE TABLE engineerknowledgebase (ID RAW(16), TEXT CLOB, METADATA JSON, EMBEDDING VECTOR);
```
### Step 5 — Embeddings (Optional)
Navigate to the **Embeddings** tab to populate the vector store:
1. **CIS Recommendations**: Upload the CIS PDF to populate the `cisrecom` table
2. **Knowledge Base**: Upload documents or paste a URL to import web pages
3. **From CIS Reports**: Click "Embed Report" to auto-embed all findings CSVs
4. Browse and inspect embeddings per table
Once embeddings exist, the **chat automatically uses RAG**.
--- ---
## OCI IAM Policies ## 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 use generative-ai-family in compartment <compartment-name>
Allow group <group-name> to read all-resources in tenancy Allow group <group-name> to read all-resources in tenancy
@@ -355,15 +470,44 @@ Allow group <group-name> to read buckets in compartment <compartment-name>
--- ---
## Supported GenAI Models (16 Chat + 3 Embedding)
### Chat Models
| Provider | Model | Model ID |
|----------|-------|----------|
| Meta | Llama 4 Maverick | `meta.llama-4-maverick-17b-128e-instruct-fp8` |
| Meta | Llama 4 Scout | `meta.llama-4-scout-17b-16e-instruct` |
| Google | Gemini 2.5 Pro | `google.gemini-2.5-pro` |
| Google | Gemini 2.5 Flash | `google.gemini-2.5-flash` |
| OpenAI | GPT-5.2 | `openai.gpt-5.2` |
| OpenAI | GPT-5.1 | `openai.gpt-5.1` |
| OpenAI | GPT-5 Mini | `openai.gpt-5-mini` |
| OpenAI | **GPT-4.1 (Default)** | `openai.gpt-4.1` |
| OpenAI | GPT-4.1 Mini | `openai.gpt-4.1-mini` |
| OpenAI | GPT-4o | `openai.gpt-4o` |
| OpenAI | o4-mini | `openai.o4-mini` |
| OpenAI | o3 | `openai.o3` |
| xAI | Grok 4 | `xai.grok-4` |
| xAI | Grok 3 | `xai.grok-3` |
| xAI | Grok 3 Mini Fast | `xai.grok-3-mini-fast` |
### Embedding Models
| Provider | Model | Dimensions |
|----------|-------|------------|
| Cohere | Embed v4.0 (Multimodal) | 1536 |
| OpenAI | Text Embedding 3 Large | 3072 |
| OpenAI | Text Embedding 3 Small | 1536 |
---
## Environment Variables ## Environment Variables
| Variable | Required | Default | Description | | Variable | Required | Default | Description |
|----------|----------|---------|-------------| |----------|----------|---------|-------------|
| `OCIR_REGION` | Yes | — | OCI region for container registry | | `APP_SECRET` | **Yes** | — | 64-byte hex key for JWT/encryption (`openssl rand -hex 64`) |
| `OCIR_NAMESPACE` | Yes | — | OCIR tenancy namespace |
| `APP_SECRET` | Yes | — | 64-byte hex key for JWT/encryption (`openssl rand -hex 64`) |
| `JWT_EXPIRY_HOURS` | No | `12` | Token expiry in hours | | `JWT_EXPIRY_HOURS` | No | `12` | Token expiry in hours |
| `PORT` | No | `8080` | Frontend port |
| `CORS_ORIGINS` | No | — | Allowed origins (comma-separated) | | `CORS_ORIGINS` | No | — | Allowed origins (comma-separated) |
| `TZ` | No | `America/Sao_Paulo` | Timezone | | `TZ` | No | `America/Sao_Paulo` | Timezone |
@@ -372,7 +516,7 @@ Allow group <group-name> to read buckets in compartment <compartment-name>
## Troubleshooting ## Troubleshooting
**Cannot pull images from OCIR:** **Cannot pull images from OCIR:**
Verify your `docker login` credentials and that the OCIR repositories exist in your namespace. Verify your `docker login` credentials and that the OCIR repository exists in your namespace.
**Backend health check fails:** **Backend health check fails:**
Check logs: `docker logs oci-cis-agent`. Ensure `APP_SECRET` is set. Check logs: `docker logs oci-cis-agent`. Ensure `APP_SECRET` is set.
@@ -383,6 +527,9 @@ Ensure the wallet ZIP contains `tnsnames.ora` and `ewallet.pem`. The DSN must ma
**GenAI returns 401/403:** **GenAI returns 401/403:**
Verify the IAM policy `Allow group ... to use generative-ai-family in compartment ...` exists. Verify the IAM policy `Allow group ... to use generative-ai-family in compartment ...` exists.
**OCI CLI test hangs with passphrase prompt:**
If your private key is encrypted, provide the passphrase in the **Key Passphrase** field when saving the credential.
--- ---
## License ## License