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.
┌─────────────────────────────────────────────────────────────┐
│ 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) │ │
│ └────────────────────┘ └────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
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
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)
Adding a new scanner requires:
- Creating a new scanner class in
scanners/ - Adding mock data in
mock_data/ - Registering the scanner in
scanner.py
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)
Each scanner follows this pattern:
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"""Standard finding structure:
{
'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
}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
Three output formats:
- Console: Colored, formatted terminal output
- JSON: Machine-readable for automation
- HTML: Professional, shareable reports
| 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
- Security group rules (0.0.0.0/0 on sensitive ports)
- Unencrypted EBS volumes
- IMDSv1 usage detection
- Public IP assignments
- Users without MFA
- Overly permissive policies
- Unused access keys (>90 days)
- Root account usage
- Auto-remediation execution (with confirmation)
- Slack/email notifications
- Dashboard for trend analysis
- Integration with AWS Security Hub
- Custom compliance frameworks (PCI, HIPAA, etc.)
- Manual testing with mock data
- Validated against 5 different S3 bucket scenarios
- Unit tests for each scanner module
- Integration tests with real AWS (test account)
- CI/CD pipeline for automated testing
- Code coverage reporting
- Mock mode: Instant (no API calls)
- Scan complexity: O(n) where n = number of resources
- Parallel scanning across services
- Caching of AWS API responses
- Rate limiting awareness
- Batch API calls where possible
python scanner.py --mock- Package as Lambda function
- Scheduled CloudWatch Events
- Write findings to S3/DynamoDB
- SNS notifications for critical findings
# .gitlab-ci.yml or .github/workflows/
- name: Security Scan
run: |
python scanner.py --no-mock --output json
# Parse and fail pipeline if critical findingsFROM python:3.11-slim
COPY . /app
WORKDIR /app
RUN pip install -r requirements.txt
ENTRYPOINT ["python", "scanner.py"]When adding new features:
- New Scanner: Follow the S3Scanner pattern
- New Check: Add to existing scanner, maintain severity logic
- Mock Data: Create realistic test scenarios
- Documentation: Update this file and README
- Testing: Add unit tests (when framework ready)
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetBucketPublicAccessBlock",
"s3:GetBucketAcl",
"s3:GetBucketPolicy",
"s3:GetBucketVersioning",
"s3:GetBucketLogging",
"s3:GetEncryptionConfiguration",
"s3:ListAllMyBuckets"
],
"Resource": "*"
}
]
}- 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
MIT License - see LICENSE file for details
For questions or contributions:
- GitHub Issues: [Report bugs or request features]
- Pull Requests: [Contribute code]
- Email: [Your contact]
Built with ❤️ by Twinkle Kamdar