CloudGuard

CloudGuard is an experimental cloud-audit assistant that combines Streamlit, Groq, and the Model Context Protocol (MCP) to let an authenticated user connect an AWS account and ask cloud-audit questions in natural language.

The current implementation focuses on AWS only. Other providers such as Azure, GCP, GitHub, and additional enterprise integrations are planned for later phases.

Current Project Status

Step 1 — Authentication

Completed:

Streamlit-based login and registration

SQLite-backed user storage

Password hashing

Streamlit session-based authentication

Protected application dashboard

Logout/session cleanup

Step 2 — AWS + MCP + Groq

Implemented/currently being integrated:

AWS Access Key / Secret Key input

Optional AWS Session Token

AWS credential verification through STS

AWS account ID and caller ARN display

Dynamic AWS Region discovery

Region selector in Streamlit

Groq-based natural-language orchestration

Config-driven MCP runtime

AWS MCP Proxy integration

Dynamic MCP tool discovery

Streamlit chat interface

Multi-turn in-session chat history

Live progress messages while AWS/MCP operations are running

Progressive ChatGPT-style response rendering

The current chat history is held in st.session_state. Persistent conversation storage in SQLite is not part of the current implementation yet.

High-Level Architecture

flowchart TD
U[User] --> UI[Streamlit UI]

    UI --> AUTH[Authentication Layer]
    AUTH --> DB[(SQLite)]

    UI --> AWSFORM[AWS Connection Layer]
    AWSFORM --> STS[AWS STS GetCallerIdentity]
    STS --> REGION[AWS Region Discovery]

    REGION --> CHAT[Chat / NLP Interface]

    CHAT --> ORCH[Groq Orchestration Layer]

    ORCH --> MCPR[MCP Runtime Client]
    MCPR --> CONFIG[MCP Configuration Loader]
    CONFIG --> JSON[config/aws_mcp.json]

    MCPR --> PROXY[AWS MCP Proxy]
    PROXY --> AWSMCP[Official AWS MCP Server]
    AWSMCP --> AWS[AWS Account / AWS APIs]

    AWS --> AWSMCP
    AWSMCP --> PROXY
    PROXY --> MCPR
    MCPR --> ORCH
    ORCH --> CHAT

Architecture Layers

The application is divided into independent layers so that UI, authentication, AWS access, MCP communication, and LLM orchestration do not become tightly coupled.

1. Presentation Layer

Technology:

Streamlit

Responsibilities:

Login / registration UI

AWS credentials form

AWS account connection state

Region selector

Chat interface

Progress/status messages

Displaying Groq answers

Logout and disconnect actions

Primary module:

ui/
└── aws_page.py

The chat UI follows a ChatGPT-style interaction:

User question
↓
Assistant bubble appears immediately
↓
Understanding your request...
↓
Connecting securely to AWS...
↓
Checking available AWS capabilities...
↓
Retrieving live AWS data...
↓
Analyzing AWS response...
↓
Final response rendered progressively

2. Authentication Layer

Responsibilities:

Register application users

Login users

Hash passwords

Verify passwords

Maintain authenticated Streamlit session

Prevent unauthenticated access to AWS functionality

Modules:

auth/
├── **init**.py
├── auth_service.py
└── password_service.py

Authentication flow:

flowchart LR
A[Register] --> B[Hash Password]
B --> C[(SQLite Users Table)]

    D[Login] --> E[Find User]
    E --> F[Verify Password]
    F --> G[Streamlit Session]
    G --> H[Protected Dashboard]

3. Persistence Layer

Current database:

SQLite

Responsibilities:

Application user storage

Authentication data

Current database file:

data/app.db

Current conceptual schema:

CREATE TABLE users (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
email TEXT NOT NULL UNIQUE,
password_hash TEXT NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

AWS credentials are not stored in SQLite.

4. AWS Connection Layer

Responsibilities:

Validate AWS credentials

Build isolated AWS environments

Run AWS CLI commands

Retrieve AWS caller identity

Discover available AWS Regions

Modules:

aws_layer/
├── **init**.py
├── credentials.py
├── cli.py
└── service.py

Credential Verification

The application verifies the user's AWS identity with:

AWS STS
↓
GetCallerIdentity
↓
Account ID
User/Role ID
ARN

The application does not treat Groq as the AWS authentication layer.

5. AWS Credential Context

User-provided AWS credentials are represented internally by an AwsCredentials object.

Conceptually:

AwsCredentials(
access_key_id=...,
secret_access_key=...,
session_token=...
)

The credential object generates the environment used by AWS CLI and MCP subprocesses:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN
AWS_REGION
AWS_DEFAULT_REGION

Security Rule

Credentials should flow like this:

Streamlit Form
↓
AwsCredentials
↓
Session Runtime
↓
AWS CLI / MCP Process

They should not flow like this:

AWS Secret Key
↓
Groq Prompt

or:

AWS Secret Key
↓
SQLite Database

6. Region Discovery Layer

AWS Regions are not intended to be permanently hardcoded in application logic.

After authentication:

Credentials
↓
EC2 DescribeRegions
↓
Region List
↓
Streamlit Selectbox

The user's selected Region becomes the runtime target for regional AWS queries.

Example:

ap-south-1
ap-northeast-1
ap-southeast-2
us-east-1
eu-west-1
...

The application also recognizes Region opt-in states such as:

opt-in-not-required
opted-in
not-opted-in

7. NLP / LLM Orchestration Layer

Technology:

Groq

Module:

groq_layer/
└── orchestrator.py

Responsibilities:

Receive the user's natural-language question

Maintain limited conversation context

Receive MCP tool schemas dynamically

Decide which tool is required

Invoke tools through the MCP runtime layer

Feed tool results back to the model

Generate a user-friendly final answer

Groq is an orchestrator, not the source of truth for AWS account data.

For account-specific claims:

Question
↓
Groq
↓
MCP Tool
↓
AWS
↓
Real AWS Result
↓
Groq Explanation

8. MCP Configuration Layer

Configuration file:

config/
└── aws_mcp.json

The project uses an MCP configuration file instead of implementing every AWS MCP capability internally.

The configuration defines external MCP servers such as:

AWS MCP Proxy

AWS Pricing MCP Server

AWS IaC MCP Server

AWS Documentation MCP Server

This lets the project use established MCP servers now and add custom CloudGuard MCP servers only when a future requirement is not covered by existing integrations.

9. MCP Runtime Layer

Modules:

mcp_runtime/
├── **init**.py
├── config.py
└── client.py

config.py

Responsibilities:

Read MCP JSON configuration

Resolve runtime placeholders

Resolve environment-based defaults

Select an MCP server by name

Build the final server configuration

Example target configuration:

${TARGET_AWS_REGION}

can resolve at runtime to:

ap-south-1

without changing source code.

client.py

Responsibilities:

Start configured stdio MCP processes

Establish ClientSession

Initialize MCP

Discover tools dynamically with tools/list

Call MCP tools

Return structured tool results to the orchestration layer

The project is not implementing the MCP protocol itself.

It uses the MCP SDK as the client/runtime abstraction.

MCP Strategy

The project currently follows a reuse-first MCP strategy.

flowchart LR
APP[CloudGuard] --> CLIENT[Generic MCP Runtime]
CLIENT --> AWSMCP[AWS MCP]
CLIENT --> PRICING[AWS Pricing MCP]
CLIENT --> DOCS[AWS Documentation MCP]
CLIENT --> IAC[AWS IaC MCP]

    CLIENT -. Future .-> CUSTOM[Custom CloudGuard MCP]

Current Principle

Use an existing MCP server when it already provides the required capability.

Create a custom CloudGuard MCP server only when:

required audit logic is Vyteq-specific,

existing MCP tools cannot expose required data,

normalization must be enforced centrally,

organization-specific controls are required,

or multi-cloud abstraction requires a dedicated common interface.

AWS MCP Runtime Flow

sequenceDiagram
participant User
participant Streamlit
participant Groq
participant MCPClient as MCP Runtime
participant Proxy as AWS MCP Proxy
participant MCP as AWS MCP Server
participant AWS

    User->>Streamlit: Ask AWS question
    Streamlit->>Groq: Question + account context
    Groq->>MCPClient: Select discovered tool
    MCPClient->>Proxy: MCP request over stdio
    Proxy->>MCP: Signed request
    MCP->>AWS: AWS API operation
    AWS-->>MCP: AWS response
    MCP-->>Proxy: MCP result
    Proxy-->>MCPClient: Tool result
    MCPClient-->>Groq: Structured data
    Groq-->>Streamlit: Natural-language answer
    Streamlit-->>User: Chat response

Example User Query

Show all running EC2 instances.

Expected logical flow:

User
↓
Streamlit Chat
↓
Groq
↓
Discover MCP capabilities
↓
Choose AWS execution/retrieval capability
↓
AWS MCP
↓
EC2 / AWS API
↓
Real AWS data
↓
Groq summarizes
↓
Streamlit displays result

A Region selected in Streamlit is treated as the target Region for regional queries.

Current Folder Structure

CloudGuard/
│
├── app.py
├── pyproject.toml
├── uv.lock
├── .env
├── .gitignore
│
├── auth/
│ ├── **init**.py
│ ├── auth_service.py
│ └── password_service.py
│
├── database/
│ ├── **init**.py
│ └── database.py
│
├── data/
│ └── app.db
│
├── aws_layer/
│ ├── **init**.py
│ ├── credentials.py
│ ├── cli.py
│ └── service.py
│
├── config/
│ └── aws_mcp.json
│
├── mcp_runtime/
│ ├── **init**.py
│ ├── config.py
│ └── client.py
│
├── groq_layer/
│ ├── **init**.py
│ └── orchestrator.py
│
└── ui/
├── **init**.py
└── aws_page.py

Dependency Direction

The intended dependency direction is:

UI
↓
Application / Orchestration
↓
MCP Runtime + AWS Services
↓
External Systems

More explicitly:

flowchart TD
UI[ui] --> GROQ[groq_layer]
UI --> AWSL[aws_layer]

    GROQ --> MCPR[mcp_runtime]

    MCPR --> CONF[config/aws_mcp.json]

    AWSL --> CLI[AWS CLI]
    MCPR --> MCP[MCP Servers]

    AUTH[auth] --> DB[database]

The UI should not contain AWS execution logic.

The Groq layer should not directly manage AWS secrets.

The MCP runtime should not contain Streamlit UI state.

Security Model

The current security model is based on separation of responsibilities.

Application Authentication

Application users authenticate against SQLite.

AWS Authentication

AWS credentials are separately entered after application login.

Credential Storage

Current design:

AWS Credentials
↓
Streamlit Session
↓
Runtime Environment

Not:

AWS Credentials
↓
SQLite

LLM Isolation

Groq should receive:

user question

account ID

identity ARN

selected Region

MCP tool definitions

MCP tool results

Groq should not receive:

Secret Access Key

Session Token

raw application secrets

AWS Authorization

AWS IAM remains the final authorization boundary.

For an audit application, connected AWS identities should use read-only or narrowly scoped audit permissions.

Dynamic Configuration Strategy

Values that vary between users/accounts should be runtime configuration, including:

AWS credentials
AWS account identity
Target AWS Region
MCP endpoint
MCP proxy package/version
MCP timeout
Groq API key
Groq model

These values should not be permanently embedded into business logic.

Current MCP Configuration Note

The baseline MCP configuration currently contains an AWS MCP Proxy entry using uvx and stdio, and also includes AWS Pricing, AWS IaC, and AWS Documentation MCP servers.

The baseline JSON still contains fixed values such as a default AWS profile and a Region metadata value. The application architecture is moving these account-specific values into runtime configuration rather than treating them as permanent project constants.

Environment Variables

Example .env:

GROQ_API_KEY=your_groq_api_key
GROQ_MODEL=openai/gpt-oss-120b

AWS_MCP_ENDPOINT=https://aws-mcp.us-east-1.api.aws/mcp
MCP_TIMEOUT_MS=100000
FASTMCP_LOG_LEVEL=ERROR

Do not commit real secrets.

Recommended .gitignore:

.venv/
.env

**pycache**/
\*.py[cod]

data/_.db
data/_.db-journal

.streamlit/secrets.toml

.vscode/
.idea/

.DS_Store
Thumbs.db

Development Environment

The project uses uv.

Create the environment:

uv venv

Install dependencies:

uv add streamlit passlib bcrypt groq python-dotenv "mcp[cli]"

Run:

uv run streamlit run app.py

AWS CLI must also be available in the host environment:

aws --version

User Journey

flowchart TD
A[Open CloudGuard] --> B{Authenticated?}

    B -- No --> C[Login / Register]
    C --> B

    B -- Yes --> D[AWS Connection]

    D --> E[Enter AWS Credentials]
    E --> F[Verify with STS]

    F -->|Invalid| E
    F -->|Valid| G[Load AWS Regions]

    G --> H[Select Region]
    H --> I[Open AWS Chat]

    I --> J[Ask Natural Language Question]
    J --> K[Groq Orchestration]
    K --> L[MCP Tool Discovery / Execution]
    L --> M[AWS]
    M --> N[Groq Final Answer]
    N --> I

Chat UX

The application currently provides an AI-chat-style experience.

During processing, the assistant can display stages such as:

Understanding your request...
Connecting securely to AWS...
Checking available AWS capabilities...
Determining which AWS data is required...
Retrieving live AWS data...
AWS data received. Analyzing the result...
Preparing the answer...

The final response is rendered progressively to give a ChatGPT-like user experience.

Current Limitations

The project is still a proof of concept / active development build.

Current limitations include:

AWS is the only cloud provider currently integrated.

Conversation history is session-based, not persisted across login sessions.

AWS credentials are entered manually by the user.

Enterprise federation/SSO for AWS is not implemented yet.

MCP tool availability depends on the configured external MCP server.

MCP server configuration is still being normalized to remove account-specific hardcoding.

Multi-region aggregation is not yet a complete orchestration workflow.

Automated compliance mapping is not yet implemented.

No production-grade secrets manager integration yet.

No background audit jobs yet.

No centralized audit result database yet.

Planned Architecture

Future target:

flowchart TD
UI[Streamlit / Future Web UI]
AUTH[Identity & Access Layer]
NLP[NLP Orchestrator]
MCP[MCP Gateway / Runtime]
DATA[(Audit Data Store)]

    UI --> AUTH
    UI --> NLP
    NLP --> MCP

    MCP --> AWS[AWS MCP]
    MCP --> GCP[GCP MCP]
    MCP --> AZURE[Azure MCP]
    MCP --> GH[GitHub MCP]
    MCP --> CUSTOM[Vyteq Custom MCP]

    AWS --> DATA
    GCP --> DATA
    AZURE --> DATA
    GH --> DATA
    CUSTOM --> DATA

Potential future providers:

AWS
GCP
Azure
GitHub
SaaS platforms
On-premise infrastructure

The goal is to keep the NLP layer provider-independent while MCP servers provide the provider-specific execution layer.

Planned Features

Near Term

Persist chat sessions in SQLite

Chat history sidebar

Reopen previous conversations

Cache repeated questions/results where appropriate

Add timestamps to messages

Add AWS IAM inspection

Add VPC/Subnet inspection

Add RDS inspection

Add Lambda inspection

Add CloudTrail inspection

Add CloudWatch inspection

Add EBS and load-balancer inspection

Improve multi-region querying

Audit Engine

AWS security posture summary

Public exposure detection

IAM risk review

Encryption checks

Logging checks

Network control checks

Misconfiguration findings

Severity assignment

Evidence collection

Compliance-control mapping

Future MCP Work

Custom MCP servers may be introduced for:

Vyteq-specific controls

Normalized multi-cloud asset discovery

Evidence collection

GRC mapping

Compliance framework checks

Custom organization policies

Report generation

Design Principles

The project currently follows these principles:

DRY — common AWS and MCP behavior belongs in reusable layers.

Config-driven — changing account/Region values should not require source-code changes.

Read-oriented auditing — the application is intended for inspection, not infrastructure mutation.

Least privilege — AWS IAM should restrict connected credentials.

Separation of concerns — UI, LLM, MCP, AWS, authentication, and persistence are separate layers.

No secret leakage — cloud credentials must not enter LLM prompts.

Dynamic tool discovery — MCP capabilities should be discovered instead of hardcoded where possible.

Provider extensibility — AWS is Phase 1 of the cloud integration architecture, not a permanent hardwired dependency.

Evidence over hallucination — live-account claims should be based on retrieved AWS data.

Technology Stack

Layer

Technology

UI

Streamlit

Language

Python

Environment / Package Management

uv

Application Authentication

Custom Python auth

Database

SQLite

Password Security

Passlib / bcrypt

NLP / LLM

Groq

Tool Protocol

MCP

MCP SDK

Python MCP SDK

AWS Access

AWS CLI + AWS MCP

MCP Transport

stdio

AWS MCP Bridge

AWS MCP Proxy

Configuration

JSON + environment variables

Project Phase

Current phase:

Phase 1
Authentication
✅

Phase 2
AWS Connection
✅

AWS Region Discovery
✅

Groq NLP
✅

MCP Runtime
✅

Dynamic MCP Tool Discovery
✅ / Active integration

Live AWS Resource Querying
🚧 Active development

Persistent Chat History
⏳ Next phase

Multi-cloud
⏳ Future

Disclaimer

CloudGuard is currently under active development.

It should be used with dedicated, least-privilege AWS audit credentials. Do not use unrestricted administrative credentials for development or testing.

License

Add the appropriate project license before public distribution.