master

Author: İsmail Taşdelen

SECURITY.md

@@ -0,0 +1,229 @@
+# Security Policy
+
+## Overview
+
+PathShield is a security tool designed to detect AWS privilege escalation paths. We take security seriously and appreciate the security research community's efforts to help keep PathShield and its users secure.
+
+## Supported Versions
+
+We provide security updates for the following versions:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.1.x   | :white_check_mark: |
+| < 0.1   | :x:                |
+
+## Reporting a Vulnerability
+
+We encourage responsible disclosure of security vulnerabilities. If you discover a security issue in PathShield, please follow these guidelines:
+
+### How to Report
+
+1. **DO NOT** create a public GitHub issue for security vulnerabilities
+2. **Email** security reports to: security@pathshield.io
+3. **Include** the following information:
+   - Description of the vulnerability
+   - Steps to reproduce the issue
+   - Potential impact assessment
+   - Suggested fix (if available)
+   - Your contact information
+
+### What to Expect
+
+- **Acknowledgment**: We will acknowledge receipt of your vulnerability report within 48 hours
+- **Assessment**: We will assess the vulnerability and determine its severity within 5 business days
+- **Updates**: We will keep you informed of our progress throughout the investigation
+- **Resolution**: We aim to release a fix within 30 days for critical vulnerabilities
+- **Credit**: With your permission, we will publicly credit you for the discovery
+
+### Response Timeline
+
+| Severity | Initial Response | Fix Target |
+|----------|-----------------|------------|
+| Critical | 24 hours | 7-14 days |
+| High     | 48 hours | 14-30 days |
+| Medium   | 5 days   | 30-60 days |
+| Low      | 7 days   | 60-90 days |
+
+## Security Considerations
+
+### AWS Credentials
+
+**PathShield requires AWS credentials to function.** Users must be aware of the following:
+
+1. **Read-Only Access**: PathShield only requires read-only IAM permissions
+2. **Credentials Storage**: Never hardcode AWS credentials in code or configuration files
+3. **Use IAM Roles**: When running on EC2 or containers, use IAM roles instead of access keys
+4. **Credential Rotation**: Regularly rotate AWS access keys used for scanning
+5. **Least Privilege**: Grant only the minimum permissions required for scanning
+
+### Recommended IAM Policy
+
+Use this least-privilege IAM policy for PathShield:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "iam:GetUser",
+        "iam:GetRole",
+        "iam:GetGroup",
+        "iam:ListUsers",
+        "iam:ListRoles",
+        "iam:ListGroups",
+        "iam:ListAttachedUserPolicies",
+        "iam:ListAttachedRolePolicies",
+        "iam:ListAttachedGroupPolicies",
+        "iam:GetPolicy",
+        "iam:GetPolicyVersion",
+        "ec2:DescribeInstances",
+        "ec2:DescribeInstanceProfile",
+        "lambda:ListFunctions",
+        "lambda:GetFunction",
+        "s3:ListAllMyBuckets",
+        "s3:GetBucketPolicy",
+        "kms:ListKeys",
+        "kms:DescribeKey"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+### Running PathShield Securely
+
+1. **Use Dedicated Scanning Role**: Create a dedicated IAM role for PathShield with minimal permissions
+2. **Enable CloudTrail**: Log all API calls made by PathShield for audit purposes
+3. **Secure Output**: Treat scan results as sensitive - they contain information about your security posture
+4. **Network Isolation**: When possible, run PathShield in an isolated network environment
+5. **Docker Security**: If using Docker, don't bind-mount sensitive directories unnecessarily
+
+### Data Handling
+
+PathShield collects the following data during scans:
+
+- IAM user, role, and group names
+- IAM policy documents
+- EC2 instance metadata
+- Lambda function configurations
+- S3 bucket policies
+- KMS key metadata
+
+**Data is never sent outside your AWS account unless you explicitly configure external integrations.**
+
+## Known Security Limitations
+
+1. **Policy Evaluation**: PathShield performs static analysis and may not detect all runtime permission conditions
+2. **Cross-Account**: Limited visibility into cross-account trust relationships without additional permissions
+3. **SCPs**: Service Control Policies (SCPs) are not currently evaluated
+4. **Permission Boundaries**: Complex permission boundary scenarios may not be fully analyzed
+5. **Temporary Credentials**: STS temporary credential expiration is not tracked in real-time
+
+## Security Best Practices for Users
+
+### Installation
+
+- Always install from official sources (PyPI, GitHub releases)
+- Verify package integrity when possible
+- Use virtual environments to isolate dependencies
+- Keep PathShield updated to the latest version
+
+### Configuration
+
+- Store configuration files with appropriate permissions (chmod 600)
+- Never commit configuration files containing credentials to version control
+- Use environment variables or AWS credential provider chain
+- Enable verbose logging for security audits
+
+### CI/CD Integration
+
+- Use ephemeral credentials in CI/CD pipelines
+- Store API tokens and secrets in secure secret managers
+- Limit pipeline permissions to read-only access
+- Review and approve changes to security scanning workflows
+
+### Output Handling
+
+- Restrict access to scan results - they contain security-sensitive information
+- Sanitize results before sharing outside security teams
+- Store historical scan results securely for compliance
+- Use encrypted storage for SARIF and JSON outputs
+
+## Vulnerability Disclosure Policy
+
+### Our Commitment
+
+- We will respond to security reports promptly
+- We will work with reporters to understand and resolve issues
+- We will keep reporters informed throughout the process
+- We will credit reporters publicly (unless anonymity is requested)
+
+### What We Ask
+
+- Give us reasonable time to address issues before public disclosure
+- Make a good faith effort to avoid privacy violations and data destruction
+- Do not exploit vulnerabilities beyond what is necessary for demonstration
+- Do not perform testing against systems you don't own
+
+## Security Hall of Fame
+
+We appreciate the following security researchers who have helped improve PathShield:
+
+*List will be updated as vulnerabilities are responsibly disclosed and resolved.*
+
+## Security Updates
+
+Subscribe to security updates:
+
+- Watch the GitHub repository for security advisories
+- Follow [@pathshield](https://twitter.com/pathshield) on Twitter
+- Subscribe to the security mailing list: security-announce@pathshield.io
+
+## Contact
+
+- **Security Issues**: security@pathshield.io
+- **General Questions**: team@pathshield.io
+- **GitHub Issues**: For non-security bugs and feature requests only
+
+## PGP Key
+
+For encrypted communications:
+
+```
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+[PGP key would be included here in production]
+-----END PGP PUBLIC KEY BLOCK-----
+```
+
+## Compliance
+
+PathShield is designed to help organizations improve their AWS security posture. However:
+
+- PathShield is provided "as-is" without warranties
+- Users are responsible for ensuring compliance with their specific requirements
+- Scan results should be validated by security professionals
+- PathShield does not replace comprehensive security audits
+
+## Legal
+
+By using PathShield, you agree to:
+
+- Use it only on AWS accounts you own or have authorization to scan
+- Not use it for malicious purposes
+- Comply with all applicable laws and regulations
+- Accept the terms of the MIT License
+
+## Acknowledgments
+
+We thank the security research community for their continued efforts to improve software security.
+
+---
+
+**Last Updated**: January 2024  
+**Version**: 1.0
+
+For questions about this security policy, contact: security@pathshield.io