SIP-SecurityHub-Mapping

AWS Lambda application that maps SIP (Security Information Program) question IDs to AWS Security Hub control IDs and generates comprehensive security reports.

Features

• Security Hub Integration: Retrieves active findings from AWS Security Hub
• SIP Mapping: Maps SIP question IDs to Security Hub control IDs
• Report Generation: Creates detailed JSON reports with statistics
• Secure by Default: Implements AWS security best practices
• CDK Support: Modern Infrastructure as Code deployment
• Customer Bucket Support: Option to use existing S3 buckets
• Modular Architecture: Clean, maintainable codebase

🚀 Quick Start

Option 1: CDK Deployment (Recommended)

# One-command deployment with CDK
./deploy-cdk.sh

Option 2: Manual CDK Deployment

# Install dependencies
make venv && source venv/bin/activate
make install install-dev

# Install CDK dependencies (npm + Python)
cd cdk && npm install && cd ..
pip install -r cdk/requirements.txt

# Bootstrap and deploy (run from project root, not cdk/)
npx cdk bootstrap
npx cdk deploy --require-approval never

📋 What CDK Creates

CDK automatically creates:

• ✅ 3 S3 buckets with unique names and security best practices
• ✅ Lambda function with automatic code deployment
• ✅ IAM roles with least-privilege permissions
• ✅ SIP mapping file uploaded to mapping bucket
• ✅ CloudWatch logs with retention policies
• ✅ Access logging and lifecycle policies

Installation

Using pip (recommended)

# Install from source
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

Using make

# Create virtual environment and install dependencies
make venv
source venv/bin/activate
make install install-dev

Development

Setup Development Environment

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install package in development mode with all dependencies
pip install -e ".[dev]"

Running Tests

# Run all tests
make test

# Or directly with pytest
pytest test/ -v

Code Quality

# Format code
make format

# Lint code
make lint

# Type checking
mypy src/

Legacy CloudFormation Deployment

Deploy with CDK-managed buckets (recommended)

# Install dependencies first
make install

# Deploy with new buckets
make deploy-new

Deploy with existing buckets

# Install dependencies
make install

# First validate your buckets
make validate-buckets BUCKETS="my-report-bucket my-mapping-bucket"

# Then deploy
make deploy-existing

Detailed Deployment

Prerequisites

# Configure AWS CLI
aws configure

# Verify permissions
aws sts get-caller-identity

Manual Deployment Steps

# 1. Install dependencies
make install

# 2. Package Lambda function
make package

# 3. Upload Lambda code to S3
aws s3 cp lambda_function.zip s3://your-code-bucket/

# 4. Deploy CloudFormation stack
aws cloudformation deploy \
  --template-file src/template.yaml \
  --stack-name sip-security-hub-mapping \
  --parameter-overrides \
    S3BucketName=your-report-bucket \
    MappingBucketName=your-mapping-bucket \
    CodeS3Bucket=your-code-bucket \
  --capabilities CAPABILITY_IAM

# 5. Upload SIP mapping file
aws s3 cp src/sip-sechub-mapping.json s3://your-mapping-bucket/

Optional Parameters

• UseExistingBuckets=true/false - Use existing vs new buckets
• KMSKeyId=your-key-id - Enable KMS encryption
• S3FolderName=custom-folder - Custom report folder name

Architecture

src/
├── sip_security_hub_mapping/     # Core application package
│   ├── config.py                 # Configuration management
│   ├── models.py                 # Data models
│   ├── security_hub_client.py    # Security Hub operations
│   ├── s3_client.py              # S3 operations
│   ├── mapping_service.py        # SIP mapping logic
│   └── report_generator.py       # Report orchestration
├── lambda_function.py            # Lambda entry point
└── template.yaml                 # CloudFormation template

cdk/
├── app.py                        # CDK application entry point
├── sip_security_hub_stack.py     # CDK stack definition
└── requirements.txt              # CDK dependencies

Security Features

✅ S3 Encryption: Server-side encryption with AES256/KMS
✅ Public Access Blocked: All public access configurations disabled
✅ Versioning Enabled: Object versioning for data protection
✅ Access Logging: Comprehensive audit trails
✅ SSL/HTTPS Enforced: Encrypted transport mandatory
✅ Least Privilege IAM: Minimal required permissions

Environment Variables

Variable	Description	Default
S3_BUCKET_NAME	Report storage bucket	Required
S3_FOLDER_NAME	Report folder path	security-hub-reports
MAPPING_BUCKET	SIP mapping file bucket	Required
MAPPING_FILE	SIP mapping filename	sip-sechub-mapping.json

Generated Reports

1. Security Hub Report: Complete findings grouped by SecurityControlId
2. SIP Mapping Report: SIP question IDs mapped to Security Hub findings

Customer Bucket Requirements

When using existing buckets, ensure they meet security requirements:

• See CUSTOMER-BUCKET-REQUIREMENTS.md
• Use validation script: python scripts/validate-bucket-security.py <buckets>

Security Compliance

All AWS Security Hub S3-related findings have been addressed:

• See S3-SECURITY-FIXES.md for detailed fixes

Documentation

• Customer Bucket Requirements
• Security Fixes Documentation
• Source Code Documentation

🆚 CDK vs CloudFormation

Feature	CDK	CloudFormation
Setup Complexity	✅ Simple	❌ Complex
Bucket Management	✅ Automatic	❌ Manual
Code Deployment	✅ Automatic	❌ Manual upload
Security Defaults	✅ Built-in	❌ Manual config
Rollback	✅ Clean	❌ Partial resources
Development	✅ Type-safe	❌ YAML/JSON

Recommendation: Use CDK for new deployments. CloudFormation templates are kept for compatibility.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting: make test lint
5. Submit a pull request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.