Initial commit: AWS Security Scanner v1.0

Author: hell-99

.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: Security Scanner CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.8, 3.9, '3.10', '3.11']
+
+    steps:
+    - uses: actions/checkout@v3
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+    
+    - name: Run scanner in mock mode
+      run: |
+        python scanner.py --mock --output json --report-file ci-test-report
+    
+    - name: Verify report generated
+      run: |
+        if [ ! -f "ci-test-report.json" ]; then
+          echo "Error: Report not generated"
+          exit 1
+        fi
+        echo "Report successfully generated"
+    
+    - name: Run tests (when available)
+      run: |
+        # Uncomment when tests are added
+        # python -m pytest tests/ -v
+        echo "Tests not yet implemented"
+    
+    - name: Upload test report as artifact
+      uses: actions/upload-artifact@v3
+      with:
+        name: test-report-python-${{ matrix.python-version }}
+        path: ci-test-report.json
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+    
+    - name: Install linting tools
+      run: |
+        python -m pip install --upgrade pip
+        pip install flake8 black
+    
+    - name: Check code style with black
+      run: |
+        black --check scanners/ scanner.py || true
+    
+    - name: Lint with flake8
+      run: |
+        # Stop the build if there are Python syntax errors or undefined names
+        flake8 scanners/ scanner.py --count --select=E9,F63,F7,F82 --show-source --statistics || true
+        # Exit-zero treats all errors as warnings
+        flake8 scanners/ scanner.py --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics || true

.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Reports
+*.html
+*.json
+security-report*
+
+# AWS Credentials
+.aws/
+credentials
+config
+
+# Test coverage
+.coverage
+htmlcov/
+.pytest_cache/

ARCHITECTURE.md

@@ -0,0 +1,264 @@
+# Project Architecture & Design
+
+## Overview
+
+AWS Security Scanner is a Python-based CLI tool designed to identify common security misconfigurations in AWS environments. The tool follows a modular architecture that allows easy extension with new security scanners.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                       CLI Interface                         │
+│                      (scanner.py)                           │
+│  - Command-line argument parsing                            │
+│  - Output formatting (Console, JSON, HTML)                  │
+│  - Report generation                                        │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   Scanner Modules                           │
+│                  (scanners/ package)                        │
+│                                                             │
+│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐  │
+│  │ S3Scanner     │  │ EC2Scanner    │  │ IAMScanner    │  │
+│  │               │  │  (planned)    │  │  (planned)    │  │
+│  └───────────────┘  └───────────────┘  └───────────────┘  │
+│                                                             │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   Data Layer                                │
+│                                                             │
+│  ┌────────────────────┐         ┌────────────────────┐     │
+│  │   Mock Data        │         │   AWS Boto3 SDK    │     │
+│  │  (JSON files)      │         │   (future impl)    │     │
+│  └────────────────────┘         └────────────────────┘     │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Design Principles
+
+### 1. Modularity
+Each service scanner (S3, EC2, IAM) is a separate module that:
+- Can be developed and tested independently
+- Follows a consistent interface pattern
+- Returns findings in a standard format
+
+### 2. Abstraction
+The scanner supports both mock and real AWS data:
+- **Mock Mode**: Uses JSON files for testing without AWS credentials
+- **Real Mode**: Uses boto3 to query actual AWS resources (future)
+
+### 3. Extensibility
+Adding a new scanner requires:
+1. Creating a new scanner class in `scanners/`
+2. Adding mock data in `mock_data/`
+3. Registering the scanner in `scanner.py`
+
+### 4. Severity-Based Reporting
+Findings are categorized by severity:
+- **CRITICAL**: Immediate action required (e.g., public sensitive data)
+- **HIGH**: Significant security risk (e.g., missing encryption)
+- **MEDIUM**: Important but not urgent (e.g., versioning disabled)
+- **LOW**: Best practice recommendations (e.g., logging disabled)
+
+## Core Components
+
+### 1. Scanner Base Pattern
+
+Each scanner follows this pattern:
+
+```python
+class ServiceScanner:
+    def __init__(self, mock_mode: bool = True):
+        """Initialize with mock or real mode"""
+        
+    def scan(self) -> List[Dict[str, Any]]:
+        """Run all security checks, return findings"""
+        
+    def _check_specific_issue(self, resource: Dict) -> None:
+        """Individual security check"""
+        
+    def get_summary(self) -> Dict[str, int]:
+        """Get severity summary"""
+```
+
+### 2. Finding Format
+
+Standard finding structure:
+
+```python
+{
+    'service': 'S3',                          # AWS service
+    'resource': 'bucket-name',                # Resource identifier
+    'severity': 'CRITICAL',                   # CRITICAL, HIGH, MEDIUM, LOW
+    'issue': 'Public Access Enabled',         # Short issue title
+    'description': 'Detailed explanation',    # Full description
+    'remediation': 'CLI commands to fix'      # Step-by-step fix
+}
+```
+
+### 3. CLI Interface
+
+Uses Click for command-line interface:
+- `--mock`: Enable mock mode (default: True)
+- `--services`: Specify services to scan
+- `--output`: Choose output format (console, json, html)
+- `--report-file`: Specify output filename
+
+### 4. Report Generation
+
+Three output formats:
+- **Console**: Colored, formatted terminal output
+- **JSON**: Machine-readable for automation
+- **HTML**: Professional, shareable reports
+
+## Security Checks
+
+### S3 Scanner
+
+| Check | Severity Logic | Description |
+|-------|----------------|-------------|
+| Public Access | CRITICAL if sensitive data, LOW if tagged public | Checks ACLs for AllUsers grants |
+| Public Policy | Always CRITICAL | Checks bucket policies for wildcard principals |
+| Encryption | HIGH if sensitive keywords, MEDIUM otherwise | Checks default encryption status |
+| Versioning | MEDIUM if critical data, LOW otherwise | Checks if versioning enabled |
+| Logging | Always LOW | Checks if access logging enabled |
+
+Sensitivity detection uses keywords: `financial`, `customer`, `personal`, `pii`, `records`, `backup`
+
+## Future Enhancements
+
+### Phase 2: EC2 Scanner
+- Security group rules (0.0.0.0/0 on sensitive ports)
+- Unencrypted EBS volumes
+- IMDSv1 usage detection
+- Public IP assignments
+
+### Phase 3: IAM Scanner
+- Users without MFA
+- Overly permissive policies
+- Unused access keys (>90 days)
+- Root account usage
+
+### Phase 4: Advanced Features
+- Auto-remediation execution (with confirmation)
+- Slack/email notifications
+- Dashboard for trend analysis
+- Integration with AWS Security Hub
+- Custom compliance frameworks (PCI, HIPAA, etc.)
+
+## Testing Strategy
+
+### Current State
+- Manual testing with mock data
+- Validated against 5 different S3 bucket scenarios
+
+### Planned
+- Unit tests for each scanner module
+- Integration tests with real AWS (test account)
+- CI/CD pipeline for automated testing
+- Code coverage reporting
+
+## Performance Considerations
+
+### Current
+- Mock mode: Instant (no API calls)
+- Scan complexity: O(n) where n = number of resources
+
+### Future Optimizations
+- Parallel scanning across services
+- Caching of AWS API responses
+- Rate limiting awareness
+- Batch API calls where possible
+
+## Deployment Options
+
+### Local Development
+```bash
+python scanner.py --mock
+```
+
+### AWS Lambda
+- Package as Lambda function
+- Scheduled CloudWatch Events
+- Write findings to S3/DynamoDB
+- SNS notifications for critical findings
+
+### CI/CD Integration
+```yaml
+# .gitlab-ci.yml or .github/workflows/
+- name: Security Scan
+  run: |
+    python scanner.py --no-mock --output json
+    # Parse and fail pipeline if critical findings
+```
+
+### Docker Container
+```dockerfile
+FROM python:3.11-slim
+COPY . /app
+WORKDIR /app
+RUN pip install -r requirements.txt
+ENTRYPOINT ["python", "scanner.py"]
+```
+
+## Contributing Guidelines
+
+When adding new features:
+
+1. **New Scanner**: Follow the S3Scanner pattern
+2. **New Check**: Add to existing scanner, maintain severity logic
+3. **Mock Data**: Create realistic test scenarios
+4. **Documentation**: Update this file and README
+5. **Testing**: Add unit tests (when framework ready)
+
+## Security & Permissions
+
+### Required IAM Permissions (Real Mode)
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:GetBucketPublicAccessBlock",
+        "s3:GetBucketAcl",
+        "s3:GetBucketPolicy",
+        "s3:GetBucketVersioning",
+        "s3:GetBucketLogging",
+        "s3:GetEncryptionConfiguration",
+        "s3:ListAllMyBuckets"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+### Best Practices
+- Never commit AWS credentials
+- Use IAM roles when running in AWS
+- Rotate access keys regularly
+- Use read-only permissions
+- Enable AWS CloudTrail for audit logging
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Contact
+
+For questions or contributions:
+- GitHub Issues: [Report bugs or request features]
+- Pull Requests: [Contribute code]
+- Email: [Your contact]
+
+---
+
+**Built with ❤️ by Twinkle Kamdar**