lambda-security-scanner 1.0.0__tar.gz

lambda_security_scanner-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toc Consulting
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lambda_security_scanner-1.0.0/PKG-INFO

@@ -0,0 +1,497 @@
+Metadata-Version: 2.4
+Name: lambda-security-scanner
+Version: 1.0.0
+Summary: A comprehensive AWS Lambda security scanner with multi-framework compliance mapping
+Author-email: Toc Consulting <tarek@tocconsulting.fr>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/TocConsulting/lambda-security-scanner
+Project-URL: Documentation, https://github.com/TocConsulting/lambda-security-scanner#readme
+Project-URL: Repository, https://github.com/TocConsulting/lambda-security-scanner
+Project-URL: Issues, https://github.com/TocConsulting/lambda-security-scanner/issues
+Keywords: aws,lambda,serverless,security,compliance,scanner,cloud,audit
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: boto3>=1.26.0
+Requires-Dist: botocore>=1.29.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: jinja2>=3.1.6
+Provides-Extra: dev
+Requires-Dist: pytest>=7.2.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/TocConsulting/lambda-security-scanner/main/assets/lambda-security-scanner-logo.png" alt="Lambda Security Scanner" style="max-width: 100%; height: auto;">
+</p>
+
+<p align="center">
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-brightgreen.svg" alt="License: MIT"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python"></a>
+  <a href="https://aws.amazon.com/lambda/"><img src="https://img.shields.io/badge/AWS-Lambda-orange.svg" alt="AWS"></a>
+</p>
+
+A comprehensive AWS Lambda security scanner with 19 security checks across 5 categories and compliance mapping for 10 frameworks (81 controls). Features multi-threaded scanning, secret detection in environment variables, and interactive HTML dashboards.
+
+## Key Features
+
+### **Comprehensive Security Analysis**
+- **Function Configuration**: Deprecated runtime detection, timeout tuning, environment variable secret scanning, ephemeral storage, external layers, X-Ray tracing, dead letter queues
+- **Access Control**: Resource policy public access, function URL authentication, CORS wildcard origins, overly permissive execution roles, shared role detection
+- **Network Security**: VPC configuration, multi-AZ deployment, unrestricted security group egress
+- **Logging & Monitoring**: CloudWatch log group validation, log retention policies, reserved concurrency
+- **Code & Supply Chain**: Code signing configuration, event source mapping failure destinations
+
+### **Compliance Frameworks**
+- **AWS Foundational Security Best Practices (FSBP)**: 5 Lambda-specific controls
+- **CIS AWS Compute Services Benchmark**: 8 controls (scanner-defined IDs mapped to the benchmark's Lambda guidance; see note below)
+- **PCI DSS v4.0.1**: 8 controls
+- **HIPAA Security Rule**: 9 controls
+- **SOC 2**: 11 controls
+- **ISO 27001:2022**: 11 controls
+- **ISO 27017:2015**: 4 cloud security controls
+- **ISO 27018:2019**: 5 PII protection controls
+- **GDPR (EU) 2016/679**: 8 controls
+- **NIST SP 800-53 Rev5**: 12 controls
+
+### **Performance & Usability**
+- **Multi-threaded Scanning**: Parallel function analysis with ThreadPoolExecutor
+- **Rich Console Output**: Progress bars, colored output, and formatted tables
+- **Multiple Report Formats**: JSON, CSV, HTML, and compliance-specific reports
+- **Beautiful HTML Reports**: Interactive dashboard with Chart.js visualizations
+- **Flexible Targeting**: Scan all functions, specific names, or exclude by name
+
+### **Production Ready**
+- **Modular Architecture**: Facade pattern with 5 dedicated checker modules
+- **Thread-safe Sessions**: Thread-local boto3 session management
+- **Graceful Degradation**: AccessDenied errors don't crash scans
+- **Mutual Exclusion Scoring**: Overlapping check variants use highest deduction only
+
+## Quick Start
+
+### Installation
+
+```bash
+# Install from source
+git clone https://github.com/TocConsulting/lambda-security-scanner.git
+cd lambda-security-scanner
+pip install .
+```
+
+### Docker Installation
+
+```bash
+# Build from source
+docker build -t lambda-security-scanner .
+```
+
+### Basic Usage
+
+```bash
+# Scan all Lambda functions
+lambda-security-scanner security
+
+# Scan with specific AWS profile
+lambda-security-scanner security --profile production
+
+# Scan specific functions only
+lambda-security-scanner security -n my-function -n other-function
+
+# Exclude specific functions
+lambda-security-scanner security --exclude-function test-func
+
+# Compliance report only
+lambda-security-scanner security --compliance-only
+
+# JSON report only, quiet mode (for CI/CD)
+lambda-security-scanner security -f json -q
+```
+
+## Commands
+
+### Security Command
+
+Scan Lambda functions for security vulnerabilities and compliance issues.
+
+```bash
+lambda-security-scanner security [OPTIONS]
+
+Options:
+  -n, --function-name TEXT       Specific function name(s) to scan (multiple)
+  --exclude-function TEXT        Function name(s) to exclude
+  --compliance-only              Generate compliance report only
+  -r, --region TEXT              AWS region (default: us-east-1)
+  -p, --profile TEXT             AWS profile name
+  -o, --output-dir TEXT          Output directory (default: ./output)
+  -f, --output-format TEXT       Report format: json, csv, html, all (default: all)
+  -w, --max-workers INTEGER      Worker threads (default: 5)
+  -q, --quiet                    Suppress console output except errors
+  -d, --debug                    Enable debug logging
+  -h, --help                     Show help
+
+# Top-level options (before the 'security' command):
+#   lambda-security-scanner --version
+#   lambda-security-scanner --help
+```
+
+**Examples:**
+```bash
+# Scan all functions with default settings
+lambda-security-scanner security
+
+# Scan specific functions in a different region
+lambda-security-scanner security -n my-api -n my-worker -r eu-west-1
+
+# Fast compliance-only scan with HTML output
+lambda-security-scanner security --compliance-only -f html -p production
+
+# High-performance scan with more threads
+lambda-security-scanner security -w 20 -r eu-west-1
+
+# JSON report only, quiet mode (for CI/CD)
+lambda-security-scanner security -f json -q
+```
+
+## Security Checks
+
+### 19 Checks Across 5 Categories
+
+| ID  | Check                                    | Severity          | Category              |
+|-----|------------------------------------------|-------------------|-----------------------|
+| A.1 | Deprecated/EOL runtime                   | HIGH/CRITICAL/LOW | Function Config       |
+| A.2 | Maximum timeout (900s)                   | LOW               | Function Config       |
+| A.3 | Environment variable secrets             | CRITICAL/HIGH     | Function Config       |
+| A.4 | Large ephemeral storage                  | LOW               | Function Config       |
+| A.5 | External Lambda layers                   | MEDIUM            | Function Config       |
+| A.6 | X-Ray tracing disabled                   | LOW               | Function Config       |
+| A.7 | No dead letter queue                     | LOW               | Function Config       |
+| B.1 | Resource policy public access            | CRITICAL          | Access Control        |
+| B.2 | Function URL no authentication           | CRITICAL          | Access Control        |
+| B.3 | Function URL CORS allows all origins     | HIGH              | Access Control        |
+| B.4 | Overly permissive execution role         | CRITICAL/HIGH     | Access Control        |
+| B.5 | Shared execution role                    | HIGH              | Access Control        |
+| C.1 | No VPC configuration                     | LOW               | Network Security      |
+| C.2 | VPC single AZ                            | MEDIUM            | Network Security      |
+| C.3 | Unrestricted SG egress                   | MEDIUM            | Network Security      |
+| D.1 | Log group missing/no retention           | MEDIUM            | Logging & Monitoring  |
+| D.2 | No reserved concurrency                  | LOW               | Logging & Monitoring  |
+| E.1 | No code signing                          | MEDIUM/LOW        | Code & Supply Chain   |
+| E.2 | ESM without failure destination          | MEDIUM            | Code & Supply Chain   |
+
+### Secret Detection in Environment Variables (A.3)
+
+The scanner decodes and scans Lambda environment variables for exposed secrets:
+
+| Pattern | Examples |
+|---------|----------|
+| AWS Access Keys | `AKIA...`, `ASIA...` |
+| AWS Secret Keys | `aws_secret_access_key=...` |
+| Passwords | `PASSWORD=`, `DB_PASSWORD=`, `SECRET_KEY=` |
+| Private Keys | `-----BEGIN PRIVATE KEY-----` |
+| GitHub Tokens | `ghp_...`, `gho_...`, `ghs_...` |
+| API Keys | `api_key=`, `api_token=`, `AUTH_TOKEN=` |
+| Connection Strings | `postgres://user:pass@host/db` |
+| SaaS Tokens | Slack, Stripe (`sk_live_`), Twilio, SendGrid |
+
+**Safe references are not flagged.** A secret-named variable whose value is a managed-secret reference (a Secrets Manager / SSM / KMS ARN, an SSM parameter path like `/app/db/pwd`, or a CloudFormation `{{resolve:...}}` dynamic reference) is the AWS-recommended pattern and is treated as clean, not as a leaked secret. Trivial config values (booleans, ports, environment names) are likewise ignored.
+
+## Compliance Frameworks
+
+| Framework | Controls | Focus |
+|-----------|----------|-------|
+| AWS-FSBP | 5 | Lambda-specific Security Hub controls |
+| CIS | 8 | Compute Services Benchmark |
+| PCI DSS v4.0.1 | 8 | Payment card data protection |
+| HIPAA | 9 | Healthcare data security |
+| SOC 2 | 11 | Service organization controls |
+| ISO 27001:2022 | 11 | Information security management |
+| ISO 27017:2015 | 4 | Cloud security controls |
+| ISO 27018:2019 | 5 | PII protection in cloud |
+| GDPR | 8 | EU data protection regulation |
+| NIST 800-53 Rev5 | 12 | Federal security controls |
+
+> **Note on control IDs:** Most frameworks use their official citations (e.g. HIPAA `164.312(a)(1)`, ISO 27001 `A.5.15`, SOC 2 `CC6.1`, NIST `AC-3`). The **CIS** entries map to the real **CIS AWS Compute Services Benchmark** Lambda guidance, but the `CIS-Lambda.N` identifiers are this scanner's own labels, not the benchmark's official recommendation numbers (which are section `5.x`). They are an alignment aid, not verbatim CIS control numbers.
+
+## Docker Usage
+
+### Basic Docker Commands
+
+```bash
+# Show help
+docker run --rm lambda-security-scanner --help
+
+# Show security command help
+docker run --rm lambda-security-scanner security --help
+```
+
+### Security Scanning with Docker
+
+```bash
+# Scan using mounted AWS credentials
+docker run --rm \
+  -v ~/.aws:/root/.aws:ro \
+  -v $(pwd)/output:/app/output \
+  lambda-security-scanner security
+
+# Scan with specific AWS profile
+docker run --rm \
+  -v ~/.aws:/root/.aws:ro \
+  -v $(pwd)/output:/app/output \
+  lambda-security-scanner security --profile production
+
+# Scan specific functions
+docker run --rm \
+  -v ~/.aws:/root/.aws:ro \
+  -v $(pwd)/output:/app/output \
+  lambda-security-scanner security -n my-function
+```
+
+### Using Environment Variables for AWS Credentials
+
+```bash
+docker run --rm \
+  -e AWS_ACCESS_KEY_ID \
+  -e AWS_SECRET_ACCESS_KEY \
+  -e AWS_DEFAULT_REGION=us-east-1 \
+  -v $(pwd)/output:/app/output \
+  lambda-security-scanner security
+
+# With session token (for temporary credentials/assumed roles)
+docker run --rm \
+  -e AWS_ACCESS_KEY_ID \
+  -e AWS_SECRET_ACCESS_KEY \
+  -e AWS_SESSION_TOKEN \
+  -e AWS_DEFAULT_REGION=us-east-1 \
+  -v $(pwd)/output:/app/output \
+  lambda-security-scanner security
+```
+
+### Docker Volume Mounts
+
+| Mount | Purpose |
+|-------|---------|
+| `-v ~/.aws:/root/.aws:ro` | Mount AWS credentials (read-only) |
+| `-v $(pwd)/output:/app/output` | Save reports to local directory |
+
+## Prerequisites
+
+### Python Requirements
+- Python 3.10 or higher
+- Required packages (installed automatically):
+  - `boto3>=1.26.0`
+  - `botocore>=1.29.0`
+  - `rich>=13.0.0`
+  - `click>=8.1.0`
+  - `jinja2>=3.1.0`
+
+### AWS Requirements
+- AWS credentials configured (via AWS CLI, environment variables, or IAM roles)
+- Required permissions:
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [{
+        "Effect": "Allow",
+        "Action": [
+            "lambda:ListFunctions",
+            "lambda:GetFunctionConfiguration",
+            "lambda:GetPolicy",
+            "lambda:GetFunctionUrlConfig",
+            "lambda:GetFunctionCodeSigningConfig",
+            "lambda:GetCodeSigningConfig",
+            "lambda:GetFunctionConcurrency",
+            "lambda:ListEventSourceMappings",
+            "iam:ListAttachedRolePolicies",
+            "iam:GetPolicy",
+            "iam:GetPolicyVersion",
+            "iam:ListRolePolicies",
+            "iam:GetRolePolicy",
+            "ec2:DescribeSubnets",
+            "ec2:DescribeSecurityGroups",
+            "logs:DescribeLogGroups",
+            "sts:GetCallerIdentity"
+        ],
+        "Resource": "*"
+    }]
+}
+```
+
+## Security Scoring
+
+Each function receives a security score (0-100) starting at **100 points**:
+
+| Check | Condition | Deduction | Severity |
+|-------|-----------|-----------|----------|
+| B.1 | Resource policy allows public access | -25 | CRITICAL |
+| B.2 | Function URL AuthType NONE | -25 | CRITICAL |
+| A.3 | Env var secrets, no KMS (mutually excl.) | -20 | CRITICAL |
+| B.4 | Admin-equivalent access (Administrator/PowerUser/IAMFull or `*`) | -20 | CRITICAL |
+| A.1 | Runtime blocked | -15 | HIGH |
+| A.1 | Runtime deprecated | -10 | HIGH |
+| B.3 | CORS allows all origins | -10 | HIGH |
+| B.4 | Service-level wildcard actions (e.g. `s3:*`) | -10 | HIGH |
+| B.4 | Privilege escalation permissions | -10 | HIGH |
+| B.5 | Shared execution role | -10 | HIGH |
+| A.3 | Env var secrets, has KMS (mutually excl.) | -10 | HIGH |
+| C.2 | VPC single AZ | -5 | MEDIUM |
+| C.3 | Unrestricted SG egress | -5 | MEDIUM |
+| D.1 | Log group missing or no retention | -5 | MEDIUM |
+| A.6 | X-Ray tracing disabled | -2 | LOW |
+| A.7 | No dead letter queue | -2 | LOW |
+| D.2 | No reserved concurrency | -2 | LOW |
+| E.1 | No code signing config | -5 | MEDIUM |
+| E.2 | ESM without failure destination | -5 | MEDIUM |
+| A.5 | External Lambda layers | -3 | MEDIUM |
+| C.1 | No VPC configuration | -3 | LOW |
+| A.1 | Runtime near EOL | -3 | LOW |
+| E.1 | Code signing policy Warn (not Enforce) | -3 | LOW |
+| A.2 | Maximum timeout (900s) | -2 | LOW |
+| A.4 | Large ephemeral storage | -2 | LOW |
+
+**Mutual exclusion rules:**
+- A.1: Only the highest-severity runtime deduction applies (blocked > deprecated > near_eol)
+- A.3: Only one of the two variants applies (no KMS > has KMS)
+- E.1: Only one of the two variants applies (no config > Warn policy)
+
+**Formula**: `Score = max(0, 100 - total_deductions)`
+
+### Score Interpretation
+
+| Score Range | Level | Action |
+|-------------|-------|--------|
+| 90-100 | Excellent | Maintain current posture |
+| 70-89 | Good | Address minor gaps |
+| 50-69 | Needs Improvement | Fix medium-priority issues |
+| 0-49 | Poor | Immediate action required |
+
+## Output Files
+
+The scanner generates reports in the specified output directory:
+
+### JSON Report (`lambda_scan_region_timestamp.json`)
+```json
+{
+  "summary": {
+    "scan_time": "2026-03-11T10:30:45",
+    "region": "us-east-1",
+    "account_id": "123456789012",
+    "total_functions": 25,
+    "average_security_score": 82.3
+  },
+  "results": [...]
+}
+```
+
+### CSV Report (`lambda_scan_region_timestamp.csv`)
+Spreadsheet-friendly format with all key metrics and compliance status.
+
+### HTML Report (`lambda_scan_region_timestamp.html`)
+Interactive dashboard with:
+- **Executive Summary**: Key metrics and risk indicators
+- **Score Distribution**: Bar chart of function security scores
+- **Compliance Overview**: Bar chart across all 10 frameworks
+- **Severity Breakdown**: Doughnut chart of findings by severity
+- **Function Details**: Sortable table with score bars
+- **Critical Findings**: Table of high/critical severity issues
+
+### Compliance Report (`lambda_compliance_region_timestamp.json`)
+Per-function compliance evaluation across all 10 frameworks with passed/failed control details.
+
+## Modular Architecture
+
+```
+lambda_security_scanner/
+├── scanner.py                  # Main scanner orchestration (facade pattern)
+├── cli.py                      # Click CLI interface
+├── compliance.py               # 81 controls across 10 frameworks
+├── html_reporter.py            # Jinja2 HTML report generation
+├── utils.py                    # Logging, scoring, formatting
+├── checks/                     # Security check modules
+│   ├── base.py                 # BaseChecker (session factory, error handling)
+│   ├── function_config.py      # A.1-A.7: Runtime, secrets, layers, tracing
+│   ├── access_control.py       # B.1-B.5: Policies, URLs, roles
+│   ├── network_security.py     # C.1-C.3: VPC, AZ, security groups
+│   ├── logging_monitoring.py   # D.1-D.2: Log groups, concurrency
+│   └── code_security.py        # E.1-E.2: Code signing, ESM
+└── templates/
+    └── report.html             # Interactive HTML dashboard
+```
+
+## Development
+
+### Setting Up Development Environment
+
+```bash
+git clone https://github.com/TocConsulting/lambda-security-scanner.git
+cd lambda-security-scanner
+
+python -m venv venv
+source venv/bin/activate
+
+pip install -e ".[dev]"
+```
+
+## Testing
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run all tests
+python -m pytest tests/ -v
+
+# Run specific test file
+python -m pytest tests/test_compliance.py -v
+
+# Run with coverage
+python -m pytest tests/ --cov=lambda_security_scanner --cov-report=html
+
+# Code formatting
+black lambda_security_scanner/ tests/
+```
+
+## Support & Contributing
+
+### Getting Help
+- **Documentation**: Check this README and inline help (`--help`)
+- **Issues**: Report bugs via [GitHub Issues](https://github.com/TocConsulting/lambda-security-scanner/issues)
+
+### Contributing
+We welcome contributions! Please:
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- **AWS Security Best Practices**: Based on official AWS security recommendations
+- **CIS Benchmarks**: Maps findings to the CIS AWS Compute Services Benchmark Lambda guidance (scanner-defined control identifiers)
+- **[ec2-security-scanner](https://github.com/TocConsulting/ec2-security-scanner)**: Architecture and design patterns
+
+---
+
+**Security Notice**: This tool is designed for defensive security purposes only. Always ensure you have proper authorization before scanning AWS resources. The tool requires read-only permissions and does not modify any AWS resources.
+
+**Performance Note**: The scanner uses parallel function analysis with ThreadPoolExecutor to minimize scan time. Use `-w` to adjust parallelism based on your API rate limits.