feat: distribution package v1.0 — OCIR-based deployment without source code
- distribution/: public release package (docker-compose + terraform VM + README v1.0) - docker-compose.yml pulls pre-built images from OCIR (no build, no source code) - terraform/: VM stack (ARM Free Tier, LB+WAF+SSL, conditional DNS/Let's Encrypt) - Removed terraform-oke/ and k8s/ from git (private, .gitignore)
This commit is contained in:
nogueiraguh
233
distribution/README.md
Normal file
233
distribution/README.md
Normal file
@@ -0,0 +1,233 @@
|
||||
<p align="center">
|
||||
<img src="logo.svg" alt="AI Agent" width="96" height="96">
|
||||
</p>
|
||||
|
||||
<h1 align="center">AI Agent — Infrastructure & Security Engineer</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.0-C74634?style=flat-square" alt="Version">
|
||||
<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/terraform-7B42BC?style=flat-square" alt="Terraform">
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
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 **MCP (Model Context Protocol)** for extensible task execution.
|
||||
|
||||
The platform runs as pre-built Docker containers — no source code required.
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
- **AI Chat Agent** with RAG (Retrieval-Augmented Generation) + MCP Tool Use
|
||||
- **Terraform Agent** for AI-powered IaC generation (plan/apply/destroy)
|
||||
- **OCI Account Explorer** — 36 resource types, KPI dashboard, start/stop actions
|
||||
- **OCI CLI Terminal** — web terminal with Tab autocomplete, OCID auto-lookup
|
||||
- **CIS Compliance Reports** — 48 CIS + 11 OBP checks, PDF/DOCX export
|
||||
- **Compliance Report** — professional Oracle-format assessment with RAG remediation
|
||||
- **OCI Services Status** — auto-detect security services + OCI Health (49 regions)
|
||||
- **Embeddings & Knowledge Base** — CIS PDF chunker, ADB vector store
|
||||
- **Oracle IAM OIDC** — SSO via Oracle Identity Domains
|
||||
- **Security** — JWT + TOTP MFA + RBAC (3 roles) + Fernet encryption + WAF
|
||||
- **i18n** — Portuguese, English, Spanish
|
||||
|
||||
---
|
||||
|
||||
## Quick Start (Docker Compose)
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Docker and Docker Compose
|
||||
- Access to the OCI Container Registry (OCIR) with pull credentials
|
||||
|
||||
### 1. Configure
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Edit `.env`:
|
||||
```env
|
||||
OCIR_REGION=us-ashburn-1
|
||||
OCIR_NAMESPACE=your_namespace
|
||||
APP_SECRET=<generate with: openssl rand -hex 64>
|
||||
```
|
||||
|
||||
### 2. Login to OCIR
|
||||
|
||||
```bash
|
||||
docker login ${OCIR_REGION}.ocir.io
|
||||
```
|
||||
|
||||
Username: `<namespace>/<username>` (or `<namespace>/oracleidentitycloudservice/<email>`)
|
||||
Password: Auth Token (generate in OCI Console > Profile > Auth Tokens)
|
||||
|
||||
### 3. Run
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### 4. Access
|
||||
|
||||
Open `http://localhost:8080`
|
||||
|
||||
The initial admin password is generated automatically and displayed in the backend logs:
|
||||
|
||||
```bash
|
||||
docker compose logs backend | grep "password"
|
||||
```
|
||||
|
||||
> You will be prompted to change the password on first login.
|
||||
|
||||
---
|
||||
|
||||
## Deploy on OCI (Terraform)
|
||||
|
||||
For production deployment on Oracle Cloud Infrastructure with Load Balancer, WAF, and SSL.
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
Internet --> WAF --> Load Balancer (HTTPS 443)
|
||||
|
|
||||
Private Subnet
|
||||
|
|
||||
Compute Instance (ARM, Free Tier eligible)
|
||||
+-- Backend container (FastAPI)
|
||||
+-- Frontend container (nginx)
|
||||
+-- Block Volume (/data)
|
||||
```
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
cd terraform
|
||||
cp terraform.tfvars.example terraform.tfvars
|
||||
```
|
||||
|
||||
Edit `terraform.tfvars` with your OCI credentials and configuration.
|
||||
|
||||
### Deploy
|
||||
|
||||
```bash
|
||||
terraform init
|
||||
terraform plan
|
||||
terraform apply
|
||||
```
|
||||
|
||||
### Resources Created
|
||||
|
||||
| Resource | Description |
|
||||
|----------|-------------|
|
||||
| VCN | Virtual Cloud Network with public/private subnets |
|
||||
| Compute | VM.Standard.A1.Flex (ARM, Free Tier eligible) |
|
||||
| Block Volume | 50GB persistent storage for /data |
|
||||
| Load Balancer | Flexible 10-100 Mbps with SSL |
|
||||
| WAF | OWASP protection (XSS, SQLi, path traversal) |
|
||||
| OCIR | 2 private container repositories |
|
||||
| DNS | Conditional — OCI DNS Zone + A record (when domain configured) |
|
||||
|
||||
### Outputs
|
||||
|
||||
After `terraform apply`:
|
||||
|
||||
```bash
|
||||
terraform output load_balancer_ip # Public IP
|
||||
terraform output app_url # https://<IP>
|
||||
terraform output ocir_backend_url # OCIR image URL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration Guide
|
||||
|
||||
### Step 1 — OCI Credentials
|
||||
|
||||
Navigate to **OCI Credentials** and add your tenancy details:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| Tenancy Name | Friendly name |
|
||||
| OCID Tenancy | `ocid1.tenancy.oc1..xxxxx` |
|
||||
| OCID User | `ocid1.user.oc1..xxxxx` |
|
||||
| Fingerprint | `aa:bb:cc:dd:...` |
|
||||
| Region | `us-ashburn-1` |
|
||||
| Private Key | `.pem` file |
|
||||
|
||||
### Step 2 — GenAI Model
|
||||
|
||||
Select an OCI credential, choose a model from the catalog, and adjust parameters.
|
||||
|
||||
### Step 3 — ADB Vector (Optional)
|
||||
|
||||
For RAG-powered chat, configure an Autonomous Database with vector tables.
|
||||
|
||||
### Step 4 — MCP Servers (Optional)
|
||||
|
||||
Register MCP servers for extended tool use in the Chat Agent.
|
||||
|
||||
---
|
||||
|
||||
## OCI IAM Policies
|
||||
|
||||
```
|
||||
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>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|----------|----------|---------|-------------|
|
||||
| `OCIR_REGION` | Yes | — | OCI region (e.g., `us-ashburn-1`) |
|
||||
| `OCIR_NAMESPACE` | Yes | — | OCIR namespace |
|
||||
| `APP_SECRET` | Yes | — | 64-byte hex key for JWT/encryption |
|
||||
| `JWT_EXPIRY_HOURS` | No | `12` | Token expiry |
|
||||
| `PORT` | No | `8080` | Frontend port |
|
||||
| `CORS_ORIGINS` | No | — | Allowed origins (comma-separated) |
|
||||
| `TZ` | No | `America/Sao_Paulo` | Timezone |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Cannot pull images from OCIR:**
|
||||
Verify your `docker login` credentials and that the OCIR repositories exist in your namespace.
|
||||
|
||||
**Backend health check fails:**
|
||||
Check logs: `docker compose logs backend`. Ensure `APP_SECRET` is set.
|
||||
|
||||
**ADB connection fails:**
|
||||
Ensure the wallet ZIP is uploaded and the DSN matches a service in `tnsnames.ora`.
|
||||
|
||||
**GenAI returns 401/403:**
|
||||
Verify the IAM policy for `generative-ai-family` exists for your user/group.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
---
|
||||
|
||||
<p align="center">
|
||||
<sub>Built for Oracle Cloud Infrastructure security compliance</sub>
|
||||
</p>
|
||||
Reference in New Issue
Block a user