Metadata-Version: 2.4
Name: kenning-cli
Version: 1.0.1
Summary: AI-powered contextual risk analysis tool for AWS infrastructure - identifies compound security and cost risks
Home-page: https://github.com/kenningproject/kenning-cli
Author: Kenning Project
Author-email: Kenning Project <info@kenningproject.com>
Maintainer-email: Kenning Project <info@kenningproject.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/kenningproject/kenning-cli
Project-URL: Repository, https://github.com/kenningproject/kenning-cli
Project-URL: Documentation, https://github.com/kenningproject/kenning-cli#readme
Project-URL: Bug Tracker, https://github.com/kenningproject/kenning-cli/issues
Keywords: aws,security,cost-optimization,devops,cloud,cli,ai,risk-analysis
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Classifier: Environment :: Console
Classifier: Natural Language :: English
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: boto3
Requires-Dist: click
Requires-Dist: colorama
Requires-Dist: python-dotenv
Requires-Dist: pydantic
Requires-Dist: ollama
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: moto; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Kenning CLI

*Intelligent AWS ## 🚀 Quick Start

### 1. Install Kenning CLI

**Option A: Install from PyPI (Recommended)**
```bash
pip install kenning-cli
```

**Option B: Install from Source**
```bash
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)**
```bash
# 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

```bash
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)**
```bash
./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**
```bash
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**
```bash
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**
```bash
kenning check-config
```
This command validates your AWS setup and permissions.

📚 **For detailed AWS setup instructions, see [AWS_SETUP.md](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

```bash
# 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
```bash
# 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`](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.

---


