⚠️ DEVELOPMENT BRANCH WARNING
This is theagent-v2-devbranch - NOT PRODUCTION READY
This branch contains features not yet in the main branch
Current Status: Development and Testing Only
Zero-Shield CLI is an AI-native security orchestrator that translates natural language into immediate AWS security actions. Built for security analysts, DevSecOps engineers, and incident responders who need rapid cloud threat investigation and remediation.
Branch: agent-v2-dev
Version: v2.0.0-dev
Status: Development and Testing Only
Last Updated: March 17, 2026
This development branch contains:
- 152 automated tests (97.4% pass rate, 4 skipped on Windows)
- 5-layer security hardening (development testing)
- 32 AWS actions across 14 services
- Comprehensive documentation and validation
📺 Watch Live Demo: Zero-Shield CLI in Action - See the March 3, 2026 commit demonstrated live!
Choose your deployment environment:
| Environment | Setup Time | Best For |
|---|---|---|
| AWS CloudShell | 2 minutes | Production use, inherits IAM roles |
| Local Development | 5 minutes | Development, testing, customization |
Platform Compatibility:
- ✅ Windows (Windows 10+) - Full support with ANSI colors
- ✅ Linux/Unix (Ubuntu 20.04+) - Native POSIX support
- ✅ macOS (macOS 12+) - Native terminal compatibility
- ✅ AWS CloudShell - Inherits IAM credentials automatically
Fastest Start (CloudShell):
# 1. Upload zero_shield_cli.py to CloudShell
# 2. Configure environment
cp environments/cloudshell/.env.example .env
# Edit .env with your GITHUB_TOKEN and QUARANTINE_SG_ID
# 3. Run
python3 zero_shield_cli.pyLocal Development:
# 1. Clone repository
git clone https://github.com/jerisadeumai/zero-shield-cli.git
cd zero-shield-cli
# 2. Install dependencies
pip install -r requirements.txt
# 3. Configure environment
cp environments/local/.env.example .env
# Edit .env with AWS credentials and GITHUB_TOKEN
# 4. Run
python3 zero_shield_cli.pyFuture releases will include additional deployment methods:
- Docker - Containerized deployment with pre-configured environment
- EC2 Instance - Direct deployment on AWS EC2 with IAM role integration
- AWS Lambda - Serverless function deployment for event-driven security
- Container Platforms - Kubernetes, ECS, and other orchestration platforms
Planned AI Model Integrations:
- Amazon Nova AI Models - Integration with Amazon's Nova foundation models for enhanced reasoning
- AWS Bedrock - Support for Claude, Llama, and other Bedrock-hosted models
- AWS SageMaker - Custom model deployment and fine-tuning capabilities
These are planned for future releases and not available in v2.0.0-dev preview.
# Natural language security operations
> "What instances are currently running?"
> "Inspect the security groups for instance i-0123456789abcdef0"
> "This instance looks compromised. Isolate it immediately."
> "Show me all GuardDuty findings from the last 24 hours"
> "What's the cost impact of running these instances?"Key Capabilities:
- 32 AWS Actions across 14 service categories (EC2, IAM, S3, RDS, Lambda, CloudWatch, GuardDuty, KMS, DynamoDB, EFS, WAF, CloudTrail, Cost Explorer, CloudWatch Logs)
- 5 LLM Models (GPT-4o, Llama-3.3-70B, Phi-4, DeepSeek-V3, gpt-4o-mini)
- OODA Loop Framework (Observe-Orient-Decide-Act)
- Security Hardened (5-layer credential redaction, encrypted state)
- Context-Aware Memory (Knowledge Graph survives reboots)
- Quick Start Guide - 5-minute setup
- AWS Setup Guide - IAM policies & permissions
- Command Reference - All available commands
- Usage Examples - Real-world scenarios
- CloudShell Setup - AWS CloudShell deployment
- Local Development - Local environment configuration
- Architecture Overview - OODA framework, memory management
- OODA Loop Details - Cognitive cycle implementation
- Test Reports - Comprehensive testing results
- Validation Reports - Complete audit history
Zero-Shield has undergone extensive security hardening (Development Testing):
- 3,069 Lines Analyzed - Development Testing: Zero critical bugs found
- 100% Code Coverage (Development Testing) - 152 tests with 97.4% pass rate (148 passing, 4 skipped on Windows)
- 5-Layer Credential Redaction (Development Testing) - AWS credentials never logged
- Encrypted State Files (Development Testing) - Session data protected at rest
- Human-in-the-Loop (Development Testing) - Destructive actions require confirmation
View detailed validation reports →
Zero-Shield CLI is built on a comprehensive formal specification with property-based testing:
- 50 Validated Requirements - Complete system requirements using EARS protocol
- 30 Correctness Properties - Formal properties with property-based testing
- 152 Total Tests - 8 action detection + 66 comprehensive + 35 security + 44 property-based tests
- 97.4% Test Pass Rate - 148 tests passing, 4 skipped (Windows file permission tests)
- Property-Based Testing - Universal correctness guarantees using Hypothesis library
- Round-Trip Integrity - Session state and Knowledge Graph persistence validated
- Security Properties - Credential redaction, prompt injection prevention, HITL confirmations
The comprehensive specification covers:
- REPL interface and OODA loop cognitive cycle
- 32 AWS actions across 14 service categories
- Multi-model LLM support (5 models)
- 5-layer security architecture
- Cross-platform compatibility (Unix/Linux, Windows, AWS CloudShell)
- Encrypted persistent storage with atomic writes
- Rate limit handling and API resilience
The agent-v2-dev branch was developed extensively using Kiro - an AI-powered development assistant that enabled rapid, specification-driven development:
Kiro-Powered Development Artifacts:
- Comprehensive Specification - 50 requirements, 30 correctness properties, complete implementation plan
- Custom Steering Rules - Project-specific AI guidance for product, technology stack, structure, and communication
- Property-Based Testing - 44 automated correctness properties using Hypothesis library
- Documentation Generation - Automated synchronization between code and documentation
- Quality Assurance - Systematic validation of all 50 requirements and 30 properties
Development Methodology:
- Specification-First - Formal requirements and design documents created before implementation
- Property-Based Testing - Universal correctness guarantees through automated property validation
- Iterative Refinement - Continuous validation against specification throughout development
- Documentation Sync - Automated verification that documentation matches implementation
Acknowledgments:
- Developed with Kiro - AI-powered development assistant
- AWS services integration via AWS SDK for Python (Boto3)
- LLM inference via GitHub Models API
- Property-based testing via Hypothesis
Special thanks to:
- @awslabs - AWS SDK and tools
- @aws - AWS platform and services
- Amazon Web Services for CloudShell environment
This development approach demonstrates how AI-assisted development with formal specifications can produce high-quality, well-tested, and thoroughly documented software.
Zero-Shield requires specific AWS IAM permissions. We provide three policy levels:
| Policy | Use Case | Permissions |
|---|---|---|
| Minimal | Read-only investigation | EC2 describe, IAM list |
| Standard | Most security operations | + S3, RDS, Lambda, CloudWatch |
| Full | Complete functionality | + Quarantine, key deactivation |
Try these example commands after setup:
# Investigation workflow
/target i-0123456789abcdef0 # Set target instance
inspect instance # Get detailed info
check its security groups # Analyze SG rules
what vpc is it in? # VPC information
# Security assessment
list guardduty findings # Recent threats
show me iam users without mfa # IAM security gaps
what s3 buckets are public? # Storage exposure
# Cost analysis
estimate cost for this instance # Cost projection
show 7 day spend breakdown # Recent spendingCurrent Version: v2.0.0-dev
Status: Development Branch - Not Yet Released
Branch: agent-v2-dev
Last Main Branch Commit: March 3, 2026 (commit: d3754fc)
Development Branch Updates: March 13-17, 2026
Development Quality Metrics:
- 3,069 lines of code in main script (zero_shield_cli.py)
- 152 total tests with 97.4% pass rate (148 passing, 4 skipped on Windows)
- 8 action detection tests (tests/test_action_detection.py)
- 66 comprehensive E2E tests (tests/test_comprehensive_e2e.py)
- 35 security validation tests (tests/test_security_fixes.py)
- 44 property-based tests:
- Platform-specific: Windows (4 tests skipped - file permission tests), Linux/Unix/macOS/CloudShell (all 152 tests run)
Welcoming contributions! See the Contributing Guide for details.
Quick contribution setup:
git clone https://github.com/jerisadeumai/zero-shield-cli.git
cd zero-shield-cli
pip install -r requirements.txt
python3 -m pytest tests/ # Run all 152 tests- Issues: GitHub Issues
- Documentation: Command Reference
- Setup Help: Quick Start Guide
This project is licensed under the MIT License - see the LICENSE file for details.
Principal Architect: Jeri L3D | JeriSadeuM
Repository: https://github.com/jerisadeumai/zero-shield-cli
Live Demo: YouTube - Zero-Shield CLI in Action (Demonstrates commit 9c56283 from March 3, 2026)
Copyright © 2026 Jeri L3D | JeriSadeuM | All Rights Reserved
Zero-Shield CLI: Where AI meets AWS security at the speed of thought.