kenning-cli 1.0.0

AI-powered contextual risk analysis tool for AWS infrastructure - identifies compound security and cost risks

Kenning CLI

*Intelligent AWS ## 🚀 Quick Start

1. Install Kenning CLI

Option A: Install from PyPI (Recommended)

pip install kenning-cli

Option B: Install from Source

git clone https://github.com/kenningproject/kenning-cli.git
cd kenning-cli
pip install -e .

2. Configure AWS Authentication

New users need to set up AWS authentication before using Kenning CLI. We provide multiple easy options:

Option A: Quick Setup Assistant (Recommended for beginners)

# If installed from PyPI, download the setup script:
curl -O https://raw.githubusercontent.com/kenningproject/kenning-cli/main/scripts/setup-aws.sh
chmod +x setup-aws.sh
./setup-aws.sh

# If installed from source:
./scripts/setup-aws.sh

Our interactive setup assistant will:

• Check if AWS CLI is installedCo-Optimization*

The Spark of Kenning

The frustration came from looking at two separate dashboards. One, a cost optimizer, was complaining about an idle EC2 instance. The other, a security scanner, was flagging a security group with an open SSH port. Neither tool told me that the idle, unmonitored instance was the one with the open port. The true risk wasn't the cost, and it wasn't just the open port—it was the combination of the two creating a perfect, hidden entry point for an attacker. I realized that tools see cost and security in isolation, but in the real world, they are dangerously interconnected.

This project was born from that realization: to build a tool that understands context.

What is Kenning CLI?

Kenning CLI is a command-line tool that provides AI-powered contextual risk analysis for your AWS account. It doesn't just list separate cost and security problems; it identifies how they amplify each other and explains these complex, compound risks in plain English.

This allows DevOps, SRE, and Cloud engineers to prioritize fixes that have the greatest combined impact on their cloud environment's health, security, and budget.

Key Features

• Comprehensive Audits: Scans for a wide range of security misconfigurations and cost inefficiencies across EC2 and S3.
• Contextual Correlation: An intelligent engine that finds high-impact "compound risks" where cost and security issues intersect.
• AI-Powered Explanations: Uses Large Language Models (LLMs) to translate complex technical findings into clear, human-readable explanations and actionable advice.
• Developer-First: A CLI tool designed to fit seamlessly into developer and CI/CD workflows.
• Structured Reporting: Generates clean Markdown reports for easy sharing and documentation.

---

🚀 Quick Start

Prerequisites

• Python 3.9+ installed
• An AWS account with appropriate IAM permissions
• AWS CLI installed (pip install awscli)

1. Install Kenning CLI

pip install -e .

2. Configure AWS Authentication

New users need to set up AWS authentication before using Kenning CLI. We provide multiple easy options:

Option A: Quick Setup Assistant (Recommended for beginners)

./scripts/setup-aws.sh

Our interactive setup assistant will:

• Check if AWS CLI is installed
• Guide you through credential configuration
• Validate your permissions
• Run a test scan to ensure everything works

Option B: Manual Configuration

aws configure

You'll need:

• AWS Access Key ID (from IAM user)
• AWS Secret Access Key (from IAM user)
• Default region (e.g., us-east-1)

Option C: Environment Variables

export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_DEFAULT_REGION=us-east-1

Option D: Check Current Configuration

kenning check-config

This command validates your AWS setup and permissions.

📚 For detailed AWS setup instructions, see AWS_SETUP.md

Required AWS Permissions: Kenning CLI needs read-only access to EC2 and S3 services. You can either:

• Attach the ReadOnlyAccess managed policy (easiest)
• Create a custom policy with specific permissions (most secure - see AWS_SETUP.md)

3. Run Your First Scan

# Basic scan
kenning scan

# Scan specific region with verbose output
kenning scan --region us-west-2 --verbose

# Use specific AWS profile
kenning scan --profile production

---

🧩 Components & Responsibilities

1️⃣ Audit Engine (Core)

• Collect AWS metadata for EC2 instances and S3 buckets.

• Identify cost inefficiencies:

  • Idle/underutilized EC2 instances.
  • Public S3 buckets (increased data egress potential).

• Identify security risks:

  • Open security groups (0.0.0.0/0).
  • Public S3 buckets (misconfiguration).

• Output structured RiskItem objects containing:

  • Resource Type, ID, Region
  • Risk Type (Cost, Security, Both)
  • Metadata for correlation.

2️⃣ Correlator

• Identify compound risks (e.g., idle EC2 with open SSH).

• Assign severity scores:

  • Low / Medium / High
  • Based on cost impact, security risk, and exposure.

• Maintain a simple rule engine for extensibility.

3️⃣ AI Explainer Agent

• Uses OpenAI GPT API / Ollama.

• Generates plain-English explanations:

  • Risk cause.
  • Why it matters.
  • One actionable remediation step.

• Supports structured output in Markdown.

4️⃣ Report Generator

• Generates Markdown reports:

  • Table of identified risks with metadata.
  • GPT-based explanations.
  • Severity overview.

• Allows easy sharing with teams or for documentation pipelines.

6️⃣ Testing & Validation

• Includes comprehensive pytest-based test suite with:
  • 8 core tests for audit engine correctness and correlator logic
  • AI data packaging demos for OpenAI, Claude, local LLMs, and custom ML models
  • Mocked AWS services using moto for reliable, fast testing
  • Future scalability examples demonstrating enterprise-grade compatibility

Quick Test Commands

# Easy way - run all tests
./run_tests.sh

# Or run specific categories
./run_tests.sh core      # Core logic tests (8 tests)
./run_tests.sh ai        # AI agent data formatting demos
./run_tests.sh debug     # Debug data collection flow
./run_tests.sh future    # Future scalability examples

• Cross-platform compatibility: Tests work on Linux, macOS, and Windows

• No hardcoded paths: Uses dynamic path resolution for open source distribution

• Complete documentation: See tests/README.md for detailed guidance

• Ensures reliability during CLI usage and validates AI integration pipeline.

---

⚙️ Tech Stack

• Language: Python 3.11+
• CLI: click
• AWS SDK: boto3
• LLM Integration: OpenAI SDK (GPT-4, GPT-3.5) / Ollama
• Reporting: Markdown generation
• Testing: pytest
• Formatting/Linting: black, flake8
• Version Control: Git + GitHub
• CI/CD: GitHub Actions (optional, for test automation)

---

💡 Novelty & Research Contributions

• ✅ Fills a research gap by combining cost optimization and security auditing in AWS within a single, context-aware tool.
• ✅ Uses LLMs to generate human-readable explanations for technical audit results, improving clarity for DevOps engineers.
• ✅ CLI-first design for practical DevOps/SRE workflows.
• ✅ Modular and extensible architecture for further research and productization.
• ✅ Evaluated in live AWS environments, providing measurable practical value.

---

📦 Final Deliverables

• ✅ Working CLI tool with core commands (scan, explain, report).
• ✅ Structured JSON outputs from audit for further processing.
• ✅ Markdown reports summarizing audit findings with GPT explanations.
• ✅ Unit-tested core modules (audit, correlator, GPT integration).
• ✅ Clean, well-documented GitHub repository with clear structure.
• ✅ Demo video showcasing the CLI tool in action.

---

🛠️ Development Workflow

• ✅ Use Git and GitHub for version control.
• ✅ Use VS Code with Python, Pylance, and Copilot extensions.
• ✅ Use GitHub Actions for optional test automation.
• ✅ Format regularly using black . and lint using flake8 ..
• ✅ Test frequently with pytest.
• ✅ Commit using a consistent structured format:

feat(audit): add EC2 idle instance detection

✅ Use branches for features:

git checkout -b feat/cli-scan

✅ Push regularly and use Pull Requests for clean history.

---

🛡️ Why Kenning CLI Matters

• Cloud cost optimization and security are deeply interconnected in real-world DevOps and SRE environments.
• Existing tools often focus on either cost or security in isolation, lacking context-aware compound risk analysis.
• LLMs can transform raw audit data into actionable insights for engineers, improving decision-making and response times.

---