Skip to main content
Version: v4.2.24

Security Documentation

🔒 Read-Only Operation Guarantee​

This document provides detailed security information about the AWS Cloud BOM Automation tools, including the comprehensive security validation and production monitoring features.

🛡️ Enterprise Security Validation​

InvenTag includes a comprehensive security validation system that ensures all AWS operations are read-only and provides detailed audit logging for compliance requirements.

ReadOnlyAccessValidator​

The ReadOnlyAccessValidator class provides enterprise-grade security validation:

from inventag.compliance import ReadOnlyAccessValidator, ComplianceStandard

# Initialize validator with compliance standard
validator = ReadOnlyAccessValidator(ComplianceStandard.GENERAL)

# Validate operations before execution
result = validator.validate_operation("ec2", "describe_instances")
if result.is_valid:
    # Operation is safe to execute
    print(f"✓ Operation approved: {result.validation_message}")
else:
    # Operation is blocked
    print(f"✗ Operation blocked: {result.validation_message}")

Production Safety Monitoring​

The ProductionSafetyMonitor provides comprehensive error handling and monitoring:

from inventag.compliance import ProductionSafetyMonitor

# Initialize production monitor
monitor = ProductionSafetyMonitor(
    enable_cloudtrail=True,
    enable_performance_monitoring=True,
    error_threshold=10
)

# Handle errors with graceful degradation
try:
    # Your AWS operation
    pass
except Exception as e:
    error_context = monitor.handle_error(
        error=e,
        operation="describe_instances",
        service="ec2"
    )
    # Error is logged and handled gracefully

Automated Security Validation​

InvenTag now includes automated security validation that enforces read-only operations at runtime:

Operation Classification System​

  • Explicit Read-Only Operations: Comprehensive whitelist of known safe operations
  • Pattern-Based Detection: Automatic classification using operation name patterns
  • Unknown Operation Blocking: Any unrecognized operation is automatically blocked
  • Real-Time Validation: Every operation is validated before execution

Verified Read-Only Operations​

All operations are automatically validated and only read-only operations are allowed:

✅ Allowed Operations (Read-Only)​

  • describe_* - Get detailed information about resources
  • list_* - List resources and their basic information
  • get_* - Retrieve specific resource data and configurations
  • lookup_* - Search for events and historical data

❌ Prohibited Operations (None Present)​

  • create_* - Create new resources
  • update_* - Modify existing resources
  • delete_* - Remove resources
  • put_* - Upload or modify data (except optional S3 report upload)
  • modify_* - Change resource configurations
  • attach_* / detach_* - Modify resource associations
  • associate_* / disassociate_* - Change network associations

Automated Security Validation Results​

Runtime Security Validation:

  • ✅ Real-time operation validation - Every AWS API call is validated before execution
  • ✅ Comprehensive audit logging - All operations logged with compliance metadata
  • ✅ Automatic blocking - Mutating operations are automatically prevented
  • ✅ Error handling - Graceful degradation with detailed error context
  • ✅ Performance monitoring - Real-time system performance tracking

Code Audit Results:

  • aws_resource_inventory.py - ✅ Read-only verified + runtime validation
  • tag_compliance_checker.py - ✅ Read-only verified + runtime validation
  • bom_converter.py - ✅ Local file operations only + runtime validation
  • security_validator.py - ✅ Security validation enforcement
  • production_monitor.py - ✅ Production safety monitoring

Only Write Operation:

  • s3.put_object() - Used only for optional report upload to S3 (validated)

📋 IAM Permission Requirements​

Minimum Required Permissions​

The tools require the following read-only permissions:

Core EC2 Permissions​

"ec2:DescribeRegions",
"ec2:DescribeInstances", 
"ec2:DescribeVolumes",
"ec2:DescribeSecurityGroups",
"ec2:DescribeVpcs",
"ec2:DescribeSubnets"

Resource Groups Tagging API (Primary Discovery)​

"resourcegroupstaggingapi:GetResources"

This single permission enables discovery of ALL taggable resources across ALL AWS services

Service-Specific Permissions​

"s3:ListAllMyBuckets",
"s3:GetBucketLocation", 
"s3:GetBucketTagging",
"rds:DescribeDBInstances",
"rds:ListTagsForResource",
"lambda:ListFunctions",
"lambda:ListTags",
"iam:ListRoles",
"iam:ListRoleTags", 
"iam:ListUsers",
"iam:ListUserTags",
"cloudformation:ListStacks",
"cloudformation:DescribeStacks",
"ecs:ListClusters",
"ecs:DescribeClusters",
"ecs:ListTagsForResource",
"eks:ListClusters", 
"eks:DescribeCluster",
"cloudwatch:DescribeAlarms"

Extended Discovery Permissions​

"config:DescribeConfigurationRecorderStatus",
"config:ListDiscoveredResources",
"config:ListAggregateDiscoveredResources", 
"config:GetResourceConfigHistory",
"cloudtrail:LookupEvents",
"logs:DescribeLogGroups",
"logs:ListTagsLogGroup",
"route53:ListHostedZones",
"route53:ListTagsForResource",
"apigateway:GET",
"dynamodb:ListTables",
"dynamodb:DescribeTable", 
"dynamodb:ListTagsOfResource",
"sns:ListTopics",
"sns:ListTagsForResource",
"sqs:ListQueues",
"sqs:GetQueueAttributes",
"sqs:ListQueueTags",
"kms:ListKeys",
"kms:DescribeKey",
"kms:ListResourceTags",
"elasticache:DescribeCacheClusters",
"elasticache:ListTagsForResource",
"opensearch:ListDomainNames",
"opensearch:DescribeDomain", 
"opensearch:ListTags",
"es:ListDomainNames",
"es:DescribeElasticsearchDomain",
"es:ListTags"

Optional S3 Upload Permission​

"s3:PutObject" on "arn:aws:s3:::YOUR-BUCKET-NAME/*"

🛡️ Security Best Practices​

1. Principle of Least Privilege​

  • Use the exact permissions listed in iam-policy-read-only.json
  • Remove permissions for services you don't need to scan
  • Restrict S3 upload to specific bucket ARNs

2. Access Control​

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RestrictToSpecificUser",
      "Effect": "Allow", 
      "Principal": {
        "AWS": "arn:aws:iam::ACCOUNT:user/inventory-scanner"
      },
      "Action": "*",
      "Resource": "*"
    }
  ]
}

3. Conditional Access​

{
  "Condition": {
    "IpAddress": {
      "aws:SourceIp": ["203.0.113.0/24"]
    },
    "Bool": {
      "aws:MultiFactorAuthPresent": "true"
    },
    "DateGreaterThan": {
      "aws:CurrentTime": "2025-01-01T00:00:00Z"
    }
  }
}

4. Monitoring and Auditing​

# Enable CloudTrail for API monitoring
aws cloudtrail create-trail \
  --name inventory-audit-trail \
  --s3-bucket-name audit-logs-bucket

# Monitor for unexpected API calls
aws logs create-log-group --log-group-name /aws/inventory/audit

5. Network Security​

  • Run from secure networks with restricted egress
  • Use VPC endpoints for AWS API calls when possible
  • Implement network ACLs to restrict access

🚨 Security Considerations​

What These Tools Can Access​

  • ✅ Resource metadata and configurations
  • ✅ Tag information across all resources
  • ✅ Network topology information (VPC/subnet details)
  • ✅ Resource relationships and dependencies
  • ✅ Historical resource configuration (via Config)
  • ✅ Recent resource creation events (via CloudTrail)

What These Tools Cannot Do​

  • ❌ Create, modify, or delete any AWS resources
  • ❌ Change resource configurations or settings
  • ❌ Access resource data/content (e.g., S3 object contents, database data)
  • ❌ Modify IAM policies or permissions
  • ❌ Start, stop, or restart services
  • ❌ Modify network configurations
  • ❌ Access encrypted data or secrets

Data Sensitivity​

The tools collect:

  • Low Sensitivity: Resource IDs, types, regions, states
  • Medium Sensitivity: Resource names, tags, network configurations
  • High Sensitivity: ARNs (contain account IDs), resource relationships

Recommendation: Treat output files as sensitive and store securely.

🔐 Compliance Considerations​

General Compliance Standards​

  • ✅ Read-only enforcement - Automated validation ensures compliance with read-only requirements
  • ✅ Comprehensive audit logging - Detailed audit trails for all operations
  • ✅ Security validation reports - Automated compliance report generation
  • ✅ Risk assessment - Automatic risk scoring and security finding generation
  • ✅ Identity validation - AWS identity type detection and validation

SOC 2 / ISO 27001​

  • ✅ Audit trail generation - Comprehensive logging supports audit requirements
  • ✅ Security monitoring - Real-time security validation and error handling
  • ✅ Performance monitoring - System performance tracking and alerting
  • ✅ Risk management - Automated risk assessment and mitigation strategies

PCI DSS​

  • ✅ No data access - Only metadata collection, no access to cardholder data
  • ✅ Environment documentation - Comprehensive resource discovery and mapping
  • ✅ Network analysis - Detailed network topology for scope definition
  • ✅ Security validation - Automated security posture assessment

GDPR​

  • ✅ No personal data access - Only resource metadata collection
  • ✅ Data mapping support - Resource discovery aids in data flow mapping
  • ✅ Classification validation - Tag compliance ensures proper data classification
  • ✅ Audit capabilities - Comprehensive audit trails for compliance demonstration

HIPAA​

  • ✅ No PHI access - Only infrastructure metadata collection
  • ✅ Environment documentation - Detailed resource inventory for compliance audits
  • ✅ Security monitoring - Continuous security validation and monitoring
  • ✅ Risk assessment - Automated security risk identification and reporting

Compliance Reporting Features​

Automated Compliance Reports​

from inventag.compliance import ComplianceManager, ComplianceStandard

# Generate comprehensive compliance report
manager = ComplianceManager(ComplianceStandard.GENERAL)
report = manager.generate_comprehensive_compliance_report()

# Key report sections:
# - Executive summary with compliance score
# - Detailed audit entries with timestamps
# - Security findings and risk assessment
# - Recommendations for improvement
# - Performance metrics and monitoring data

Security Validation Reports​

from inventag.compliance import ProductionSafetyMonitor

monitor = ProductionSafetyMonitor()
security_report = monitor.generate_security_validation_report()

# Report includes:
# - Total operations and success rates
# - Security findings and violations
# - Risk score calculation
# - CloudTrail event correlation
# - Recommendations for security improvements

📞 Security Contact​

For security-related questions or to report security issues:

  1. Review this documentation thoroughly
  2. Test in non-production environments first
  3. Use minimal permissions for your specific use case
  4. Monitor AWS CloudTrail for API usage validation

🔄 Security Updates​

This security documentation is maintained alongside the codebase. Any changes to AWS API usage will be reflected here with version updates.