# Kenning CLI
## 🚀 Step-by-Step Setup Guide
### 1. Install Python 3 and pip
**Ubuntu/Debian:**
```bash
sudo apt update && sudo apt install -y python3 python3-pip
```
**Fedora/RHEL/AlmaLinux:**
```bash
sudo dnf install -y python3 python3-pip
```
**CentOS (older):**
```bash
sudo yum install -y python3 python3-pip
```
**macOS (Homebrew):**
```bash
brew install python3
```
**Windows (Chocolatey):**
```powershell
choco install python
```
---
### 2. Install Kenning CLI and AWS CLI
```bash
pip3 install kenning-cli awscli
```
---
### 3. Configure AWS Credentials
```bash
aws configure
```
_Follow the prompts to enter your AWS Access Key, Secret Key, and default region._
---
### 4. (Optional) Use the Interactive AWS Setup Assistant
```bash
cd /path/to/kenning-cli
./scripts/setup-aws.sh
```
_This script checks your AWS CLI, credentials, and permissions interactively._
---
### 5. (Optional) Install Ollama for Local AI Explanations
**All Linux/macOS:**
```bash
curl -fsSL https://ollama.com/install.sh | sh
```
**Start Ollama (only once):**
```bash
ollama serve &
```
**Download the recommended model:**
```bash
ollama pull phi3
```
---
### 6. Verify Installation
```bash
kenning --help
```
---
### 7. Run Your First Scan
```bash
kenning scan
```
---
**Docker Alternative (No Python Needed):**
```bash
# Install Docker & Docker Compose (see https://docs.docker.com/get-docker/)
git clone https://github.com/kenningproject/kenning-cli.git
cd kenning-cli/docker
docker compose up --build
# To run CLI commands:
docker compose run kenning scan
```
---
## What is Kenning CLI?
Kenning CLI is a command-line tool that:
- Scans your AWS account for cost and security risks
- Correlates findings to reveal high-impact "compound risks"
- Uses AI (OpenAI, Ollama, or local LLMs) to explain risks in plain English
- Generates actionable Markdown reports for teams and compliance
**Why?** Because real-world cloud risks are never just about cost or security—they’re about context.
---
## Features
- 🔍 **Comprehensive Audits:** EC2, S3, and more
- 🧠 **Contextual Correlation:** Finds where cost and security risks overlap
- 🤖 **AI Explanations:** Human-readable, actionable insights
- 📄 **Markdown Reports:** Shareable, compliance-ready output
- 🛠️ **CLI-First:** Fits DevOps, SRE, and CI/CD workflows
---
## Usage
```bash
# Scan your AWS account
kenning scan
# Explain findings with AI
kenning explain
# Generate a Markdown report
kenning report
```
See `kenning --help` for all options.
---
## Requirements
- Python 3.9+
- AWS account with read-only EC2/S3 permissions
- (Optional) Ollama or OpenAI API for AI explanations
---
## Contributing
Pull requests are welcome! See `CONTRIBUTING.md` for guidelines.
---
## License
MIT. See `LICENSE` for details.
```
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.
---
Raw data
{
"_id": null,
"home_page": "https://github.com/kenningproject/kenning-cli",
"name": "kenning-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Kenning Project",
"author_email": "info@kenningproject.com",
"download_url": null,
"platform": null,
"description": "# Kenning CLI\n\n\n\n## \ud83d\ude80 Step-by-Step Setup Guide\n\n### 1. Install Python 3 and pip\n\n**Ubuntu/Debian:**\n```bash\nsudo apt update && sudo apt install -y python3 python3-pip\n```\n**Fedora/RHEL/AlmaLinux:**\n```bash\nsudo dnf install -y python3 python3-pip\n```\n**CentOS (older):**\n```bash\nsudo yum install -y python3 python3-pip\n```\n**macOS (Homebrew):**\n```bash\nbrew install python3\n```\n**Windows (Chocolatey):**\n```powershell\nchoco install python\n```\n\n---\n\n### 2. Install Kenning CLI and AWS CLI\n\n```bash\npip3 install kenning-cli awscli\n```\n\n---\n\n### 3. Configure AWS Credentials\n\n```bash\naws configure\n```\n_Follow the prompts to enter your AWS Access Key, Secret Key, and default region._\n\n---\n\n### 4. (Optional) Use the Interactive AWS Setup Assistant\n\n```bash\ncd /path/to/kenning-cli\n./scripts/setup-aws.sh\n```\n_This script checks your AWS CLI, credentials, and permissions interactively._\n\n---\n\n### 5. (Optional) Install Ollama for Local AI Explanations\n\n**All Linux/macOS:**\n```bash\ncurl -fsSL https://ollama.com/install.sh | sh\n```\n**Start Ollama (only once):**\n```bash\nollama serve &\n```\n**Download the recommended model:**\n```bash\nollama pull phi3\n```\n\n---\n\n### 6. Verify Installation\n\n```bash\nkenning --help\n```\n\n---\n\n### 7. Run Your First Scan\n\n```bash\nkenning scan\n```\n\n---\n\n**Docker Alternative (No Python Needed):**\n```bash\n# Install Docker & Docker Compose (see https://docs.docker.com/get-docker/)\ngit clone https://github.com/kenningproject/kenning-cli.git\ncd kenning-cli/docker\ndocker compose up --build\n# To run CLI commands:\ndocker compose run kenning scan\n```\n\n---\n\n## What is Kenning CLI?\n\nKenning CLI is a command-line tool that:\n- Scans your AWS account for cost and security risks\n- Correlates findings to reveal high-impact \"compound risks\"\n- Uses AI (OpenAI, Ollama, or local LLMs) to explain risks in plain English\n- Generates actionable Markdown reports for teams and compliance\n\n**Why?** Because real-world cloud risks are never just about cost or security\u2014they\u2019re about context.\n\n---\n\n## Features\n\n- \ud83d\udd0d **Comprehensive Audits:** EC2, S3, and more\n- \ud83e\udde0 **Contextual Correlation:** Finds where cost and security risks overlap\n- \ud83e\udd16 **AI Explanations:** Human-readable, actionable insights\n- \ud83d\udcc4 **Markdown Reports:** Shareable, compliance-ready output\n- \ud83d\udee0\ufe0f **CLI-First:** Fits DevOps, SRE, and CI/CD workflows\n\n---\n\n## Usage\n\n```bash\n# Scan your AWS account\nkenning scan\n\n# Explain findings with AI\nkenning explain\n\n# Generate a Markdown report\nkenning report\n```\n\nSee `kenning --help` for all options.\n\n---\n\n## Requirements\n\n- Python 3.9+\n- AWS account with read-only EC2/S3 permissions\n- (Optional) Ollama or OpenAI API for AI explanations\n\n---\n\n## Contributing\n\nPull requests are welcome! See `CONTRIBUTING.md` for guidelines.\n\n---\n\n## License\n\nMIT. See `LICENSE` for details.\n```\nOur interactive setup assistant will:\n- Check if AWS CLI is installed\n- Guide you through credential configuration\n- Validate your permissions\n- Run a test scan to ensure everything works\n\n**Option B: Manual Configuration**\n```bash\naws configure\n```\nYou'll need:\n- AWS Access Key ID (from IAM user)\n- AWS Secret Access Key (from IAM user)\n- Default region (e.g., us-east-1)\n\n**Option C: Environment Variables**\n```bash\nexport AWS_ACCESS_KEY_ID=your_access_key\nexport AWS_SECRET_ACCESS_KEY=your_secret_key\nexport AWS_DEFAULT_REGION=us-east-1\n```\n\n**Option D: Check Current Configuration**\n```bash\nkenning check-config\n```\nThis command validates your AWS setup and permissions.\n\n\ud83d\udcda **For detailed AWS setup instructions, see [AWS_SETUP.md](AWS_SETUP.md)**\n\n**Required AWS Permissions:**\nKenning CLI needs read-only access to EC2 and S3 services. You can either:\n- Attach the `ReadOnlyAccess` managed policy (easiest)\n- Create a custom policy with specific permissions (most secure - see AWS_SETUP.md)\n\n### 3. Run Your First Scan\n\n```bash\n# Basic scan\nkenning scan\n\n# Scan specific region with verbose output\nkenning scan --region us-west-2 --verbose\n\n# Use specific AWS profile\nkenning scan --profile production\n```\n\n---\n\n\n## \ud83e\udde9 Components & Responsibilities\n\n### 1\ufe0f\u20e3 Audit Engine (Core)\n\n* Collect AWS metadata for **EC2 instances and S3 buckets**.\n* Identify **cost inefficiencies**:\n\n * Idle/underutilized EC2 instances.\n * Public S3 buckets (increased data egress potential).\n* Identify **security risks**:\n\n * Open security groups (0.0.0.0/0).\n * Public S3 buckets (misconfiguration).\n* Output structured `RiskItem` objects containing:\n\n * Resource Type, ID, Region\n * Risk Type (Cost, Security, Both)\n * Metadata for correlation.\n\n### 2\ufe0f\u20e3 Correlator\n\n* Identify **compound risks** (e.g., idle EC2 with open SSH).\n* Assign **severity scores**:\n\n * Low / Medium / High\n * Based on cost impact, security risk, and exposure.\n* Maintain a simple rule engine for extensibility.\n\n### 3\ufe0f\u20e3 AI Explainer Agent\n\n* Uses **OpenAI GPT API / Ollama**.\n* Generates **plain-English explanations**:\n\n * Risk cause.\n * Why it matters.\n * One actionable remediation step.\n* Supports structured output in Markdown.\n\n### 4\ufe0f\u20e3 Report Generator\n\n* Generates **Markdown reports**:\n\n * Table of identified risks with metadata.\n * GPT-based explanations.\n * Severity overview.\n* Allows easy sharing with teams or for documentation pipelines.\n\n\n### 6\ufe0f\u20e3 Testing & Validation\n\n* Includes **comprehensive pytest-based test suite** with:\n * **8 core tests** for audit engine correctness and correlator logic\n * **AI data packaging** demos for OpenAI, Claude, local LLMs, and custom ML models\n * **Mocked AWS services** using moto for reliable, fast testing\n * **Future scalability** examples demonstrating enterprise-grade compatibility\n\n#### Quick Test Commands\n```bash\n# Easy way - run all tests\n./run_tests.sh\n\n# Or run specific categories\n./run_tests.sh core # Core logic tests (8 tests)\n./run_tests.sh ai # AI agent data formatting demos\n./run_tests.sh debug # Debug data collection flow\n./run_tests.sh future # Future scalability examples\n```\n\n* **Cross-platform compatibility**: Tests work on Linux, macOS, and Windows\n* **No hardcoded paths**: Uses dynamic path resolution for open source distribution\n* **Complete documentation**: See [`tests/README.md`](tests/README.md) for detailed guidance\n\n* Ensures reliability during CLI usage and validates AI integration pipeline.\n\n---\n\n## \u2699\ufe0f Tech Stack\n\n* **Language**: Python 3.11+\n* **CLI**: click\n* **AWS SDK**: boto3\n* **LLM Integration**: OpenAI SDK (GPT-4, GPT-3.5) / Ollama\n* **Reporting**: Markdown generation\n* **Testing**: pytest\n* **Formatting/Linting**: black, flake8\n* **Version Control**: Git + GitHub\n* **CI/CD**: GitHub Actions (optional, for test automation)\n\n---\n\n## \ud83d\udca1 Novelty & Research Contributions\n\n* \u2705 **Fills a research gap** by combining **cost optimization** and **security auditing** in AWS within a single, context-aware tool.\n* \u2705 Uses **LLMs to generate human-readable explanations** for technical audit results, improving clarity for DevOps engineers.\n* \u2705 CLI-first design for **practical DevOps/SRE workflows**.\n* \u2705 Modular and extensible architecture for further research and productization.\n* \u2705 Evaluated in live AWS environments, providing measurable practical value.\n\n---\n\n## \ud83d\udce6 Final Deliverables\n\n* \u2705 **Working CLI tool** with core commands (`scan`, `explain`, `report`).\n* \u2705 **Structured JSON outputs** from audit for further processing.\n* \u2705 **Markdown reports** summarizing audit findings with GPT explanations.\n* \u2705 **Unit-tested core modules** (audit, correlator, GPT integration).\n* \u2705 **Clean, well-documented GitHub repository** with clear structure.\n* \u2705 **Demo video** showcasing the CLI tool in action.\n\n---\n\n\n## \ud83d\udee0\ufe0f Development Workflow\n\n* \u2705 Use **Git and GitHub** for version control.\n* \u2705 Use **VS Code with Python, Pylance, and Copilot** extensions.\n* \u2705 Use **GitHub Actions** for optional test automation.\n* \u2705 Format regularly using `black .` and lint using `flake8 .`.\n* \u2705 Test frequently with `pytest`.\n* \u2705 Commit using a **consistent structured format**:\n\n```\nfeat(audit): add EC2 idle instance detection\n```\n\n\u2705 Use branches for features:\n\n```\ngit checkout -b feat/cli-scan\n```\n\n\u2705 Push regularly and use Pull Requests for clean history.\n\n---\n\n## \ud83d\udee1\ufe0f Why Kenning CLI Matters\n\n* **Cloud cost optimization and security are deeply interconnected** in real-world DevOps and SRE environments.\n* Existing tools often focus on **either cost or security in isolation**, lacking context-aware compound risk analysis.\n* LLMs can transform raw audit data into **actionable insights** for engineers, improving decision-making and response times.\n\n---\n\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "AI-powered contextual risk analysis tool for AWS infrastructure",
"version": "1.0.11",
"project_urls": {
"Homepage": "https://github.com/kenningproject/kenning-cli"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eebbe721b45d13a81f1ba696a439b6b23332fe54cb4d1a434380080e0eaa11a9",
"md5": "34bff2d92902a0d669b3495eb8d7cbd5",
"sha256": "91f02a40e9ea1b5dd5238f88e862e522e6db2102436bff2c39ee97df599bb4e5"
},
"downloads": -1,
"filename": "kenning_cli-1.0.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "34bff2d92902a0d669b3495eb8d7cbd5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 69642,
"upload_time": "2025-08-09T15:41:41",
"upload_time_iso_8601": "2025-08-09T15:41:41.444806Z",
"url": "https://files.pythonhosted.org/packages/ee/bb/e721b45d13a81f1ba696a439b6b23332fe54cb4d1a434380080e0eaa11a9/kenning_cli-1.0.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-09 15:41:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kenningproject",
"github_project": "kenning-cli",
"github_not_found": true,
"lcname": "kenning-cli"
}
JSON
