Skip to content
BranchesTags

Repository files navigation

🛡️ SentinelAI: Automated AWS Security Assistant

✅ Status: Production Ready • Coverage: 98% • Tests: 43/43 passing

SentinelAI is a modular, AI-powered assistant that helps cloud engineers and security architects audit, visualize, and govern AWS environments with speed and precision. It is built for automation, clarity, and extensibility.

🚀 Quick Start

# create and activate a venv (if not already created)
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run all tests (43 tests, full suite)
python -m pytest tests/ -v

# Run example integration workflow
python examples/integration_demo.py

# Test Lambda function routing
python test_lambda.py

# Read the quick reference
cat QUICK_REFERENCE.md

🚀 Deployment

Build Lambda Package

./build.sh

Deploy to AWS

# Upload the package to S3
aws s3 cp sentinelai-lambda.zip s3://your-bucket-name/

# Deploy CloudFormation stack
aws cloudformation deploy \
  --template-file templates/iam-analyzer.yaml \
  --stack-name sentinelai-stack \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides \
    LambdaCodeS3Bucket=your-bucket-name \
    LambdaCodeS3Key=sentinelai-lambda.zip

# Get API Gateway URL
aws cloudformation describe-stacks \
  --stack-name sentinelai-stack \
  --query 'Stacks[0].Outputs[?OutputKey==`ApiGatewayUrl`].OutputValue' \
  --output text

API Usage

IAM Policy Analysis:

curl -X POST https://your-api-gateway-url/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "policy": {
      "Version": "2012-10-17",
      "Statement": [
        {"Effect": "Allow", "Action": "*", "Resource": "*"}
      ]
    }
  }'

CloudTrail Analysis:

curl -X POST https://your-api-gateway-url/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "logs": [
      {
        "eventName": "CreateAccessKey",
        "sourceIPAddress": "203.0.113.42"
      }
    ]
  }'

📚 Documentation (read these first)

Document Purpose Read Time
QUICK_REFERENCE.md Fast answers & commands 5 min
docs/LAMBDA_MODULES.md Complete module reference 15 min
DOCUMENTATION_MAP.md Where to find things 5 min
COMPLETION_SUMMARY.md What was built this session 10 min
PROGRESS_REPORT.md Detailed project status & metrics 15 min

📐 Architecture Overview

SentinelAI is composed of modular components that interact with AWS services, LLMs, and visualization tools:

  • Input Sources: IAM policies, CloudTrail logs, architecture diagrams, natural language queries
  • Processing Layer: Python modules, LLM adapters (Bedrock), boto3, analysis engines
  • Output Layer: Markdown reports, JSON analysis outputs, dashboards, and alerts

Visual architecture diagram: docs/architecture.drawio (if present)

🧱 Core Modules (Implemented)

sentinelai/
├── templates/
│   └── iam-analyzer.yaml        # CloudFormation template for Lambda + Bedrock
├── sentinelai_lambda/           # Lambda modules (iam, cloudtrail, bedrock)
│   ├── iam_analyzer.py          # Python code for IAM analysis
│   ├── cloudtrail_auditor.py    # CloudTrail log auditor
│   └── bedrock_client.py        # Bedrock (LLM) helper
├── docs/
│   └── LAMBDA_MODULES.md        # Module documentation and examples
├── examples/
│   └── integration_demo.py      # Integration demo (IAM + CloudTrail)
├── tests/                       # Unit tests (pytest)
└── README.md

🧪 Sample Output (short)

IAM Analyzer sample result:

{
  "PolicyName": "AdminAccess",
  "Issues": [
    "Wildcard in Action: 's3:*'",
    "Missing Condition: No MFA enforcement",
    "Overly broad Resource: '*'"
  ],
  "Severity": "High"
}

🧭 Roadmap (high level)

Milestone Status Target
IAM Analyzer ✅ Completed Aug 2025
CloudTrail Auditor ✅ Completed Aug 2025
Diagram Reviewer In Progress Sep 2025
Governance Guide Generator Planned Sep 2025
ChatOps Assistant (Bedrock) Planned Oct 2025
Risk Dashboard UI Planned Oct 2025

📦 How to use

  • Run the integration demo to see the workflow:
source venv/bin/activate
python examples/integration_demo.py
  • Run tests:
python -m pytest tests/ -v --cov=sentinelai_lambda

📁 Where to look next

  • Quick developer guide: QUICK_REFERENCE.md
  • Module docs & API: docs/LAMBDA_MODULES.md
  • Tests: tests/ (see test_*.py files)
  • Integration demo: examples/integration_demo.py

If you'd like, I can also:

  • Add CI / coverage badges to the header
  • Create a one-click deploy script for the CloudFormation template
  • Open a PR with these changes and a commit message

Thanks — tell me which of the above you'd like next.

🛡️ SentinelAI: Automated AWS Security Assistant

SentinelAI is a modular, AI-powered assistant designed to help cloud engineers and security architects audit, visualize, and govern AWS environments with speed and precision. Built for automation, clarity, and extensibility.

📐 Architecture Overview

SentinelAI consists of modular components that interact with AWS services, LLMs, and visualization tools. Here's a high-level view:

  • Input Sources: IAM policies, CloudTrail logs, architecture diagrams, natural language queries
  • Processing Layer: Python scripts, LLMs (Bedrock/OpenAI), boto3, Vision
  • Output Layer: Markdown docs, dashboards, security alerts, architecture feedback

📊 Visual architecture diagram available in /docs/architecture.drawio

🧱 Core Modules

Module Functionality Powered By
🔐 IAM Policy Analyzer Flags overly permissive policies, missing conditions, wildcards LLM + Python
📜 CloudTrail Log Auditor Detects suspicious activity, privilege escalation, unusual API calls LLM + boto3
🧩 Architecture Diagram Reviewer Accepts diagrams (via upload or draw.io) and provides security feedback LLM + Vision
📘 Governance Guide Generator Auto-generates Markdown docs with security best practices LLM
🧠 ChatOps Assistant Natural language interface to query AWS resources and get security advice LLM + Bedrock or OpenAI
📊 Risk Dashboard Visualizes flagged issues, severity scores, and remediation paths Streamlit or React frontend

🚀 Roadmap

Milestone Status Target Date
✅ IAM Analyzer MVP Completed August 2025
✅ CloudTrail Auditor Completed August 2025
🧩 Diagram Reviewer Integration In Progress September 2025
📘 Governance Guide Generator Planned September 2025
🧠 ChatOps Assistant (Bedrock) Planned October 2025
📊 Risk Dashboard UI Planned October 2025

📂 Sample Outputs

🔐 IAM Policy Analyzer

{
  "PolicyName": "AdminAccess",
  "Issues": [
    "Wildcard in Action: 's3:*'",
    "Missing Condition: No MFA enforcement",
    "Overly broad Resource: '*'"
  ],
  "Severity": "High"
}

🧱 Architecture

graph TD
A[User Uploads IAM Policy or Logs] --> B[Lambda Function]
B --> C[Bedrock Claude Model]
C --> D[Security Feedback]
D --> E[S3 / DynamoDB Storage]
D --> F[Streamlit / React Dashboard]
Loading

Getting Started

1. Clone the Repo

git clone https://github.com/your-username/sentinelai.git
cd sentinelai

2. Deploy IAM Analyzer via CloudFormation

aws cloudformation deploy \
  --template-file templates/iam-analyzer.yaml \
  --stack-name SentinelAI-IAMAnalyzer \
  --capabilities CAPABILITY_NAMED_IAM

3. Test the Lambda Function

Test Case:

{
  "policy": {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": "*",
        "Resource": "*"
      }
    ]
  }
}

🧠 Bedrock Integration

SentinelAI uses Claude v2 via AWS Bedrock. Ensure your IAM role has the following permissions:

{
  "Effect": "Allow",
  "Action": ["bedrock:InvokeModel"],
  "Resource": "*"
}

📁 Project Structure

sentinelai/
├── templates/
│   └── iam-analyzer.yaml        # CloudFormation template for Lambda + Bedrock
├── lambda/
│   └── iam_analyzer.py          # Python code for IAM analysis
├── docs/
│   └── governance_guide.md      # Auto-generated security best practices
├── dashboard/                   # (Optional) Streamlit or React frontend
└── README.md

🧪 Sample Output

⚠️ Security Risks Detected:
- Wildcard "*" used in Action and Resource
- No conditions specified
- Policy grants full administrative access

✅ Recommendations:
- Replace "*" with specific actions
- Add conditions (e.g., IP restrictions)
- Use least privilege principle

🧭 Roadmap

  • IAM Analyzer (Lambda + Bedrock)
  • CloudTrail Log Auditor
  • Architecture Diagram Reviewer
  • ChatOps Assistant
  • Risk Dashboard
  • CI/CD Pipeline with GitHub Actions

👨‍💻 Author

Chinedu — Aspiring AWS SysOps Administrator & Cloud Security Architect Focused on automation, governance, and platform-level solutions. 📫 LinkedIn | 🧠 Portfolio

📜 License

MIT License. See LICENSE for details.

About

SentinelAI — GenAI-Powered Cloud Security Suite

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages