[FEATURE] RAG-powered AI insights layer with Azure security skill embeddings

[Vishnu2707]

What to build

Implement a RAG (Retrieval Augmented Generation)
powered AI insights layer that grounds OpenShield's
AI responses in validated Azure security knowledge
rather than generic LLM output.

This is the feature that separates OpenShield from
every other free CSPM tool. Instead of the AI
guessing at remediation, it retrieves structured
practitioner workflows and answers from grounded,
accurate security knowledge.

---

Background reading

Before starting read these:

1. The AI provider abstraction layer already merged
   in api/services/ai_provider.py — this is what
   you will call to get completions

2. This open source skill library which we will
   cherry pick Azure cloud security skills from:
   github.com/mukul975/Anthropic-Cybersecurity-Skills
   Apache 2.0 licensed, free to use

3. ChromaDB docs for the vector store:
   docs.trychroma.com

---

What to build — step by step

Step 1 — Pull Azure relevant skills

From github.com/mukul975/Anthropic-Cybersecurity-Skills
navigate to skills/ and find all Azure and cloud
security relevant SKILL.md files.

Pull the ones relevant to our rule categories:

• Storage misconfiguration skills
• Network security group skills
• Identity and access management skills
• Key Vault and secrets management skills
• VM and compute security skills
• Database security skills

Save them under a new directory:
ai/knowledge/skills/

Step 2 — Build the embedding pipeline

Create ai/embed.py that:

• Reads all SKILL.md files from ai/knowledge/skills/
• Reads all rule descriptions from scanner/rules/
• Reads CIS and NIST control descriptions from
  compliance/frameworks/
• Chunks and embeds all content into ChromaDB
• Saves the ChromaDB collection to ai/vectorstore/

# ai/embed.py
# Run once to build the vector store
# python ai/embed.py

import chromadb
from pathlib import Path

def build_vectorstore():
    client = chromadb.PersistentClient(path="ai/vectorstore")
    collection = client.get_or_create_collection("openshield")
    # embed skills, rules, and compliance controls
    # ...

Step 3 — Build the retrieval helper

Create ai/retriever.py that:

• Loads the ChromaDB collection
• Takes a query string
• Returns the top 5 most relevant chunks

# ai/retriever.py

def retrieve(query: str, n_results: int = 5) -> list[str]:
    # query the vector store
    # return relevant chunks as a list of strings

Step 4 — Build the three Flask endpoints

Create api/routes/ai.py with three endpoints:

POST /api/ai/summary

• Fetches all current findings from the database
• Retrieves relevant context from the vector store
• Calls ai_provider.get_completion() with findings
  and context
• Returns a plain English executive summary

POST /api/ai/prioritise

• Fetches all findings
• Uses AI to rank by actual exploitability and
  business risk not just severity label
• Returns findings in priority order with reasoning

POST /api/ai/ask

• Accepts a freeform question in the request body
• Retrieves relevant context from the vector store
• Returns a grounded answer about the subscription
  posture

Step 5 — Wire up the route

Register ai_bp in api/app.py alongside the other
blueprints.

---

Request and response format

POST /api/ai/summary
Request:
{
"provider": "anthropic",
"api_key": "sk-ant-...",
"model": "claude-sonnet-4-6" // optional
}

Response:
{
"summary": "Your subscription has 14 findings...",
"provider": "anthropic",
"model": "claude-sonnet-4-6"
}

POST /api/ai/ask
Request:
{
"provider": "groq",
"api_key": "gsk_...",
"question": "What is the fastest path to CIS compliance?"
}

Response:
{
"answer": "Based on your current findings...",
"sources": ["AZ-NET-002", "CIS 6.1", "..."]
}

---

New dependencies to add to requirements.txt

chromadb==0.4.24
sentence-transformers==2.7.0

---

Files to create

ai/init.py
ai/embed.py
ai/retriever.py
ai/knowledge/skills/ (directory with SKILL.md files)
api/routes/ai.py

Files to modify

api/app.py (register the ai blueprint)
requirements.txt (add chromadb and sentence-transformers)

---

Important rules

• Never store or log API keys anywhere
• API key comes from the request body only,
  never from environment variables
• All three endpoints require JWT auth like
  every other API endpoint
• If the vector store does not exist yet return
  a clear error message telling the user to run
  python ai/embed.py first
• Graceful fallback if ChromaDB is not installed

---

Acceptance Criteria

• Azure relevant skills pulled from the skill
  library and saved under ai/knowledge/skills/
• embed.py builds the vector store successfully
• retriever.py returns relevant chunks for a
  test query
• POST /api/ai/summary returns a meaningful
  plain English summary of current findings
• POST /api/ai/prioritise returns findings
  ranked by risk
• POST /api/ai/ask returns a grounded answer
  with source references
• All three endpoints require JWT auth
• No API keys stored or logged
• CI passes, base branch is dev

Branch

feat/rag-ai-insights

Difficulty

Medium-High — requires understanding of embeddings,
vector stores, and the existing OpenShield API
patterns. Read the existing api/routes/ files
before starting to understand the patterns.