GustavoNogueira/A-Team-Security-Infra-Agent-Engineer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
83602019a0976a23bd026f9b249ce470378a2b5e
A-Team-Security-Infra-Agent…/README.md
nogueiraguh 83602019a0 docs: complete README with all deployment options
2026-04-02 16:53:13 -03:00

23 KiB
Raw Blame History

A-Team Security — Infrastructure & Security Agent Engineer

A-Team Security — Infrastructure & Security Agent Engineer

Oracle Cloud Infrastructure — CIS Foundations Benchmark 3.0 — AI-Powered Compliance Platform

Version OCI Docker Terraform License

Overview

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 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.

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

AI Chat Agent with RAG + MCP Tool Use

  • 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 — single ADB connection per search, smart table skip, CIS recommendation text filter for exact matching, follow-up context enrichment
  • Source hierarchy: findings tables > cisrecom (official remediation) > engineerknowledgebase (complementary) — temporal awareness with extract dates, tenancy isolation via JSON_VALUE filter
  • 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)
  • Chat Memory Compaction: automatic summarization of older messages when conversation exceeds ~6000 tokens — keeps 20 recent messages intact
  • 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)

  • 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
  • Compartment-aware: browse and select target compartment, with existing OCI resources injected as context
  • 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
  • Terraform CLI installed in container (v1.14.7)

OCI Account Explorer

  • KPI stats bar: real-time resource counts per category with tooltip breakdown
  • 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
  • Tree-view navigation with resizable compartment panel
  • Multi-region support with checkbox selection

OCI CLI Terminal

  • Linux-style web terminal for OCI CLI interaction directly from the browser
  • 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

OCI Services

  • 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 ocistatus.oraclecloud.com — 49 regions, search, geographic filters

CIS Compliance Reports (Oracle Official Engine)

  • Powered by Oracle's official cis_reports.py (48 CIS + 11 OBP checks)
  • Granular execution parameters: CIS Level (1/2), OCI Best Practices, Raw Data, OCID Redaction
  • 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
  • CIS Engine auto-update: check for new versions from Oracle's GitHub and update with one click

LAD A-Team CIS Compliance Report

  • Professional compliance report following Oracle Cloud Security Assessment format (cover page, purpose statement, disclaimer, copyright)
  • 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

  • Auto-embed CIS Reports: one-click embedding of all report CSVs
  • CIS PDF Chunker: segments CIS PDF by recommendation number, target 7000 chars with 500-char overlap
  • Auto-detect embedding dimension: detects table dimension from DDL and selects correct model automatically
  • 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

  • JWT authentication with configurable expiry
  • 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
  • Fernet encryption (AES-128-CBC + HMAC-SHA256) for credentials and sensitive settings
  • User isolation: ownership checks on ~70 endpoints, is_global flag for shared resources, private reports, per-user embeddings
  • Force password change on first login (random password generated at startup)
  • Audit logging for all operations
  • Rate limiting on login and OIDC endpoints (10 attempts / 5 min)
  • Non-root container execution

Theme & UI

  • Light/Dark mode with Oracle Dark Premium design
  • 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)

Deployment

Prerequisites

  • Docker installed
  • Access to the OCI Container Registry (OCIR)
  • OCI API Key pair (private .pem key + fingerprint) for application configuration

OCIR Authentication

docker login us-ashburn-1.ocir.io
  • Username: <namespace>/oracleidentitycloudservice/<email>
  • Password: Auth Token (generate in OCI Console > Profile > Auth Tokens)

Option 1 — Docker (any machine)

Run on any machine with Docker installed (Linux, macOS, Windows).

docker run -d \
  --name oci-cis-agent \
  -p 8080:8080 \
  -v agent-data:/data \
  -e APP_SECRET=$(openssl rand -hex 64) \
  -e TZ=America/Sao_Paulo \
  --restart unless-stopped \
  us-ashburn-1.ocir.io/idi1o0a010nx/oci-cis-agent:latest

Access: http://localhost:8080

Option 2 — OCI Compute Instance (Terraform)

Automated production deployment on Oracle Cloud with Load Balancer, WAF, and SSL.

cd terraform
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with OCI credentials

terraform init
terraform plan
terraform apply

Resources provisioned:

Resource Description
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)
Block Volume 50GB persistent storage for application data
Load Balancer Flexible 10-100 Mbps with SSL
WAF OWASP protection — XSS, SQL injection, path traversal + rate limiting
DNS OCI DNS Zone + A record (conditional — when domain is configured)

Access: https://<load_balancer_ip> (from terraform output app_url)

Option 3 — OCI Container Instances

Run as a serverless container on OCI without managing VMs.

oci container-instances container-instance create \
  --compartment-id <COMPARTMENT_OCID> \
  --display-name "oci-cis-agent" \
  --availability-domain <AD> \
  --shape "CI.Standard.E4.Flex" \
  --shape-config '{"ocpus": 2, "memoryInGBs": 16}' \
  --containers '[{
    "imageUrl": "us-ashburn-1.ocir.io/idi1o0a010nx/oci-cis-agent:latest",
    "displayName": "agent",
    "environmentVariables": {
      "APP_SECRET": "<YOUR_SECRET>",
      "TZ": "America/Sao_Paulo"
    }
  }]' \
  --vnics '[{"subnetId": "<SUBNET_OCID>"}]' \
  --image-pull-secrets '[{
    "registryEndpoint": "us-ashburn-1.ocir.io",
    "secretType": "BASIC",
    "username": "<OCIR_USER>",
    "password": "<AUTH_TOKEN>"
  }]'

Option 4 — Kubernetes (OKE / any K8s cluster)

Deploy on Oracle Kubernetes Engine or any Kubernetes cluster.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: oci-cis-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: oci-cis-agent
  template:
    metadata:
      labels:
        app: oci-cis-agent
    spec:
      containers:
      - name: agent
        image: us-ashburn-1.ocir.io/idi1o0a010nx/oci-cis-agent:latest
        ports:
        - containerPort: 8080
        env:
        - name: APP_SECRET
          valueFrom:
            secretKeyRef:
              name: agent-secret
              key: app-secret
        - name: TZ
          value: "America/Sao_Paulo"
        volumeMounts:
        - name: data
          mountPath: /data
        resources:
          requests:
            memory: "2Gi"
          limits:
            memory: "4Gi"
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: agent-data
      imagePullSecrets:
      - name: ocir-credentials
---
apiVersion: v1
kind: Service
metadata:
  name: oci-cis-agent
spec:
  type: LoadBalancer
  ports:
  - port: 443
    targetPort: 8080
  selector:
    app: oci-cis-agent

First Login

After any deployment option, check the container logs for the initial admin password:

docker logs oci-cis-agent | grep "password"
# or
kubectl logs deployment/oci-cis-agent | grep "password"

You will be prompted to change the password on 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
Key Passphrase (optional) Only required if the private key is encrypted

Click Test 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 (16 models across 5 providers)
  3. Adjust the GenAI region if needed
  4. Adjust parameters (temperature, max_tokens, etc.)

For dedicated endpoints, switch Serving Type to DEDICATED and provide the endpoint ID.

Step 3 — MCP Servers (Optional)

Register MCP servers for extended task execution and Chat Agent tool use:

Type Use Case
stdio Local Python scripts (e.g., CIS check runner)
SSE Remote HTTP servers
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:

CREATE TABLE <table_name> (
    ID        RAW(16),
    TEXT      CLOB,
    METADATA  JSON,
    EMBEDDING VECTOR
);

Run the SQL below to create all 11 required tables:

-- 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

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>

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

Variable Required Default Description
APP_SECRET Yes — 64-byte hex key for JWT/encryption (openssl rand -hex 64)
JWT_EXPIRY_HOURS No 12 Token expiry in hours
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 repository exists in your namespace.

Backend health check fails: Check logs: docker logs oci-cis-agent. Ensure APP_SECRET is set.

ADB connection fails (DPY-6005): Ensure the wallet ZIP contains tnsnames.ora and ewallet.pem. The DSN must match a service name in tnsnames.ora.

GenAI returns 401/403: 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

MIT

Built for Oracle Cloud Infrastructure security compliance by LAD A-Team

Reference in New Issue View Git Blame Copy Permalink