Skip to main content

Boto3 Governance Wrapper

FieldValue
Document IDASCEND-SDK-009
Version1.0.0
Last UpdatedDecember 19, 2025
AuthorAscend Engineering Team
PublisherOW-KAI Technologies Inc.
ClassificationEnterprise Client Documentation
ComplianceSOC 2 CC6.1/CC6.2, PCI-DSS 7.1/8.3, HIPAA 164.312, NIST 800-53 AC-2/SI-4

Reading Time: 10 minutes | Skill Level: Beginner

Overview​

The ASCEND Boto3 Wrapper adds transparent AI governance to all AWS SDK operations. With a single line of code, every boto3 call is evaluated against your governance policies.

How It Works​

┌─────────────────────────────────────────────────────────────────────┐
│                    BOTO3 GOVERNANCE FLOW                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐              │
│  │   Your      │    │   ASCEND    │    │    AWS      │              │
│  │   Code      │───▶│   Wrapper   │───▶│   API       │              │
│  │             │    │             │    │             │              │
│  │ s3.delete() │    │ ✓ Risk=HIGH │    │ Bucket      │              │
│  │             │    │ ✓ APPROVED  │    │ Deleted     │              │
│  └─────────────┘    └─────────────┘    └─────────────┘              │
│                            │                                         │
│                            │                                         │
│                            ▼                                         │
│                    ┌─────────────┐                                   │
│                    │   ASCEND    │                                   │
│                    │   Platform  │                                   │
│                    │             │                                   │
│                    │ Policy      │                                   │
│                    │ Evaluation  │                                   │
│                    │ Audit Log   │                                   │
│                    └─────────────┘                                   │
│                                                                       │
└─────────────────────────────────────────────────────────────────────┘

Installation​

pip install ascend-boto3-wrapper

Package Info: ascend-boto3-wrapper on PyPI | Version: 1.0.0 | License: Proprietary

Requirements​

  • Python 3.8+
  • boto3 >= 1.26.0

Quick Start​

# Source: sdk/ascend-boto3-wrapper/ascend_boto3/wrapper.py:349
from ascend_boto3 import enable_governance

# Enable governance globally - one line!
enable_governance(api_key="owkai_your_key_here")

# All boto3 operations now go through ASCEND
import boto3

# This will require approval for HIGH risk
s3 = boto3.client('s3')
s3.delete_bucket(Bucket='production-data')  # Governed!

# This will auto-approve for LOW risk
s3.list_buckets()  # Governed but auto-approved

Configuration Options​

# Source: sdk/ascend-boto3-wrapper/ascend_boto3/wrapper.py:349
from ascend_boto3 import enable_governance

enable_governance(
    # Required
    api_key="owkai_your_key_here",

    # Optional
    base_url="https://pilot.owkai.app",
    agent_id="aws-automation-001",
    agent_name="AWS Automation Agent",

    # Auto-approve settings
    auto_approve_low_risk=True,    # Auto-approve LOW risk ops
    auto_approve_medium_risk=False, # Require approval for MEDIUM

    # Bypass rules
    bypass_services={"cloudwatch", "logs"},  # Skip these services
    bypass_operations={"s3.list_buckets"},   # Skip specific operations

    # Testing
    dry_run=False  # Log decisions without enforcing
)
OptionTypeDefaultDescription
api_keystrRequiredASCEND API key
base_urlstrhttps://pilot.owkai.appAPI endpoint
agent_idstrAuto-generatedUnique agent identifier
agent_namestrAWS Boto3 AgentHuman-readable name
auto_approve_low_riskboolTrueAuto-approve LOW risk
auto_approve_medium_riskboolFalseAuto-approve MEDIUM risk
bypass_servicesSet[str]{}Services to skip
bypass_operationsSet[str]{}Operations to skip
dry_runboolFalseLog without enforcing

Risk Classification​

The wrapper automatically classifies AWS operation risk:

Risk Levels by Service​

Risk LevelServices/OperationsExamples
LOWRead-only operationss3.get_object, ec2.describe_instances
MEDIUMWrite operationss3.put_object, dynamodb.put_item
HIGHDelete operationss3.delete_bucket, ec2.terminate_instances
CRITICALIAM/Security changesiam.create_user, kms.delete_key

Classification Logic​

# Source: sdk/ascend-boto3-wrapper/ascend_boto3/risk_classifier.py
from ascend_boto3.risk_classifier import classify_operation_risk, RiskLevel

# Check operation risk before execution
risk_score, risk_level = classify_operation_risk(
    service='s3',
    operation='delete_bucket',
    params={'Bucket': 'my-bucket'}
)

print(f"Risk: {risk_level.value} ({risk_score})")
# Output: Risk: high (75)

Bypass Rules​

Skip governance for specific services or operations:

Bypass by Service​

enable_governance(
    api_key="owkai_xxx",
    bypass_services={
        "cloudwatch",     # Skip all CloudWatch operations
        "logs",           # Skip all CloudWatch Logs
        "cloudformation"  # Skip all CloudFormation
    }
)

Bypass by Operation​

enable_governance(
    api_key="owkai_xxx",
    bypass_operations={
        "s3.list_buckets",           # Skip S3 list buckets
        "ec2.describe_instances",    # Skip EC2 describe
        "sts.get_caller_identity"    # Skip STS identity check
    }
)

Handling Decisions​

Approved Actions​

Approved actions execute normally:

s3 = boto3.client('s3')

# This will be logged and proceed if approved
response = s3.get_object(Bucket='my-bucket', Key='data.json')
# Returns normal boto3 response

Denied Actions​

Denied actions raise PermissionError:

from ascend_boto3 import enable_governance

enable_governance(api_key="owkai_xxx")

try:
    s3 = boto3.client('s3')
    s3.delete_bucket(Bucket='critical-production-data')
except PermissionError as e:
    print(f"Operation denied: {e}")
    # Output: Operation denied by Ascend governance.
    # Reason: Bucket deletion requires manager approval.
    # Action ID: act_123xyz

Dry Run Mode​

Test governance without blocking operations:

enable_governance(
    api_key="owkai_xxx",
    dry_run=True  # Log decisions but don't enforce
)

# All operations execute, but decisions are logged
s3 = boto3.client('s3')
s3.delete_bucket(Bucket='test-bucket')
# Logs: "[DRY RUN] Would execute: s3.delete_bucket"
# Actually executes the delete

Disabling Governance​

from ascend_boto3 import enable_governance, disable_governance, is_governance_enabled

enable_governance(api_key="owkai_xxx")

# ... governed operations ...

# Disable when done
disable_governance()

# Check status
if is_governance_enabled():
    print("Governance is active")
else:
    print("Governance is disabled")

Production Example​

#!/usr/bin/env python3
"""
Production AWS Automation with ASCEND Governance
"""
import os
import logging
import boto3
from ascend_boto3 import enable_governance

# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def setup_governance():
    """Initialize governance with production settings."""
    enable_governance(
        api_key=os.environ["ASCEND_API_KEY"],
        agent_id="aws-automation-prod",
        agent_name="AWS Production Automation",

        # Auto-approve only LOW risk in production
        auto_approve_low_risk=True,
        auto_approve_medium_risk=False,

        # Skip monitoring services
        bypass_services={"cloudwatch", "logs"},

        # Never skip delete operations
        # bypass_operations={}
    )
    logger.info("ASCEND governance enabled")

def cleanup_old_buckets():
    """Delete S3 buckets older than 90 days."""
    s3 = boto3.client('s3')

    try:
        response = s3.list_buckets()  # AUTO-APPROVED (low risk)

        for bucket in response['Buckets']:
            bucket_name = bucket['Name']

            if should_delete_bucket(bucket):
                logger.info(f"Requesting deletion of {bucket_name}")

                try:
                    # REQUIRES APPROVAL (high risk)
                    s3.delete_bucket(Bucket=bucket_name)
                    logger.info(f"Deleted {bucket_name}")

                except PermissionError as e:
                    logger.warning(f"Deletion denied: {e}")
                    # Queue for manual review
                    queue_for_review(bucket_name, str(e))

    except Exception as e:
        logger.error(f"Cleanup failed: {e}")
        raise

def should_delete_bucket(bucket):
    """Check if bucket should be deleted."""
    # Your business logic here
    return False

def queue_for_review(bucket_name, reason):
    """Queue bucket for manual review."""
    logger.info(f"Queued {bucket_name} for manual review: {reason}")

if __name__ == "__main__":
    setup_governance()
    cleanup_old_buckets()

Fallback Behavior​

When ASCEND is unavailable:

# Source: sdk/ascend-boto3-wrapper/ascend_boto3/wrapper.py:176
# For HIGH/CRITICAL risk: FAIL CLOSED (deny)
# For LOW/MEDIUM risk: FAIL OPEN (allow with warning)

# The wrapper logs failures and acts accordingly:
# INFO: [Ascend Governance] s3.delete_bucket - Risk: HIGH (75) - DENIED
# WARNING: Governance evaluation failed, denying high-risk operation

Monitoring​

CloudWatch Metrics​

The wrapper logs structured metrics:

{
    "service": "s3",
    "operation": "delete_bucket",
    "risk_score": 75,
    "risk_level": "high",
    "decision": "approved",
    "action_id": "act_123xyz",
    "latency_ms": 45
}

Log Analysis​

# Find denied operations
grep "DENIED" /var/log/app.log

# Find high-risk approvals
grep "Risk: HIGH.*APPROVED" /var/log/app.log

Troubleshooting​

IssueCauseSolution
ValueError: API key requiredMissing API keySet ASCEND_API_KEY env var
PermissionError on low-riskStrict policiesCheck Smart Rules in dashboard
All operations deniedAPI connectivityVerify network access to ASCEND
Operations executing without governanceNot enabledCall enable_governance() first

Supported AWS Services​

The wrapper supports all boto3 services. Risk classification is available for:

  • S3 - Object storage operations
  • EC2 - Compute instance management
  • RDS - Database operations
  • DynamoDB - NoSQL operations
  • Lambda - Function management
  • IAM - Identity and access
  • KMS - Key management
  • SNS/SQS - Messaging
  • Secrets Manager - Secrets operations

Other services use default risk classification based on operation type.

Next Steps​

Document Version: 1.0.0 | Last Updated: December 2025