Nimbus Assistant

AWS Security Vulnerability Scanner & Blast-Radius Visualiser

Nimbus Assistant is a full-stack application that discovers security vulnerabilities across your AWS account by aggregating findings from multiple AWS security services and Prowler. It presents results through an interactive dashboard, a filterable findings table, and a graph view that maps blast-radius relationships between affected resources.

---

Table of Contents

• Features
• Architecture
• nimbus-cli — AI Fix Suggestions
• Local Development
• Configuration
• API Reference
• Project Structure
• Tech Stack
• License

---

Features

• Multi-source scanning — aggregates findings from six AWS security sources:

  Source	What it checks
  AWS Inspector	CVE / vulnerability scanning for EC2, Lambda, ECR
  AWS Access Analyzer	Public / cross-account access on IAM, S3, KMS, etc.
  AWS GuardDuty	Threat detection findings
  AWS Security Hub	Consolidated security standards findings
  AWS Config	Resource configuration compliance
  Prowler v5	300+ CIS / best-practice checks (runs as CLI subprocess)

• AI-Powered Analysis — Bedrock Knowledge Base with Claude Haiku 4.5 for intelligent security recommendations, backed by curated AWS security documentation.

• Interactive Dashboard — summary cards, severity pie chart, per-service bar chart — all clickable to drill into filtered findings.

• Findings Table — filter by severity, source, service, or free-text search.

• Blast-Radius Graph — radial layout powered by React Flow; click any resource to highlight its blast radius and connected resources.

---

Architecture

┌──────────────┐       ┌──────────────────────────────┐
│   Browser    │──────▶│       Frontend (nginx)       │
│  :80         │       │  React + Vite + TailwindCSS  │
│              │       │  /api/* → proxy to backend   │
└──────────────┘       └──────────┬───────────────────┘
                                  │
                       ┌──────────▼───────────────────┐
                       │     Backend (FastAPI)         │
                       │  Python 3.12 + Prowler CLI    │
                       │  :8000                        │
                       └──────┬───────────┬───────────┘
                              │           │
               ┌──────────────▼──┐  ┌─────▼──────────────────┐
               │  AWS Account    │  │  Amazon Bedrock         │
               │  Inspector,     │  │  Claude Haiku 4.5       │
               │  GuardDuty,     │  │  Knowledge Base (S3 +   │
               │  Security Hub,  │  │  S3 Vectors native      │
               │  Config, etc.   │  │  vector store)          │
               └─────────────────┘  └─────────────────────────┘

---

nimbus-core — Python SDK

nimbus-core is the shared SDK that powers both the CLI and the backend. Install it directly to use Nimbus in your own Python projects, CI pipelines, or scripts.

Install

pip install nimbus-core

Usage

from nimbus_core import NimbusClient

# With an existing Knowledge Base
client = NimbusClient(region="us-east-1", kb_id="YOUR_KB_ID")
result = client.suggest_fix("S3 bucket is publicly accessible")
print(result.remediation)

# Or provision a new KB first
client = NimbusClient(region="us-east-1")
client.init()
result = client.suggest_fix("EC2 instance has no IMDSv2")

---

nimbus-cli — AI Fix Suggestions

nimbus-cli is a pip-installable CLI tool that calls Bedrock directly from your terminal — no web UI or backend server needed.

Install

pip install nimbus-assist-cli

Or with pipx for an isolated environment (recommended):

pipx install nimbus-assist-cli

If you don't have pipx: sudo apt install pipx && pipx ensurepath (Ubuntu/Debian) or brew install pipx && pipx ensurepath (macOS).

For local development, install from source:

pip install -e sdk/nimbus-core
pip install -e sdk/nimbus-cli

Prerequisites

• AWS credentials configured (aws configure or env vars)
• Bedrock model access enabled:
  • amazon.titan-embed-text-v2:0
  • anthropic.claude-haiku-4-5-20251001-v1:0

First-time setup

nimbus-cli --init
# or specify a region (default: us-east-1)
nimbus-cli --init --region us-east-2

Validates AWS credentials and provisions the full RAG pipeline (S3 docs bucket, S3 Vectors, Bedrock KB).

Usage

nimbus-cli --suggest-fix --text "S3 bucket is publicly accessible"
nimbus-cli --suggest-fix --text "EC2 instance has no IMDSv2 enforced"
nimbus-cli --suggest-fix --text "IAM role has wildcard * permissions"

Calls Bedrock directly — no backend server, no Docker, no database needed.

Switch AWS account or refresh credentials

export AWS_PROFILE=other-account   # or export AWS_ACCESS_KEY_ID=...
nimbus-cli --reconfigure

Clears saved config and re-initializes with the currently active credentials.

---

Local Development

# Configure backend credentials
cp backend/.env.example backend/.env
# Edit backend/.env — set AWS_REGION and credentials

# Start everything (backend + frontend + postgres)
docker compose up --build

URL	Description
http://localhost:3000	Frontend
http://localhost:8000/docs	Backend Swagger UI

Backend only

cd backend
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload --port 8000

Frontend only

cd frontend
npm install
cp .env.example .env   # set VITE_USE_CACHED=false for live backend
npm run dev            # http://localhost:5173

---

Configuration

Backend Environment Variables

Variable	Default	Description
AWS_REGION	us-east-1	AWS region to scan
AWS_PROFILE	—	Named AWS CLI profile
AWS_ACCESS_KEY_ID	—	Explicit access key
AWS_SECRET_ACCESS_KEY	—	Explicit secret key
APP_ENV	development	development or production
LOG_LEVEL	INFO	Logging verbosity
DATABASE_URL	postgresql+psycopg2://nimbus:nimbus@db:5432/nimbus	Database connection
BEDROCK_KB_ID	—	Bedrock Knowledge Base ID
BEDROCK_MODEL_ID	anthropic.claude-haiku-4-5-20250620	Bedrock model

Frontend Environment Variables

Variable	Default	Description
VITE_USE_CACHED	true	true = cached JSON, false = live backend

---

API Reference

All endpoints are prefixed with /api/v1.

Method	Endpoint	Description
GET	/health	Health check + AWS account ID probe
POST	/scan/comprehensive/refresh	Run full live scan and replace cached result
GET	/scan/comprehensive	Cached full scan response
GET	/scan/comprehensive?service=ec2&severity=CRITICAL,HIGH	Filtered cached findings
GET	/scanners/all?severity=CRITICAL,HIGH	Cached graph response filtered by severity
GET	/scanners/inspector	Inspector findings only
GET	/scanners/access-analyzer	Access Analyzer findings only
GET	/scanners/guardduty	GuardDuty findings only
GET	/scanners/security-hub	Security Hub findings only
GET	/scanners/prowler	Prowler findings only
POST	/remediation	Get AI fix for a specific finding
POST	/remediation/cli	Search cached findings by query and get AI fix

Full interactive docs at /docs (Swagger) and /redoc (ReDoc).

---

Project Structure

Nimbus_Assistant/
├── sdk/
│   ├── nimbus-core/             # Python SDK (shared library)
│   │   ├── pyproject.toml
│   │   └── nimbus_core/
│   │       ├── __init__.py      # exports NimbusClient, FindingInput, RemediationResult
│   │       ├── client.py        # NimbusClient — main SDK entry point
│   │       ├── bedrock.py       # Bedrock RAG: normalize, prompt, retrieve_and_generate
│   │       ├── infra.py         # RAG pipeline provisioning (S3, Vectors, KB)
│   │       └── models.py        # FindingInput, RemediationResult, InitResult
│   └── nimbus-cli/              # pip-installable CLI tool (wraps nimbus-core)
│       ├── pyproject.toml
│       └── nimbus_cli/
│           └── main.py          # CLI entrypoint (--init, --suggest-fix, --reconfigure, --destroy)
├── backend/
│   ├── Dockerfile
│   ├── requirements.txt         # includes nimbus-core
│   └── app/
│       ├── main.py              # FastAPI app
│       ├── config.py            # Pydantic settings
│       ├── core/                # AWS client, graph builder
│       ├── models/              # Schemas + DB models
│       ├── routers/             # API endpoints
│       ├── scanners/            # Inspector, GuardDuty, Access Analyzer, etc.
│       └── services/            # Business logic (uses nimbus-core for remediation)
├── frontend/
│   ├── Dockerfile
│   ├── nginx.conf
│   └── src/
│       ├── components/          # Dashboard, Findings, Graph, Layout
│       ├── hooks/               # Data fetching
│       ├── store/               # Zustand state
│       └── types/               # TypeScript interfaces
└── docker-compose.yml           # Local dev: backend + frontend + postgres

---

Tech Stack

Backend

Technology	Purpose
Python 3.12	Runtime
FastAPI	REST API framework
boto3 / botocore	AWS SDK
Prowler 5.19.0	CLI security scanner (300+ checks)
Amazon Bedrock	AI analysis (Claude Haiku 4.5)
pydantic	Schema validation & config
uvicorn	ASGI server

Frontend

Technology	Purpose
React 19	UI library
TypeScript 5.9	Type safety
Vite 7	Build tool / dev server
TailwindCSS v4	Utility-first CSS
@xyflow/react 12	Interactive graph
Recharts 3	Dashboard charts
Zustand 5	State management

---

License

This project is licensed under the GNU General Public License v3.0.